Strategies for migrating instances

General principles

• Consider the business process definition and its variables as the interface and process instances as the realization of that interface.
• As part of instance migration, past (completed) tasks are migrated into the current process version. It is important that the process can resolve a completed execution context in order to preserve historical information.
• The new process version must be designed to provide backward compatibility to instances that you want to migrate.
• If you have removed a task, it is sometimes possible to account for the difference by moving the resulting orphaned token, although there are limitations to this capability.

Design-time considerations

In most cases, deprecate entities that you no longer want rather than deleting them. See the information about teams, undercover agents, services, and variables for some specific examples of this advice.

Here are some hints to aid you in successfully migrating instances.

Business process definitions that use an SCA service as the triggering mechanism for receiving message events

• Do not change the SCA service interface on any receiving message events, that is, the type of the message business object type, the identifier of the service, and the correlation specification, including its variable.
• Do not delete any receiving message event that is triggered by SCA invocation.
• Do not rename or delete any variable that is used as a Process Instance Identifier.
• Do not change the type nor the type definition of any variable that is marked as a Process Instance Identifier.

Business process definitions in toolkits

Having a business process definition in a toolkit can result in process instances running in the toolkit. You cannot migrate a process instance that is running in a toolkit.

Environment variables

• Do not change the type of environment variables.
• Regardless of the migration option you choose, the process server copies environment variables from the installed snapshot or snapshots. If environment variable values were changed from the defaults, the most recently set values are the ones that are used. In the case where an installation service sets the values, those values are considered the most recent and are the values used.
• You can remove an environment variable as long as the process no longer refers to it. Because environment variables are accessed through JavaScript, removing them is less problematic than removing local variables.

Exposed process values

• The instance migration process copies exposed process values (EPVs) from all installed snapshots. If EPVs were changed from the defaults, the most recently set values are the ones used. In the case where an installation service sets the values, those values are considered the most recent and are the values used.
• EPVs in referenced toolkits are copied only if the referenced toolkit is not already available on the target server.

Gateways

• For a parallel gateway, both branches must complete to complete the process successfully. Therefore, if you choose to delete an orphaned token on one branch of a parallel gateway, the process using the parallel gateway will never be able to complete.

Human services and coaches

• If migration occurs while a task is running, the user interface from the old version is still displayed. Refreshing or clicking Next has no effect. You need to restart or claim the task after migration.
• If you must update coaches and you want all existing instances to use the updated coaches, programmatically move the active token back to the task that uses the new coaches.

Linked processes

• You can add a linked process if there is no token to be honored.

Teams

• The migration program merges the team members (users and groups) from previously installed snapshots into the snapshot that now contains the migrated instances.
• Users added by an installation service before the migration are not overwritten. However, if the team on the target server is empty or does not exist (meaning that it was added in the new snapshot), it is "seeded" with the users and groups from the Process Center. This is considered a "seed" because the real bindings will likely be updated after the installation.
• If the team was updated in the new snapshot, if, for example, a user or group was added or deleted, those changes are not applied during the merge process.
• Do not change the assignment of a task to a new team. A team is determined when the task is created, not when the task is claimed or migrated. If a task is assigned the Employees role in the original instance, that assignment is migrated to the new instance. Only members of that group can claim the task.

Services

• If a service was used but is no longer needed, leave it in the process application but mark it as deprecated. You can change the service to a no-operation service by directly joining the start event to the end event in your diagram.

Tasks

• As part of the instance migration, you migrate past (completed) tasks into the current process version.
• Use a policy file to proactively compare snapshots before instance migration to identify tasks that potentially have orphaned tokens.
• You can add a task if it has no task instance associated with it.
• If you have removed a task, it is sometimes possible to account for the difference by moving the resulting orphaned token.
• Do not change the assignment of a task to a new team. See the section about "Teams" in this topic.
• You can move a token back to a task that has been modified to restart the task.

Tokens

