Integrating Flowable Workflow Engine with Spring Boot: A Comprehensive Guide

The article begins with a brief history of Java workflow engines, noting that jBPM was the original engine created by Tom Baeyens, which later led to the forked projects Activiti, Camunda, and Flowable. It highlights the current mainstream engines—Activiti (cloud‑oriented), Flowable (feature‑rich), and Camunda (lightweight with a built‑in BPMN editor).

Key BPMN Concepts

Using a simple leave‑request process as an example, the article explains the four fundamental BPMN elements: events, sequence flows, tasks, and gateways. It describes various task types (receive, send, service, script, user) and gateway types (exclusive, parallel, event, inclusive).

Spring Boot Integration

Step 1: Create a Spring Boot project and add the Flowable starter dependency.

<dependency>
    <groupId>org.flowable</groupId>
    <artifactId>flowable-spring-boot-starter</artifactId>
    <version>6.7.2</version>
</dependency>

Step 2: Configure the MySQL datasource in application.yml so that Flowable can create its tables automatically.

spring:
  datasource:
    driverClassName: com.mysql.jdbc.Driver
    url: jdbc:mysql://
host
:
port
/process?useSSL=false&useUnicode=true&characterEncoding=utf-8
    username:
username
password:
password

Step 3: Design the BPMN diagram using the Flowable BPMN visualizer plugin (or the online editor) and place the .bpmn20.xml file under resources/processes . The example file is named ask_for_leave.bpmn20.xml .

The resulting process flow is:

Start event → Employee user task (submit leave request)

Team‑lead user task → Exclusive gateway (approve/reject)

If approved, Manager user task → Exclusive gateway (final approve/reject)

Service task for failure notification → End event

Service Task Implementation

A custom Java class implements JavaDelegate to handle the failure notification.

@Slf4j
@Component
public class LeaveFailService implements JavaDelegate {
    @Override
    public void execute(DelegateExecution delegateExecution) {
        log.info("审批不通过{}", delegateExecution.getCurrentActivityId());
    }
}

Process Diagram Viewing API

The controller provides an endpoint /pic that, given a process instance ID, retrieves the active activity IDs and generates a PNG diagram using Flowable’s ProcessDiagramGenerator . The generated image shows the current position of the workflow.

Unit Tests

Several JUnit tests demonstrate how to start the process, complete tasks for employee, team‑lead, and manager, and set variables such as assignee IDs and approval results.

@SpringBootTest
@Slf4j
@ActiveProfiles("dev")
class ProcessApplicationTests {
    @Autowired RuntimeService runtimeService;
    @Autowired TaskService taskService;
    public static final String yuangongId = "yuangongID_3";
    public static final String zuzhangId = "zuzhangId_3";
    public static final String manageId = "manageId_3";
    @Test
    void askForLeave() {
        HashMap
map = new HashMap<>();
        map.put("leaveTask", yuangongId);
        ProcessInstance pi = runtimeService.startProcessInstanceByKey("ask_for_leave", map);
        runtimeService.setVariable(pi.getId(), "name", "javaboy");
        runtimeService.setVariable(pi.getId(), "reason", "休息一下");
        runtimeService.setVariable(pi.getId(), "days", 10);
        log.info("创建请假流程 processId：{}", pi.getId());
    }
    // Additional tests for submitting, approving, and rejecting omitted for brevity
}

Common Issues

1. Diagram text appears as garbled characters : This occurs when the system lacks a default font. Installing a Chinese font (e.g., SimSun) or configuring Flowable’s font properties resolves the problem.

@Configuration
public class FlowableConfig implements EngineConfigurationConfigurer
{
    @Override
    public void configure(SpringProcessEngineConfiguration cfg) {
        cfg.setActivityFontName("宋体");
        cfg.setLabelFontName("宋体");
        cfg.setAnnotationFontName("宋体");
    }
}

2. Modifying a deployed BPMN file does not affect already running instances : Once a process instance starts, its definition is persisted. Changes only affect new instances.

The article concludes with a promotional note inviting readers to join a community for further discussion and to explore related resources.