Postmigration tasks for Business Process Choreographer

IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from previous versions > Migrating your IBM BPM Advanced V7.5.x or WebSphere Process Server V7.x or V6.2.x runtime > Postmigration tasks
Postmigration tasks for Business Process Choreographer

If your servers or clusters run Business Process Choreographer, you must perform some additional tasks before you start your servers or clusters.

You must have already successfully upgraded the Business Process Choreographer database schema and, if necessary, migrated the runtime data. You must also have successfully migrated your servers and clusters.

Perform these tasks, if they apply to your environment, before you use IBM BPM V8.0.1 in production.

Procedure
If you used people assignment before migrating to V8.0.1, you must perform the following actions:
If you applied any changes to the default XSL transformation files (EverybodyTransformation.xsl, LDAPTransformation.xsl, SystemTransformation.xsl, VMMTransformation.xsl, and UserRegistryTransformation.xsl) that are in the INSTALL_ROOT/ProcessChoreographer/Staff directory, then you must reapply your changes to the IBM BPM V8.0.1 versions of these files after migration. In a clustered environment, the transformation file must be available on the dmgr and on each node that hosts members of the cluster where Business Process Choreographer is configured. Verify that they all use the same version of the transformation file.
Custom XSL transformation files in the INSTALL_ROOT/ProcessChoreographer/Staff directory are migrated automatically. Custom XSL transformation files in other directories might have to be copied manually, depending on the exact value of the transformation file path specified in the earlier version of the people directory configuration (previously known as the staff plug-in configuration).
If you used the substitution feature and substitution information is stored in one of the user repositories that are configured for VMM, you must add the new properties for substitutionStartDate and substitutionEndDate to your repository. The steps that you must perform depend on whether you store the substitution information in the VMM file registry or in the VMM property extension registry:
For the VMM file registry:
Add the substitutionStartDate and substitutionEndDate properties to the definition of the PersonAccount entity type in the wimxmlextension.xml file.The file is in profile_root/config/cells/ cellName/wim/model. In a ND environment, edit the file on the dmgr.

The file is in profile_root/config/cells/ cellName/wim/model.
The file is in profile_root\config\cells\ cellName\wim\model.
Extend the file to include the new properties:
<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim" 
     dataType="STRING" multiValued="false" propertyName="isAbsent">
    <wim:applicableEntityTypeNames>PersonAccount</wim:applicableEntityTypeNames>
</wim:propertySchema>

<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim" 
     dataType="STRING" multiValued="true" propertyName="substitutes">
     <wim:applicableEntityTypeNames>PersonAccount</wim:applicableEntityTypeNames>
</wim:propertySchema>

<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim" 
     dataType="STRING" multiValued="false" propertyName="substitutionStartDate">
    <wim:applicableEntityTypeNames>PersonAccount</wim:applicableEntityTypeNames>
</wim:propertySchema>

<wim:propertySchema nsURI="http://www.ibm.com/websphere/wim" 
     dataType="STRING" multiValued="false" propertyName="substitutionEndDate">
     <wim:applicableEntityTypeNames>PersonAccount</wim:applicableEntityTypeNames>
</wim:propertySchema>
The changes become effective when the servers are restarted. In a ND environment, the dmgr must also be restarted.
For the VMM property extension registry:
Check that the substitution properties isAbsent and substitutes are defined for the property extension repository. If they were not defined before migration, no substitution information was stored in the VMM property extension repository, and this migration step is not required.
Change to the directory INSTALL_ROOT/bin and enter the following commands in either local mode or connected mode. In a ND environment, enter the commands on the dmgr.
wsadmin -username  admin -password  adminPassWord
$AdminTask listIdMgrPropertyExtensions
Add the new properties substitutionStartDate and substitutionEndDate to the property extension repository configuration by entering the following commands:
$AdminTask addIdMgrPropertyToEntityTypes 
   {-name substitutionStartDate 
    -dataType String 
    -isMultiValued false 
    -entityTypeNames PersonAccount 
    -repositoryIds LA} 
