micronaut-camunda-external-client

This open source project allows you to easily integrate Camunda 's External Task Clients into Micronaut Framework projects.

The Micronaut Framework is known for its efficient use of resources. With this integration you can easily implement an external client which to process external tasks. If you use GraalVM you have startup times of about 35ms!

The integration is preconfigured with sensible defaults, so that you can get started with minimal configuration: simply add a dependency in your Micronaut project!

If you also want to run the Camunda Workflow Engine on a Micronaut application, have a look at the open source project micronaut-camunda-bpm.

We're not aware of all installations of our Open Source project. However, we love

• listening to your feedback,
• discussing possible use cases with you,
• aligning the roadmap to your needs!

📨 Please contact us!

Do you want to try it out? Please jump to the Getting Started section.

Do you want to contribute to our open source project? Please read the Contribution Guidelines and contact us.

Micronaut Framework + Camunda = ❤️

Table of Contents

• ✨ Features
• 🚀 Getting Started
  • Dependency Management
  • Creating a Client
  • ExternalTaskSubscription Annotation
  • Configuration
  • Examples
  • Supported JDKs
• 🏆 Advanced Topics
  • Customize the External Task Client
  • GraalVM
• 📚 Releases
• 📆 Publications
• 📨 Contact

✨Features

• Camunda external client can be integrated by simply adding a dependency to your project.
• A worker can subscribe to multiple topics.
• The worker's external task client can be configured with properties and programmatically.

🚀Getting Started

This section describes what needs to be done to use micronaut-camunda-external-client-feature in a Micronaut project.

Dependency Management

The Camunda External Worker integration works with both Gradle and Maven, but we recommend using Gradle because it has better Micronaut Support.

You have the following options to integrate the Camunda External Worker integration:

• Create a new Micronaut project using Micronaut Launch and check that the "camunda-external-worker" feature is selected.

• Manually add the dependency to a Micronaut project:

  Click to show Gradle configuration

  Add the dependency to the build.gradle file:

  implementation("info.novatec:micronaut-camunda-external-client-feature:2.10.0")

  Click to show Maven configuration

  Add the dependency to the pom.xml file:

  <dependency>
    <groupId>info.novatec</groupId>
    <artifactId>micronaut-camunda-external-client-feature</artifactId>
    <version>2.10.0</version>
  </dependency>

Note: The module micronaut-camunda-external-client-feature includes the dependency org.camunda.bpm:camunda-external-task-client which will be resolved transitively.

Creating a Client

The minimal configuration requires you to provide a handler for a specific topic and a configuration that points to the Camunda REST API. You can register multiple handlers in this way for different topics. To register a handler you just need to add the annotation ExternalTaskSubscription and specify the topic to listen to. On start of the application the external task client will automatically connect to the specified Camunda REST API and start fetching tasks.

Example configuration in application.yml

camunda.external-client:
  base-url: http://localhost:8080/engine-rest

Example handler:

import info.novatec.micronaut.camunda.external.client.feature.ExternalTaskSubscription;
import jakarta.inject.Inject;
import org.camunda.bpm.client.task.ExternalTask;
import org.camunda.bpm.client.task.ExternalTaskHandler;
import org.camunda.bpm.client.task.ExternalTaskService;

@Singleton
@ExternalTaskSubscription(topicName = "my-topic")
public class ExampleHandler implements ExternalTaskHandler {

    @Override
    public void execute(ExternalTask externalTask, ExternalTaskService externalTaskService) {
        // Put your business logic here
    
        externalTaskService.complete(externalTask);
    }
}

ExternalTaskSubscription Annotation

The annotation accepts the following properties:

Configuration

You may use the following properties (typically in application.yml) to configure the external task client.

You can also configure the subscriptions via configuration with the same properties as the annotation. You can then reference the configuration with the annotation by using the topic name, e.g.:

Important: If you set withOutTenantId = true in the annotation on your handler, you cannot overwrite this property afterwards.

camunda:
  external-client:
    subscriptions:
      my-topic:
        lock-duration: 29000
        variables:
          - variable-one
          - variable-two
        local-variables: true

@Singleton
@ExternalTaskSubscription(topicName = "my-topic")
public class SimpleHandler implements ExternalTaskHandler {
    ...
}

Examples

Here are some example applications:

• Calculation where the server with a BPMN process creates calculations which will be executed by the external task client.
• Internal example application used during development. Remember that you need to start the Camunda Process Application first.

Supported JDKs

We officially support the following JDKs:

• JDK 8 (LTS)
• JDK 11 (LTS)
• JDK 17 (LTS)

🏆Advanced Topics

Customize the External Task Client

With the following bean it is possible to customize the external task client, e.g. to implement custom backoff strategies or register a client request interceptor.

import info.novatec.micronaut.camunda.external.client.feature.ExternalClientCustomizer;
import io.micronaut.context.annotation.Replaces;
import jakarta.inject.Inject;
import org.camunda.bpm.client.ExternalTaskClientBuilder;
import org.camunda.bpm.client.backoff.BackoffStrategy;
import org.camunda.bpm.client.interceptor.ClientRequestInterceptor;

