Flowable CMMN REST API

How the Flowable CMMN REST API lets front ends and services drive cases

The Flowable REST layer exposes its CMMN engine over HTTP, so a front end or integration can start cases, see open work and complete it without embedding the engine in its own process. Teams need this when case work must be driven from outside the Java application, for example from a single-page app, a mobile client or a back-office service written in another language. The key decision is where the engine runs: in the Flowable REST application or in a Spring Boot service that includes the REST starter, and whether the calling system is trusted to act for people or only for itself.

The main capability groups are starting case instances from a deployed case definition, listing plan items and human tasks for a case or a user, completing or transitioning them, reading and writing case variables, and querying case history. Each group maps to a set of resources in the Flowable REST documentation. Before writing any client code, confirm the exact endpoints, request and response payloads, and authentication scheme for the Flowable version you run. The 8.0.0 release moved the stack to Spring Framework 7 and Spring Boot 4, and the release notes list JSON and test-framework changes that can affect payload handling, so the API reference for your version is the source of truth, not older blog posts or examples.

Plan the integration around the calls your users will actually make. A common first step is to map each screen or service action to one case-level operation and one list query, then check which of those operations the REST layer supports for your case model. Ask your team or DeployOpen to confirm the authorization behavior of each call during design, because the engine does not decide which user may act on which task on its own. The sections on security and history below cover those checks in more depth.

Deployment options for the Flowable CMMN REST API

This table compares the three documented routes to CMMN over HTTP: the standalone Flowable REST application, Spring Boot starters, and an embedded engine JAR with your own controllers. Read each row as a decision about who builds and secures the API surface, and the main takeaway is that more control over the endpoints means more code and more upgrade work for your team.

Option	When it fits	Who owns security	Build effort, upgrade coupling and API control
Standalone Flowable REST application	Teams that want the engine's CMMN REST endpoints without writing server code, and can run the REST application as its own service	Your team configures authentication and network placement for the REST application, and checks default accounts before exposure	Lowest build effort. Upgrades follow the REST application release. API surface is the one the product exposes, so custom endpoints need a separate service
Spring Boot starters for REST and CMMN	Java teams on Spring Boot who want CMMN endpoints inside an application they already deploy and monitor	Your team owns Spring Security configuration, token validation and authorization checks for each case operation	Moderate build effort. Upgrades track the Spring Boot and starter versions, which must match your Spring baseline. Endpoints can be wrapped or filtered in the same application
Embedded CMMN engine JAR with your own controllers	Teams that need a narrow, domain-shaped API, or run in Java SE, servlet containers or Java EE where starters do not apply	Your team owns every endpoint, including input validation, case ownership checks and audit logging	Highest build effort, since you write and test each controller against the engine API. Upgrades touch your code directly. Full control over which operations and payloads are exposed
Choice of pattern for front ends	Front ends that call cases directly for simple status and task actions	Requires per-user authorization on each plan item and task call, which the engine does not enforce for you	Confirm in your environment which REST resources cover the operations your front end needs before choosing a route

What happens to a request from a front end to a running case

A call from a browser or service to the CMMN REST API passes through your gateway or backend first, then reaches the Flowable REST application or an embedded CMMN engine, which reads and writes the database you configured. The engine records history as it runs, so every case start, plan item transition and task completion leaves data behind that you will query later. The decision you need to make early is where the authorization check sits. The engine does not decide who may start a case or complete a task. Your application does, and it should make that check before the request reaches the endpoint. Identity handling inside the engine can also be replaced through its identity service interface, so confirm how user and group lookups for task assignment will resolve in your deployment and which component owns that data.

Timers and asynchronous jobs run on the async executor, which uses a thread pool and coordinates multiple nodes through lock owners and lock expiration times stored in the database. That means an HTTP response can return before work scheduled by a timer or async step has run, and a job may be picked up by a different node than the one that received the request. Do not assume that a completed response means every downstream effect of the case has finished. Check the Flowable advanced documentation for the version you run, and test which REST calls return only after the engine state is committed and which schedule background work. Plan your front end to read the resulting state rather than assume it, and make a note of which operations need a follow-up query.

Confirm the synchronous behavior of each call in your version with a test against a staging database rather than relying on general descriptions. Record the database type, since the Flowable configuration docs list several supported options, and verify the transaction boundaries and history settings you have chosen. Use the Flowable advanced documentation as the reference for the async executor and lock behavior, and document the result so that your gateway timeouts, retry rules and user-facing status messages match what the engine actually does.

Setting up the Flowable CMMN REST API with a check at each step

This sequence takes a team from an empty environment to a running case that is started, inspected, acted on and audited through the REST API, with a verification before each move to the next stage.

