Skip to main content
Version: 8.8 (unreleased)

Getting started

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

Version compatibility​

Camunda Spring Boot SDK versionJDKCamunda versionBundled Spring Boot version
8.7.x≥ 178.7.x3.4.x
8.8.x≥ 178.8.x3.4.x

Add the Camunda Spring Boot 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.8.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 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.

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>
    cloud:
      cluster-id: <your cluster id>
      region: <your cluster region id>

Self-Managed​

note

Camunda is configured with URLs (http://localhost:26500 instead of localhost:26500 + plaintext connection flag).

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>

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

camunda:
  client:
    mode: self-managed
    tenant-id: <default>
    auth:
      client-id: <your client id>
      client-secret: <your client secret>
      token-url: https://my-keycloak/auth/realms/camunda-platform/protocol/openid-connect/token
    grpc-address: https://my-grpc-address
    rest-address: https://my-rest-address

Obtain the Camunda client​

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

@Autowired
private CamundaClient 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​

To implement a job worker, you need to declare a method like this on a bean:

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

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

Writing test cases​

To learn more about writing test cases using Zeebe Process Test, see Camunda Spring Boot SDK integration.