Flowable process instance migration: when running instances must move to a new version
When a process definition changes while instances are still running on the old version, those instances keep following the old model unless you move them. Flowable's process instance migration API, part of the BPMN engine's Java API, moves in-flight instances from one process definition version to another so they continue on the new model. It is aimed at platform and process teams who ship process changes to production and cannot wait for every case to finish before deploying, and at the architects who must decide whether long-running processes can tolerate a version change at all.
A migrated instance keeps its historic information, so audit trails and recorded activity from before the move remain queryable after it. That matters for regulated workloads, where the record of how a loan application or claim was handled must stay intact across a release. The engine treats the feature as part of the BPMN engine rather than a separate product, so the same Java API and the same database schema your deployment already uses are the foundation. Flowable open source is licensed under Apache 2.0, which governs how you may use and modify the engine in your own infrastructure. That licence is context for the decision, not a substitute for testing the migration against your own models.
Before you choose migration over letting instances finish on the old version, confirm three things with your process owners: how long instances typically run, which activities changed identifiers between versions, and whether any running instances sit in states the new model cannot represent. Flowable's docs describe a validation step that should run before any migration, and the exact checks it performs and their limits should be confirmed against the version your team uses, as detailed in the Flowable process instance migration docs. Treat the outcome of that check as the gate for the release, not as a formality.
How to validate a Flowable migration before running it
This sequence lets your team confirm, before any data changes, that each in-flight instance can move to the new definition version and that the mappings cover every activity that changed.
Confirm the source and target definitions
Identify the deployed process definition that running instances use today and the new version you intend to move them to. Record both definition keys and version numbers in the migration ticket so the validation run can be repeated exactly. Confirm that the new version is deployed to the same engine and database as the instances you plan to migrate. The step is done when both definitions are visible in the engine's repository and the team agrees on the source and target pair.
Diff activity IDs between the two versions
Compare the activity IDs in the old and new BPMN models, either by reviewing the diagrams side by side or by scripting a comparison of the XML. Activities whose IDs are unchanged are mapped automatically, so the list that matters is every activity that was renamed, split, merged or removed. Assign an owner to each changed activity and note the intended target. The output is a written list of activity pairs that the migration mapping must cover.
Write the activity migration mappings
Express each changed activity as an activity migration mapping in the Java code that drives the migration, following the pattern shown in the Flowable process instance migration documentation. Keep the mappings in version control next to the process definitions they belong to, so they are reviewed with the model change. Check the mapping class and method names against the docs for the Flowable version you run, because the exact API surface is documented there. The step is done when every changed activity from the diff has a mapping or a documented reason it does not need one.
Build the migration builder and validate
In code, call createProcessInstanceMigrationBuilder(), then migrateToProcessDefinition(...) with the target definition, then add your mappings and call validateMigration(...). Validation does not change any instance, so it can run against the instances you select without committing to the move. Confirm in the docs which return type validateMigration produces and which methods it exposes, since this page does not restate them. The step is done when the validation call returns a result object your code can inspect.
Review the validation result for each instance
Read the validation result for every selected instance and record which ones pass and which report problems. Typical findings to check include activities in the running instance that have no target in the new version and activities that have changed in a way the mappings do not cover. Treat any failure as a blocker until the mapping is corrected or the instance is excluded by a documented decision. The output is a result list that the migration owner signs off before any migrate call is made.
Rehearse on a copy of production data
Restore a recent copy of the production database into a non-production environment that runs the same Flowable version, the same database type and the same deployed definitions. Run the full validation there, using the instance selection your production run will use, so that the results reflect real active state rather than a few test instances. Ask your team to confirm that the copy is refreshed close enough to the planned run that instances have not moved far since validation. The step is done when the rehearsal result matches what the team expects.
Hand off validated mappings to the migrate run
Freeze the definition versions, mappings and instance selection that passed the rehearsal, and record them in the release record along with the Flowable version and database. Run the same migration code against production only after the approval is recorded, and keep the validation output as evidence of what was checked. If production state has changed materially since the rehearsal, rerun validation before migrating rather than assuming the earlier result still holds.
When activity migration mappings are required
The rule to plan around is simple: according to the Flowable docs, activities whose IDs are unchanged between the source and target definition versions map automatically, while activities whose IDs changed need explicit activity migration mappings. Before you start, compare the two BPMN files activity by activity and list every ID that is new, removed or renamed. That list, not the diagram, tells you how much mapping work the migration needs. Assume nothing about automatic mapping for a changed ID, because the engine cannot infer that a renamed task is the same task.
The changes that most often need a mapping are predictable. A renamed user task usually keeps its business meaning but gets a new ID when a modeler recreates the element. A subprocess that is split into two, or two merged into one, changes the scope in which running tokens sit. A replaced gateway, such as an exclusive gateway swapped for an inclusive one, changes the structure around active executions even when the surrounding tasks look identical to a business user. Each of these can leave a running instance sitting on an activity that does not exist in the target version, so the mapping must say where that execution should go.
A missed mapping should surface in validation, not at runtime. Run validateMigration(...) on the migration builder before calling migrate, and treat any reported gap as a blocking defect for that definition pair. Confirm the exact mapping syntax, the method names for declaring activity mappings, and how the validation output reports unmapped activities in the Flowable process instance migration docs before you write any code, because the API surface is specific to the version you run. Record each mapping in version control next to the BPMN change so reviewers can check it against the process design.
Migration options and when each fits
This table compares the main choices for moving running Flowable instances to a new definition version. Read each row for when the option fits and the trade-off you accept, then match the choices to your release risk and the number of instances on the old version.
| Decision | When it fits | Main trade-off |
|---|---|---|
| Migrate all instances at once | A small, known set of instances, a short window, and a team ready to roll back if validation output surprises them | A single run touches every matching instance, so a mapping error affects the whole population together |
| Batch migration | Large populations, or instances that must move in controlled groups while the business keeps working | Two versions run side by side for longer, so support, reporting and new-release fixes must account for both |
| Validate-only run | Before every production migration, and whenever activity mappings change | Validation reports problems but changes nothing, so it does not prove the data state will stay the same at run time |
| Migrate after validation passes | Standard practice for any migration that will touch live instances | Validation results can go stale if instances move on, so repeat the check close to the actual run |
| Automatic mapping | Activities keep the same IDs between versions, so the engine can match them without extra configuration | Only works for unchanged IDs; renamed or split activities fail validation or land in unexpected places |
| Explicit activity mappings | A task or activity ID changed, or one step became several, and in-flight instances must continue at the right point | Every mapping is maintenance to write, test and review, and a wrong mapping is easy to miss until a test case covers it |
| Migrate in place | Business rules require current instances to follow the latest logic, and the change is backward compatible for running work | Instances skip the old logic immediately, so any change in meaning or missing variables must be handled before the run |
| Leave instances on the old version | Changes are large, data contracts differ, or instances are near completion and finishing on the old logic is safer | Old versions stay deployed and tested for longer, and the team must track which instances remain on each version |
Batch migration and history handling
Migrating a few instances is a single call, but a large running population needs batching, a record of which version each instance ran on, and a clear view of what history remains afterward. The cards below cover the decisions that connect those concerns for a Flowable migration.
Batch instances to limit blast radius
Split the affected population into batches sized to the load your database and async executor can absorb, rather than moving every instance in one run. A failed batch can then be inspected and retried without repeating work already completed. Ask the team to confirm how the Flowable batch migration API groups instances and how it reports partial failures in your Flowable version before choosing batch boundaries. Run a small pilot batch in a non-production copy first.
Validate every batch before running it
Call validateMigration on each batch's migration builder before calling migrate, so mappings that do not resolve are reported before any instance changes. Treat validation output as the gate for each batch and keep the report with the change record. Validation confirms the mapping, not the business outcome, so the team should still test representative instances that are waiting on user tasks, timers or called subprocesses.
Migrated instances keep their history
The Flowable docs state that a migrated instance keeps its historic information. Activities completed on the old definition stay recorded against the old version, so reports that join history to definitions must handle both versions. Confirm with your Flowable version how historic activity and task rows reference the definition ID before writing queries that assume a single version per instance.
Trace the version before and after
Record the process definition ID and version for each instance before the migration, then query the same identifiers afterward to confirm the move. Store the mapping from old to new definition as part of the change record, so an auditor or support engineer can answer which version an instance ran on at any point. This is the evidence that links the migration to the instance-level history.
Retention decides what evidence survives
The history level and cleanup schedule decide how much of the pre-migration execution remains. If history is set to a low level or old rows are cleaned on a schedule, the record of activities run on the old version may be gone before anyone needs it. Review the history level and cleaning settings with the compliance owner before the migration, and see the history levels topic for the retention choices themselves.
Plan releases to avoid stranded instances
Long-running instances can stay on an old version for months if no migration is planned, which multiplies the number of versions your team must support. Set a release practice that names when old definitions are migrated or retired, and track how many instances remain on each version. Ask the team to confirm how the engine handles deletion of definitions that still have running instances in your version.
Release practices that avoid long-lived instances on old versions
Treat instance migration as a routine release step, not an emergency fix. Before each change to a process definition, run an inventory of running instances grouped by definition version, using the engine's query APIs on the process definition key. The inventory tells you how many instances sit on each version, how old they are, and which activities they are waiting in. For each change, decide whether those instances should be migrated to the new version or allowed to drain on the old one. Migrate when the change is a fix or a field addition that maps cleanly onto existing activities. Let instances drain when the change alters the flow in a way that would make the mapping risky, and record the decision with the change ticket so the reason is still visible months later.
Long timers and human tasks are the usual reason instances stay on old versions. A process that waits thirty days for an approval or a deadline timer may outlive several releases, and nothing in the engine forces it to move. Set a deadline for each old version, after which remaining instances are migrated in a batch or cancelled by an agreed rule, and make the owner of that deadline explicit. Monitor the count of instances per version over time, not just once, so a stalled cohort shows up before it becomes a support problem. Confirm with your Spring Boot version how the /actuator/flowable endpoint exposes running process details, since the exact fields and whether counts per definition version are available should be checked in the Flowable docs and in your own environment before you build dashboards on them.
Setting up migration in a Flowable project
This sequence moves in-flight Flowable process instances to a new definition version in controlled stages, so each batch is validated, checked and recorded before the next one starts. The output is a migration record that shows which instances moved, which were held back and why.
Confirm the engine version and migration API
Before any design work, the engineering lead confirms the Flowable engine version in use and checks that the process instance migration builder is available in that version's Java API. Record the version in the migration plan, along with the Spring Boot or servlet container baseline your application runs on. Confirm this against the Flowable process instance migration documentation for your exact version, because the API surface differs between releases. The step is done when the team can call the builder in a test class against a deployed definition and get a result without errors.
Deploy the new definition beside the old one
The development team deploys the new process definition version to the engine without retiring the version that running instances use. Both versions stay deployed so that instances in flight can still execute and so the migration builder can reference the source and target definitions. Confirm that each deployment has its own definition ID and version number, and that the deployment pipeline records which artifact produced each one. The step is done when a query for both definition keys returns the expected versions in the target environment.
Build and review the activity mappings
The process owner and a Flowable developer compare the old and new BPMN models activity by activity. Activities whose IDs are unchanged map automatically, so the review focuses on renamed, split, merged or removed activities, which need explicit activity migration mappings. Each mapping should name a source activity and a target activity, and the review should record any source activity that has no valid target. The step is done when every activity in the old model is either mapped, unchanged or explicitly marked as one that will block migration.
Validate the migration on staging copies
The developer runs the migration builder with validateMigration against a copy of production data restored into a staging database, and reviews every reported problem. Validation should be run before migrate is called, and any instance that fails validation is listed with its current activity and the reason. Fix the mappings or the target model, then repeat until the validation output is clean or the remaining cases are agreed to be handled separately. The step is done when the team has a written list of instance states that cannot migrate and a decision for each.
Run a pilot batch in production
The operations lead selects a small, low-risk set of production instances at the same stage and migrates them with the same mappings used in staging. The team checks that each migrated instance continues on the expected activity, that its variables are intact, and that its history still shows the earlier activities. Confirm that the async executor jobs for these instances run on the new definition and that no failed jobs appear. The step is done when the pilot instances have been reviewed and the team agrees the mappings are safe for the rest of the population.
Migrate production in checked batches
The operations lead migrates the remaining instances in batches, selecting each batch by process state so that instances at the same activity move together. After each batch, the team checks the count of migrated instances, the count of failures, the job queue for new errors and a sample of instances against the expected activity. A batch that shows unexpected failures or stuck jobs pauses the run until the cause is understood. The step is done when a batch completes with the expected counts and no unresolved failures.
Record results and retire the old version
The engineering lead writes a migration record that lists the source and target versions, the mappings used, the validation output, the pilot results, each batch's counts and any instances handled manually. Keep this record with the release documentation so auditors and future maintainers can trace what changed and why. Retire the old definition only after a confirmed query shows no running instances on it, and confirm the retirement with the process owner. The step is done when the record is stored and a query for the old version returns no active instances.
Security and operational risks of migrating live instances
Moving running instances to a new definition version changes data that the business depends on, and the engine does not decide who may do it, how it is recorded, or how far it can be undone. The cards below cover the risks that connect authorization, audit, failure handling, database load and rollback, each with the check to make before the first production run.
Who may run migrations
Flowable does not decide which users or services may start a migration. Your application must restrict the migration builder to a named operator role, or to a deployment pipeline identity, and reject requests from anyone else. Check that the same restriction covers the REST endpoints and any admin screens, not only the code path your team uses. Confirm which accounts can reach the migration API in each environment, including staging copies that hold production-like data.
Audit trail of migrations
A migration changes which definition a running instance follows, so auditors will ask who moved which instances and when. Record the operator identity, the source and target definition versions, the instance selection criteria, and the run timestamp in your own log or ticketing system, because the engine history shows the instance's history but not the approval behind the move. Keep the approval reference with the batch record. Verify that these records survive the history cleaning schedule you configure.
Failed and partial batches
A large batch can stop midway after some instances have moved and others have not. Plan how your run will be resumed, which instances are selected on rerun, and how to find instances still on the old version after a failure. Treat each instance as the unit of success, and re-run validation before retrying so a changed instance state is not migrated blindly. Ask your team how the batch reports individual failures and whether a retry is idempotent for your mappings.
Database locks and transaction size
Migrating many instances in one transaction holds database locks on the runtime tables for the length of the run and can block job execution and user task completion. Split large populations into smaller batches, run them in a low-traffic window, and watch lock waits on the database during the first batch. Size each batch with a rehearsal in a copy of production data, and confirm your database platform's locking behavior before the run. Coordinate with the async executor so timers do not fire against instances mid-move.
Rollback limits
A migrated instance cannot be assumed to return cleanly to the old definition. Once tasks, activity IDs or variables have been mapped to the new version, reversing the move may require a second migration with its own mappings, or it may not be possible at all for some changes. Decide before the run which states you will accept as a rollback target, keep the old definition deployed for as long as instances still need it, and test the reverse mapping in staging. Do not treat a deleted old definition as a safe fallback.
Scoping mappings to the change
Activities whose IDs are unchanged between versions map automatically, while changed activities need explicit migration mappings. A mapping written for one release can misroute instances if a later edit reuses an ID for a different purpose. Review every mapping against the BPMN diff, confirm that unmapped active activities are caught by validation, and keep the mapping file under version control with the release that introduced it.
Questions teams ask before migrating Flowable instances
What drives the effort of migrating Flowable process instances?
The effort depends mostly on how much the new process definition changed from the old one. If activity IDs stay the same, the Flowable docs state that those activities map automatically, so the work is largely validation and testing. Changed or removed activities need explicit activity migration mappings, and each mapping must be reasoned through for every instance that could be waiting at that point. Other drivers include the number of running instances, how many definition versions are in flight at once, whether variables need transformation, how many integrations call into the process, and how much history the business needs to keep. Ask for an inventory of affected definitions and a count of running instances per version before estimating anything.
Can our own team migrate Flowable instances without outside help?
A capable Flowable team can migrate instances in-house if it has engine experience, a test environment that mirrors production data, and time to build and run validation. The validation step matters most: the Flowable docs show calling validateMigration on the migration builder before running migrate, so the team can see problems without changing data. Outside help is most useful when mappings are complex, when many versions must move together, or when the team has not yet operated the engine at scale. Whichever route you take, the work should be written down as a scope with named deliverables before it starts.
How long does a migration pilot take, and what changes the duration?
No fixed duration applies, because the pilot length depends on instance volume, the number of activity mappings that need design, and how many environments must be tested before production. A pilot on a small set of representative instances usually runs faster than a full-volume rehearsal, but the rehearsal is what proves batch runtime and rollback behavior. Ask any partner, including DeployOpen, for a schedule that lists the mapping work, validation runs, rehearsal runs and sign-off gates separately, so you can see which items drive the calendar.
What does the migration need from our team, such as test data and sign-off?
The work needs business owners who can confirm that each mapped step means the same thing in the new version, and engineers who can supply production-like data. Test data should include instances at different points in the process, including those waiting on timers, messages, and user tasks, because those are where mappings most often fail. Business sign-off should cover the mapping decisions for each changed activity and the expected outcome for instances that cannot be mapped. Plan time from both groups before the pilot starts, since waiting on data or decisions is a common cause of delay.
Does a migrated instance keep its history?
According to the Flowable docs, a migrated instance keeps its historic information, so audit and reporting data recorded under the old version remains available after the move. Confirm this against the Flowable version and history level you run, and test a migrated instance's history query before go-live. Also decide how history from old definition versions will be read by reports once the old definitions are retired, because that choice affects both audit evidence and database size.
When should we choose not to migrate running instances?
Not migrating is a valid choice when the change is small, when the number of instances on the old version is low and will finish soon, or when mapping work would cost more than letting instances complete. Another option is to keep both versions deployed until the old instances drain, which works well when process lengths are known and bounded. Avoid leaving instances on old versions indefinitely, since every extra version adds support and testing load. Make the decision per change, and record which instances will run to completion and which will be migrated.
How do we avoid long-lived instances on old versions in future releases?
Plan process changes so that most instances finish within a known window, and keep activity IDs stable where possible so future changes need fewer mappings. Set a release practice that names the migration approach for each change before the new version is deployed, and track instance counts per definition version on a dashboard. Teams that review version counts at each release usually catch stranded instances early. Ask your Flowable engineers to document the chosen approach for each release in the change record.
How DeployOpen scopes and delivers Flowable migrations
DeployOpen plans and delivers Flowable process instance migration as a fixed-scope engagement inside your own infrastructure. We start from the process definitions and running instances you have, validate each planned move before anything changes, and hand over the mappings, runbooks and tests your team needs to repeat the work.
How we scope
- We inventory deployed process definitions, their versions and the count of instances still running on each
- The written scope names which definition versions move, which activity mappings are needed and which instances stay put
- We agree how migration validation results are recorded and who signs off before a batch runs
- Scope states the history retention expectations for migrated instances and the cleanup work they require
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
How we build
- We write the migration builder logic and run validateMigration against a copy of production data first
- Activity migration mappings are built for every activity whose ID changed between the old and new versions
- Batch migration jobs are scripted with logging, so each instance outcome can be traced after the run
- We test migrated instances through their remaining steps, including timers, subprocesses and call activities
- Tests run in non-production environments that mirror your database type and engine configuration
How we hand over
- You receive the mapping definitions, migration scripts and validation reports as versioned source in your repository
- Runbooks describe pre-migration checks, rollback decisions and how to rerun a failed batch safely
- We document which instances were migrated, which were left on old versions and why
- Knowledge transfer sessions walk your engineers through the validation and batch process end to end
- Release practices are written down so future versions avoid long-lived instances on retired definitions
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the initial migration
- Retainer work can cover migration of later definition versions as your process models change
- Support can include reviewing new deployments for activity IDs that will need mappings
- Confirm with your team which Flowable version and database you will run before scoping support terms
- Ask any partner how they handle failed batches, since recovery steps shape operational risk
