Flowable persists all workflow state and process metadata in a relational database. To effectively manage or debug a Flowable integration, its essential to understand the underlying table structure and the mechanisms used to initialize the process engine.

Database Table Naming Conventions

Flowable categorizes its database tables using specific prefixes. This modular approach helps distinguish between static definitions, active instances, and historical records. The database consists of five primary categories:

• ACT_RE (Repository): Contains static resources such as process definitions, deployments, and related metadata like images or rules.
• ACT_RU (Runtime): Stores data for active process instances, including tasks, variables, and job executions. Data is removed from these tables once an instance completes to maintain high performance.
• ACT_HI (History): Holds archived data for completed and ongoing processes, allowing for auditing and analytical reporting on past tasks and variables.
• ACT_GE (General): Used for shared data across various engine components.
• ACT_ID (Identity): Manages organizational structures, including users, groups, and their respective permissions.

Detailed Table Reference

The following table describes the specific purpose of the core tables generated during initialization:

Initializing the Process Engine

The ProcessEngine is the central hub of Flowable. It can be configured using either a programmatic Java API or an external XML configuration file.

Programmatic Configuration

You can define the database connection and engine behavior direct in Java code using the StandaloneProcessEngineConfiguration class:

// Define database connection settings
ProcessEngineConfiguration engineConfig = new StandaloneProcessEngineConfiguration()
    .setJdbcUrl("jdbc:mysql://127.0.0.1:3306/flowable_db?useSSL=false&serverTimezone=UTC")
    .setJdbcUsername("db_user")
    .setJdbcPassword("secure_password")
    .setJdbcDriver("com.mysql.cj.jdbc.Driver")
    .setDatabaseSchemaUpdate(ProcessEngineConfiguration.DB_SCHEMA_UPDATE_TRUE);

// Instantiate the engine
ProcessEngine workflowEngine = engineConfig.buildProcessEngine();

XML Configuration File

Alternatively, Flowable can automatically load settings from a file named flowable.cfg.xml located in the classpath's resources directory. This is often preferred for separating environment details from logic.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans.xsd">

    <bean id="processEngineConfiguration" 
          class="org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration">
        <property name="jdbcUrl" value="jdbc:mysql://localhost:3306/flow_system?characterEncoding=UTF-8" />
        <property name="jdbcDriver" value="com.mysql.cj.jdbc.Driver" />
        <property name="jdbcUsername" value="root" />
        <property name="jdbcPassword" value="password" />
        <property name="databaseSchemaUpdate" value="true" />
    </bean>
</beans>

When using an XML configuration, you can retrieve the engine instance with a single line of code:

// Automatically loads flowable.cfg.xml from resources
ProcessEngine defaultEngine = ProcessEngines.getDefaultProcessEngine();

Internal Bootstrapping Logic

When getDefaultProcessEngine() is invoked, Flowable performs an internal initialization routine. It scans the classpath for flowable.cfg.xml or flowable-context.xml (when integrating with Spring). The engine ensures that only one instance is initialized per configuration, avoiding redundant overhead during application startup.

public static synchronized void init() {
    if (!isInitialized()) {
        if (processEngines == null) {
            processEngines = new HashMap<>();
        }
        ClassLoader classLoader = ReflectUtil.getClassLoader();
        
        // Load default standalone configuration
        Enumeration<URL> resources = classLoader.getResources("flowable.cfg.xml");
        while (resources.hasMoreElements()) {
            URL resourceUrl = resources.nextElement();
            initProcessEngineFromResource(resourceUrl);
        }
        
        // Load Spring-based context if available
        resources = classLoader.getResources("flowable-context.xml");
        while (resources.hasMoreElements()) {
            URL springResource = resources.nextElement();
            initProcessEngineFromSpringResource(springResource);
        }
        
        setInitialized(true);
    }
}