Choose the deployment option
Decide whether the CMMN engine will run embedded in your own Spring or Java application, or whether you will run the Flowable REST application as a separate service that your front ends and other systems call over HTTP. The Flowable getting started guide describes both embedding and the REST application as supported routes. Record the choice with the team that owns the runtime, because it sets which starters, endpoints and deployment pipeline you will use. Check: a short written decision exists that names the runtime, the Java and Spring baseline in use, and who will operate it. Confirm the exact Java and Spring versions against the Flowable release you select.
Provision and verify the database
Provision a database from the list Flowable documents as supported: H2, MySQL, Oracle, PostgreSQL, DB2 or Microsoft SQL Server. Confirm the exact version against the Flowable configuration documentation for your release, and set the character encoding and collation your organization requires before the first start, since changing them later is disruptive. If you choose MySQL, note that the Flowable configuration docs say versions below 5.6.4 lack millisecond precision, so check your server version and time handling before relying on timestamps in history. Check: a test connection from the application host succeeds with the intended user and privileges, and the server version and character settings are recorded in your environment notes.
Add the REST and CMMN starters or deploy the REST application
If you embed the engine, add the Flowable Spring Boot starters for REST and the CMMN engine to the application build, using the starter set that matches your Spring Boot line. If you run the REST application, deploy it to your servlet container or container platform and point it at the database. Flowable documents starters for the REST layer and for individual CMMN, BPMN and DMN engines, and an actuator endpoint at /actuator/flowable. Check: the application starts without schema or configuration errors, the actuator endpoint responds in an authenticated context, and the REST root responds with the expected authentication challenge rather than an open response.
Deploy a case definition
Deploy a small test case model with a human task that has a clearly named assignee, using the deployment mechanism your pipeline will use in production. Keep the model simple, with one stage, one human task and one milestone, so that failures are easy to isolate. Deploy through the REST API so that the same path can later be automated. Check: the case definition is listed through the REST API with the expected key and version, and the deployment is visible in the engine after a restart of the application, confirming it was persisted to the database rather than held in memory.
Start a test case over the API
Start an instance of the deployed case definition through the REST API, passing a case variable that your later steps will read. Use an authenticated service or test user for the call, because the endpoints must sit behind your own authentication and authorization layer. Keep the returned case instance identifier, since every later call depends on it. Check: the response contains a case instance identifier and the expected case variable, and querying the case instance by that identifier returns it in the active state.
List plan items and complete one human task
Query the plan items of the running case through the REST API and locate the human task that should be waiting for the assignee you configured. Then complete that task through the API, supplying any variables the task expects. Confirm that the task appears for the expected assignee and not for others, because assignment is one of the first things to fail when identity integration is wrong. Check: the human task is listed with the expected name and assignee before completion, its state changes to completed after the call, and the milestone or next plan item updates as the model specifies.
Query the case history
Query the history endpoints for the case instance to confirm that the engine recorded what happened: case start, plan item transitions, the completed task and the variable changes you made. Compare the returned timestamps with the order of your test calls, and if you use MySQL, check that the time values have the precision you need. Check: history rows exist for the case instance and the completed human task, they appear in the expected order, and a second query by a different identity is refused or filtered as your security configuration requires.

Which Flowable version changes the REST stack you build on

The Flowable 7.x line moved the engines to Java 17, Spring Boot 3 and Jakarta EE, and it focused on the BPMN, CMMN, DMN and event registry engines together with their REST APIs. The release notes for 7.0.0 also removed the UI applications, the form and content engines, the Mule integration and async history, so any REST client that depended on those components needs a different path. For a team that already runs Spring Boot 3, this line keeps the framework baseline unchanged.

Payload parsing: Client code and any custom REST resources keep the JSON library and serialization behavior that the 7.x release line ships with, so existing request and response handling is the least disruptive starting point.
Spring Boot baseline: Applications stay on Java 17 and Spring Boot 3, using the Flowable starters for the CMMN engine and REST support that match that baseline.
Test tooling: Existing JUnit 3 and 4 tests keep running on the 7.x line, so a test suite that has not moved to JUnit 5 does not need to change before the upgrade decision.
Scope of the REST API: The CMMN REST endpoints sit alongside the BPMN, DMN and event registry endpoints, so case calls that hand off to processes or decisions use the same API family.
Long-term alignment: Choose this line when the platform team needs a Spring Boot 3 baseline for other services and wants to schedule the move to a later major release separately.

Before you choose, confirm your client JSON handling, any custom REST code and your test framework against the Flowable 7.0.0 release notes and the release notes for later 7.x versions.

Securing the Flowable CMMN REST API endpoints

The CMMN REST API exposes case start, plan item and task operations, variables and history, and the engine does not decide who may do what on its own. The cards below cover the layers you need to design around it: who authenticates, who is authorized, how traffic reaches the endpoints, and how monitoring is protected.

