aolmez / quarkus-zeebe

Camunda Platform 8 (Zeebe) Quarkus extension

Quarkus Zeebe

Usage

To use the extension, add the dependency to the target project:

<dependency>
    <groupId>io.quarkiverse.zeebe</groupId>
    <artifactId>quarkus-zeebe</artifactId>
    <version>{version}</version>
</dependency>

Upgrade

In version >0.7.0 we removed the hazelcast dependency and zeebe-simple-monitor for test and dev services. Now we do use zeebe-test-container with debug exporter and zeebe-dev-monitor. In test module we remove our assert API and switch to Camunda BpmnAssert from zeebe-process-test.

API migration

0.6.x	0.7.x
io.quarkiverse.zeebe.test.BpmnAssert	io.camunda.zeebe.process.test.assertions.BpmnAssert

Configuration

Build configuration

# enable auto load bpmn resources true|false
quarkus.zeebe.resources.enabled=true
# src/main/resources/bpmn 
quarkus.zeebe.resources.location=bpmn
# enable health check true|false
quarkus.zeebe.health.enabled=false
# enable opentracing true|false
quarkus.zeebe.opentracing.enabled=true
# enable opentelemetry true|false
quarkus.zeebe.opentelemetry.enabled=true

Runtime configuration

# broker configuration
quarkus.zeebe.client.broker.gateway-address=localhost:26500
quarkus.zeebe.client.broker.keep-alive=PT45S
# cloud configuration
quarkus.zeebe.client.cloud.cluster-id=
quarkus.zeebe.client.cloud.client-id=
quarkus.zeebe.client.cloud.client-secret=
quarkus.zeebe.client.cloud.region=bru-2
quarkus.zeebe.client.cloud.base-url=zeebe.camunda.io
quarkus.zeebe.client.cloud.auth-url=https://login.cloud.camunda.io/oauth/token
quarkus.zeebe.client.cloud.port=443
quarkus.zeebe.client.cloud.credentials-cache-path=
# worker configuration
quarkus.zeebe.client.worker.max-jobs-active=32
quarkus.zeebe.client.worker.threads=1
quarkus.zeebe.client.worker.default-name=default
quarkus.zeebe.client.worker.default-type=
# message configuration
quarkus.zeebe.client.message.time-to-live=PT1H
# security configuration
quarkus.zeebe.client.security.plaintext=true
quarkus.zeebe.client.security.cert-path=
# job configuration
quarkus.zeebe.client.job.timeout=PT5M
quarkus.zeebe.client.job.pool-interval=PT0.100S
# overwrite job handler annotation
quarkus.zeebe.client.workers.<type>.name=
quarkus.zeebe.client.workers.<type>.timeout=
quarkus.zeebe.client.workers.<type>.max-jobs-active=
quarkus.zeebe.client.workers.<type>.request-timeout=
quarkus.zeebe.client.workers.<type>.poll-interval=
quarkus.zeebe.client.workers.<type>.fetch-variables=
quarkus.zeebe.client.workers.<type>.exp-backoff-factor=1.6
quarkus.zeebe.client.workers.<type>.exp-jitter-factor=0.1
quarkus.zeebe.client.workers.<type>.exp-max-delay=5000
quarkus.zeebe.client.workers.<type>.exp-min-delay=50
# client tracing configuration
quarkus.zeebe.client.tracing.attributes=bpmn-process-id,bpmn-process-instance-key,bpmn-process-element-id,
bpmn-process-element-instance-key,bpmn-process-def-key,bpmn-process-def-ver,bpmn-retries,bpmn-component,
bpmn-job-type,bpmn-job-key,bpmn-class

Exemplary Setup for your local development

Generally speaking there are three ways to configure your quarkus project to speak with camunda:

• Local dev instance with dev services
• Shared local dev instance
• Direct interaction with Camunda SaaS/ on-premise

You can see some exemplary configurations for each of the setups below. Please note that these are only exemplary and can be adapted to your needs.

Local dev instance with dev services

# enable auto load bpmn resources 
quarkus.zeebe.resources.enabled=true
# src/main/resources/bpmn
quarkus.zeebe.resources.location=bpmn

# Enable Dev-Monitor Dev Service:
quarkus.zeebe.devservices.enabled=true
quarkus.zeebe.devservices.monitor.enabled=true

# Only start devservices, if no running docker container is found
quarkus.zeebe.devservices.shared=true
quarkus.zeebe.devservices.monitor.service-name=zeebe-dev-monitor
quarkus.zeebe.devservices.service-name=zeebe_broker

Shared local dev instance

quarkus.zeebe.client.broker.gateway-address=localhost:26500
# If you are sure that there is already an instance running, yu can directly deactivate it
quarkus.zeebe.devservices.enabled=false
quarkus.zeebe.devservices.shared=true
quarkus.zeebe.devservices.monitor.serviceName=zeebe-dev-monitor
quarkus.zeebe.devservices.serviceName=zeebe_broker

