Writing a Zeebe Exporter – Part One

By
  • Blog
  • >
  • Writing a Zeebe Exporter – Part One
TOPICS

30 Day Free Trial

Bring together legacy systems, RPA bots, microservices and more with Camunda

Sign Up for Camunda Content

Get the latest on Camunda features, events, top trends, and more.

TRENDING CONTENT

Exporters allow you to tap into the Zeebe event stream and export selected events to other systems. You can filter events, perform transformations, and even trigger side-effects from an exporter. In this post, we’ll step through implementing an exporter.

In later posts, we’ll look more in depth at configuration and performance – but for now we’ll cover the bare minimum to help you understand how exporters work in Zeebe.

Building an Exporter

Follow along these steps to create a minimal exporter that can be deployed to a Zeebe broker.

Note: Zeebe is under active development, and things may change. I have noted in each step things that are most likely to change.

  • Create a new maven project:
mvn archetype:generate -DgroupId=io.zeebe 
    -DartifactId=zeebe-exporter-demo 
    -DarchetypeArtifactId=maven-archetype-quickstart 
    -DinteractiveMode=false
  • Add zeebe-exporter-api as a dependency in the project’s pom.xml file:
<dependency>
    <groupId>io.zeebe</groupId>
    <artifactId>zeebe-exporter-api</artifactId>
    <version>0.17.0</version>
</dependency>

Note: the current version at the time of writing is Zeebe 0.17.0. Check the releases page for the latest version.

  • Rename the file src/main/java/io.zeebe/App.java to DemoExporter.java, then edit it and import the Exporter interface:
import io.zeebe.exporter.api.spi.Exporter;

Note: as of May 28, 2019, there is an open issue to move this interface to io.zeebe.exporter.api.Exporter.

  • Remove the main method from the App class, rename it as DemoExporter, and implement Exporter:
public class DemoExporter implements Exporter {

}
  • If your IDE supports it, use code completion to implement the methods you need to fulfill the Exporter interface:
public class DemoExporter implements Exporter {

    public void configure(Context context) {

    }

    public void open(Controller controller) {

    }

    public void close() {

    }

    public void export(Record record) {

    }
}

Exporter Life-cycle

These methods are the life-cycle hooks for an exporter.

Configure

The configure method allows your exporter to read any configuration specified for it in the zeebe.cfg.toml file, using the Context parameter. If your exporter throws in this method, the broker will halt during startup. This prevents the broker from starting if an exporter doesn’t have sufficient configuration to operate.

Open

If your exporter does not throw in the configure method, then another instance is created, its configure method is called, and then the open method is called. In this method you can get a reference to a Controller. The Controller provides an asynchronous scheduler that can be used to implement operation batching (we will look at that in another post), and a method to mark a record as exported.

Close

When the broker shuts down, the close method is called, and you can perform any clean-up that you need to.

Export

Whenever a record is available for export, the export method is called with the record to export. Remember that you must move the exporter record position forward, otherwise the broker will not truncate the event log.

Exporting a Record

We’ll make the simplest exporter possible: we’ll write a JSON representation of the record to the console.

We won’t need configure or close, so we can remove them.

  • We will grab a reference to the Controller in the open method first of all:
public class DemoExporter implements Exporter {
    Controller controller;

    public void open(Controller controller) {
        this.controller = controller;
    }

    public void export(Record record) {

    }
}
  • Now we will implement an export method to (a) print out the record, and (b) mark the record as exported:
public class DemoExporter implements Exporter {
    Controller controller;

    public void open(Controller controller) {
        this.controller = controller;
    }

    public void export(Record record) {
        System.out.println(record.toJson());
        this.controller.updateLastExportedRecordPosition(record.getPosition());
    }
}

Deploy the Exporter

  • Build the exporter, using mvn package.
  • Copy the resulting zeebe-exporter-demo-1.0-SNAPSHOT.jar file to the lib directory of your Zeebe broker.
  • Edit the zeebe.cfg.toml file, and add an entry for the exporter:
[[exporters]]
id = "demo"
className = "io.zeebe.DemoExporter"
  • Start the broker.
  • Now, deploy a bpmn diagram to the broker, and you will see the deployment being logged to the console by your exporter.

The source code for this exporter is available on GitHub, and a docker-compose configuration for it is available in the exporter-demo folder.

Camunda Developer Community

Join Camunda’s global community of developers sharing code, advice, and meaningful experiences

Start the discussion at forum.camunda.io

Try All Features of Camunda

Related Content

We're streamlining Camunda product APIs, working towards a single REST API for many components, simplifying the learning curve and making installation easier.
Learn about our approach to migration from Camunda 7 to Camunda 8, and how we can help you achieve it as quickly and effectively as possible.
We've been working hard to reduce the job activation latency in Zeebe. Read on to take a peek under the hood at how we went about it and then verified success.