Integrating Camunda 7 Workflow Engine into a Spring Boot Application

Concept

Process (PROCESS) : BPMN file defines the whole process.

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

Variables : Parameters passed between tasks.

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

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

Core Components

Process Engine – the engine that executes processes.

Web Applications – web UI for management.

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>

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

Database Tables

Camunda creates several groups of tables after startup:

ACT_ID_* – user module tables.

ACT_HI_* – historical data (process, task, variable).

ACT_RE_* – process definitions and deployments.

ACT_RU_* – runtime data (instances, tasks, variables).

ACT_GE_* – binary data of deployed resources.

Login & Console

Login URL: http://localhost:8081/ (admin / 123456). After login the Camunda Cockpit and Tasklist are available.

Modeling a Process

Use Camunda Modeler to create a BPMN diagram, save it as test_1.bpmn, and place it under src/main/resources/bpmn. The diagram is automatically deployed on application start.

Task Types

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

Service Task – executed automatically by the engine.

Gateways

Exclusive Gateway – only the first matching outgoing flow is taken.

Parallel Gateway – all outgoing flows are taken.

Inclusive Gateway – one or more matching flows are taken.

Development Example

Controller and service snippets illustrate how to start a process, query definitions, and complete tasks:

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

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

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

API Usage

Process API

Start: runtimeService.startProcessInstanceByKey(key, params) Suspend: runtimeService.suspendProcessInstanceById(id) Activate: runtimeService.activateProcessInstanceById(id) Delete:

runtimeService.deleteProcessInstance(id, "reason")

Task API

Query tasks:

taskService.createTaskQuery().taskAssignee("zhangsan").list()

Historic tasks: historyService.createHistoricTaskInstanceQuery().list() Rollback example (simplified):

Task active = taskService.createTaskQuery().taskId(taskId).active().singleResult();
List<HistoricTaskInstance> history = historyService.createHistoricTaskInstanceQuery()
    .processInstanceId(instanceId)
    .orderByHistoricActivityInstanceStartTime()
    .desc()
    .list();
// modify process instance to jump back to a previous activity
runtimeService.createProcessInstanceModification(instanceId)
    .cancelAllForActivity(active.getTaskDefinitionKey())
    .startBeforeActivity(previousTaskKey)
    .execute();

Variables

Set a variable:

runtimeService.setVariable(instanceId, "PATIENT_ID", value);

Get a variable:

Object v = runtimeService.getVariable(instanceId, "GENERAL_ID");

Historic variable query:

HistoricVariableInstance var = historyService.createHistoricVariableInstanceQuery()
    .processInstanceId(instanceId)
    .variableName("PATIENT_ID")
    .singleResult();
Object value = var.getValue();

Task Listener

TaskListener t21 = delegateTask -> {
    String taskId = delegateTask.getId();
    Map<String, Object> vars = delegateTask.getVariables();
    delegateTask.setVariable("key", "value");
};

Execution Listener

public class ExampleExecutionListenerOne 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 and accessed in listeners or delegates to store business‑specific data such as process progress.

Identity Service

Set the authenticated user for audit information:

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

Conclusion

The article provides a complete walkthrough for adding Camunda 7 to a Spring Boot project, covering Maven setup, configuration, database schema, BPMN modeling, task handling, listeners, and variable management, enabling developers to build robust workflow‑driven applications.