Flowable Engine Documentation

The Identity Management (IDM) engine manages the following core entities in its database schema:

• User / UserEntity: User information.
• Group / GroupEntity: Group information.
• MembershipEntity: Links users to groups.
• Privilege / PrivilegeEntity: Privilege definitions (e.g., for controlling access to Flowable Modeler or Task apps).
• PrivilegeMappingEntity: Links a user and/or group to a privilege.
• Token / TokenEntity: Authentication tokens used by UI applications.

Flowable provides four distinct groups of Public REST APIs to interact with the Flowable Engine services:

• Process API: Provides access to most of the Flowable services.
• Decision API: Provides access to the Flowable DMN (Decision Model and Notation) engine.
• Form API: Provides access to the Flowable Form engine.
• Content API: Provides access to the Flowable Content Services.

Flowable is a compact and efficient workflow and Business Process Management (BPM) platform. It provides three core engines written in Java:

• BPMN process engine: For business process modeling.
• CMMN case engine: For case management.
• DMN rule engine: For decision modeling.

Flowable can be run embedded within a Java application or as a standalone service on a server, cluster, or in the cloud. It features deep integration with Spring and provides both rich Java and REST APIs for orchestrating human or system activities.

Flowable provides support for the Case Management Model and Notation (CMMN) 1.1 standard, which is used to represent case models. The implementation includes:

• CMMN 1.1 Modeler: A tool to create case models.
• Java Engine: An engine capable of importing and executing CMMN 1.1 case models.
• Demonstration UI: A user interface for executing case models, allowing users to interact with human tasks and forms.

Key concepts include case models (the container), plan models (the structure within the case), and plan items (individual elements like human tasks, milestones, process tasks, or stages).

A 'none' start event has no specific trigger (like a timer or message). It is used when a process instance is started manually via the API using startProcessInstanceByXXX methods.

Key details:

• Sub-processes always use a none start event.
• If a process has multiple message start events and a single none start event, calling startProcessInstanceByKey or startProcessInstanceById will target the none start event.
• If a process has multiple message start events but no none start event, calling startProcessInstanceByKey or startProcessInstanceById will throw an exception.

Flowable is a lightweight Java-based business process engine for BPMN 2.0. You can integrate it into your architecture in several ways:

1. Embedded Engine: Include the Flowable library as a JAR in your Java environment (Java SE, Spring, Tomcat, Jetty, JBoss, WebSphere, etc.). This allows you to call the engine's APIs directly from your code.
2. REST API: Communicate with the engine over HTTP using the Flowable REST API.
3. Flowable Applications: Use out-of-the-box UIs such as Flowable Modeler, Flowable Admin, Flowable IDM, and Flowable Task for process management.

Flowable uses a MAJOR.MINOR.MICRO versioning strategy:

• MAJOR: Core engine evolutions.
• MINOR: New features and new APIs.
• MICRO: Bug fixes and improvements.

Compatibility Guarantees:

• Flowable aims for source compatibility (applications build without error and semantics remain unchanged) and binary compatibility (JARs can be dropped in as replacements) during MINOR and MICRO releases for all non-internal classes.
• API Deprecation: If an API change is introduced in a MINOR release, the old API is kept and marked with @Deprecated. It is removed two MINOR versions later.

The Flowable engine automatically detects and terminates event listeners (user or timer) that are no longer useful to prevent orphaned listeners.

Removal triggers include:

• When all tasks/plan items that a listener is waiting for (or that would trigger the listener's purpose) are completed and the stage/case reaches a state where the event can no longer be listened to.
• When an event listener is referenced by an entry sentry, and the target of that sentry is no longer active.
• When a competing listener (e.g., a timer vs. a user event) is triggered first, the other is removed if it is not referenced elsewhere.

Note on future plan items: The engine does not remove a listener if it is still needed for plan items that have not yet been created, provided their parent stage is in a non-terminal state.

Sentries in CMMN are used to declaratively configure when plan item instances activate or stop. The Flowable CMMN engine evaluates sentries whenever state changes occur in a case instance, such as:

• Starting a case instance.
• Triggering a wait state plan item (e.g., a human task) to continue.
• Changing case instance variables (added, updated, or deleted).
• Changing the state of a plan item instance (e.g., via RuntimeService termination or manual start).
• Manually triggering evaluation via RuntimeService#evaluateCriteria.

The engine continues to schedule evaluations as long as changes occur. Once the state becomes stable (no more changes), evaluation stops.

The Flowable Docker base image is built upon azul/zulu-openjdk-alpine:21-jre-latest. It is designed to provide a secure environment for running Flowable applications by including a non-root user and utility scripts.

Key features include:

• Non-root execution: Includes a flowable:flowable user, allowing you to 'step down' from root when executing Flowable applications to improve security.
• Utilities: Includes su-exec for switching users and ttf-dejavu fonts.
• Wait script: Includes wait-for-something.sh to assist with container startup orchestration (e.g., waiting for a database to be ready).

Flowable uses an Async Executor to handle two primary types of background jobs:

1. Timers: Associated with events like boundary events on user tasks. They are stored in the ACT_RU_TIMER_JOB table with a due date. A background thread periodically checks for due timers and converts them into async jobs.
2. Async Continuations: Created when a service task is configured with the flowable:async="true" attribute. These are inserted into the ACT_RU_JOB table. If the async executor is enabled, these jobs are immediately locked to prevent duplicate execution.

Error Handling & Retries:

• If a job fails, it is transformed into a timer job with a due date to be retried later.
• After a configurable number of failed retries (asyncExecutorNumberOfRetries), the job is moved to the ACT_RU_DEADLETTER_JOB table for manual administrator intervention.