Designer > System Services > Migration Service

Migration Service

The migration service allows fine grain control over migrating running process instances to a newer (or different) version of a process definition. The simplest way to migrate running processes is to specify this choice in the Process Deployment Descriptor of the newer version being deployed, on the General Deployment Options page.

However, if the newer process version has significant changes, such as new activities, variables, or participants, you can create a migration service to test the migration, by selecting one or a few process instances to migrate. Then analyze the results on the Active Process Details page of the server. If errors occur, a process is suspended and errors are reported in the server log. Please note that Process Server does not validate changes to incoming and outgoing message structures between the existing plan and the new plan.

Another use case for a migration service is to have fine grain control over migration. For example, you don't have to migrate instances to the online version of the same process definition. You can migrate to any other process definition that is on the server. And you can pinpoint only those running process instances that you want to migrate.

The process you create for handling migration uses the Migrate system service that has two operations that you must use in order:

•Create Map operation

This operation takes as input the Plan Id of the process definition that process instances are running against. Each Plan Id on the server is unique and is a property of each version of a process definition. All process instances run against a Plan Id.

The create map operation returns a migration map XML document as a string. The map contains the migration structure between plans, which describes the transformation of the activities, links, and variables from one process definition to the other.

•Migrate operation

This operation takes as input the migration map and the process id (pid) of the running process instance to migrate.

The migrate operation returns the XML document that contain list of migration warnings (if any) and the backup process Id. By default, the process instance is migrated to the Plan Id of the online version of the same process definition, but you can specify any Plan Id on the server.

Input and Output for Create Map

The input for the create map operation looks like the following example. You must provide a Plan Id for the running process instances to migrate. For your process request message that passes data to this operation, you can look up the Plan Id on the Active Process Detail page or obtain it programmatically in various ways, such as a using a database query or the appropriate Admin API call.

The following example show sample data. Note that the toPlanId is optional. If deleted, the default behavior is to map to the online version of the same process definition.

<migration:createMapRequest xmlns:migration="http://docs.active-endpoints/wsdl/migration/2011/04/migration.xsd">
<migration:fromPlanId>144</migration:fromPlanId>

<migration:toPlanId>145</migration:toPlanId>
</migration:createMapRequest>

The following example shows just the beginning of the migration map created for the response:

<createMapResponse xmlns="http://docs.active-endpoints/wsdl/migration/2011/04/migration.xsd">
<migrationMap><![CDATA[
<processMigration xmlns="http://schemas.activevos.com/processMigration/2010/05/processMigrationMapper.xsd">
<migrationInfo>
<locationInfo>
<locationId>1</locationId>
<locationPath>/process</locationPath>
<idsToRoot />
</locationInfo>
<mapForVariable>false</mapForVariable>
<migrationMapper>
<oldLocationInfo>
<locationId>1</locationId>
<locationPath>/process</locationPath>
<idsToRoot />
</oldLocationInfo>
<activityStrategy>
<stateMapType>0</stateMapType>
<defaultLocationInfo>
<locationId>1</locationId>
<locationPath>/process</locationPath>
<idsToRoot />
</defaultLocationInfo>
</activityStrategy>
</migrationMapper>
</migrationInfo>
...
</createMapResponse>

Input and Output for Migrate

The input for the migrate operation requires a pid. For your process request message that passes data to this operation, you can look up the pid on the Active Processes list or obtain it programmatically. Basically you can use the getProcessList API call (or a report) to bring back the set of process ids matching the ones you want to migrate. If you have a large number to migrate, you can migrate many instances in parallel.

The following example show sample data:

<migration:migrateRequest xmlns:migration="http://docs.active-endpoints/wsdl/migration/2011/04/migration.xsd">

<migration:migrationMap>string</migration:migrationMap>
<migration:pid>850</migration:pid>

<migration:toPlanId>145</migration:toPlanId>

<migration:createBackup>false</migration:createBackup>
</migration:migrateRequest>

The following is a sample migrate response message:

<migrateResponse xmlns="http://docs.active-endpoints/wsdl/migration/2011/04/migration.xsd">
<response>MIGRATION_WARNING Errorcode:3001. Migration Warning: The empty activity is being marked as Finished when it is not. This might result in invalid output for the pid 850. (location path /process/sequence/empty)</response>
<backupPid>851</backupPid>
</migrateResponse>

Creating a BPEL Process That Migrates Process Instances to a New Version

Use the following procedure:

1. In the Project Explorer, create a new orchestration project.
2. Select File > New > BPEL Process.
3. Name the process and click Finish.
4. Create a receive/reply based on a WSDL you create. The request message for the process must provide a Plan Id and one or more process Ids of running process instances.
5. In the Participants view, create a new Partner Service Provider.
6. Select System Services.
7. Select Migration.
8. From Participants view, drag the create map operation to the canvas to create an invoke activity. This activity takes as input the process plan Id and creates a map of the process structure.
9. From the Participants view, drag the migrate operation below the create map invoke to create a second invoke activity. This activity takes as input the migration map and process id and migrates the running process instance to the online version of the same plan Id, by default. You can specify any Plan Id, depending on the structure of your process.

Testing Your Migration Process

Deploy the migration process to the server and then you can test it as follows:

1. Deploy a process and instantiate a long-running process instance.
2. Deploy a second version of the process. Do not select the migrate option in the PDD.
3. Instantiate the migration process with a request message containing a Plan Id of the original version and the pid of the running process instance.

For doing migration programmatically outside of a BPEL process, refer to Using the Process Server Migration Web Service.

Using the Process Server Migration Web Service

For doing migration programmatically outside of a BPEL process, you can use the Process Server SOAP-based migration Web service.

On the server, open the following page:

http://localhost:8080/active-bpel/services

On this page, scroll down to locate the AeProcessMigrationService:

http://localhost:8080/active-bpel/services/AeProcessMigrationService?wsdl

Using a tool such as SOAP UI, create a request to migrate one process instance, as shown in the following example: