How do instance migration policies work when installing a new snapshot in BAW (migrate, leave, delete)?

Question

When we install a new snapshot of a process app on the Process Server, the dialog offers options for the running instances. What exactly do "migrate", "leave on the old snapshot" and the migration policy files do, and how do we handle instances that cannot be migrated?

Answer 1

Every install of a new snapshot has to decide what happens to the running instances of the previous snapshot; the engine offers three behaviours and a policy file to fine-tune them:

• Migrate instances - the running instances are re-pointed to the new snapshot: their execution contexts are mapped onto the new model (activities by id, variables by name), and the next step runs on the new version. Fails per instance when the model changed incompatibly (an activity the token sits on no longer exists, a variable type changed) - those instances stay on the old snapshot and are listed in the migration result.
• Leave instances on the old snapshot - old instances finish on the old version (both snapshots stay installed and active); new instances start on the new default snapshot. The safe default for big changes; delete / archive the old snapshot only when its instance count is zero.
• Delete instances - only for test environments.

Migration policy file (BAW 20+, Operations REST / Process Admin): an XML that pins how specific artifacts migrate - which activities are considered equivalent (renamed activities), which instances to include (by process, by state), and whether tasks in progress are kept:

<!-- migration policy: map a renamed activity, exclude a process, keep open tasks -->
<migrationPolicy xmlns="http://www.ibm.com/xmlns/bpmnx/migration">
  <processMigration name="Order Handling" includeInFlight="true" keepOpenTasks="true">
    <activityMapping sourceActivityId="8d1f7b3a-…" targetActivityId="c2a0e5d9-…"/>   <!-- old "Approve" -> new "Approve order" -->
  </processMigration>
  <processMigration name="Batch Cleanup" includeInFlight="false"/>
</migrationPolicy>
# apply with the Operations REST API (BAW 20+) after installing the new version
POST /ops/std/bpm/containers/migrate?container=ORD&source_version=2.2&target_version=2.3&policy_file_name=ord-2.3.xml
GET  /ops/system/queue/{id}      -> progress and per-instance results

Practice: test the migration on a copy of production instances (a test server with restored data), keep old activities in the model until their instances drained (question on migrating old instances), and read the migration report - instances that failed to migrate are still running on the old snapshot, they are not lost. On CP4BA the same APIs and policies apply to Workflow Servers.

References

• Operations REST API - migrating instances with a policy
• BAW documentation - migrating process instances to a new snapshot