@Singleton
@Replaces(ExternalClientCustomizer.class)
public class MyExternalClientCustomizer implements ExternalClientCustomizer {

    @Override
    public void customize(ExternalTaskClientBuilder builder) {
        // Do your customization here e.g.:
        BackoffStrategy backoffStrategy = ...
        ClientRequestInterceptor interceptor = ...

        builder.backoffStrategy(backoffStrategy)
                .addInterceptor(interceptor);
    }
}

Important: the values set within your customizer have higher priority than the properties set in your configuration file.

GraalVM

With GraalVM you can reduce start-up time and memory usage even more! For example, on a developer environment the start-up time will drop to about 35ms!

The following instructions are based on macOS - other operating systems will probably be similar. Feel free to create a pull request with updated instructions for other operating systems.

Initial Setup

Install the gu executable to be able to install native-image based on instructions: https://www.graalvm.org/docs/getting-started/macos/ which links to https://github.com/graalvm/graalvm-ce-builds/releases

tar -xvf graalvm-ce-java17-darwin-amd64-21.3.0.tar.gz
sudo mv graalvm-ce-java17-21.3.0 /Library/Java/JavaVirtualMachines
/usr/libexec/java_home -V
sudo xattr -r -d com.apple.quarantine /Library/Java/JavaVirtualMachines/graalvm-ce-java17-21.3.0
export PATH=/Library/Java/JavaVirtualMachines/graalvm-ce-java17-21.3.0/Contents/Home/bin:$PATH
gu install native-image
native-image --version

Install GraalVM

Install GraalVM using SDKMAN!:

curl -s "https://get.sdkman.io" | bash
sdk install java 21.3.0.r17-grl

Initialize Environment

sdk use java 21.3.0.r17-grl
export PATH=/Library/Java/JavaVirtualMachines/graalvm-ce-java17-21.3.0/Contents/Home/bin:$PATH
export JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-ce-java17-21.3.0/Contents/Home

Create Reflection Configuration

cd micronaut-camunda-external-client-example
../gradlew clean build
mkdir -p src/main/resources/META-INF/native-image
java -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image -jar build/libs/micronaut-camunda-external-client-example-0.0.1-SNAPSHOT-all.jar

Start the server and cancel the client with Ctrl-C once you see that the client is running when it repeatedly logs Completed external task.

Build Image

The generated reflect-config.json misses three entries (why?) which we add manually:

{
    "name":"org.camunda.bpm.client.variable.impl.format.json.JacksonJsonDataFormatProvider",
    "queryAllPublicMethods":true,
    "methods":[{"name":"<init>","parameterTypes":[] }]
},
{
    "name":"org.camunda.bpm.client.variable.impl.format.serializable.SerializableDataFormatProvider",
    "queryAllPublicMethods":true,
    "methods":[{"name":"<init>","parameterTypes":[] }]
},
{
    "name":"org.camunda.bpm.client.variable.impl.format.xml.DomXmlDataFormatProvider",
    "queryAllPublicMethods":true,
    "methods":[{"name":"<init>","parameterTypes":[] }]
},

Now build the native image - note: this will take a few minutes:

../gradlew clean nativeCompile

Start Native Client

You can then start the external client (Note: Server must be running):

build/native/nativeCompile/micronaut-camunda-external-client-example

The application will be up and processing the first tasks in about 35ms (!):

INFO  io.micronaut.runtime.Micronaut - Startup completed in 33ms. Server Running: http://localhost:8888
INFO  i.n.m.c.e.c.example.SimpleHandler - Completed external task: 47*2=94
INFO  i.n.m.c.e.c.example.SimpleHandler - Completed external task: 22*2=44
INFO  i.n.m.c.e.c.example.SimpleHandler - Completed external task: 48*2=96

📚Releases

The list of releases contains a detailed changelog.

We use Semantic Versioning.

The following compatibility matrix shows the officially supported Micronaut Framework and Camunda versions for each release. Other combinations might also work but have not been tested. The current release of the external client will probably work with a server running on Camunda 7.9.0 and newer.

Download of Releases:

• GitHub Artifacts
• Maven Central Artifacts

📆Publications

• 2021-11: Automating Processes with Camunda and Micronaut)
  Recording of the Novatec Summit by Tobias Schäfer (45 Minutes)
• 2021-07: Automate any Process on Micronaut
  Blogpost by Tobias Schäfer
• 2021-04: The Camunda External Client for Micronaut
  by Tobias Schäfer and Martin Sawilla

📨Contact

If you have any questions or ideas feel free to create an issue or contact us via GitHub Discussions.

We love listening to your feedback, and of course also discussing the project roadmap and possible use cases with you!

This open source project is being developed by envite consulting GmbH and Novatec Consulting GmbH with the support of the open source community.