Co-authored by @Pere Fernandez

When deploying Process Definitions as Business Services in a cloud environment, process instances follow the sequence flow defined in the deployed Process Definition. But what happens when these instances are long-running, waiting on timers or user tasks for weeks or even months, and you need to update the deployed Process Definition? Without intervention, those process instances remain tied to outdated workflows, potentially leading to inconsistencies and operational issues.

Introducing Process Instance Migration (PIM)

To solve this challenge, BAMOE 9.3.1 introduces Process Instance Migration (PIM). This feature allows process instances to migrate to newer versions of their Process Definitions by mapping nodes from the original definition to nodes in the target definition. Once migrated, process instances follow the updated sequence flow, ensuring alignment with the latest business logic.

Why It Matters

• Keeps long-running processes aligned with evolving business rules.

• Reduces operational risk caused by obsolete workflows.

• Enables flexibility to adapt processes without restarting instances.

How to use BAMOE PIM?

Prerequisites (BAMOE PIM Add-on)

BAMOE 9.3.1 introduces the BAMOE PIM Add-on which is shipped as part of the BAMOE BOM, and adding it to your Business Service is straightforward. It enables the PIM REST API, which is also used by BAMOE Management Console. Add the dependency to your pom.xml:

For Quarkus

<dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-addons-quarkus-pim</artifactId>
</dependency>

For Spring Boot

<dependency>
  <groupId>com.ibm.bamoe</groupId>
  <artifactId>bamoe-addons-spring-boot-pim</artifactId>
</dependency>

In addition to the BAMOE PIM Add-on dependency, you must also update your database schemas by running the SQL scripts which will create the PIM tables and necessary indexes. Here are the tables description:

Concepts

BAMOE PIM operates in two major phases: Plan creation and Plan execution.

1. Plan creation: Define the source and target Process Definitions and the explicit node mappings, if required.

2. Plan execution: Execute the PIM Plan to migrate process instances that match the criteria to the new Process Definition.

What happens during migration?

PIM does more than just switch process definitions, it ensures consistency across subsystems:

• Subsystem adaptation: Migrates process nodes and updates associated elements in subsystems like data-index and user tasks. Jobs do not require adaptation. After migration, the Business Service remains fully functional through both REST APIs and UIs.

• Active elements only: PIM migrates only active elements (active node instances, active user tasks, etc.). Nodes that are not longer active will not be migrated.

• Data handling: PIM does not migrate data stored in process variables or task variables. If your new Process Definition contains additional variables, they will be initialized with an empty value. If your data model changes, you must ensure backward compatibility. Otherwise, PIM cannot properly migrate process instances, and you’ll need to use alternative strategies, such as draining out existing instances.

Mapping rules and limitations

To maintain process integrity after migration, PIM has some strict mapping rules. For node mappings PIM has implicit or explicit node mappings.

• Implicit node mapping: All nodes that can be on a waiting state in the source process definition must exist in the target process definition with their original node ID.

• Explicit node mapping: When implicit mapping is not satisfied you need to provide explicit node mappings, and it has some rules:

• Nodes type: Only nodes that can put the process instance in a waiting state (catch events, user tasks, work items, call activities/subprocesses) should be included in the explicit mapping list, since only active elements are migrated.

• Same family mapping: Nodes must map to nodes of the same type. For example, a user task cannot be mapped to an event.

• Removed nodes: If a node is removed in the target process definition, the source node must be explicitly mapped to a node of the same family in the target process definition.

• User Task limitation: Tasks in BPMN are immutable in the user task subsystem. To modify task details during migration, define a new task with a different ID and node ID in the target process definition and map accordingly.

Using PIM through REST API

For teams that prefer automation or integration over UI, BAMOE exposes a REST API for Process Instance Migration. Below is a quick overview of the most important endpoints.

Managing PIM plans via REST API

POST /pim/plan: Create a new migration plan that defines how process instances move from a source process to a target process.

