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 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
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.