Direct interaction with Camunda live instance

Preferably you would be using a dev instance of Camunda and not your production process engine ;)

# Disable local dev services
quarkus.zeebe.devservices.enabled=false

# Enter your cloud credentials from the zeebe portal
quarkus.zeebe.client.broker.gateway-address=
# cloud configuration
quarkus.zeebe.client.cloud.cluster-id=
quarkus.zeebe.client.cloud.client-id=
quarkus.zeebe.client.cloud.client-secret=
quarkus.zeebe.client.cloud.region=
quarkus.zeebe.client.cloud.base-url=zeebe.camunda.io
quarkus.zeebe.client.cloud.auth-url=https://login.cloud.camunda.io/oauth/token
quarkus.zeebe.client.cloud.port=443

# Make sure you are disabling plaintext security, otherwise connection will fail
quarkus.zeebe.client.security.plaintext=false

Tracing

Whether zeebe tracing is enabled or not is done by quarkus.zeebe.tracing.enabled build time property. The default is true, but shown here to indicate how it can be disabled.

quarkus.zeebe.tracing.enabled=true

OpenTelemetry

If you already have your Quarkus project configured, you can add the quarkus-opentelemetry-exporter-otlp extension to your project.

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry-exporter-otlp</artifactId>
</dependency>

Zeebe example
Quarkus OpenTelemetry

OpenTracing

If you already have your Quarkus project configured, you can add the smallrye-opentracing extension to your project.

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-opentracing</artifactId>
</dependency>

Zeebe example
Quarkus OpenTracing

Dev-Services

Dev Services for Zeebe is automatically enabled unless:

• quarkus.zeebe.devservices.enabled is set to false
• quarkus.zeebe.broker.gateway-address is configured

Dev Service for Zeebe relies on Docker to start the broker. If your environment does not support Docker, you will need to start the broker manually, or connect to an already running broker. You can configure the broker address using quarkus.zeebe.broker.gateway-address.

To activate Zeebe-Dev-Monitor Dev Service use this configuration:

quarkus.zeebe.devservices.enabled=true
quarkus.zeebe.devservices.monitor.enabled=true

Property qquarkus.zeebe.devservices.monitor.enabled=true will activate the debug exporter.

Configuration

quarkus.zeebe.devservices.enabled=true|false
quarkus.zeebe.devservices.port=
quarkus.zeebe.devservices.shared=true
quarkus.zeebe.devservices.service-name=zeebe
quarkus.zeebe.devservices.image-name=
# zeebe dev monitor dev-service
quarkus.zeebe.devservices.monitor.enabled=true|false
quarkus.zeebe.devservices.monitor.port=
quarkus.zeebe.devservices.monitor.image-name=ghcr.io/lorislab/zeebe-dev-monitor:1.0.0
quarkus.zeebe.devservices.monitor.service-name=zeebe-dev-monitor

Simple usage

@ZeebeWorker(type = "job1")
public class Job1 implements JobHandler {

    @Override
    public void handle(JobClient client, ActivatedJob job) throws Exception {
        Parameter p = job.getVariablesAsType(Parameter.class);
        client.newCompleteCommand(job.getKey())
                .variables(p).send().join();
    }
}

Testing

To use the test extension, add this dependency to the project:

<dependency>
    <groupId>io.quarkiverse.zeebe</groupId>
    <artifactId>quarkus-zeebe-test</artifactId>
    <version>{version}</version>
    <scope>test</scope>
</dependency>

To use the ZeebeClient and BpmnAssert in the tests use the @QuarkusTestResource(ZeebeTestResource.class) and enable this configuration:

quarkus.zeebe.devservices.enabled=true

Test example

import io.quarkiverse.zeebe.test.ZeebeTestResource;
import io.quarkus.test.common.QuarkusTestResource;
import io.camunda.zeebe.client.ZeebeClient;

@QuarkusTest
@QuarkusTestResource(ZeebeTestResource.class)
public class BaseTest extends AbstractTest {

    @InjectZeebeClient
    ZeebeClient client;

    @Test
    public void startProcessTest() {
        ProcessInstanceEvent event = client.newCreateInstanceCommand()
                .bpmnProcessId("test").latestVersion()
                .variables(Map.of("k","v")).send().join();

        ProcessInstanceAssert a = BpmnAssert.assertThat(event);
        await().atMost(7, SECONDS).untilAsserted(a::isCompleted);
    }
}

We can reuse the test for the integration test.

import io.quarkus.test.junit.QuarkusIntegrationTest;

@QuarkusIntegrationTest
public class BaseIT extends BaseTest {

}

For more information check examples in the integration-tests directory in this repo.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Andrej Petras 💻 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!