Skip to main content

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​

Spring Zeebe SDK versionJDKCamunda versionBundled Spring Boot version
8.5.x (< 8.5.16)≥ 178.5.x3.2.x
8.5.x (>= 8.5.16, < 8.5.18)≥ 178.5.x3.3.x
8.5.x (>= 8.5.18)≥ 178.5.x3.4.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.

note

Ensure you provide grpcAddress and restAddress in absolute URI format: scheme://host(:port).

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

Configuring OAuth Scope (Optional)​

The OAuth scope can be configured via the following client environment variable only:

ZEEBE_TOKEN_SCOPE=xxx

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.