Migrating active process instances from one BPM snapshot to another can have its difficulties if you are not aware of some pitfalls.

This document hopefully explains these pitfalls and how to avoid them.

 

Migrating In-flight Process Instances in IBM BPM

 

Owen Cline owenc@us.ibm.com

Executive IT Specialist BPM - WW GBS-SWG Smarter Process CoC

 

Contents

 

 

 

 

Introduction

 

IBM BPM supports the migration of in-flight process instances and tasks from an older snapshot of the process application to a new snapshot of the process application.

However, depending on the types of changes made to the process application, run-time errors can occur when an attempt is made to run the migrated instance with the new snapshot of the process application.

If you make these kinds of changes in your process application, you can expect that migrated process instances (IFP) or tasks (IFT) will have a run-time error:

• Addition, deletion or update of a variable, and reference to new/missing variable between services or processes

• Removing an activity from a BPD

• Removing a gateway from a BPD

• Changing the variable used to evaluate a gateway

• Changing a variable's type

• Removing an event listener - This will not cause any technical problems, but older events from previous IFPs will now be ignored; so, there will be a functional problem with stalled BPDs.

• Removal of a group or all members of a group that previous IFTs have been assigned to

• Removal of a coach or a coach-style service without taking into account users that may have postponed tasks on that coach

• Removing a button on the coach (tasks postponed with close-window will not re-render the coach, thus old and non-existent buttons will be displayed if a user resumes an IFT)

• Removing a wait event component from a BPD

• Removing a user-centric (coach based) activity from a BPD

• Removing a system lane activity from a BPD

• Do not change the type of an environment variable

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

 

These types of changes will not affect migrated process instances (IFP) or tasks (IFT):

• Switching ICs/connectors without changing inputs/outputs

• Changing JavaScript without changing variables or variable types

• Changing switch/gateway logic without changing variables or variable types

• Switching cosmetic coach look and feel via CSS, JSPs or images.

• Switching layouts on coaches

• Removing lines that none of the previous IFPs are going to follow (requires analysis)

 

Some more points to know are:

• If you remove an activity in the new snapshot and a migrated process instance token was on that removed activity, the process instance will immediately fail and there will be no recovery. There is no way to repair this. In this example, if the TestingGettingData is removed in the next snapshot (version) of the BPD, token #2 will be orphaned. During the process migration, you need to make sure that all tokens on the TestingGettingData activity are moved to the Cleanup activity for example. This will be discussed later in the document.

 

One method some use is to leave the activity in the new version but remove the input wire like this:

 

 

• If a new attribute is added to coach and a migrated process instance was positioned on that coach and the coach was rendered already in the browser and the "Submit" button was clicked, a run-time error will occur. If you go to the Process Inspector, you can resume the coach task and the new coach will be displayed with the new attribute but any data that was previously entered will be lost and the user will have to re-enter the data.

• You have to be careful when migrating process applications with UCA because UCA only fire events on the default snapshot. So if you use UCA to move your tokens in you process applications with Starting Message Events or Intermediate Message Events, the UCA events will only be handled in the default snapshot. Do not delete or replace a UCA.

• If you add a variable and modify an existing gateway to evaluate on it, migrated process instances will fail because the new evaluation variable is not defined.

 

Changing Variables (Business Objects)

 

It is common to make changes to Business Objects (variables) with a new version of a process. Here are some best practices:

1. For each old variable no longer needed: If the old version of the process needed this variable, then do not delete it, just ignore it going forward. Update the documentation in your processes, services and/or variable types to note that this variable/property is now deprecated. Once all of the instances that required this variable have been completed and purged from the BPM product database, you can consider removing it then if you like.

2. For new variables required: Make sure to provide an innocuous default value for all new variables or properties introduced. Moreover, make sure that you have error-avoidance code anywhere you access that property, allowing for the possibility of an undefined variable or property, or a null variable or property. This may require populating the new variable or property prior to showing it in a coach (e.g., using a script that checks for null or undefined, then provides a default value, if necessary).

