IBM BPM, V8.0.1, All platforms > Administer applications and processes in the runtime environment > Manage installed snapshots

Manage orphaned tokens

An orphaned token is a pointer that is associated with an activity that was removed from a business process definition (BPD).

You can use a policy file, a REST API, or Process Inspector to manage orphaned tokens.

Think of a token as an active execution step within the process. Tokens will exist on each active activity as well as for timer and message events on an active activity.

A token becomes orphaned if its associated activity is removed from a BPD of a migrated snapshot. You need to decide what to do with potential orphaned tokens or risk that the process instances will not complete.

For example, you have installed a new version of a process application. The new version has cleaned up a number of activities that are no longer used from the earlier version. However, there are tokens that still exist for some of these unused activities. You must either delete or move these orphaned tokens, or the migrated process instances might not be able to complete. When orphaned tokens are deleted or moved, the process instance will try to resume at a next step. If a next step cannot be determined from the revised BPD, the instance will complete when there are no more active tokens.

Consider a second example. Again you are installing a new version of a process application. A number of explicit exception events have been removed from some of the nested processes. This removal could potentially lead to orphaned tokens when instances are migrated to the new version. It should be possible to delete (that is, to ignore) these tokens when instances are migrated from the old to the new version of the process without causing instances to hang.

The easiest way to identify and manage orphaned tokens is to generate a policy file and use it to specify whether each potential orphaned token should be moved or deleted during instance migration. If you migrate the snapshot instance without using a policy file, orphaned tokens may be created. In this case, you can use the REST API client to delete or move these orphaned tokens. You can also use the web Process Inspector to delete orphaned tokens. These methods are described in the accompanying topics.

Important considerations

Take care when making decisions about whether to delete or move tokens. Here are some of the specific cases to keep in mind while you are making those choices:

• You can move an orphaned token from one activity to another activity in the same process or subprocess.

• You can move an orphaned token from an activity in a process to an activity in any of its subprocesses.

• You can move an orphaned token from an activity in a subprocess to an activity in its parent process.

• You cannot move an orphaned token from an activity in an event subprocess to an activity outside that event subprocess.

• You cannot move an orphaned token from an activity outside an event subprocess to an activity in that event subprocess.

• You cannot move the an orphaned token in a linked process to its parent process or to another linked process.

• You can only delete or move a token that is a leaf node in the execution tree; any parent orphaned tokens will be handled implicitly.

  For example, suppose an activity implemented as a subprocess is deleted in a new snapshot. Deleting an orphaned token in the subprocess will also delete the orphaned token on the parent activity.

• 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.

• When you move a token, you are actually deleting it from one activity and creating a new copy of it attached to a different activity. This behavior creates a limitation if you are using multiple instances of nested business objects.

  For example, if you have an activity that has three tokens associated with it and you move those tokens to a second activity, only one token is created on the second activity.

Where you can move tokens

Source Activity Location	Target in Same Process	Target in Parent Process	Target in Child Subprocess	Target in Child Event Subprocess	Target in Child Linked Process
Process	Yes	N/A	Yes	No	No
Subprocess	Yes	Yes	Yes	No	No
Event subprocess	Yes	No	Yes	No	No
Linked process	Yes	No	Yes	No	No

• Manage orphaned tokens with a policy file
  Use a policy file to proactively compare snapshots before instance migration to identify the potential locations of orphaned tokens and specify whether each orphaned token should be deleted or moved.
• Manage tokens using the REST API Client and Process Inspector
  

  You can use the REST API client to move or delete tokens.

  You can use the web Process Inspector to delete orphaned tokens, but not to move them.

• Changing the security policy
  

  If you are upgrading from an earlier version of IBM BPM, you might need to configure the security policy before you move or delete a token.

Manage installed snapshots