Flowable case instance migration: when running cases must move to a new version
When a case model changes, cases already in progress keep running on the definition they started with unless you move them. Flowable case instance migration is the mechanism for moving those running instances to a new case definition version so that work already done is preserved and the case can continue. In practice, the migration relates each plan item in the old version to a plan item in the new one, creates plan items for elements that exist only in the new model, and deals with the parts of the case that carry state: local variables, pre and post expressions, and sub cases that may already be running. Each of those parts can break a migration if the mapping is incomplete, so the mapping is the design work, not an afterthought.
Teams usually need this when a change affects live work: a stage is split, a task is renamed or moved into a different stage, a sentry condition is tightened, or a sub case is replaced. The first decision is whether in-flight cases should move at all. Some cases are better left on the old version and allowed to finish, particularly where the regulatory or business meaning of the old steps has changed. Migration also does not replace the review of your own data. It does not decide what a half-finished review or approval means under the new model, and it does not fix a variable whose type or meaning changed. Before you commit, confirm with the Flowable documentation for your engine version which migration API calls, mapping options and validation behaviors apply, since these details change between releases. The Flowable docs on advanced topics are a reasonable starting point, and the Flowable 8.0.0 release notes show which baseline your build uses.
The practical rule is to validate before you change anything. Use the REST API to request a dry run of the migration against a sample of real instances, from a copy of production data, and review every instance the validation rejects. Look for plan items with no target, sub cases that cannot be terminated cleanly, and variables that the new expressions will read differently. Record the outcome per case type and decide, in writing, which cases migrate, which finish on the old version, and who signs off on exceptions. Plan a rollback path for the period when both versions run side by side, and confirm how your team will monitor cases that land in unexpected states after the move.
Which migration approach fits your running cases
This table compares three ways to handle running case instances when a case definition changes: migrating them in place, letting them finish on the old version, or terminating and restarting them. Read each row against your own case volumes, customer commitments and the Flowable version you run, because the answer depends on how far the new model departs from the old one.
| Approach | When it fits | Business cost | Confirm in the Flowable docs for your version |
|---|---|---|---|
| Migrate in place with plan item mappings | Changes are additive or renamed, and in-flight cases must continue from their current stage without losing work | Mapping design and testing effort up front, plus a rehearsal on production-like data before cutover | Supported mapping options, how plan items are created for new elements, and how pre and post expressions and local variables are handled |
| Let open instances finish on the old definition | Cases are long-running, the change is large, and business users can tolerate running two versions side by side | Two definitions stay deployed and supported for longer, and reporting must cover both versions | Deployment behavior for multiple case definition versions and how the old version's jobs and listeners keep running |
| Terminate and restart affected cases | Cases are short-lived, the data can be re-entered safely, or the old logic is unsafe to keep running | Work in progress is lost or repeated, and customers or staff may need to be informed or re-served | Behavior of terminating case instances and any sub cases, and which variables and history survive a restart |
| Validate the migration first over REST | Any option that changes running instances, so the plan can be checked before anything is moved | Test environment time and a written migration plan that names affected instances and expected outcomes | Which migration validation endpoints exist in your version and what they report about unmappable plan items |
Setting up a validated case instance migration
This sequence moves a Flowable case instance migration from a planning exercise to a verified change, so that every running case has a known outcome before live data is touched. Each step produces a record your team can review and sign off before the next one starts.
Deploy both definition versions to a test environment
Deploy the current and target CMMN case definitions to a non-production environment running the same Flowable engine version that production uses. Confirm that both definition versions are deployed, that their IDs and version numbers match what your deployment pipeline recorded, and that the target version passes the same deployment checks as the one you plan to ship. Matching engine versions matter because the migration behavior you test must be the behavior you get in production. The step is done when both versions are visible through the CMMN REST API in the test environment and the engine version is recorded in your change ticket.
Inventory running instances and plan item states
Query the running case instances in production or a production copy, grouped by case definition version, and record the active plan items in each one with their current states, such as available, active, enabled or waiting for repetition. Include child cases, stage nesting and any plan items that carry local variables your business logic reads. The output is a written inventory showing how many instances exist per version and which plan item states appear in each group. Ask the team that owns the case model to confirm that no state appears in the inventory that they do not expect, because unexpected states are the most common source of migration surprises.
Write plan item mappings and expressions
For each plan item in the source version, decide where it maps in the target version, and for each new element in the target version, decide whether the migration creates a plan item for it or leaves it absent. Write the pre and post expressions that govern the mapping, and document the local variables each mapped item needs. Assign an owner to every expression and record the reason for it in the mapping document. The step is complete when the mapping document contains one entry for every source plan item and every target element that will be created, with no blank fields and no entries marked to be decided later.
Confirm every active plan item maps or has a documented outcome
Cross-check the inventory from the earlier step against the mapping document. Every active or available plan item in the inventory must either map to a target plan item, or carry a documented outcome such as terminate, leave in place with a stated reason, or handle manually. Also confirm how child cases and sub cases will be treated, including whether they are terminated before the parent migrates. The check passes when a reviewer can point to one mapping or one documented outcome for every active plan item and no item is left unresolved. Items without an outcome block the next step.
Run a validation pass over REST without changing live data
Using the CMMN REST API, submit the migration request for each affected instance in a validation mode against the test environment, then review the results without applying any change to live data. Record which instances pass, which fail, and the reason for each failure, including expression errors, missing variables and plan items that the target version cannot accept. The validation pass is complete when every failure has been either fixed in the mapping or accepted with a documented decision. Run the same validation again after any change to the mapping, so the final result reflects the version you will execute.
Rehearse on a copy of production data
Restore a recent copy of production data into a separate environment running the same engine version and execute the full migration there, using the same mapping, expressions and REST calls planned for production. Compare the instance count, plan item states and variable values before and after the rehearsal, and check that child cases behave as the mapping documents. Record the elapsed time of the rehearsal so the production window can be planned from observed data rather than estimates. The rehearsal is complete when the post-migration state matches the expected state for every sampled and all affected instances, and when the team agrees that any remaining differences are accepted in writing.
Execute the migration and verify the results
Run the migration against production using the rehearsed sequence and the same REST calls, with a rollback plan agreed before the window opens. After execution, repeat the inventory query, compare the new plan item states with the mapping, confirm that no instance is left in a state that the mapping did not describe, and check that business-critical case variables and history records are intact. Keep the validation and rehearsal records with the change ticket. The migration is verified when every affected instance is accounted for in the post-migration inventory and the team has signed off on the comparison against the rehearsal results.
How each kind of change in a case model is handled
A mapping attaches a running plan item to the element that replaces its definition in the new case version. For each plan item in flight, the migration must decide which element it maps to and whether it keeps its current state and open work. If the mapping points to the wrong element, the case keeps running the old behavior under a new name, and users see tasks that no longer match the model.
- Identity: Confirm the mapped element has the same meaning as the original, so sentries and milestones that reference it still fire on the right events.
- State: Decide whether an active or completed plan item carries its state across. A completed item mapped to an element that should still be open can skip required work.
- Human tasks: Check assignee, candidate groups and form data on mapped user tasks, since they carry over and users see them immediately.
- Sentry references: Trace every sentry and criterion that refers to a mapped item. An on-part that listens to an item whose identity changed stops triggering.
Test each mapping with instances in each state (available, active and completed) and confirm the case moves through the same sentries it would have used before cutover.
A plan item added in the new version has no running counterpart in existing instances. The migration must decide whether to create it for in-flight cases and, if so, in which state. A new item created too late may start work for a case that has already passed the point where it applies. If it is not created, sentries that depend on it may never fire, and the case can complete without the new step.
- Creation: Decide per new element whether it should be created for existing instances, and confirm the initial state it receives.
- Entry criteria: Evaluate the new item's entry criteria against current variables before cutover, so it does not start on data that predates the new rule.
- Completion effects: Check whether an unfinished new item blocks stage or case completion through its required or completion rules.
- Work assignment: New human tasks create work for users who may not expect it. Confirm owners and notify them before the change goes live.
Test by migrating a sample of instances at each stage of progress, then check which new plan items appear, which stay absent and whether each case can still complete.
A removed element leaves running plan items with no definition to follow, and a renamed element looks to the engine like a removal plus an addition unless it is mapped explicitly. The migration must decide what happens to open work under each removed item and whether a rename keeps the same identity. Getting this wrong leaves orphaned work, duplicates tasks for the same activity, or drops history that reports depend on.
- Removal: Decide whether an active plan item of a removed element is terminated with a recorded reason or allowed to finish. Confirm in the docs for your version which of these the engine supports.
- Renames: Add an explicit mapping for a rename where the meaning is unchanged. Without it, the same work can appear twice.
- Orphaned variables: Variables that only fed a removed element may no longer be used, while variables the renamed element expects may be missing from older instances.
- Reporting and audit: Terminated items must remain readable in history, and reports that group by element name need updated labels so counts stay comparable.
Test removed and renamed elements against instances that are mid-flight, then compare task lists and history entries before and after the change.
Pre and post expressions run when a plan item transitions, and local variables are scoped to a stage or plan item rather than the whole case. The migration must decide whether expressions still evaluate correctly on migrated instances and whether local variables exist in the scope and type the new definition expects. Mistakes here often appear later, in the middle of a case, as wrong values, failed evaluations or sentries that decide on stale data.
- Pre expressions: Check whether a pre expression assumes an earlier step ran. On a migrated instance, that step may have run under the old definition with different output.
- Post expressions: Confirm post expressions do not repeat side effects such as notifications or external calls for work already completed.
- Local variable scope: Map variables from their old scope to the new one. A variable moved from case level to stage level is invisible to code that reads it at the old scope.
- Type and name changes: Confirm variable names and types match what new expressions read, since a mismatch fails during evaluation.
- Expression language and scripts: Verify that the expression language and any scripting are supported in your version, and review scripts for security implications.
Test expressions by replaying representative instances through each stage, then inspect variable values before and after each transition.
Sub cases are child cases started by case tasks, and they may be running under the old definition when the parent moves to the new one. The migration must decide whether each running child is terminated, left on its current version or migrated separately. Terminating a child ends its open work, while leaving it running can leave parent and child expecting different variable contracts. Blocking tasks add a further constraint, because a waiting parent cannot continue until its child resolves.
- Terminate: Stopping a child ends its open work. Confirm whether that work must be completed, reassigned or redone, and who is told.
- Keep: A child left on the old definition keeps its behavior, but the data passed across the parent boundary may no longer match. Verify it.
- Blocking versus non-blocking: Check where each parent is waiting before deciding. A parent blocked on a child that is terminated needs an explicit path forward.
- Migration order: If children migrate separately, plan the order so no parent calls a child definition that has been withdrawn.
- Business impact: Terminating a child can change reporting, service levels or customer communication, so get sign-off from the process owners.
Test parents and children in matched and mismatched versions, and confirm that waiting parents resume and terminated children leave a clear history entry.
Access, audit and data risks during a case migration
Migrating running case instances changes live data under live work, so the controls around the run matter as much as the mapping itself. The six considerations below cover who may act, what gets recorded, how sensitive variables are protected, how validation endpoints are secured, how the run can be reversed, and how expressions are reviewed before they touch production cases.
Who may run and approve
A case migration can change the state of every open case of a definition, so the people who plan, approve and execute it should be named and limited. Separate the person who builds the plan mapping from the person who signs off the production run, and confirm that your identity provider or Flowable's identity service grants the migration operation only to that approved group. Check who holds administrative accounts on the engine, because those accounts can bypass the approval you intended.
Audit trail for the run
Record the plan, the target definition version, the approver, the start and end times, and the count of instances moved and skipped in your change record before the run starts. Flowable history stores case data, but a migration record that ties those entries to an approved change is what an auditor will ask for. Confirm with your own team which fields your change process requires and export them alongside the engine's history.
Personal and regulated variables
Case variables often hold personal, financial or health data, and a migration copies or rewrites them. Inventory which variables each case carries, decide whether any must be excluded from logs or validation output, and confirm where migration diagnostics are written. Mask or avoid those variables in test exports, because a validation run against a copy of production data creates a second store that needs the same protection.
Securing validation endpoints
Validating a migration over REST exposes engine operations to whoever can reach the endpoint, so the validation API should sit behind your normal authentication and network controls and be disabled once the run is complete. Use a dedicated account with the narrowest rights needed, rotate its credentials after the window closes, and confirm that the endpoints do not return variable values you are not willing to show the operator.
Backup and rollback before the run
Take a database backup and record the deployed definition versions before any instance moves, and test restoring that backup in a non-production copy. Flowable's migration model moves instances between versions, so a rollback is a restore or a second planned migration, not an undo. Agree in advance which of these your team will use, who decides, and how long the paused cases can stay in their pre-run state.
Review of expressions before execution
Pre and post expressions run against live case data when instances move, so a typo or an unintended side effect can change many cases at once. Require a written review of each expression, confirm which variables it reads and writes, and rehearse it against a representative copy before production. Ask the engine team to confirm how expressions are evaluated in your configuration, and keep the reviewed version under version control so the approved text is the one that runs.
What validation over REST should catch before any instance moves
Validating the mapping over the CMMN REST API before any instance moves is the cheapest way to find out where a migration will fail. A dry run against a copy of production data shows which running cases would break under the new definition, so the team fixes the mapping while nothing has changed. The first thing to look for is unmapped active plan items: any plan item that is active in a running case and has no counterpart in the target version. Each one is a point where a case would stall or be left in a state the new model cannot explain. The validation output should list these per case, not as a single count, because a few high-volume case types usually carry most of the risk.
The second category is expressions that reference variables missing in the new version. Pre and post expressions, sentry conditions and variable event listeners are evaluated against case variables, and a revised model often renames or drops a variable that an expression still reads. Confirm the variable names each expression uses in the target definition, and check which of those variables exist on the running instances, since a variable added in the new version will not be present on cases that started before it. The third category is sub cases that would be orphaned: a child case or process started from a case task that has no parent plan item to report back to once the mapping changes. Check the parent-child links for each running instance and decide whether the child terminates, continues independently or is remapped.
Confirm which validation calls your Flowable version exposes before you design the process around them. The REST API surface for case migration has changed across releases, so check the endpoint list and request fields against the documentation for the exact version you run, and treat any call you cannot find there as unavailable. Then run the full validation, including the mapping, the expression checks and the orphan report, in a rehearsal environment built from a recent copy of production data, and compare its results with a real migration of a sample of cases. Record which findings the rehearsal missed so the checklist improves before the production run.
Limits to confirm in your own environment
Case instance migration depends on details that differ by Flowable version, database, runtime configuration and case model. The cards below list what to confirm against the documentation for your exact release and your own environment before you commit to a cutover plan. Each item affects whether a migration can be validated safely and how long the running system must be handled with care.
Migration behavior for your exact version
The mapping rules, endpoints and validation behavior for moving running case instances are tied to a specific Flowable release. Confirm the migration API and its REST endpoints in the documentation for the version you run, not for an earlier release you once tested. The 8.0.0 release notes are the starting point for the current major line, and any version-specific change should be re-tested in a non-production copy of your data.
Supported database and large instance counts
Flowable lists H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server as supported database types. Support for a database type does not tell you how a bulk migration will perform against your row counts, indexes and locking behavior. Ask for benchmark evidence or run a timed rehearsal on a production-sized copy, and confirm any MySQL version against the millisecond precision note in the configuration docs.
Async executor behavior during cutover
The async executor runs timers and asynchronous jobs from a thread pool and uses lock owners and lock expiration times stored in the database to coordinate nodes. During a cutover, confirm how jobs that are locked or due to fire are handled, whether you will pause job acquisition, and how expired locks are recovered on other nodes. Decide in advance whether timers may fire against old or new definitions while the migration runs.
Case model features that change migration
Plan item mappings are simpler when a case model keeps stable plan item identifiers and conservative sentry logic. Repetition rules, event listeners, sub cases and local variables can each change what a running instance needs after the move. Inventory these features in both the old and new definitions, and test each instance state that uses them rather than relying on a single happy-path example.
Java, Spring and Jakarta baseline changes
A move to a newer Flowable major version can also change the Java, Spring and Jakarta baseline your application must run on. Upgrading the platform and migrating case instances in one step multiplies the failure modes and makes root cause analysis harder. Confirm which baseline your release requires, whether your Spring Boot and JSON libraries are compatible, and whether the migration can be run on the old stack before the platform upgrade.
Commercial product terms if considered
If you evaluate Flowable Work, Engage, Orchestrate or Design, confirm the licensing, support and service terms in writing before design begins. The commercial products are built on the same engines, but their modeling, monitoring and governance features are separate contracts. Ask which support tier covers migration questions, whether professional services are included, and how upgrades to the commercial products relate to your open-source engine version.
Questions teams ask before migrating running Flowable cases
Can our internal team migrate running Flowable case instances without outside help?
Yes, a team with Flowable CMMN experience and access to the case models can do this in-house, and many do. The work is mostly careful mapping: matching each old plan item to a new one, deciding what happens to plan items that have no counterpart, and checking expressions against live data. Teams without prior experience with the CMMN runtime usually find the risk sits in the edge cases rather than the mapping itself. An outside partner adds value when the team lacks a rehearsal environment, lacks time to review every running sub case, or wants an independent check before production. Confirm which skills your engineers already have before deciding.
What drives the effort of a Flowable case migration?
Four factors matter most. The first is the number of running case instances, since each one must be checked against the mapping and tested. The second is the number of changed elements, including new plan items, removed items, renamed items and changed sentries. The third is sub case depth, because a parent case that calls child cases or processes must be migrated along with them, and their state must still make sense. The fourth is expression complexity, since pre and post expressions and local variables that read data from old versions need review for every affected element. Ask any provider to break its quote down along these four factors.
How long does it take to plan and rehearse a case migration?
Duration depends on the same drivers as effort: how many definitions change, how many instances are running, how deep the sub case trees go, and how complex the expressions are. Planning covers inventorying running instances, writing the mapping and reviewing it with model owners. Rehearsal means running the migration against a copy of production data in a non-production environment and validating results, ideally over the REST API first. Ask for a written timeline with separate phases for planning, rehearsal, approval and cutover, because approval time from your own change board is often the largest variable.
What does the migration need from our side?
Three things are needed early. First, model owners must confirm the business meaning of changed stages, milestones and tasks, because mapping errors usually come from misreading intent. Second, you need representative test data, meaning case instances in a range of states, including ones with open sub cases and local variables. Third, you need a non-production environment on the same Flowable version and database type as production. Plan for approval time from change and risk owners as well, since they must sign off on the mapping and the rollback path before any production instance moves.
Can we leave some case instances on the old definition version?
Yes, and that is often the safer option for long-running cases. Existing instances can keep running on their original definition while new cases start on the new version, which avoids migrating work that is close to completion. The trade-off is that you then maintain both versions for as long as old instances exist, and reporting, support and deployment steps must handle two definitions. Check how many instances remain on the old version over time, and decide in advance when a migration is required, for example before a dependent decision or integration is removed.
What should a quote for a Flowable case migration include?
A useful quote lists the scope in writing: the case definitions and versions covered, the number of running instances or the method for counting them, and the sub cases and processes in scope. It should itemize planning, mapping, expression review, rehearsal, validation, cutover support and handover of runbooks. It should state which environments are used, who approves the mapping, what happens if rehearsal finds issues, and what is excluded, such as changes to unrelated models or Flowable upgrades. Ask which costs are one-time and which recur, for example post-migration support, and request that any assumptions about your data and environments be written down.
How DeployOpen scopes and delivers a case migration
DeployOpen plans, builds, tests and documents Flowable case instance migrations inside your own infrastructure, starting from a written scope. The work moves running cases to a new definition version only after the mappings have been validated over the Flowable CMMN REST API in a non-production environment.
How we scope
- The written scope lists each case definition, version pair and the running instances in each state that must move.
- Plan item mappings for every changed element are reviewed with your case owners before any build work starts.
- Engagements are fixed-scope, so deliverables, timelines and exclusions are agreed in writing before work begins.
How we build
- Mapping files, pre and post expressions, and local variable handling are written and version-controlled alongside the case models.
- Terminations of sub cases are tested against copies of production data to confirm no unintended plan items are left behind.
- Validation runs over the CMMN REST API first, so each mapping is checked against real instance state before any live migration.
How we hand over
- Runbooks document the migration order, rollback steps and the checks to run after each batch of instances moves.
- Test evidence, mapping decisions and change records are delivered so your team can repeat or audit the migration.
- Knowledge transfer sessions walk your engineers through the tooling, expressions and validation scripts used on the project.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the initial migration closes.
- Post-migration monitoring checks for failed jobs and stalled plan items on the migrated instances during the agreed window.
- Future case definition changes can be planned as separate scoped work, reusing the mapping and validation approach.