• In the BPMN process engine, a token is a pointer to an active execution step within the process. Tokens exist on activities. There can also be tokens for timer and message events on an active activity. When you migrate a process instance from one version to another, the tokens can be placed back on the same step in the new version to indicate the current active activity. However, if the step that the token referenced no longer exists in the new version, the token is now “orphaned”.
• You cannot delete a token from a subprocess. You must delete tokens from the main process.

Undercover agents

• An undercover agent (UCA) responds according to the settings from the old snapshot. That is, an active UCA still listens to events from the tip or from a previous version, even after migration. Therefore, do not delete or replace a UCA.

Variables for processes and services

• Your new process version or service must provide backward compatibility to the instances that you want to migrate.
• Do not remove variables.
• Do not rename variables, or if you must, introduce the new variable with a new name, and deprecate the old variable. In this case, deprecating means to leave the variable unchanged and do not use it any more.
• Do not change the type of your variables, for example from a simple to a complex variable. If you must change a variable type, introduce a new variable with the new type, and deprecate the old variable.
• If you use complex types, you might find problems with a migrated instance. Each complex type has a version identifier specified for it. Migration does not update this identifier, which means you might have problems accessing complex type business objects after migration.
• Migrated instances may fail when you add variables to a process or service, because the variables are not initialized. If a new variable is added, initialize it with an appropriate default value, or ensure that the code is designed to handle an undefined or null variable.

Runtime actions

Administrators should schedule a blackout period and manage orphaned tokens to aid the process of migrating instances.

Blackout periods

Events that fire during migration could cause your migration to fail. In the Process Admin Console Event Manager, schedule a blackout period so events are not activated during instance migration. See Creating and maintaining blackout periods.

Orphaned tokens

If you migrate currently running instances to a new version of the snapshot, problems can occur if the new version removes steps or other components from the business process definition. When instances that are running on a server have tokens on business process definition or service-level components that were removed in the new snapshot, migration can fail. Tokens indicate where a runtime instance is running. Tokens can be present on an activity, a conditional sequence line, a coach, a service call, and numerous other elements. For more information about orphaned tokens and advice about how to move or delete them, see Managing orphaned tokens.

Testing

Verify the results of instance migration in a test environment before you install the new snapshot on a production server.

Tuning for better migration performance

Performance depends on the number of instances in the process, the number of tasks in those instances, and the size of the execution context. Try testing how long the migration takes with 100 instances. From that result, estimate the time that the whole migration requires.

The number of tasks associated with an instance and the size of the associated application data affects the migration time.

Before V8.5.5, only a single thread was used for migrating all instances. In V8.5.5 and later versions, you can choose which tasks to migrate, choose whether to defer the update of the execution context of the tasks, and set the thread pool size.

<server>
  <instance-migration>
    <thread-pool-size> 5 </thread-pool-size>
    <migrate-tasks> all | none | skip-closed <migrate-tasks>
    <defer-ec> true | false </defer-ec>
  </instance-migration>
</server>

<server>
  <instance-migration>
    <thread-pool-size>5</thread-pool-size>
    <migrate-tasks>skip-closed<migrate-tasks>
    <defer-ec>false</defer-ec>
  </instance-migration>
</server>

<server>
  <instance-migration merge="mergeChildren"> 
    <thread-pool-size merge="replace">10</thread-pool-size>
    <defer-ec merge="replace">true</defer-ec>
  </instance-migration>
</server>

<server>
  <instance-migration merge="mergeChildren"> 
    <thread-pool-size merge="replace">10</thread-pool-size>
    <migrate-tasks merge="replace">all</migrate-tasks>
  </instance-migration>
</server>

<server>
  <instance-migration merge="mergeChildren"> 
    <thread-pool-size merge="replace">8</thread-pool-size>
    <migrate-tasks merge="replace">none</migrate-tasks>
    <defer-ec merge="replace">true</defer-ec>
  </instance-migration>
</server>