Introduction and Quick‑Start Guide to the Flowable Workflow Engine

1. Introduction

When approval processes become complex, manual handling increases development cost and business complexity; a workflow engine like Flowable reduces these issues by providing visual modeling, automated execution, and flexible condition handling.

2. Technology Selection

Among popular workflow engines (Activiti, Flowable, Camunda), Flowable is chosen for its active community, performance focus, and extensibility, making it suitable for high‑throughput, multi‑node approval scenarios.

3. Flowable Engine Overview

3.1 Basic Elements

Process Definition : BPMN 2.0 model describing the sequence and logic of a business process.

Process Instance : A concrete execution of a process definition, identified by a unique ID.

Task : Work unit (user, service, script, etc.) that must be completed by a participant.

Gateway : Controls conditional branching and merging (exclusive, parallel, etc.).

Execution : Represents the runtime state of a process, including current node and variables.

Variable : Data stored and passed between nodes, dynamically managed by Flowable.

Listener : Hooks into lifecycle events such as start, end, or task assignment.

3.2 API Overview

RepositoryService : Deploy, delete, query process definitions and resources.

RuntimeService : Start, suspend, terminate process instances; manage variables.

TaskService : Create, claim, complete, and query tasks.

IdentityService : Manage users, groups, and memberships.

HistoryService : Query historical data of process instances and tasks.

ManagementService : Low‑level operations such as table creation and engine configuration.

3.3 System Tables

Flowable automatically creates runtime tables (ACT_RU_*) and history tables (ACT_HI_*). Key tables include:

Table Name

Meaning

ACT_HI_PROCINST

Historical process instance information.

ACT_HI_TASKINST

Historical task instance information.

ACT_HI_VARIABLE

Historical process variables.

ACT_RU_EXECUTION

Current execution instances.

ACT_RU_TASK

Current tasks.

ACT_RU_VARIABLE

Runtime variables.

Applications often add custom business tables (e.g., work‑order, approval‑node) to store domain‑specific state.

4. BPMN 2.0 Modeling

4.1 BPMN 2.0 Specification

BPMN 2.0 provides a standardized graphical notation for business processes, supporting rich elements, gateways, sub‑processes, and extensibility, and integrates seamlessly with execution engines like Flowable.

4.2 Drawing the Diagram

The Flowable UI (a Spring Boot‑based application) can be started with:

java -jar flowable-ui.war

After launching, the Modeler allows creation of a simple process, assignment of user tasks, and export of the diagram as an XML file.

5. Quick Start

5.1 Import Starter

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

5.2 Deploy Model

@Test
public void createConfig() throws Exception {
    File file = new File("/Users/xxx/Documents/flowbale/model/testModel.bpmn20.xml");
    FileInputStream fileInputStream = new FileInputStream(file);
    Deployment deploy = repositoryService.createDeployment()
        .addInputStream("testModel.bpmn20.xml", fileInputStream)
        .tenantId("业务线ID，用于数据隔离")
        .name("testModel")
        .deploy();
    System.out.println("id=" + deploy.getId());
}

5.3 Query Process Definition

@Test
public void getProcessDefinition() {
    ProcessDefinition pd = repositoryService.createProcessDefinitionQuery()
        .processDefinitionKey("testModel")
        .orderByProcessDefinitionVersion().desc()
        .list().get(0);
    System.out.println(pd);
}

5.4 Create Approval Work‑Order

Map
variableMap = new HashMap<>();
variableMap.put("testUserList", Lists.newArrayList("nick","jack","tony"));
String processDefinitionKey = "testModel";
Long businessId = 1L;
String tenantId = "1001";
runtimeService.startProcessInstanceByKeyAndTenantId(processDefinitionKey, businessId + "", variableMap, tenantId);

5.5 Retrieve Pending Tasks

List
taskList = taskService.createTaskQuery()
    .taskAssignee("jack")
    .list();

5.6 Approve Task

Map
variableMap = new HashMap<>();
variableMap.put("flag", 1); // 1 = approve, 0 = reject
taskService.complete(taskId, variableMap);

5.7 Event Listener

Flowable provides built‑in event listeners; the example below registers a listener for process‑completion events.

package com.zhuanzhuan.workflow_engine.config;

import org.flowable.common.engine.api.delegate.event.FlowableEngineEventType;
import org.flowable.common.engine.api.delegate.event.FlowableEventDispatcher;
import org.flowable.spring.SpringProcessEngineConfiguration;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.ApplicationListener;
import org.springframework.context.event.ContextRefreshedEvent;
import org.springframework.context.annotation.Configuration;

@Configuration
public class FlowableListenerConfiguration implements ApplicationListener
{
    @Autowired
    private SpringProcessEngineConfiguration configuration;
    @Autowired
    private ProcessEndListener processEndListener;
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        FlowableEventDispatcher dispatcher = configuration.getEventDispatcher();
        dispatcher.addEventListener(processEndListener, FlowableEngineEventType.PROCESS_COMPLETED);
    }
}

package com.zhuanzhuan.workflow_engine.listener;

import org.flowable.common.engine.api.delegate.event.FlowableEvent;
import org.flowable.engine.delegate.event.impl.FlowableEntityEventImpl;
import org.springframework.stereotype.Component;

@Component
public class ProcessEndListener implements FlowableEventListener {
    @Override
    public void onEvent(FlowableEvent flowableEvent) {
        // Send MQ message or notify the initiator when the process ends
    }
    @Override
    public boolean isFailOnException() { return true; }
    @Override
    public boolean isFireOnTransactionLifecycleEvent() { return true; }
    @Override
    public String getOnTransaction() { return TransactionState.COMMITTED.name(); }
}

6. Summary

The Flowable engine offers a powerful, extensible platform for building approval workflows; developers can integrate user groups, permission modules, asynchronous tasks, and custom business tables as needed, tailoring the architecture to specific project requirements.

7. References

1. Flowable official documentation: https://www.flowable.org/documentation.html 2. Technology selection discussion: https://www.zhihu.com/question/59274016/answer/2398240513