Getting started

This project allows you to leverage Zeebe APIs (gRPC and REST) in your Spring Boot project. Later on, we’ll expand the Spring Zeebe SDK to deliver a Camunda Spring SDK that provides a unified experience for interacting with all Camunda APIs in Java Spring.

Version compatibility

Camunda Spring SDK version	JDK	Camunda version	Bundled Spring Boot version
8.5.x	>= 17	8.5.x	3.2.x

Add the Spring Zeebe SDK to your project

Add the following repository and Maven dependency to your Spring Boot Starter project:

<repositories>
    <repository>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>identity</id>
        <name>Camunda Identity</name>
        <url>https://artifacts.camunda.com/artifactory/camunda-identity/</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.camunda</groupId>
    <artifactId>spring-boot-starter-camunda-sdk</artifactId>
    <version>8.5.0</version>
</dependency>

Enable the Java Compiler -parameters-flag

If you don't want to specify annotation values just as the process variable name on the variable annotation, the Java compiler flag -parameters is required.

If you are using Maven you can enable this with the Compiler plugin:

<build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <compilerArgs>
            <arg>-parameters</arg>
          </compilerArgs>
        </configuration>
      </plugin>
    </plugins>
  </build>

If you are using Gradle:

tasks.withType(JavaCompile) {
    options.compilerArgs << '-parameters'
}

If you are using IntelliJ:

Settings > Build, Execution, Deployment > Compiler > Java Compiler

Configuring the Camunda 8 connection

The default properties for setting up all connection details are hidden in modes. Each connection mode has particular defaults to ease configuration.

The mode is set on camunda.client.mode and can be self-managed or saas. Further usage of each mode is explained below.

note

Zeebe will now also be configured with a URL (http://localhost:26500 instead of localhost:26500 + plaintext connection flag).

Saas

Connections to Camunda SaaS can be configured by creating the following entries in src/main/resources/application.yaml:

camunda:
  client:
    mode: saas
    auth:
      client-id: <your client id>
      client-secret: <your client secret>
    cluster-id: <your cluster id>
    region: <your cluster region>

Self-Managed

If you set up a Self-Managed cluster with Identity, Keycloak is used as the default Identity provider. As long as the port config (from Docker Compose or port-forward with Helm charts) is the default, you must configure the accompanying Spring profile and client credentials:

camunda:
  client:
    mode: self-managed
    auth:
      client-id: <your client id>
      client-secret: <your client secret>
      issuer: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token

If you have different endpoints for your applications or want to disable a client, configure the following:

camunda:
  client:
    mode: self-managed
    tenant-ids:
      - <default>
    auth:
      client-id: <your client id>
      client-secret: <your client secret>
      issuer: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
    zeebe:
      enabled: true
      grpc-address: http://localhost:26500
      rest-address: http://localhost:8080
      prefer-rest-over-grpc: false
      audience: zeebe-api

Obtain the Zeebe client

You can inject the Zeebe client and work with it to create new workflow instances, for example:

@Autowired
private ZeebeClient client;

Deploy process models

Use the @Deployment annotation:

@SpringBootApplication
@Deployment(resources = "classpath:demoProcess.bpmn")
public class MySpringBootApplication {

This annotation internally uses the Spring resource loader mechanism. This is powerful, and can also deploy multiple files at once, for example:

@Deployment(resources = {"classpath:demoProcess.bpmn" , "classpath:demoProcess2.bpmn"})

Or, define wildcard patterns:

@Deployment(resources = "classpath*:/bpmn/**/*.bpmn")

Implement the job worker

@JobWorker(type = "foo")
public void handleJobFoo(final ActivatedJob job) {
  // do whatever you need to do
}

See the configuration documentation for a more in-depth discussion on parameters and configuration options for job workers.