3. For each change to a variable name: Changing of variable names is accomplished by creating a new variable instead of re-naming an existing one. You should avoid changing variable names unless it is truly needed. Usually, changes to variable names are for the benefit of the process author and have no benefit to the end users or to the process itself. If the name change cannot be avoided, then add a new variable/property with the new name and update the old variable/property with documentation indicating that it is deprecated. DO NOT remove the old variable from your data structures. Now refer to the "old variable" case and "new variable" case above. Note that property changes should be handled like variable name changes.

4. For each change to a variable type: For property changes, please refer to the previous paragraphs. Each property should be treated almost like its own variable, being gently deprecated or being carefully added in as a new property with appropriate defaults and error-handling code. If the variable type's name is going to change, the recommend procedure is to create a new variable type rather than changing the old variable type's name. In your services and processes, establish a new variable that has the new type, and transition your processes/services to use the new variable type (and populate it with defaults or with values from the old variable type as needed).

 

 

Testing Migration Changes

 

This step is crucial. You should make a backup of a database based on the old model (a snapshot). Then import the new model changes and experiment with the correctness of the result. Test the "edge cases." Where errors are found, go back to the Process Center environment to fix them. Then restore the snapshot and reapply the upgrade to retest.

This process may require more than one snapshot iteration to get it right. If you think the first snapshot might not have enough experimental data, or services or processes "stopped" at the right spots to expose potential problems, then run some new instances to get to those edge cases, and take a new snapshot so that it can be tested and retested before going to production.

 

Identifying and Managing Orphaned Tokens

 

IBM BPM V8 provides a new set of capabilities for managing orphan tokens, which result from migration of in-flight process instances to a new process application snapshot that does not have some of the activities that existed in the previous snapshot. The new capabilities include analysis of two snapshots to identify steps that can potentially result in orphan tokens, as well as the ability to define orphan token handling policies and a set of REST APIs for moving or deleting orphan 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 the Process Inspector to manage orphaned tokens.

The following table shows the options for how to move orphan tokens when installing version two of a snapshot:

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

 

 

You can run the wsadmin command as shown in Listing 1 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 to handle each token. During migration, if a policy file is specified, the migration uses that file to determine whether to delete or move orphaned tokens.

 

Open a wsadmin session:

wsadmin -conntype SOAP -port 8880 -host localhost -user admin

-password admin -lang jython

 

Run the BPMCheckOrphanTokens command:

AdminTask.BPMCheckOrphanTokens('[-processAppAcronym HSS

-sourceSnapshotName "V1" -targetSnapshotName "V2" -outputFile

C:\TokenPolicyFile_HSS_V1_to_V2.xml]')

 

where:

processAppAcronym: A required parameter that identifies the process application that is to be installed; in this case, HSS.

sourceSnapshotName: A required parameter that provides the snapshot name from which instances will be migrated (the old version); in this case, V1.

targetSnapshotName: A required parameter that provides the snapshot name to which instances will be migrated (the new version); in this case, V2.

outputFile: A required parameter that provides the file path to the directory where the orphan token policy file will be generated and a name for that file; in this case, C:\TokenPolicyFile_HSS_V1_to_V2.xml. Use this XML file during the migration of active process instances.

 

Inside the TokenPolicyFile_HSS_V1_to_V2.xml file, you will see a list of every process instance that has a token that will be orphaned if you proceed with the migration. You can use this information to either modify the new snapshot so that you have less orphaned tokens or you can continue with the migration and modify the TokenPolicyFile_HSS_V1_to_V2.xml to tell the migration process how to handle these tokens during the migration.

 

 

Viewing and Managing Data Transfer Errors During a Process Instance Migration

 

During a process instance migration in the Performance environment, you might notice that the migration takes a long time.

You might discover that the highest SQL activity in the database are updates to the BPMPERF.LSW_DATA_TRANSFER_ERRORS table. Look for any PFS-0065 definition errors in the table.