$AdminTask addIdMgrPropertyToEntityTypes 
   {-name substitutionEndDate 
    -dataType String 
    -isMultiValued false 
    -entityTypeNames PersonAccount 
    -repositoryIds LA}
The changes become effective when the servers are restarted. In a ND environment, the dmgr must also be restarted.
Verify that the new properties were added to the property extension repository configuration by entering the following command:
$AdminTask listIdMgrPropertyExtensions
Configure the REST API endpoints for the Business Flow Manager and Human Task Manager, update all references, and map the web modules to a web server.

If you used Business Space to access Business Process Choreographer, and you have not configured it to use the federated REST APIs, you can do that configuration now. To register the new endpoints with Business Space, using the administrative console, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, click Business Space Configuration, then under Additional Properties click REST service endpoint registration and for Service Endpoint Target verify that Process services and Task services are selected.
If you still use the bpcEndpoints.xml file, the endpoint configuration is not migrated automatically, so use the administrative console to make sure that the references to the REST APIs for Business Space are correct. If that since version 6.2, you should configure the Business Process Choreographer REST API endpoints for Business Space by using the administrative console rather than using the bpcEndpoints.xml file. To check or change the Business Process Choreographer REST API endpoints for Business Space:

To change the endpoint for the Business Flow Manager, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Business Flow Manager, and under Additional Properties click REST Service Endpoint.
To change the endpoint for the Human Task Manager, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Human Task Manager, and under Additional Properties click REST Service Endpoint.
To register these endpoints with Business Space, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, click Business Space Configuration, then under Additional Properties click REST service endpoint registration, and make sure that the correct Service Endpoint Target for the Process services and Task services are selected.

If you migrated to a different machine, you must make sure that the REST API endpoint references for Business Process Choreographer Explorer and Business Space point to the correct host name and port number of the server. In a clustered environment, if you use a proxy server or HTTP server in front of several application servers, you can achieve load balancing and high availability by directing the REST requests to that server.

To change the context root for the REST API web modules:

In the administrative console click Applications > Application Types > WebSphere enterprise applications > BPEContainer_ suffix > Context Root for Web Modules. Where suffix is either node_name_ server_name or the cluster_name where Business Process Choreographer is configured.
Verify that the context root for the web module BFMRESTAPI is correct and unique.
In the administrative console click Applications > Application Types > WebSphere enterprise applications > TaskContainer_ suffix > Context Root for Web Modules
Verify that the context root for the web module HTMRESTAPI is correct and unique.

To change the endpoint references for Business Process Choreographer Explorer, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Business Process Choreographer Explorer, then in the list of configured Business Process Choreographer Explorer instances, click one instance to edit it and change the values for Business Flow Manager REST API URL and Human Task Manager REST API URL. Repeat this step as necessary for the other instances.

To change the endpoint references for Business Space:

To change the endpoint for the Business Flow Manager, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Business Flow Manager, and under Additional Properties click REST Service Endpoint.
To change the endpoint for the Human Task Manager, click either Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Human Task Manager, and under Additional Properties click REST Service Endpoint.

The JAX web services APIs were configured during migration. You might want to map the web modules to a web server and change the context root for the web modules of the JAX web services APIs.
To change the context root:

In the administrative console click Applications > Application Types > WebSphere enterprise applications > BPEContainer_ suffix > Context Root for Web Modules. Where suffix is either node_name_ server_name or the cluster_name where Business Process Choreographer is configured.
Verify that the context root for the web module BFMJAXWSAPI is correct and unique.
In the administrative console click Applications > Application Types > WebSphere enterprise applications > TaskContainer_ suffix > Context Root for Web Modules
Verify that the context root for the web module HTMJAXWSAPI is correct and unique.
If you performed the "minimum downtime" scenario to migrate a cluster, run the bpeupgrade.jacl script to deploy the new versions of the predefined human tasks and to ensure that the new Business Process Choreographer JAX web services APIs are added.
CAUTION:
Do not try to use the administrative console to update the predefined human task applications.
Stop the dmgr.
On the dmgr, change to the directory where the bpeupgrade.jacl script is located, and run the script. Enter the following commands:
cd  INSTALL_ROOT/ProcessChoreographer/config
../../bin/wsadmin.sh -conntype NONE -profileName  profileName 
                     -f bpeupgrade.jacl -cluster  clusterName
