Why teams move the Flowable REST WAR to a Spring Boot application
Teams move the Flowable REST WAR to a Spring Boot application when they want the Flowable REST API inside their own deployable unit, with their own build, configuration, security filters and release cadence, instead of a separate flowable-rest.war deployed beside other applications on Tomcat. The short answer is that the move is usually a moderate, well-bounded effort, not a rewrite. The Flowable REST application is itself a Spring Boot application, so the properties, externalized configuration and bean definitions you already depend on carry over more directly than they would in a generic WAR-to-Spring-Boot move. The old rest.* and engine.* properties map to flowable.* properties managed by the Flowable starter, and the starters flowable-spring-boot-starter-rest and flowable-spring-boot-starter supply the engine and REST wiring you would otherwise assemble yourself. Confirm the exact property mapping against the Flowable applications guide for the version you run, because mappings are version-specific.
Scope depends less on the WAR itself than on what surrounds it. Count the custom beans, servlet filters, listeners and delegates added to the WAR, because each one must be re-registered in your application context and retested. Identity is the next driver: if you replaced the default identity service through IdmIdentityServiceImpl or the IdmIdentityService interface, that code must be reattached and its connection to your directory verified. Database settings and the H2 default, which the WAR uses until configured otherwise, need explicit production values before any data moves. Finally, your deployment practice sets the pace: a team with a tested pipeline for process definitions and configuration will move faster than one that deploys by copying files to Tomcat. Ask any partner to base the quote on a written inventory of these four areas, and to name which Flowable version and Spring Boot baseline the target uses, since the Flowable 8.0.0 line requires Spring Boot 4 and does not support Spring Boot 3.
What maps cleanly from the REST WAR and what needs redesign
This table compares each part of the flowable-rest.war deployment with its counterpart in a Spring Boot application built on Flowable starters. Read the Spring Boot column as the target you must confirm in your own build, not as a finished migration step. The main takeaway is that REST paths, properties and the database layer move with some translation, while container assumptions, default accounts and custom wiring usually need redesign.
| Area | In the REST WAR | In your Spring Boot application |
|---|---|---|
| REST paths | Served under /flowable-rest with Swagger docs at /flowable-rest/docs | Path prefix is set by your application configuration; confirm every path your clients call still resolves |
| Property names | Legacy rest.* and engine.* keys | Map to flowable.* keys managed by the starter; Spring Boot externalized configuration still applies |
| Database | Starts on in-memory H2 unless you configure otherwise | You must set the datasource explicitly; the supported list includes MySQL, Oracle, PostgreSQL, DB2 and SQL Server |
| Container | Deployed as a WAR on a Jakarta Servlet 6 container such as Tomcat 10 or later | Runs as an executable application; the servlet container becomes an embedded choice you must confirm |
| Starter choice | Single deployable covering all engines and REST | Pick flowable-spring-boot-starter, the REST variant, or a single-engine starter; each changes which beans and endpoints exist |
| Identity handling | Default accounts and identity setup shipped with the application | Replace with your own identity service through IdmIdentityService or an override; review default accounts before go-live |
| Custom beans and listeners | Often attached through WAR-level configuration or classpath scanning | Re-register as Spring beans; check bean names and injection points against the new starter wiring |
| Monitoring | Application-level monitoring as configured in the WAR | Actuator starter exposes /actuator/flowable for running process data; confirm exposure settings in your build |
Choosing the right Flowable starter for your application
The Flowable REST application is a Spring Boot application, so replacing the WAR means choosing starters that bring the same engines and endpoints into your own build. The starter you pick decides which engines load and which REST paths exist, so the choice should be made against the calls your clients make today.
All engines without REST
The flowable-spring-boot-starter loads the BPMN, CMMN, DMN and event registry engines in one application without exposing HTTP endpoints. It fits services that call the Java API directly, such as a back-end module that starts processes from application code. Before choosing it, confirm that no existing client depends on the REST paths in your current WAR, because this starter will not serve them.
All engines with REST
The flowable-spring-boot-starter-rest is the closest match to the current WAR because it combines all engines with the REST API. This is usually the first option to test against your existing clients. Inventory every path your clients call, including the /flowable-rest context path, and compare it with the endpoints this starter registers in a test run.
Single engine starters
Process-only, CMMN-only and DMN-only starters load one engine, with or without REST. A decision service that only evaluates DMN tables can run on the DMN starter, which keeps the footprint small. The trade-off is that a client calling a process endpoint against a DMN-only application will fail, so each deployment unit must be mapped to the engines its clients use.
Actuator starter for monitoring
The actuator starter exposes the /actuator/flowable endpoint for monitoring running processes. It is an addition to an engine starter, not a replacement for one, so it does not provide any process or REST API on its own. Confirm with your operations team which health and monitoring checks currently run against the WAR, since those probes must point at the new application.
Matching endpoints before cutover
The starter choice sets which REST endpoints exist, so a path that worked on Tomcat can return a 404 after the move. Build a comparison of current request logs against the endpoints from the new application, and record each gap as either a client change or a starter change. This check should happen before the build is frozen, not during the cutover window.
How the move runs from inventory to decommissioning the WAR
The sequence turns an undocumented flowable-rest.war on Tomcat into a Spring Boot application that serves the same REST contract, with each stage producing evidence that the next stage depends on. Work is ordered so that clients are moved only after the new application has matched the old one against real data.
Inventory REST usage, properties and custom beans
Your team and DeployOpen list every REST path your clients call, including the Swagger endpoints under /flowable-rest/docs, and record which clients call each one. The team also exports the current rest.* and engine.* properties from the WAR's configuration, identifies custom beans, listeners, delegates and identity service overrides, and notes the database type and version. Done means a written inventory that names each path, property and custom class, with an owner for each client, and a list of anything you cannot yet explain.
Map properties to the Flowable starter
Each legacy rest.* and engine.* property is mapped to its flowable.* equivalent under the Flowable Spring Boot starter, because the REST application is itself a Spring Boot application with externalized configuration. Properties with no direct equivalent are flagged for a decision rather than silently dropped. Done means a reviewed property map that your security and platform owners have signed off, including where authentication and database settings are defined and how secrets are supplied.
Build the Spring Boot application with the chosen starter
DeployOpen builds a Spring Boot project around the Flowable starter that matches the scope: all engines with REST, or only the process, CMMN or DMN engines you actually use. Custom beans, delegates and the identity service are ported into the project, and the Flowable version is pinned to a release that fits your Java and Spring baseline. Done means the application starts against an empty schema, the REST paths from the inventory respond, and the build produces a single artifact your pipeline can deploy.
Pilot against a copy of the production database
The new application is started against a restored copy of the production database so that existing process definitions, active instances, jobs and history are read by the new build. Your DBA confirms the schema and the database version are within the supported list, and the team checks that timers and async jobs are picked up without duplicate execution. Done means a pilot report listing startup results, any schema or job errors, and the fixes applied and retested.
Run both applications in parallel and compare responses
The WAR and the Spring Boot application are run side by side against the same data, and a set of representative requests is replayed against each. Responses are compared for status codes, payload structure, pagination, error messages and ordering, and any difference is classified as intended or as a defect. Done means a comparison log in which every difference is either fixed or accepted in writing by the client owners.
Cut over clients and data
Clients are switched to the new base URL or routing rule in agreed groups, and a short write freeze is planned if the database must be copied for a final time. Rollback steps are rehearsed, including how to point clients back to the WAR and how to confirm that no process state was written only to the new database. Done means every client group reports successful calls from the new application, the cutover record lists the final data copy checks, and the rollback has been tested at least once.
Decommission Tomcat and the WAR
After an agreed observation period, the WAR is removed from Tomcat, the Tomcat instance and its configuration are retired, and the old properties files, certificates and service accounts are removed or documented as retired. Backups of the WAR, its configuration and the final database state are retained according to your retention policy. Done means the inventory is marked closed, the runbook reflects the new deployment, and your operations team has confirmed that the monitoring endpoint and logs for the new application are in place.
Carrying over database settings and authentication
The first thing to settle is the database, because the WAR starts on an in-memory H2 database by default and a Spring Boot application that starts without explicit settings will do the same. Nothing in that setup survives a restart, so the reader must point the application at a supported database (the configuration docs list H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server) and decide deliberately how the schema is created. Confirm which schema creation approach your team will use, who owns the DDL in each environment, and whether production schemas are created by a pipeline or by the engine at startup. If the target is MySQL, check the version against the precision note in the configuration docs, since versions below 5.6.4 lack millisecond precision, which affects timer and history timestamps. Record the datasource properties you carry over as flowable.* and Spring datasource keys, not as legacy engine.* keys.
Authentication is the second place where the WAR's defaults will not carry over unchanged. Identity management is replaceable: the Flowable docs say you can override IdmIdentityServiceImpl or implement the IdmIdentityService interface, and an LDAP identity service is provided as a reference. Before writing any code, document how users, groups and their privileges are resolved in your current deployment, including which directory is authoritative, how group names map to Flowable groups, and which accounts exist by default. Those accounts must be removed or replaced in the new application. Your team should also confirm how the REST endpoints are protected, because the Spring Boot application will need its own security configuration rather than the WAR's container setup.
Test identity and database behavior against a copy of production-like data before cutover. Ask a sample of users, including one from each group that starts or completes tasks, to call the same REST paths and compare results with the existing WAR. Verify that a timer or async job created on one node is picked up after a lock expires when two instances run, since the async executor relies on lock owners and expiration times stored in the database. Deciding these items early is cheaper than discovering them after the first production migration of running instances.
What drives the effort and duration of the move
This table lists the factors that most change how long the move takes and what it costs, with the direction each one pushes effort. Use it to see which answers from your own environment will shape a quote, and to check whether a proposal accounts for them. The main takeaway is that custom code, identity scope and client path dependencies usually outweigh the WAR swap itself.
| Driver | Effect on effort | What to ask for in a quote |
|---|---|---|
| Custom beans and delegates in the WAR's classpath | Raises effort: each bean or delegate must be ported to the starter's configuration model and retested | A count of custom beans, listeners and delegates, and a porting estimate per item |
| Identity replacement scope | Raises effort when the WAR uses a custom or LDAP identity service that must be reimplemented or verified against the Spring Boot security setup | Which identity service is in use today, whether it changes, and the test cases for users, groups and permissions |
| Database change during the move | Raises effort when the schema, driver or vendor changes at the same time as the application, since the two changes must be separated and verified | Whether the database stays the same, and a plan for schema creation and data validation if it does not |
| REST clients depending on exact paths | Raises effort in proportion to the number of clients that call fixed URLs, since each path, property and response shape must be preserved or versioned | An inventory of client applications, the endpoints each uses, and the compatibility tests planned for them |
| Properties and externalized configuration | Lowers effort when properties are few and map cleanly to flowable.* keys, raises it when environment-specific settings are spread across files and scripts | A mapping table from old rest.* and engine.* keys to new keys, and where each secret is stored |
| Deployment pipeline maturity | Lowers effort when builds, container images and environment promotion are already automated; raises it when the WAR is deployed by hand to Tomcat | Whether the proposal includes pipeline changes, how process definitions are deployed, and rollback steps |
| Parallel run length | Raises effort and duration because both the WAR and the new application must stay in sync and be compared | The length of the parallel run, the comparison method, and who signs off on cutover |
| Running process instances at cutover | Raises effort when many instances or timers are in flight and must continue on the new application without loss | How in-flight jobs and timers are handled and whether the quote covers a rehearsal of the switch |
What usually goes wrong and how to prevent it
Moving from a WAR on Tomcat to a Spring Boot application changes more than the packaging. The REST surface, defaults, database, job execution and dependency baseline can all shift without an obvious error. The cards below cover the risks we see most often and the checks that catch them before cutover.
Silently different REST paths
The WAR serves REST under its own context path, with Swagger at /flowable-rest/docs. A Spring Boot application uses its own server context path and servlet mapping, so existing clients can receive 404 responses or hit a different path with no error in the engine logs. Inventory every client call, then compare the paths the new application exposes against that list in a staging environment before any traffic moves. Confirm the context path and documentation location with the Flowable applications guide and your own configuration.
H2 left in production
The REST application starts with an in-memory H2 database by default. A new Spring Boot project may also inherit an embedded database when no datasource is set, so the application can start cleanly while writing process state to memory that disappears on restart. Set the datasource explicitly, add a startup check that fails when the URL points at H2, and confirm that running instances appear in the target database before cutover.
Async jobs picked up by new nodes
The async executor stores lock owners and lock expiration times in the database, so jobs and timers are recovered when a node's lock expires and another node takes them. Running the old WAR and the new application against the same database during a rolling cutover can cause duplicate or stalled timers. Plan a single writer window, drain the old node's executor, and check that lock expiration settings match your deployment model before scaling out.
Spring and Jackson version drift
Starters for newer Flowable releases move the baseline. Flowable 8.0.0 requires Spring Framework 7 and Spring Boot 4 and does not support Spring Boot 3, and it uses Jackson 3 by default with a Jackson 2 compatibility layer. Custom beans, delegates and serializers built against older libraries can fail at startup or change date and JSON output. Pin the versions you test, run serialization tests against recorded REST responses, and review the release notes before choosing a starter.
Forgotten properties
Old rest.* and engine.* properties map to flowable.* keys managed by the starter, but any property missed in the mapping is ignored without warning. Settings such as history level, async executor options, security or database pool sizes can revert to defaults silently. Build a property inventory from the old WAR's configuration, translate each entry, and write a check that compares the effective configuration of both deployments at startup.
Questions buyers ask before moving the REST WAR
How much effort does moving the REST WAR to Spring Boot take?
The effort depends mostly on how much the current WAR has been changed from stock. A stock flowable-rest.war with default H2 storage and no custom beans is the smallest case. Effort grows with the number of custom Java classes, delegates and listeners packaged alongside the WAR, the number of rest.* and engine.* properties in use, the authentication setup in front of the API, and the database and deployment pipeline you already run. The Flowable applications guide notes that old rest.* and engine.* properties map to flowable.* properties, so the property mapping itself is usually a small part of the work. Ask any partner to inventory these items against your current WAR before quoting.
How long does the migration take?
No duration is fixed by the supplied facts, so treat any number you hear as a claim to verify. Duration follows from the inventory above, the number of environments that need the new application, the depth of testing against your process definitions and REST clients, and how many change windows your organization allows for cutover. Ask for a written plan with phases, entry and exit criteria for each phase, and the dates your team must supply reviewers, test data and access.
What does the migration need from our team?
Expect to supply several roles: an owner who knows which client applications call the REST API, someone who can export the current configuration and custom code, a database administrator for schema and credentials, and a platform engineer for the build and deployment pipeline. Your team also needs to name the authentication source the API uses today and confirm who approves changes to process definitions in each environment. Agree these responsibilities in the written scope so testing and cutover do not wait on informal access.
Can an internal team move the REST WAR without a partner?
Often yes, if the team already builds Spring Boot services, has Flowable experience and can run the existing REST API tests against the new application. The work is manageable for a stock WAR with few customizations and is harder when custom beans, identity overrides or unusual database settings are involved. Compare your team's time against the inventory, the testing you need and the risk of a failed cutover. A fixed-scope engagement lets you buy specific pieces, such as the property mapping, the authentication design or the pipeline, while your team keeps the rest.
Should we use Spring Boot 4 or Spring Boot 3 as the baseline?
Choose based on the Flowable version you target. The Flowable 8.0.0 release notes describe an upgrade to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3, and Flowable 8.0.0 was released on February 27, 2026. Flowable 7.0.0 moved to Spring Boot 3, Java 17 and Jakarta EE. If you move to Flowable 8, plan for Spring Boot 4, Jackson 3 as the default JSON library and removal of JUnit 3 and 4 support in your tests. If your application must stay on Spring Boot 3, confirm which Flowable line supports it before you start.
What happens to the WAR during a parallel run?
A common approach is to run the new Spring Boot application beside the existing WAR, point a subset of test clients at it and compare responses for the same process definitions and instances. The WAR stays deployed and serves production traffic until the cutover decision. Plan for both applications to avoid writing to the same database schema at the same time unless the design explicitly supports it. Also plan for the async executor: the Flowable advanced docs describe lock owners and lock expiration stored in the database, so confirm how jobs and timers behave while two nodes can see the same data. Confirm the rollback path before the parallel run starts.
Choosing a Spring Boot baseline for the new application
The first decision is which Spring Boot line the new application will sit on, because that choice follows from the Flowable version you run. Flowable 8.0.0 moved to Spring Framework 7 and Spring Boot 4 with no backward compatibility for Spring Boot 3. Flowable 7 was built on Spring Boot 3, so a team that stays on Flowable 7 should keep its application on Spring Boot 3, while a team that moves to Flowable 8 must plan for Spring Boot 4 from the start. Mixing the two is not a supported path, so confirm the exact Flowable version your WAR runs today, including the version of any embedded engine jars, before you pick the parent POM. Check the release notes for the version you are moving to at Flowable 8.0.0 release notes.
Two library changes in the 8.0.0 line affect custom code more than configuration. Jackson 3 is now the default JSON library, with a Jackson 2 compatibility layer available. Any custom delegate, listener, REST extension or bean that imports Jackson 2 types, or that serializes variables with Jackson 2 annotations, needs an explicit review. Test framework support also changed: JUnit 3 and 4 support was removed, so any existing Flowable test suite that depends on them must be migrated before the build can pass. Ask your development team to list every custom class that touches JSON or tests, and to state which of these two areas it depends on. That list is the input to the effort estimate for the baseline decision.
How DeployOpen scopes and delivers the move
DeployOpen plans the move of your flowable-rest.war deployment to a Spring Boot application you own, starting from a written inventory of your REST paths, properties, authentication and custom beans. We then build, test and document the new application inside your own infrastructure and hand it over with the runbooks your team needs to operate it.
How we scope
- Inventory every REST path, property and client your current flowable-rest.war serves before work starts
- Confirm which Flowable starter fits your needs, such as the all-engines REST starter or a single-engine starter
- Record the database, authentication, custom beans and deployment pipeline that the new application must keep
- Agree the scope in writing as a fixed-scope engagement with deliverables and timelines named in advance
- Confirm with your team whether ongoing support, upgrades or testing should follow as a retainer
How we build
- Recreate the REST application as a Spring Boot project, mapping legacy rest.* and engine.* properties to flowable.* settings
- Carry custom beans and identity services across, and test each one against the new starter configuration
- Set up authentication and database connections in your environment, then run regression tests against the REST endpoints
- Wire the build into your existing deployment pipeline so the new application ships the same way your other services do
- Confirm the Swagger documentation, actuator endpoints and logging behave as your operators expect before cutover
How we hand over
- Deliver the source, configuration and pipeline definitions in repositories you control
- Provide a written runbook covering startup, configuration keys, database settings and rollback to the WAR
- Document the test results, the endpoint compatibility checks and any known differences from the original deployment
- Walk your platform and engineering teams through operation, monitoring and troubleshooting before handover closes
- Record open decisions so your team can confirm them with the vendor or in your own environment
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the handover
- Plan upgrades of the Flowable version and Spring Boot baseline as separate, scoped work
- Review configuration and dependency changes for each Flowable release before your team adopts them
- Keep the support scope in writing so response expectations and included work are clear to both sides
- Ask for a quote built from the written scope, since DeployOpen does not publish a price list
