BPM Migration

Introduction

The BPM Migration feature allows you to migrate running process instances from one version of a BPM model to another. When a BPM model is updated and redeployed, existing instances may still be running on the previous version. The migration tool provides a controlled way to move these instances to the new version by mapping nodes between versions.

Access

Navigate to: Application Builder > BPM components > Technical monitoring > BPM Migration

BPM Migration grid

Configuration

Creating a Migration

BPM Migration form

To create a new migration:

  1. Select the Source version (1): The BPM model version from which instances will be migrated.

  2. Select the Target version (2): The BPM model version to which instances will be migrated. The available target versions are filtered based on the selected source version (only other versions of the same model are shown).

  3. Optionally check migrate all the instances of previous version (3): When enabled (upgradeAllInstances), every running instance of the source version is migrated, not only a single instance. The outcome is reported in the Migration report panel (see Migration Report).

  4. Click Generate Node Mapping (4): This automatically generates a mapping between the nodes of the source and target versions.

  5. Optionally check Remove old version menu (5): If enabled, the menu associated with the old version will be removed after migration.

Both source and target versions must be selected before generating the node mapping.

Node Mapping

After generating the node mapping, a dashlet displays the mapping between source and target nodes for each process in the model:

For each process:

  • The Source node column displays the nodes from the source version.

  • The Target node column provides a dropdown selector allowing you to choose the corresponding node in the target version.

The system automatically suggests matching nodes based on their identifiers.

Executing the Migration

Once the node mapping is configured:

  1. Review the mapping for each process to ensure correctness.

  2. Click the Migrate button at the bottom of the mapping dashlet.

  3. The system will migrate all running instances from the source version to the target version, updating the activity positions according to the node mapping.

Migration is an irreversible operation. Ensure that the node mapping is correct before executing the migration.

Migration Report

When migrate all the instances of previous version is enabled, the migration processes every running instance of the source version and records the outcome in the Migration report panel of the form:

Field Description

Total instances to migrate

Number of running instances found on the source version (totalInstancesToMigrate).

Successful migrations

Number of instances migrated without error (successfulMigrations).

Failed migrations

Number of instances whose migration raised an error (failedMigrations).

When at least one migration failed, an Instances not migrated due to error button appears. Clicking it opens the grid of WkfInstance records whose migrationStatusSelect is set to Migration error (value 3) for the source version, so you can inspect and fix the failed instances individually.

Migrations are processed one instance at a time. A failure on one instance does not stop the others; the failed instances are simply counted in Failed migrations and listed through the error button.

Instance-Level Migration

Migration can also be triggered from a specific process instance form. In this case:

  • The Source version is pre-set to the instance’s current version and is read-only

  • You only need to select the Target version and generate the node mapping

  • Only the selected instance is migrated (not all instances of the source version)

This is accessible from the Process instance view under BPM components > Technical monitoring > Process Instances.

Auto-Migration During Deployment

When a new version of a BPM model is deployed, the system can automatically migrate running instances. This auto-migration:

  1. Finds all running process instances from the previous deployment

  2. Matches process definitions between old and new versions by their process key

  3. Builds a Camunda MigrationPlan based on the migration mapping

  4. Migrates each instance individually, updating:

    • The process definition version

    • Active activity positions

    • Event triggers for intermediate catch events

    • Active user tasks (via wkfUserActionService.migrateUserAction())

If any individual instance migration fails, an error status is recorded for that instance, but the deployment continues for other instances.

Auto-migration during deployment uses the migration map provided in the deployment dialog. If no migration map is provided, running instances remain on the previous version.

Migration Locking

To prevent two concurrent migrations of the same model, a deployment that carries a migration sets a lock on the target WkfModel (isMigrationOnGoing = true) while the migration runs. If a deployment is triggered while a migration is still ongoing, it is rejected with the message Migration is already ongoing. and no second migration is started.

The lock is cleared automatically:

  • when the migration completes (whether it succeeded or recorded per-instance errors), and

  • when an unexpected error aborts the deployment — the controller resets isMigrationOnGoing to false so the model does not stay locked after a failure.

This is handled by BpmDeploymentService.setIsMigrationOnGoing(), called from WkfModelController.deploy().

Migration History

Each process instance maintains a migration history that records version transitions. This history is accessible from the process instance view and includes:

  • Version code: The version identifier

  • Created on: When the history entry was created

  • Updated on: When the migration was applied

  • Open editor: A button to open the BPM editor for the corresponding version

Technical Details

WkfMigration Entity

Field Type Description

sourceVersion

M2O: WkfModel

Source BPM model version

targetVersion

M2O: WkfModel

Target BPM model version

mapping

Large String

JSON data containing the node-to-node mapping

removeOldVersionMenu

Boolean (default: false)

Whether to remove menus from the old version after migration

upgradeAllInstances

Boolean

When true, migrate every running instance of the source version

totalInstancesToMigrate

Integer

Number of instances found for migration (report)

successfulMigrations

Integer

Number of instances migrated successfully (report)

failedMigrations

Integer

Number of instances whose migration failed (report)

WkfInstanceMigrationHistory Entity

Field Type Description

wkfInstance

M2O: WkfInstance

The migrated process instance

versionCode

String

Version identifier of the model

versionId

Long

Database ID of the WkfModel version

migrationHistoryUpdatedOn

DateTime

When the migration was applied

Backend Services

  • WkfMigrationController — Handles form actions: generate node map, set target version domain, execute migration

  • WkfMigrationServiceImpl — Core migration logic: node mapping generation, Camunda migration plan creation, instance migration

  • BpmDeploymentServiceImpl.migrateRunningInstances() — Auto-migration during deployment