Authenticate before requests reach the engine

Decide where identity is checked: at an API gateway, inside the application, or in both. Many teams put OIDC sign-in in front of the REST layer, while the Flowable docs describe replacing the identity management service by overriding IdmIdentityServiceImpl or implementing IdmIdentityService, with an LDAP implementation as a reference. Confirm which identity source your users come from, and test that expired or revoked sessions cannot still start cases or complete tasks.

Authorize every case and task action

The engine does not check whether a given user may start a specific case, complete a particular human task, or read another user's history. Your application or gateway must map roles and ownership to each CMMN operation, such as case start, plan item listing, task completion and history queries. Write these checks as explicit rules, and test them with users who should be refused, not only with users who should succeed.

Limit network exposure and terminate TLS

Keep the Flowable REST application on an internal network segment and publish only the paths your front ends need through a gateway or reverse proxy. Terminate TLS at a controlled point, and confirm that internal hops are encrypted where they cross trust boundaries. Check that database and admin ports are not reachable from the same network path as public traffic.

Remove default and sample accounts

Sample users and default credentials are common in example deployments and must not reach production. Before go-live, inventory every account the engine and REST application create, disable or replace them, and rotate any secrets that were used during development. The security sibling topic covers default accounts in detail, so use it as the checklist for this step.

Restrict the actuator monitoring endpoint

The Spring Boot starters expose an actuator endpoint at /actuator/flowable for monitoring running processes. Do not leave it open to general traffic. Allow access only from your monitoring network or to operations roles, and confirm that the gateway does not forward it to public routes. Review what the endpoint reveals about running instances before you enable it outside a test environment.

Review scripting and XML risks separately

Scripts, expressions and XML definitions can change engine behavior, so they are a separate attack surface from the REST endpoints themselves. Only deploy case definitions from approved sources, and make sure the API cannot upload new definitions without review. The security sibling topic on scripting and XML risks covers these controls in depth.

What does it cost to expose the Flowable CMMN REST API?

What drives the cost of exposing the Flowable CMMN REST API?

The cost is driven by how much of the surface your front ends and services will call, and how much of your own code sits around it. The main drivers are the number of case definitions that must be startable and observable over REST, the number of human task and plan item actions that need a custom check, the identity integration you need, the number of environments you run, and the depth of automated testing you expect. Each case definition adds mapping work for variables, plan item names and error responses. Custom authorization, meaning rules that decide whether a given user may complete a given human task or read a given case, is usually the largest single item, because the engine leaves that decision to your application. A quote should break these drivers out so you can see which ones you can reduce.

Can our team build the CMMN REST API exposure alone using the open-source docs?

A team with Java and Spring experience can build a working exposure layer from the open-source documentation, and the Flowable getting started guide explains the embedding and HTTP options. The harder parts are design decisions that the docs do not make for you: which user may start which case, how human task ownership maps to your directory, how errors reach a front end, and how you prove that a request was authorized. Teams that have not built this before usually underestimate the testing and the security review. Whether you build alone depends on your skills, your deadline and how much review your security function requires. Ask yourself whether you have an engineer who can own the design for the life of the application.

What does our organization need to provide before the work starts?

Before work starts, you need to name owners on your side. A business owner should confirm which cases and plan items front ends will drive. A technical owner should approve the deployment option, which may be a Spring Boot application, a servlet container or the Flowable REST application. A security owner should agree the authentication approach and the authorization rules. You also need an identity provider that issues tokens or sessions the exposure layer can validate, a supported database such as PostgreSQL, MySQL, Oracle, Microsoft SQL Server, DB2 or H2 for development, and representative test data. Test data should include users, groups and case variables that match production shapes without exposing real personal data. Confirm each of these in writing before the scope is fixed.

How long does it take to expose the Flowable CMMN REST API?

Duration depends on the written scope, so no figure is given here. The scope sets the number of case definitions, the custom authorization rules, the identity integration, the environments and the test coverage. A narrow scope with one case definition, an existing identity provider and a standard deployment will take far less time than a scope covering many cases, several environments and custom rules for human tasks. Ask for a timeline that lists each milestone, the client input it depends on and the test evidence delivered at each step. A timeline that does not depend on your input is usually optimistic. DeployOpen quotes follow a written scope, so the timeline and deliverables are agreed in writing before work starts.

Which costs are one-time and which recur after go-live?

One-time costs include design of the endpoints, the authorization model, the identity integration, the initial test suite and the deployment setup for each environment. Recurring costs come from keeping the exposure layer current with Flowable releases, rotating credentials and certificates, updating case definitions when the business changes them, and reviewing access as roles change. Flowable's release history matters here: Flowable 8.0.0 was released on February 27, 2026, following 7.2.0 on August 21, 2025, and the 8.0.0 release notes describe an upgrade to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3. Any upgrade of the exposure layer should be scoped as its own piece of work. Ask the provider whether support and upgrades are quoted as a retainer.

