Master Camunda 7 Integration with Spring Boot: A Step‑by‑Step Guide

Introduction

The project requires a workflow engine; Camunda 7 was chosen. This guide focuses on integrating Camunda with an existing Spring Boot application and its configuration.

Concepts

Process (PROCESS) : BPMN file defining the workflow.

Process Instance (Instance) : A running instance of a process.

Variables : Parameters passed between tasks.

Task (TASK) : Each node defined in the workflow.

Deployment : Deploying the .bpmn file to the engine.

Core Components

Process Engine : Executes the workflow.

Web Applications : Web‑based management UI.

API Overview

Official documentation:

https://docs.camunda.org/manual/7.18/user-guide/process-engine/process-engine-api/

Spring Boot Integration

Dependencies

<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter</artifactId>
  <version>7.18.0</version>
</dependency>
<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-rest</artifactId>
  <version>7.18.0</version>
</dependency>
<dependency>
  <groupId>org.camunda.bpm.springboot</groupId>
  <artifactId>camunda-bpm-spring-boot-starter-webapp</artifactId>
  <version>7.18.0</version>
</dependency>

Database

MySQL is used; a new database named camunda is created and tables are generated automatically on startup.

POM File

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.3</version>
  </parent>
  <groupId>com.example</groupId>
  <artifactId>camunda-demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <properties>
    <java.version>17</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
      <groupId>org.camunda.bpm.springboot</groupId>
      <artifactId>camunda-bpm-spring-boot-starter</artifactId>
      <version>7.18.0</version>
    </dependency>
    <dependency>
      <groupId>org.camunda.bpm.springboot</groupId>
      <artifactId>camunda-bpm-spring-boot-starter-rest</artifactId>
      <version>7.18.0</version>
    </dependency>
    <dependency>
      <groupId>org.camunda.bpm.springboot</groupId>
      <artifactId>camunda-bpm-spring-boot-starter-webapp</artifactId>
      <version>7.18.0</version>
    </dependency>
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
      <version>8.0.32</version>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

application.yml

server:
  port: 8081

camunda.bpm:
  admin-user:
    id: admin
    password: 123456
    firstName: yu
  filter:
    create: All tasks

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:8101/camunda
    username: root
    password: 123456
    type: com.mysql.cj.jdbc.MysqlDataSource

Running the Application

After starting, the Camunda web UI is available at http://localhost:8081/ with the admin credentials defined above. The console shows the deployed processes and generated database tables such as ACT_ID_*, ACT_HI_*, ACT_RU_*, and ACT_GE_*.

Business Integration

Modeling a Process

Use Camunda Modeler to create a BPMN file (e.g., test_1.bpmn) and place it under src/main/resources/bpmn. After restarting, the process appears in the web UI.

Task Types

User Task : Requires manual completion via taskService.complete(taskId, variables).

Service Task : Executed automatically by the engine.

Gateways

Exclusive Gateway : Only one outgoing path is taken.

Parallel Gateway : All outgoing paths are taken.

Inclusive Gateway : One or more matching paths are taken.

API Usage

Process API

ProcessInstance instance = runtimeService.startProcessInstanceByKey(processKey, params);
runtimeService.suspendProcessInstanceById(instance.getId());
runtimeService.activateProcessInstanceById(instance.getId());
runtimeService.deleteProcessInstance(instance.getId(), "manual delete");

Task API

List<ProcessDefinition> list = repositoryService.createProcessDefinitionQuery().list();
List<Task> list = taskService.createTaskQuery().taskAssignee("zhangsan").list();
List<ProcessInstance> instances = runtimeService.createProcessInstanceQuery().listPage(1, 10);
List<HistoricProcessInstance> hist = historyService.createHistoricProcessInstanceQuery().list();
List<Task> tasks = taskService.createTaskQuery().orderByTaskCreateTime().desc().list();
// Task rollback example
Task activeTask = taskService.createTaskQuery().taskId(taskId).active().singleResult();
List<HistoricTaskInstance> historic = historyService.createHistoricTaskInstanceQuery()
    .processInstanceId(instanceId)
    .orderByHistoricActivityInstanceStartTime().desc()
    .list();
HistoricTaskInstance curr = historic.stream()
    .filter(v -> !v.getTaskDefinitionKey().equals(activeTask.getTaskDefinitionKey()))
    .findFirst().orElseThrow(() -> new IllegalStateException("Already at initial task"));
runtimeService.createProcessInstanceModification(instanceId)
    .cancelAllForActivity(activeTask.getTaskDefinitionKey())
    .setAnnotation("re‑execute")
    .startBeforeActivity(curr.getTaskDefinitionKey())
    .execute();

Process Variables

runtimeService.setVariable(instance.getId(), "PATIENT_ID", relatedId);
Object var = runtimeService.getVariable(instance.getId(), "GENERAL_ID");
HistoricVariableInstance histVar = historyService.createHistoricVariableInstanceQuery()
    .processInstanceId(instance.getId())
    .variableName("PATIENT_ID")
    .singleResult();
String value = (String) histVar.getValue();

Task & Execution Listeners

Listeners can be defined as beans and attached to tasks or executions to run custom Java code or EL expressions.

@Bean
TaskListener t21() {
  return delegateTask -> {
    String taskId = delegateTask.getId();
    String instanceId = delegateTask.getProcessInstanceId();
    Map<String, Object> vars = delegateTask.getVariables();
    // custom logic
    delegateTask.setVariable("key", "value");
  };
}

public class ExampleExecutionListener implements ExecutionListener {
  @Override
  public void notify(DelegateExecution execution) {
    execution.setVariable("variableSetInExecutionListener", "firstValue");
    execution.setVariable("eventReceived", execution.getEventName());
  }
}

Extension Properties

Custom properties can be added to BPMN elements to store business‑specific data such as progress percentages.

Identity Service

Camunda’s IdentityService can set the authenticated user for audit purposes:

identityService.setAuthenticatedUserId(UserUtil.getUserId().toString());
Authentication auth = identityService.getCurrentAuthentication();

Assigning Task Owner and Assignee

taskService.setAssignee(task.getId(), UserUtil.getUserId().toString());

The guide concludes with a preview of the next article that will cover detailed business integration and advanced API usage.