Skip to main content
Version: 8.5

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 versionJDKCamunda versionBundled Spring Boot version
8.5.x>= 178.5.x3.2.x

Add the Spring Zeebe SDK to your project

Add the following Maven dependency to your Spring Boot Starter project, replacing x with the latest patch level available:

<dependency>
<groupId>io.camunda</groupId>
<artifactId>spring-boot-starter-camunda-sdk</artifactId>
<version>8.5.x</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 Zeebe cluster connection

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

zeebe.client.cloud.clusterId=xxx
zeebe.client.cloud.clientId=xxx
zeebe.client.cloud.clientSecret=xxx
zeebe.client.cloud.region=bru-2

You can also configure the connection to a Self-Managed Zeebe broker:

zeebe.client.cloud.clientId=xxx
zeebe.client.cloud.clientSecret=xxx
zeebe.client.cloud.authUrl=xxx
zeebe.client.broker.grpcAddress=xxx
zeebe.client.broker.restAddress=xxx
zeebe.client.security.plaintext=true

Example of configuring the connection to a Self-Managed Zeebe cluster:

zeebe.client.cloud.clientId=your-client-id
zeebe.client.cloud.clientSecret=your-client-secret
zeebe.client.cloud.authUrl=http://localhost:18080/auth/realms/your-realm/protocol/openid-connect/token
zeebe.client.broker.grpcAddress=http://localhost:26500
zeebe.client.broker.restAddress=http://localhost:8080
zeebe.client.security.plaintext=true
note

The zeebe.client.cloud.authUrl property above is the Keycloak token endpoint.

You can also configure the connection to a Self-Managed Zeebe cluster using environment variables and specifying your gateway address:

Environment variable to be set using this approach:

ZEEBE_AUTHORIZATION_SERVER_URL=xxx
ZEEBE_CLIENT_ID=xxx
ZEEBE_CLIENT_SECRET=xxx

Example environment variables to be set to configure gRPC and REST connection:

ZEEBE_GRPC_ADDRESS=http://127.0.0.1:26500/
ZEEBE_REST_ADDRESS=http://127.0.0.1:8080/

Properties to be set using this approach:

zeebe.client.broker.gateway-address=http://127.0.0.1:26500
zeebe.client.security.plaintext=true

You can enforce the right connection mode, for example if multiple contradicting properties are set:

zeebe.client.connection-mode=CLOUD
zeebe.client.connection-mode=ADDRESS

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 of job workers.