cd  INSTALL_ROOT\ProcessChoreographer\config
..\..\bin\wsadmin -conntype NONE -profileName  profileName 
                  -f bpeupgrade.jacl -cluster  clusterName
Where profileName is the name of the dmgr's profile and clusterName is the name of cluster where Business Process Choreographer is configured. Change to the directory INSTALL_ROOT/ProcessChoreographer/config and enter this command:
../../bin/wsadmin.sh -conntype NONE -profileName  profileName 
                     -f bpeupgrade.jacl -cluster  clusterName
Start the dmgr.
Synchronize the configuration changes with the nodes and restart the cluster members.
Optional: Delete any old versions of predefined human task applications. It is possible that the migration introduced new versions of the predefined human task applications, but because there might still be running instances of the old predefined human task applications, the old predefined human task applications are not undeployed during migration. Therefore it is possible that new and old versions of the predefined human task applications might exist in your system, and you should perform the following actions:

To identify whether your system contains multiple versions of the predefined human tasks, in the administrative console, click Applications > Application Types > WebSphere enterprise applications.
Locate all applications with names of the following patterns:

HTM_PredefinedTasks_V nnn_ scope.ear
HTM_PredefinedTaskMsg_V nnn_ scope.ear
Where

nnn

is the version number when the application was last updated, for example 700. If the newest version of these applications looks older than the current release, it just means that it did not change since that version. The important thing is whether there are multiple versions of these applications.

scope

is either nodeName_ serverName or clusterName, depending on whether the predefined tasks are installed on a single server or on a cluster.

If there are multiple versions of the predefined human tasks, make a note of the old versions. When there are no old instances still running, you can delete all the old instances, and then undeploy the old version of the applications. Undeploying the old applications helps to reduce the server start time.

If you migrated from a version earlier than 7.5 and none of your applications use the Business Flow Manager or Human Task Manager's query or query table APIs, you can improve your database performance by running the optionalUpgradeIndexes.sql script, which removes the indexes that are only used by those APIs. If you did not already remove these indexes, perform Remove redundant indexes.
If you used the Business Process Choreographer Explorer reporting function, you should be aware that it is not available anymore. Except for the reporting database, all applications and resources for the reporting function were deleted during migration.
If you need to monitor and report on your BPEL processes, plan to use IBM Business Monitor.
If you do not need to keep the contents of the reporting database, you can drop the database functions, schema, or table spaces .
Change to the directory that contains the generated scripts for your database.

profile_root/dbscripts/ProcessChoreographer/ database_type/ database_name/ schema_name
profile_root\dbscripts\ProcessChoreographer\ database_type\ database_name\ schema_name

Where database_type has one of the following values: DB2, DB2zOS, or Oracle, database_name is the name of the reporting database, and schema_name is the schema name used. If no schema name was used for the reporting database, the schema_name directory does not exist and the scripts are generated in the database_name directory.

Verify that the directory contains the following scripts:

dropFunction_Observer.sql
dropFunctions_Observer.sql
dropSchema_Observer.sql
dropTablespace_Observer.sql

