Guide to Setting Up and Using the Flowable Workflow Engine with Spring Boot

Today we share a practical workflow engine called Flowable and demonstrate how to set it up and use it in a Spring Boot backend project.

1. Deploy Flowable UI

Download Flowable 6.6.0 from https://github.com/flowable/flowable-engine/releases/download/flowable-6.6.0/flowable-6.6.0.zip , extract flowable-6.6.0\wars\flowable-ui.war , and drop the WAR into Tomcat. Access http://localhost:8080/flowable-ui and log in with the default account admin/test .

2. Design BPMN Diagram

Use the Flowable UI > APP.MODELER to draw a simple leave‑approval process. The diagram includes events, sequence flows, gateways, and user tasks (Student, Teacher, Principal). The process flow is: start → Student → Teacher → Gateway (agree/reject) → Principal → end.

3. Database Tables

Flowable creates tables prefixed with ACT_ . Key prefixes are:

ACT_RE_ : repository (static) data such as process definitions.

ACT_RU_ : runtime data (process instances, tasks, variables).

ACT_HI_ : historic data (completed instances, tasks).

ACT_GE_ : generic data (byte arrays, properties).

Relevant tables include act_ge_bytearray , act_hi_procinst , act_ru_task , act_id_user , etc.

4. Backend Project Setup

Create a Spring Boot project (JDK 8) with the following pom.xml dependencies:

<dependency>
    <groupId>org.flowable</groupId>
    <artifactId>flowable-spring-boot-starter</artifactId>
    <version>6.6.0</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>5.1.45</version>
</dependency>

Configure the datasource in application.yml :

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/flowable?useSSL=false&characterEncoding=UTF-8&serverTimezone=GMT%2B8
    driver-class-name: com.mysql.jdbc.Driver
    username: root
    password: 123456

5. Flowable API and Services

The main services are RepositoryService, RuntimeService, IdentityService, TaskService, HistoryService, etc. The following Java example shows how to deploy a ZIP, start a process, claim and complete tasks, and query historic data:

import lombok.extern.slf4j.Slf4j;
import org.flowable.engine.*;
import org.flowable.engine.history.HistoricProcessInstance;
import org.flowable.engine.repository.Deployment;
import org.flowable.engine.repository.ProcessDefinition;
import org.flowable.engine.runtime.Execution;
import org.flowable.engine.runtime.ProcessInstance;
import org.flowable.idm.api.Group;
import org.flowable.idm.api.User;
import org.flowable.task.api.Task;
import org.flowable.task.api.history.HistoricTaskInstance;
import org.springframework.beans.factory.annotation.Autowired;

@Slf4j
public class TestFlowable {
    @Autowired private RepositoryService repositoryService;
    @Autowired private RuntimeService runtimeService;
    @Autowired private HistoryService historyService;
    @Autowired private org.flowable.engine.TaskService taskService;
    @Autowired private org.flowable.engine.IdentityService identityService;

    public void createDeploymentZip() {
        try {
            File zipTemp = new File("f:/leave_approval.bpmn20.zip");
            ZipInputStream zipInputStream = new ZipInputStream(new FileInputStream(zipTemp));
            Deployment deployment = repositoryService.createDeployment()
                .addZipInputStream(zipInputStream)
                .deploy();
            log.info("部署成功:{}", deployment.getId());
        } catch (FileNotFoundException e) { e.printStackTrace(); }

        List
list = repositoryService.createProcessDefinitionQuery()
            .processDefinitionKey("leave_approval").list();

        String processDefinitionKey = "leave_approval";
        String businessKey = "schoolleave";
        Map
variablesDefinition = new HashMap<>();
        ProcessInstance processInstance = runtimeService.startProcessInstanceByKey(
            processDefinitionKey, businessKey, variablesDefinition);
        log.info("启动成功:{}", processInstance.getId());

        // Student task
        List
taskList = taskService.createTaskQuery()
            .taskCandidateGroup("stu_group").orderByTaskCreateTime().desc().list();
        for (Task task : taskList) {
            taskService.claim(task.getId(), "my");
            taskService.complete(task.getId());
        }

        // Teacher task with decision variable
        List
taskListTe = taskService.createTaskQuery()
            .taskCandidateGroup("te_group").orderByTaskCreateTime().desc().list();
        for (Task task : taskListTe) {
            taskService.claim(task.getId(), "myte");
            Map
vars = new HashMap<>();
            vars.put("command", "agree");
            taskService.complete(task.getId(), vars);
        }

        // Historic queries
        List
historicProcessList = historyService
            .createHistoricProcessInstanceQuery()
            .processDefinitionKey("leave_approval").list();
        List
historicTaskList = historyService
            .createHistoricTaskInstanceQuery()
            .processDefinitionKey("leave_approval").list();
    }
}

Additional APIs allow moving tasks, changing activity states, and querying users/groups when they are stored in the database.

6. References

Flowable documentation (Chinese translation): https://github.com/qiudaoke/flowable-userguide

Official demo and community articles linked throughout the guide.

The article concludes with promotional messages and QR codes, but the technical content above provides a complete, reproducible workflow‑engine setup for Java backend developers.