Completing configuration for Business Process Choreographer

If you have an IBM® BPM Advanced deployment environment, you must perform some additional tasks before you start your clusters.
Figure 1. Sample environment after the target is started. The source environment is not running. The target can read from the databases.
The details of the diagram are provided in the figure caption.

Before you begin

You have successfully upgraded the Business Process Choreographer database schema.

About this task

Perform these tasks, if they apply to your environment, before you use IBM Business Process Manager V8.5.6 in production.

Procedure

  1. Update the Human Task Manager email service configuration.
    1. Open the Human Task Manager configuration. Click Servers > Clusters > WebSphere application server clusters > cluster_name, where cluster_name is the name of the application cluster in your deployment environment. Under Business Process Manager, expand Business Process Choreographer and click Human Task Manager > Configuration.
    2. Note the E-mail session JNDI name.
    3. Verify the migrated Escalation URL prefix, Task URL prefix, Administrator URL prefix, and Process Explorer URL prefix settings. If necessary, update them according to your V8.5.6 environment.
    4. Click Resources > Mail > Mail Sessions.
    5. Locate the template mail session with the JNDI name that was created for you (the one you found in step 1b).
    6. In the Outgoing Mail Properties section, update the Server, Protocol, User, and Password settings according to your migration source environment.
  2. Apply any settings that were customized for the Business Process Choreographer Explorer. In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name . On the Configuration tab, in the Business Process Manager section, expand Business Process Choreographer and click Business Process Choreographer Explorer.
  3. If you changed the mapping of Java EE roles for human tasks or BPEL processes, ensure that you apply the same mappings. For more information about these roles, see Security in human tasks and BPEL processes. For more information about changing the mappings, see Assigning users and groups to roles and Assigning users to RunAs roles.
  4. If you used people assignment before you migrated to V8.5.6, you must perform the following actions:
    1. Configure the same people directory provider that you used on the migration source.
      1. If you used the LDAP people directory provider, perform the actions described in Configuring the LDAP people directory provider.
        Note: If you used the BPMConfig command to migrate, the LDAP configuration was migrated from source to target.
      2. If you used the Virtual Member Manager people directory provider, perform the actions described in Configuring the Virtual Member Manager people directory provider.
    2. 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 Business Process Manager V8.5.6 versions of these files after migration.

      In a network deployment environment, the transformation files must be available on the deployment manager and on the managed nodes (if they are on different computers). Make sure that they all use the same version of the transformation files.

      To find the transformation files that you are using in the source environment, check the value of the transformation file path that is specified in the people directory configuration. If the transformation file path is install_root/ProcessChoreographer/Staff directory, you are using the default files. Otherwise, you are using custom transformation files that you must manually copy to the target environment and reconfigure in the people directory configuration.

      Note: Custom XSL transformation files must be copied manually, depending on the exact value of the transformation file path that is specified in the earlier version of the people directory configuration (previously known as the staff plug-in configuration).
    3. 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:
      1. Add the substitutionStartDate and substitutionEndDate properties to the definition of the PersonAccount entity type in the wimxmlextension.xml file. In a network deployment environment, edit the file on the deployment manager.

        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="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>
      2. The changes become effective after the deployment manager is restarted.
      For the VMM property extension registry:
      1. 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 network deployment environment, enter the commands on the deployment manager.

        wsadmin -username admin -password adminPassWord
        $AdminTask listIdMgrPropertyExtensions
      2. 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}
      3. The changes become effective after the deployment manager is restarted.
      4. Verify that the new properties were added to the property extension repository configuration by entering the following command:
        $AdminTask
        listIdMgrPropertyExtensions
  5. 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.
    1. Optional: 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 Servers > Clusters > WebSphere application server clusters > cluster_name, then in the Business Process Manager section, click Business Space REST services endpoint registration and verify that the entries for Process services and Task services are correct.
    2. If you migrated to a different computer, 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.
      1. To change the context root for the REST API web modules, in the administrative console:
        1. Click Applications > Application Types > WebSphere enterprise applications > BPEContainer_suffix > Context Root for Web Modules, where suffix is the cluster_name where Business Process Choreographer is configured.
        2. Make sure that the context root for the web module BFMRESTAPI is correct and unique.
        3. Click Applications > Application Types > WebSphere enterprise applications > TaskContainer_suffix > Context Root for Web Modules
        4. Make sure that the context root for the web module HTMRESTAPI is correct and unique.
      2. To change the endpoint references for Business Process Choreographer Explorer, click Servers > Clusters > WebSphere application server clusters > cluster_name, then under Business Process Manager, 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.

      3. To change the endpoint references for Business Space:
        1. To change the endpoint for the Business Flow Manager, click Servers > Clusters > WebSphere application server clusters > cluster_name, then under Business Process Manager, expand Business Process Choreographer, and click Business Flow Manager, and under Additional Properties click REST Service Endpoint.
        2. To change the endpoint for the Human Task Manager, click Servers > Clusters > WebSphere application server clusters > cluster_name, then under Business Process Manager, expand Business Process Choreographer, and click Human Task Manager, and under Additional Properties click REST Service Endpoint.
    3. 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:
      1. Click Applications > Application Types > WebSphere enterprise applications > BPEContainer_suffix > Context Root for Web Modules, where suffix is the cluster_name where Business Process Choreographer is configured.
      2. Make sure that the context root for the web module BFMJAXWSAPI is correct and unique.
      3. Click Applications > Application Types > WebSphere enterprise applications > TaskContainer_suffix > Context Root for Web Modules
      4. Make sure that the context root for the web module HTMJAXWSAPI is correct and unique.
  6. 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:
    1. To identify whether your system contains multiple versions of the predefined human tasks, in the administrative console, click Applications > Application Types > WebSphere enterprise applications.
    2. Locate all applications with names of the following patterns:
      • HTM_PredefinedTasks_Vnnn_cluster_name.ear
      • HTM_PredefinedTaskMsg_Vnnn_cluster_name.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.
      cluster_name
      is the name of the cluster.
    3. 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.
  7. Optional: If you migrated from version 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.
    1. In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name, then under Business Process Manager, expand Business Process Choreographer, and click Human Task Manager > Configuration.
    2. Under Advanced people assignment and categorization, select the features that you want to enable.
  8. If you modified the faces-config-beans.xml configuration file to specify thresholds for the queries for the Business Process Choreographer Explorer before you migrated to V8.5.6, you must reapply the changes.
    Note: 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.
  9. 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.
    1. Import your application.
    2. 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 Business Process Manager Advanced, all of these files are in the following directory:
      install_root/ProcessChoreographer/client
    3. 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
    4. Export your application.
  10. Optional: 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 Removing redundant indexes.
  11. Optional: You can improve the database performance by activating shared work items. See the related task link.
  12. Optional: Retune your database now or later. For example, for DB2® databases, run REORG and RUNSTATS.
  13. If you used the Business Process Choreographer Explorer reporting function, you should be aware that it is not available anymore. The applications and resources for the reporting function have not been created in the migration target environment. The reporting database was not dropped though, and is still available when needed. If you need to monitor and report on your BPEL processes, plan to use IBM Business Monitor.
  14. If you want to use IBM Business Monitor to monitor Service Component Architecture (SCA) events, you must set a custom property to enable SCA events.
    1. In the administrative console, click Servers > Clusters > WebSphere application server clusters > cluster_name, then under Business Process Manager, expand Business Process Choreographer, and click Business Flow Manager > Custom Properties.
    2. Click New to add a custom property.
    3. Enter the name Compat.SCAMonitoringForBFMAPI and the value true.
    4. Save the changes. The setting will be activated the next time that you restart the server or cluster where Business Process Choreographer is configured.
  15. Optional: Perform Tuning.