Integrating Camunda 7 Workflow Engine with Spring Boot: Concepts, Configuration, and API Usage

Introduction

The project requires a workflow engine to design business processes, and Camunda 7 is selected. This guide focuses on integrating Camunda with an existing Spring Boot application and demonstrates core usage and configuration.

Concepts

Process (PROCESS) : BPMN file defining the whole workflow.

Process Instance (Instance) : Runtime instance after the process starts.

Variables : Parameters passed between tasks.

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

Process Deployment : Deploying the .bpmn file to the engine.

Core Components

Process Engine – the engine that executes processes.

Web Applications – web‑based management UI.

API Overview

Official documentation: Camunda Process Engine API

Spring Boot Integration

Dependency Integration

Maven dependencies (Camunda starter, REST starter, and webapp starter) are required. Example:

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

The database used is MySQL; a new schema (e.g., camunda ) will be created automatically.

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>
        ... (Camunda and MySQL dependencies as shown above) ...
    </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 login configuration
camunda.bpm:
  admin-user:
    id: admin
    password: 123456
    firstName: yu
  filter:
    create: All tasks

# MySQL connection
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

Startup Result

After starting the application, the Camunda web UI is accessible at http://localhost:8081/ with the admin credentials defined above.

Database Tables

Camunda automatically creates tables such as ACT_ID_* (user data), ACT_HI_* (history), ACT_RE_* (resources), ACT_RU_* (runtime), and ACT_GE_* (generic data).

Business Integration

Modeling Process Diagrams

Use Camunda Modeler (download from Camunda Modeler ) to create .bpmn files, then place them under src/main/resources/bpmn . The example models an OA approval flow.

Task Types

User Task – requires manual completion via taskService.complete(taskId, variables);

Service Task – executed automatically by the engine.

Gateways

Camunda supports exclusive, parallel, and inclusive gateways to control flow based on variables.

Example Service Code

public void startProcess() {
    ProcessInstance instance = runtimeService.startProcessInstanceByKey("key");
    System.out.println(instance);
}

public List
findProcesses() {
    return repositoryService.createProcessDefinitionQuery().list();
}

public List
findTasks() {
    return taskService.createTaskQuery().list();
}

API Usage

Process‑related API

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

Task‑related API

List
list = repositoryService.createProcessDefinitionQuery().list();
List
list = taskService.createTaskQuery().taskAssignee("zhangsan").list();
List
instances = runtimeService.createProcessInstanceQuery().listPage(1, 10);
List
hist = historyService.createHistoricProcessInstanceQuery().list();
List
tasks = taskService.createTaskQuery().orderByTaskCreateTime().desc().list();

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();

Listeners

Task Listener example:

TaskListener t21() {
    return delegateTask -> {
        String taskId = delegateTask.getId();
        // custom logic
        delegateTask.setVariable("", "");
    };
}

Execution Listener example:

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

Extension Properties

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

Identity Service & Permissions

Set the authenticated user for process start:

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

Assign task owners:

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

The article concludes with a call for discussion and provides links to additional resources.