Payload fields:

• sourceProcessId (String) – ID of the source process.

• sourceProcessVersion (String) – Version of the source process.

• targetProcessId (String) – ID of the target process.

• targetProcessVersion (String) – Version of the target process.

• nodeMapping (List) – Optional list of node mappings (sourceId → targetId).

Example:

{
  "sourceProcessId": "hiring",
  "sourceProcessVersion": "1.0",
  "targetProcessId": "hiring2",
  "targetProcessVersion": "1.0",
  "nodeMapping": [
    {
      "sourceId": "_B8C4F63C-81AD-4291-9C1B-84967277EEF6",
      "targetId": "_CBB6BF5D-21DA-43D2-A20B-C361694AF7AE"
    }
  ]

Response:
Returns the plan details, validation status, and warnings/errors if any.

GET /pim/plan/{planId}: Fetch details of a specific migration plan, including mappings and validation results.

DELETE /pim/plan/{planId}: Remove a migration plan that is not currently in use.

GET /pim/plans: Retrieve all migration plans, with optional filters using query params:

• sourceProcessId

• targetProcessId

Managing migrations via REST API

POST /pim/migration: Executes the migration of active process instances from the source to the target process definition using the specified migration plan.

• Full migration: If no instance IDs are provided, all active process instances of the source process will be migrated.

• Bulk migration: Provide a list of process instance IDs to migrate a subset.

Performance Note:
Migrations can take time due to heavy database updates. You can configure the transaction timeout in application.properties:

bamoe.pim.transaction-timeout=<seconds>

Database Limits for Bulk Migration:

Each database has a maximum number of parameters allowed in an update operation. This affects how many process instance IDs you can include in a bulk migration request. Below are the limits for each supported database:

• H2 → 50,000 IDs

• PostgreSQL → 50,000 IDs

• Oracle → 1,000 IDs

• MS SQL Server → 2,000 IDs

{
  "planId": "<plan_id>",
  "processInstanceIds": ["id1", "id2", "id3", ...]
}

Response:

• migrationId: Unique identifier for the migration.

• migratedProcessInstancesCount: Number of instances migrated.

• skippedProcessInstanceIds: IDs that were not migrated (if any).

{
  "status": 200,
  "message": "Migration finished",
  "data": {
    "migrationId": "<migration_id>",
    "planId": "<plan_id>",
    "migratedProcessInstancesCount": 100000
  }
}

GET /pim/migration/processes/{processInstanceId}: Returns the list of migrations associated with a given process instance, including timestamps for when the migration was created and applied.

{
  "status": 200,
  "message": "Retrieved migrated process instance",
  "data": [
    {
      "migrationId": "<migration_id>",
      "processInstanceId": "<process_instance_id>",
      "planId": "<plan_id>",
      "createdAt": "2025-11-20T00:00:00.000+00:00",
      "appliedAt": "2025-11-20T15:23:58.910+00:00"
    }
  ]
}

Using PIM through BAMOE Management Console

To simplify the migration process, BAMOE provides a dedicated UI integrated into the BAMOE Management Console. If your are not familar with BAMOE Management Console, check out the BAMOE Documentation(https://www.ibm.com/docs/en/ibamoe/9.3.x?topic=services-managing-live-workflows-using-bamoe-management-console). This UI leverages the PIM REST API (enabled by the BAMOE PIM Add-on) to create and execute migration plans visually.

Prerequisites

• As mentioned before on this blog, include the BAMOE PIM Add-on dependency in your Business Service pom.xml.
  Without this, the PIM UI will display an error: “BAMOE (PIM) Add-on is missing.”

• Select a specific Business Service for migration. The PIM UI does not support multi-service visualization.

Once these requirements are met, you can access Process Instance Migration under Advanced in the BAMOE Management Console.

PIM Plans

The migration process starts with creating a PIM Plan, which defines:

• Process Mapping: Source and target Process Definitions.

• Node Mapping: Mapping between nodes in the source and target definitions.

Select your source and target Process Definitions. When you select them, the SVG diagrams will be loaded if available in your Business Service. Once the processes are selected, the node mapping options will appear. Map nodes as required, following the previously discussed mapping concepts. If you’re using SVGs generated with the new BPMN Editor, selecting nodes will highlight them in the diagram.

Click “Create PIM Plan” to open the plan summary, review its content, and click Confirm if everything is correct. A validation will run automatically and check for any errors or warnings based on the previously discussed concepts.

After the plan is created, you can either go to the Plan Execution page by clicking “Go to PIM Plan”, or stay on the current page and create another plan by clicking “Create another PIM Plan”.

Executing a PIM Plan

On the Execution Page, you can choose between “All Process Instances”, which migrates all matching instances, or “Select Process Instances”, which migrates a subset based on filters. The currently available filters include process instances by ID, start date, last updated date, and SLA due date.

All Process Instances has no execution limit but for Selected Process Instances, limits apply:

• Max 1,000 instances per request

• Max 50 iterations per migration (up to 50,000 instances total)

To proceed with the migration execution, click “Execute PIM Plan” to open the Execution Summary. Review its content and check for warnings. Ensure the system is not exposed to consumers during migration, and keep a database backup ready before proceeding.

Finally, click “Execute PIM Plan” to perform the migration. Migration time depends on the number of instances. At this step, there are two different behaviors depending on your previous selection.

• All Process Instances:

  Migration is interruptible. After completion, you’ll see a “Migration finished” message. If an error occurs, migration will not happen.

  

• Select Process Instances:

  Migration can be interrupted anytime by pressing “Stop new migrations”. Already migrated batches will not roll back.

• Migrating without stop:

• Migrating without stop:

Step-by-Step PIM Operation Overview

Before starting with the migration, ensure your Business Services are upgraded to BAMOE 9.3.1.
Important: PIM does not migrate data, so the source and target Process Definitions must be compatible.

Here’s the recommended migration flow:

Moment 0 (baseline)

Your Business Service (BSv1) and Process Definition (PDv1) are running in production.

Moment 1 (New deployment + Create PIM Plan)

Deploy a new Business Service (BSv2) with both PDv1 and PDv2. They must have different IDs. This new service is internal only, use this stage to validate and fix issues. You can redeploy as many times as needed. BSv2 is still not exposed to the outside world yet, so it is only available internally.

Moment 2 (Downtime)

Ensure all Business Services connected to the database are inaccessible during migration. Performing updates on the database during migration can result in data loss, errors, or even corruption. Therefore, it’s crucial to back up the database before proceeding.

Moment 3 (Execute PIM Plan)

Execute PIM on BSv2. BSv1 remains available for rollback if needed. After execution, validate that BSv2 is working correctly.

Error Recovery

If an errors occur:

• Restore the database from backup done on Moment 2.

• Remove BSv2 and reconnect BSv1.

• Reassess and deploy a BSv2.1 that is compatible with BSv1.

Moment 4 (New basiline)

After successful validation, remove BSv1. This becomes your new baseline.

Moment 5 (optional clean up)

After Moment 4, the BSv2 will have the PDv1. If you want to remove PDv1 from BSv2 you must:

• Deploy BSv2.1 without PDv1. This is possible because BSv2.1 is a subset of BSv2, so this wouldn’t have compatibility issues.

• Remove BSv2 after BSv2.1 is running.

Best Practices

• Avoid running migrations on a live system to prevent data corruption.

• Always back up your database before executing a migration.

Wrapping Up

Process Instance Migration in BAMOE 9.3.1 gives organizations the flexibility to keep long-running workflows aligned with evolving business logic, without restarting instances. By following the recommended steps and leveraging the BAMOE PIM Add-on and BAMOE Management Console, you can ensure smooth, risk-free migrations.