When errors are added via SQL updates to the BPMPERF.LSW_DATA_TRANSFER_ERRORS table, the migration (in WLE v7.2) was doing a table scan and was the top database activity. To speed up the process instance migration, the table was truncated.

Here is one error you might see:

(PFS-0065) The tracking group with external ID guid:6e0137fda2974be4:-71b109af:1335fc23242:-7ff7 is not defined. Send definitions to define the tracking group.

com.lombardisoftware.client.delegate.BusinessDelegateException: (PFS-0065) The tracking group with external ID guid:6e0137fda2974be4:-71b109af:1335fc23242:-7ff7 is not defined. Send definitions to define the tracking group.

      at com.lombardisoftware.client.delegate.BusinessDelegateException.asBusinessDelegateException(BusinessDelegateException.java:41)

      at com.lombardisoftware.client.delegate.APIServicesDelegateDefault.loadTrackingData(APIServicesDelegateDefault.java:90)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore$ProcessOneRecord.execute(DataTransferCore.java:565)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore$ProcessOneRecord.execute(DataTransferCore.java:542)

      at com.lombardisoftware.utility.db.DbUtils.executeWithConnection(DbUtils.java:36)

      at com.lombardisoftware.utility.db.DbUtils$1.doInTransaction(DbUtils.java:75)

      at com.lombardisoftware.server.core.TXCommand$3.call(TXCommand.java:84)

      at com.lombardisoftware.utility.spring.ProgrammaticTransactionSupport.executeInExistingTransaction(ProgrammaticTransactionSupport.java:447)

      at com.lombardisoftware.utility.spring.ProgrammaticTransactionSupport.execute(ProgrammaticTransactionSupport.java:215)

      at com.lombardisoftware.server.core.TXCommand.executeInDeadlockRetryLoop(TXCommand.java:82)

      at com.lombardisoftware.utility.db.DbUtils.executeInTransaction(DbUtils.java:72)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore.processSingly(DataTransferCore.java:276)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore.processByClaim(DataTransferCore.java:238)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore.transferFromProcessServers(DataTransferCore.java:140)

      at com.lombardisoftware.server.tracking.transfer.DataTransferCore.transferData(DataTransferCore.java:96)

      at sun.refl

 

In summary, you will need to define a process to monitor errors in the BPMPERF.LSW_DATA_TRANSFER_ERRORS table and then resolve them (i.e. remove the errors from BPMPERF.LSW_DATA_TRANSFER_ERRORS table). One way to do this is to use the BPM Performance Admin Console manage these errors:

http://pic.dhe.ibm.com/infocenter/wle/v7r2/index.jsp?topic=%2Fcom.ibm.wle.doc%2Fadminguide%2Ftopic%2Fmanaging_perfsvr_transfer_errors.html

 

 

Useful Links

 

Strategies for migrating instances

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp?topic=%2Fcom.ibm.wbpm.admin.doc%2Ftopics%2Fcstrategies_migratinginstances.html

 

Migrating instances

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.imuc.doc/migrating/primer/topic/upgrading_runtime_environments.html

 

Data migration rules

http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=%2Fcom.ibm.wbpm.admin.doc%2Ftopics%2Freleasing_installing_procs_E.html

 

Webcast replay: IBM Business Process Manager and WebSphere Lombardi Edition - Understanding the Effects of Migrating Snapshots with In-Flight Instances

http://www-01.ibm.com/support/docview.wss?uid=swg27025165

 

Migrating process instances in IBM Business Process Manager V8

http://www.ibm.com/developerworks/bpm/bpmjournal/1305_norelus/1305_norelus.html

 

BPM In-flight instance migration slowness -Steps to improve performance

http://wiki.bpmwiki.com/display/commwiki/BPM+In-flight+instance+migration+slowness+-Steps+to+improve+performance

Tags:  ibm bpm migration