Defining the instance migration policy by using a REST API

When you migrate from one version to another, you can use IBM Business Automation Studio to define an instance migration policy for deleting or moving orphaned tokens. Otherwise, you can use a REST API call to create the migration policy. An orphaned token is a token that is associated with an activity that exists in the source version but not in the destination version.

Important: To use a REST API call to create a migration policy, you must be a member of the administrator group.

About this task

You call the operations REST API

POST
https://host:port/root/ops/std/bpm/containers/container/migration_policies?sourceContainerSnapshotAcronyms=source_acronyms&targetContainerSnapshotAcronym=target_acronym

. root is the context root for the server. In Business Automation Workflow, the root is bas. container is the acronym of the project that contains the version you want to migrate from. source_acronyms is a comma-separated list of source version acronyms. target_acronym is the acronym of the version that is the target of the migration.

Note:

Encode the commas in the sourceContainerSnapshotAcronyms query parameter with %2C.
BPMCSRFToken is required for this REST API. For more information, see Preventing cross site request forgery .

The following examples illustrate how to use the REST API to create a migration policy:

Create a migration policy for migrating from version V01 to target V03 of the workflow automation WF1:

POST http://host:port/root/ops/std/bpm/containers/WF1/migration_policies?sourceContainerSnapshotAcronyms=V01&targetContainerSnapshotAcronym=V03

Create a migration policy for migrating from versions V01 and V02 to target V03 of the workflow automation WF1:

POST http://host:port/root/ops/std/bpm/containers/WF1/migration_policies?sourceContainerSnapshotAcronyms=V01%2CV02&targetContainerSnapshotAcronym=V03

After you call this REST API, a policy file is created that shows the orphaned activities (steps). Note the migration_policy_Id returned in the response because you’ll need this for the next step.

After you download the created policy file, you can then call operations REST API GET https://host:port/root/ops/std/bpm/containers/container/versions/target_acronym/migration_policies/migration_policy_id/export?source_version=source_acronym. root is the context root for the server. In Business Automation Workflow, the root is bas. container is the acronym of the project that contains version you want to migrate from. target_acronym is the acronym of the version which is the target of the migration. source_acronym is the source version acronym. migration_policy_id is the migration_policy_Id field returned from the previous POST REST API response.

The following example illustrates how to use the REST API to export your newly created migration policy file.

Export your created migration policy file for migrating from version V01 to target version V03 of the workflow automation WF1 where 2125.bdd71957-1a38-41f9-b425-44df022f9ea8 is the migration_policy_Id returned from the previous POST REST API:
```
GET http://host:port/root/ops/std/bpm/containers/WF1/versions/V03/migration_policies/2125.bdd71957-1a38-41f9-b425-44df022f9ea8/export?source_version=V01
```

Now that you have created a migration policy file, you can use the following procedure to make changes.

Procedure

Review the instance migration policy file to determine if changes are needed.
Orphaned activities have a step element added to the file with the delete operation set for each step element. Therefore, there are no orphaned activities if no step elements are in the file. Don't modify the process, step, or other parent XML elements. For each step, a delete XML element is added: <delete suspendProcess="false"/>.
For advice and considerations regarding moving or deleting tokens, see Defining the instance migration policy.
To move orphaned tokens, change the delete XML element to a move element, as shown in the Results section.
The move element requires two string attributes: name and targetStepId. Use the name and targetStepId associated with the activity you want to move the orphaned token to. You can get these values from Workflow Designer. In Workflow Designer, open the target version and corresponding process. Then, select the target activity for the token and open the Properties view for it. In the General tab of the Properties view, you will find the name to use for the name attribute, and in the Documentation tab of the Properties view you will find the ID to use for the targetStepId attribute of the move element. The attributes are case sensitive.
Optional: You can suspend the process instance after an orphaned token has been deleted or moved so you can edit the data before resuming the instance. To suspend the process, change the suspendProcess attribute from false to true.

Results

The following XML snippet shows a completed policy file that has both move and delete instructions:

<?xml version="1.0" encoding="UTF-8"?>
<orphanTokenPolicy>
  <processApplication acronym="HSS" id="2066.9ab0d0c6-d92c-4355-9ed5-d8a05acdc4b0" name="Hiring Sample">
    <sourceSnapshot acronym="RHS8570" id="2064.f1659d94-2365-4903-8a90-9fa62f3ccd31" name="Responsive Hiring Sample v8570_01"/>
    <targetSnapshot acronym="OTT" id="2064.b15dcea3-1e3f-4721-9a6c-b3f23046f68c" name="Ophaned Token Test"/>
    <process bpdId="25.c904b3b1-afc1-4698-bf5a-a20892c20275" name="Standard HR Open New Position">
      <step id="bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-75fb" name="Submit position request">
        <move name="User Task" suspendProcess="true" targetStepId="e78fd2f7-c441-4011-8a42-ae339bf3f581"/>
      </step>
      <step id="bpdid:431b0753c33842e2:3d5457c0:141a2fd3448:-7576" name="Send escalation notice">
        <delete suspendProcess="false"/>
      </step>
    </process>
  </processApplication>
</orphanTokenPolicy>

What to do next

You can now use the policy file during instance migration, as discussed in Defining the instance migration policy.