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

About this task

This task applies to a process application snapshot that has one or more running instances. You are deploying a new version of a process. The new version has cleaned up a number of steps that are no longer used from the earlier version. However, it is possible that tokens exist on some of these unused tasks. These tokens should be mapped to existing steps in the new process so that when the you migrate the instances, the process instances do not fail. You can also delete (ignore) tokens that are no longer used in the new process.

If you use a policy file to help you with this task, follow the procedure set out here. Run the BPMCheckOrphanTokens wsadmin command to get a list that you can use to spot potential migration problems so that when you migrate to the new version of the snapshot, you have some confidence that it will work. When the file is generated, it will identify all the potential orphaned tokens. Go through the file and identify how you want each token to be handled. During migration, if a policy file is specified, the migration uses that file to determine whether to delete or move orphaned tokens. If migration does not produce any orphaned tokens, the file is not used. For more information about the BPMCheckOrphanTokens command, see BPMCheckOrphanTokens wsadmin command.

Procedure

Detect orphaned tokens. Use this XML file during the migration of active process instances. The wsadmin command compares two snapshots and produces an XML file listing all the steps in the BPD where orphaned tokens could potentially occur. The command generates an XML representation of all possible locations of orphan tokens in a policy file.
Edit the policy file using a text editor.
1. Go through the list of potential orphaned tokens and decide whether each token should be moved or deleted. By default, a delete action is specified for each token. You can change delete to move.
2. When you are moving a potential orphaned token, you need to specify the target activity using the activity acronym. In Process Designer, select the target activity to which you want to move the orphaned token. From the Properties view for that activity, copy its system ID (which has a value like bpdid:b999d6be478ef107:21bb67e6:134387269e4:-7ff4) to your clipboard. The ID is case sensitive.
3. Add a move instruction to the policy file in place of the delete instruction that is there by default. Paste the token ID into the instruction. Here is an example of a simple move instruction:
```
<process bpdId="27d4fbbc-0175-4201-80d1-132100aca191" name="Top-level only">
    <step id="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7fe0" name="B">
      <move targetStepId="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7ff4" name="A"/>
    </step>
</process>
```
  The policy file will not let you move a token to an invalid location. See Managing orphaned tokens for some general advice about moving potential orphaned tokens.
Optional: You can add an attribute to suspend the process for any activity in the policy file. That attribute suspends the process instance after a token has been deleted or moved so you can edit the data before resuming the instance. To use the suspendProcess option, set the attribute to "true".
```
<move targetStepId="bpdid:b12b770ce3d97e30:3a0ee98f:133c7d2dc73:-7f72" name="E1" suspendProcess="true"/>
```
The attribute suspendProcess="true" applies only to active instances. Inactive instances are not affected by the attribute. If an instance is already suspended, after migration using the orphaned token policy file it remains suspended.
From the Process Admin Console, select Installed Apps.
From the list of snapshots, select the one to which you are migrating data.
In the Migrate Inflight Data from Snapshot window, select a snapshot to migrate from, then browse to the location of the policy file and click Migrate.
Look at the result in the Process Inspector to ensure that all orphaned tokens have been deleted or moved or to adjust any data values after migration.