Tip: These files are generated by the BPMGenerateUpgradeSchemaScripts command-line utility. If you did not run that utility during Manually upgrading the product databases, the SQL files will not exist and run the utility before proceeding.
If you were using SQL-based user-defined functions (UDFs) in the Business Process Choreographer reporting database, you can delete the functions by running the dropFunctions_Observer.sql script.
For example:
For a DB2 for z/OS database:
db2 -tf dropFunction_Observer.sql
For a DB2 database:
db2 -tf dropFunctions_Observer.sql
For an Oracle database:
sqlplus  userID/ password    @ database_name@dropFunctions_Observer.sql
To drop the schema, run the dropSchema_Observer.sql script.
For example:
For a DB2 or DB2 for z/OS database:
db2 -tf dropSchema_Observer.sql
For an Oracle database:
sqlplus  userID/ password    @ database_name@dropSchema_Observer.sql
To drop the table space, run the dropTablespace_Observer.sql script.
For example:
For a DB2 or DB2 for z/OS database:
db2 -tf dropTablespace_Observer.sql
For an Oracle database:
sqlplus  userID/ password    @ database_name@dropTablespace_Observer.sql
Optional: Retune your database now or later.
For example, for DB2 databases, run REORG and RUNSTATS.
If you migrated from version 6.2, or 7.0 without Feature Pack 1, and you want to use work baskets and business categories, you must enable these features in the administrative console.

In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Human Task Manager > Configuration.
Under Advanced people assignment and categorization, select the features that you want to enable.

If you modified the faces-config-beans.xml configuration file to specify thresholds for the queries for the Business Process Choreographer Explorer before migrating to V8.0.1, you must reapply the changes. For more information, refer to the following technote: Business Process Choreographer Explorer - Customization and Tuning Options.
Since version 6.1, only predefined views are affected by the settings in the faces-config-beans.xml file. The thresholds for custom views are specified as part of their definition.
If you use a generated JavaServer Faces (JSF) client for BPEL processes or human tasks, or if you created an application for BPEL processes or human tasks using JSF components, and your server is configured to use Apache MyFaces 2.0, you must replace the Business Process Choreographer JAR files. Using IBM Integration Designer, perform the following actions for each affected application.

Import your application.
Replace the following files in the WEB-INF/lib directory of your project:

bfmclientmodel.jar
htmclientmodel.jar
bpcclientcore.jar
bpcjsfcomponents.jar
bpeapi.jar
taskapi.jar

In IBM BPM Advanced, all of these files are in the following directory:

INSTALL_ROOT\ProcessChoreographer\client

INSTALL_ROOT/ProcessChoreographer/client

These files are in the INSTALL_ROOT/ProcessChoreographer/client directory.
Optional: Remove the following unnecessary files from the WEB-INF/lib directory of your project if they are there:

bpe137650.jar
icu4j_3_4_1.jar
task137650.jar

Export your application.

If you migrated from a version earlier than 7.0, change the business process navigation mode to the new default. From version 7.0, the default navigation mode for business processes uses the work-manager. Before version 7.0, the default navigation mode used JMS messaging. Because the navigation mode is not changed during migration, if you want to improve performance by using the work-manager-based navigation, you must select it manually, as described in the related link "Improving the performance of business process navigation".
Optional: You can improve the database performance by activating shared work items. This is described in the related link "Adding support for shared work items".
Optional: Change the database retention behavior for iterated inline human tasks. Before version 7.0, inline human tasks that were processed as part of multiple "while" loops or "repeat-until" loops were kept in the database by default. The new default behavior, starting with version 7.0, is that if "while" loops or "repeat-until" loops iterate multiple times, the inline human tasks that were processed in previous iterations are deleted from the database.
If you want to maintain the previous behavior for both types of loop in migrated environments, you must add a new custom property manually. In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Business Flow Manager > Custom Properties.. Then add a property named InlineHumanTasks.KeepOverMultipleWhileLoopIterations with the value true. When you no longer want the old behavior, you must delete the custom property.
If you want to use IBM Business Monitor to monitor Service Component Architecture events, you must set a custom property to enable SCA events.

In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name or Servers > Server Types > WebSphere application servers > server_name, then under Business Integration, expand Business Process Choreographer, and click Business Flow Manager > Custom Properties.

Click New to add a custom property.
Enter the name Compat.SCAMonitoringForBFMAPI and the value true.
Save the changes. The setting will be activated the next time that you restart the server or cluster where Business Process Choreographer is configured.
Postmigration tasks

Related information:
Listing information about process and task templates
Uninstalling business process and human task applications, using the administrative console
Uninstalling business process and human task applications, using administrative commands
Improving the performance of business process navigation
Adding support for shared work items
Remove redundant indexes