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

If you use a policy file to help you with migrating instances, follow the procedure set out here.

Procedure

Use one of the following methods to generate the policy file for orphaned tokens:
- Generate the file using Process Center. For information, see Defining the migration policy.
- Generate the file using wsadmin commands:
  1. 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. The wsadmin command compares two snapshots and produces an XML file listing all the steps in the BPD where orphaned tokens could potentially occur. For more information about the BPMCheckOrphanTokens command, see BPMCheckOrphanTokens wsadmin command.
  2. Edit the file and identify whether each token should be moved or deleted. By default, tokens are deleted. To change delete to move, add a move instruction to the policy file in place of the delete instruction. In the move instruction, specify the target activity using its 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 and then paste it to the targetStepId attribute of the move instruction. The ID is case sensitive.
    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>
```
    See Managing orphaned tokens for some general advice about moving potential orphaned tokens.
  3. 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"/>
```
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.