Does identity integration add much to the cost of the CMMN REST API?

Identity integration is one of the larger cost drivers because the REST API must know who is calling and what that person may do. Flowable's docs state that identity management can be replaced by overriding the IdmIdentityServiceImpl class or by implementing the IdmIdentityService interface, and that an LDAP identity service implementation is provided as a reference. Connecting to an existing directory, such as LDAP or an identity provider you already run, is typically less work than designing a new user store. The cost rises when group membership is complex, when roles come from several systems or when you need to map external claims to engine groups. Ask for the identity mapping to be written out before estimating the work.

When does a partner help most with the CMMN REST API?

A partner helps most when the scope includes custom authorization for human tasks and case instances, when several environments and identity sources must behave the same way, or when the exposure layer will be reviewed by security or compliance teams that expect evidence. A partner is also useful when your own team lacks recent Flowable experience or cannot commit an owner for the life of the application. DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and runs security testing of the APIs. DeployOpen does not issue audit reports or certifications, so independent assessors remain responsible for those. Most engagements are fixed-scope, and ongoing support is available as a retainer.

Limits to confirm in your environment before go-live

The CMMN REST API behaves according to the exact Flowable version, deployment and database you run, not according to general descriptions. The cards below list the items to confirm in release notes, REST documentation and a test environment before you commit a front end or service to them.

Endpoint paths and payload shapes

Confirm the exact paths, HTTP methods, request bodies, response fields and pagination parameters for the version you deploy. Case instance, plan item and human task resources can differ in naming and nesting between releases, so record a sample request and response for each call your front end depends on. Treat any client code generated from older examples as unverified until it passes against your build.

Synchronous behavior and async jobs

Establish, for each operation, whether the response reflects a completed state or only an accepted request. Some transitions may trigger timers, asynchronous jobs or follow-on tasks that finish after the HTTP call returns. Your front end should read back the resulting state or handle a pending state, and your tests should cover both outcomes rather than assume an immediate update.

Payload and concurrency limits

Ask which request size limits apply at the REST application, the servlet container and any gateway in front of it. Also determine how many concurrent requests your deployment handles before latency or errors rise. Load test the case start, task completion and variable update paths with realistic variable payloads, since large variables increase both request size and database writes.

Scaling with the database and async executor

Multiple REST application nodes share one database, and the async executor coordinates them through lock owners and lock expiration times. Confirm the lock settings your version uses, how expired locks are recovered, and how quickly another node picks up a job after a failure. Check that your database connection pool and transaction settings hold up when several nodes run the same case work at once.

Retained and queryable history

Confirm which case, plan item, milestone and task history your configuration records and how long it is kept. History level settings determine whether plan item transitions and variable changes can be queried through the API at all. Verify the history query filters you need, such as by case definition, state or date range, against real data before you design reports or audit evidence on them.

Spring and Jackson changes by version

Read the release notes for your target version before upgrading or choosing a starter. Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3, and made Jackson 3 the default JSON library with a Jackson 2 compatibility layer. Serialization changes can alter response formats that your front end parses, so compare JSON output in a test environment on both libraries.

How DeployOpen scopes, builds and supports Flowable case APIs

DeployOpen plans, implements, hardens, documents and supports self-hosted Flowable deployments inside your own infrastructure. For the CMMN REST API, we start from a written scope that names the case definitions, endpoints and front-end or service callers involved, then build and test the integration against your identity model and data.

How we scope

Inventory the case definitions, plan item types and human tasks your front ends and services need to reach through the REST API.
Map each caller to the REST operations it needs, such as starting cases, listing plan items, completing tasks and reading case variables.
Agree in writing which history queries, security controls and deployment environments are inside the fixed scope before work starts.

How we build

Build the REST calls against your Flowable version, confirming endpoint behavior and payload shapes in a test environment you control.
Enforce authorization in your application layer for every case start, task completion and variable read, since the engine does not make those decisions for you.
Test happy paths, rejected requests and permission boundaries, and document the results alongside the scoped deliverables.

How we hand over

Deliver an API reference for your case endpoints, with example requests, expected responses and the variables each call reads or writes.
Provide configuration for authentication, network exposure and Flowable REST application settings, stored as code your team can review.
Walk your engineers through runbooks for common failures, including unauthorized calls, missing case definitions and history query limits.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer that covers changes to the case API after go-live.
Retainer work can include re-running endpoint tests when you move to a newer Flowable release, after reviewing its release notes.
Confirm with DeployOpen during scoping which support hours, response expectations and upgrade responsibilities the retainer includes.