Instance migration ("in-flight" upgrade) moves running instances from the old snapshot to the new one when the new snapshot is installed with Migrate instances (Process Admin > Installed Apps, or the BPMConfig / Operations REST migration policy). It fails when a running instance sits on something the new model no longer has or when data shapes changed. Rules that keep it safe:
- Never delete or rename activities that running instances can be on - keep the old activity (hide it with a gateway that new instances skip) until the old instances have left it; rename only the label, not the id (the designer keeps the id when you edit the name field, and changes it when you delete + recreate).
- Add, do not change, variables - new variables get their default on migrated instances; changing a type (String → Integer, single → list) breaks the execution context. Add a new field and migrate the value in a script at the next step.
- Coaches and services can change freely - an open task keeps the old coach until it is completed; the next task uses the new version. Service flow changes apply to the next call.
- Nested / linked processes: a running linked process instance stays on its old snapshot until it ends; the parent migrates.
- Test: install the new snapshot on a test server that has copies of production instances at every step (or create them with a test data generator), migrate, and run each instance through to the end. The Process Inspector shows migration errors per instance; the Operations REST (/ops/std/bpm/containers/migrate) returns a queue you can poll.
- Fallback: keep the old snapshot installed and active alongside the new one (default = new); instances that cannot migrate finish on the old version (leave in-flight instances on the old snapshot option); delete the old snapshot only when its instance count is zero.
# migrate instances of a container to the new version with a policy (Operations REST, BAW 20+)
POST /ops/std/bpm/containers/migrate?container=ORD&source_version=1.3&target_version=1.4&policy_file_name=orders-1.4.xml
# a policy file can pin specific instance ids or exclude activities; without a policy every eligible instance migrates
References