Profile upgrade instructions for IBM Business Process Manager Version 8.5.0 Fix Pack 2 (V8.5.0.2)

Table of Contents

• Upgrading network deployment profiles for IBM Business Process Manager Advanced or IBM Business Process Manager Standard
• Upgrading stand-alone profiles for IBM Business Process Manager Express or IBM Integration Designer's Unit Test Environment (UTE)
• Identifying and recovering from profile upgrade or bootstrapProcessServerData errors 
• Rolling back the IBM BPM environment

  
 

Upgrading network deployment profiles for IBM Business Process Manager Advanced or IBM Business Process Manager Standard

To upgrade each deployment environment, first back up your existing installation, install V8.5.0 Fix Pack 2 (V8.5.0.2) onto the deployment manager and each managed node, and then start the deployment manager and nodes.

Procedure

1. Stop all the Java processes associated with the IBM Business Process Manager (BPM) products being upgraded.
   
   
1. Stop the single cluster or the three clusters in the following order: Support, Application, and then Messaging.
2. Stop any other servers, the node agents, and then the deployment manager.
3. Stop any other associated JVMs such as the Profile Management Tool.
4. Disable the Windows service or another function that automatically restarts the servers when they are down until the upgrade process is complete.
   Important: The product might not continue to run successfully if you install V8.5.0.2 when a Java process related to IBM WebSphere Application Server is running. 
   
   
2. Back up your IBM BPM profiles. This fix pack updates the core product files and all the profiles that require a maintenance update. Before you upgrade a product, run the backupConfig command to back up the configuration files of each profile that the fix pack can update. After the command runs, a message that confirms the success of the process is displayed. For more information about running this command, see Backing up and restoring administrative configuration files.
   
   
3. If you changed any of the following default XSL transformation files, back them up before installing the fix pack. The files are in install_root/ProcessChoreographer/Staff where install_root is the installation location of IBM Business Process Manager and are named:
• EverybodyTransformation.xsl  
• LDAPTransformation.xsl  
• SystemTransformation.xsl  
• UserRegistryTransformation.xsl
• VMMTransformation.xsl
  
  These files are overwritten during the installation of V8.5.0.2, and the changes applied to these files are lost. After you upgrade your product and before you start the server or a cluster, replace the XSL transformation files with the backup versions. 
  
  
4. Back up all databases associated with this IBM BPM environment.
   
   
5. Install V8.5.0.2 onto the deployment manager installation interactively or silently:
• Upgrading an installation interactively by using IBM Installation Manager
• Upgrading an installation silently by using the IBM Installation Manager command line (imcl)
  
  In addition, install all recommended interim fixes. See Recommended Fixes for IBM Business Process Manager products.
  
  
6. Install V8.5.0.2 onto all managed node installations interactively or silently:
• Upgrading an installation interactively by using IBM Installation Manager
• Upgrading an installation silently by using the IBM Installation Manager command line (imcl)
  
  In addition, install all recommended interim fixes. For more information, see Recommended Fixes for IBM Business Process Manager products.
  
  
7. Advanced upgrade only: If the IBM BPM V8.5.0.0 environment was created by using IBM DB2 for z/OS and it is then upgraded to V8.5.0.2, use the following Alter statement to change the column name:
   
   ALTER TABLE @SCHEMA@.FailedEvents RENAME DEST_COMP_NAME to DESTINATION_COMPONENT_NAME;
   
   where @SCHEMA@ is the schemaName used for the Common database.
   
   Also, ensure the script in <install_root>/BPM/dbscripts/DB2zOS/Create/createSchema_CommonDB.sql file reflects the correct column name DESTINATION_COMPONENT_NAME.
   
   For more information, see JR52564: FAILED EVENT TRIGGERED BUT NOT UPDATED TO FAILEDEVENTS TABLE DB2 Z/OS.
   
   
8. Start the deployment manager server. It will take a few minutes to complete the profile upgrade and run the bootstrapProcessServerData command when the server starts for the first time. This can be significantly longer than the time it takes to normally start up. You can monitor the <profile_root>/properties/service/productDir/logs/runConfigActions.log file to see the activity that is in progress during the profile upgrade process.
   Note:
• At this point, start only the deployment manager. Also, do not use the BPMConfig -start command or the IBM BPM Quick Start console until after the server has started successfully for the first time.
• Websphere Application Server must have write permission to <profile_root>/bin shell scripts during initial server startup.
  
  
9. Check for and fix bootstrap or profile upgrade errors, as explained in Identifying and recovering from profile upgrade or bootstrapProcessServerData errors. 
   
   
10. If you have a web server such as IBM HTTP Server (IHS) configured in your environment, some Business Space-based applications lose their web server target mappings during the profile upgrade. To restore the web server target mappings, complete the following steps:
    
    
1. Open the administrative console and go to Applications > All applications.
   
   
2. For each of the widget applications, BPMAdministrationWidgets_<appClusterName>, HumanTaskManagementWidgets_<appClusterName>, wesbWidget_<appClusterName>, and BusinessRules_<appClusterName>, complete the following steps:
1. In the All applications list, click the application name.
2. On the Configuration tab, click the Manage Modules link in the Modules section.
3. In the Clusters and servers list box, select both the existing deployment target (as listed in the Server column) and the web server deployment target.
4. In the modules list, click Select All > Apply > OK.
5. Save the configuration changes.
   
   
11. If you have a custom virtual host configured in your deployment environment, the Remote Artifact Loader and REST Services Gateway applications lose their virtual host mapping during the profile upgrade. To restore the custom virtual host mappings, complete the following steps:
    
    
1. Open the administrative console and go to Applications > All applications.
   
   
2. For both applications, RemoteAL61_<appClusterName> and REST Services Gateway_<appClusterName>, complete the following steps:
1. In the All applications list, click the application name.
2. On the Configuration tab, click the Virtual hosts link in the Web Module Properties section.
3. In the Virtual host list box, select the custom virtual host, for example, <deName>.Proxy_host.
4. Click OK.
5. Save the configuration changes.
   
   
12. Update the web server plug-in.
    Some new web modules have been added to the product applications in V8.5.0.2. These modules are mapped to the web server if the product applications are mapped. However, you must update the plugin-cfg.xml file for the web server with the new associations. In some cases, you might have to manually move the file to the web server after it has been generated in IBM BPM. Web server mappings are updated in the upgrade, and the web server plug-ins might need to be propagated (or generated and propagated). For more information, see the Plug-ins configuration documentation.
    
    
13. For each managed node in the Network Deployment environment, complete the following steps:
1. Start the node agent.
   Note: The managed node profile is updated automatically the first time the server starts after the fix pack is installed.
2. Check for and fix profile upgrade errors, as explained in Identifying and recovering from profile upgrade or bootstrapProcessServerData errors.
   
   
14. Ensure that node synchronization is completed.
    Check the administrative console under System Administration > Nodes to confirm that the node synchronization was successful. If there is a problem, use the syncNode command to perform synchronization.
    
    
15. Review the optional post-installation task information for additional actions you might need to take. Make the changes and perform synchronization before restarting the clusters to avoid restarting the environment again after these changes.
    
    
16. Use the Ripplestart option to start the single cluster or to start your three clusters in this sequence: Messaging, Application, and then the Support cluster. See starting a cluster.
    
    
17. After an IBM Process Center environment is upgraded to V8.5.0.2, existing Process Designer users must follow the instructions for Updating the IBM Process Designer.
    
    
18. Clear the cache in browsers that are used to access the server. In addition, if you intend to access the server by using IBM Process Designer, clear the cache in the default browser.
    
    
19. Important: When you upgrade to a fix pack, the IBM Process Portal application is replaced in your profiles. If you previously added any customization to the process application in Process Designer (for example, an IBM Connections server or an IBM Sametime server), and you still want to use those servers, you must complete the following tasks:
1. Define the servers again in the fix pack version of the Process Portal application.
2. Create a snapshot.
3. Activate the snapshot on Process Center.
4. Install the snapshot on Process Server.
   
   
20. Your IBM BPM environment is now upgraded and running at the V8.5.0.2 level. Perform any application validation testing you require at this time.
    

Upgrading stand-alone profiles for IBM Business Process Manager Express or IBM Integration Designer's Unit Test Environment (UTE)

To upgrade IBM Business Process Manager Express profiles, follow the instructions to back up your profiles and databases, install V8.5.0.2, and restart your server.

Procedure

1. Stop all the stand-alone servers and Java processes associated with the IBM BPM products that are being upgraded.
   
   Also ensure that you stop the other associated JVMs such as the Profile management Tool. If you have a Windows service or another function that automatically restarts the servers when they are down, ensure that the service or function is disabled until the upgrade process is complete.
   
   Note: The product might not continue to run successfully if you install V8.5.0.2 when a Java process related to WebSphere Application Server is running. 
   
   
2. Back up your IBM BPM profiles. This fix pack updates the core product files and all the profiles that require a maintenance update. Before you upgrade, run the backupConfig command to back up the configuration files of each profile that the fix pack can update. After the command runs, a message that confirms the success of the process is displayed. For more information about running this command, see Backing up and restoring administrative configuration files.
   
   
3. Integration Designer UTE only: If you changed any of the following default XSL transformation files, back them up before you install the fix pack because these files are overwritten during the installation of V8.5.0.2.. The files are in install_root/ProcessChoreographer/Staff directory where install_root is the installation location of IBM Business Process Manager and the files are named
• EverybodyTransformation.xsl  
• LDAPTransformation.xsl  
• SystemTransformation.xsl  
• UserRegistryTransformation.xsl
• VMMTransformation.xsl
  
  After you upgrade your installation and before you start the server or a cluster, replace the XSL transformation files with the backup versions. 
  
  
4. Back up all databases associated with this IBM BPM environment.
   
   
5. Install V8.5.0.2 interactively or silently:
• Upgrading an installation interactively by using IBM Installation Manager
• Upgrading an installation silently by using the IBM Installation Manager command line
  
  In addition, install all recommended interim fixes. See Recommended Fixes for IBM Business Process Manager products.
  
  
6. For each stand-alone profile in IBM BPM Express, complete the following steps:
   
   
1. Start the stand-alone application server. It will take a few minutes to complete the profile upgrade and run the bootstrapProcessServerData command. This can be significantly longer than the time it takes to normally start up. You can monitor the <profile_root>/properties/service/productDir/logs/runConfigActions.log file to see the activity that is in progress during the profile upgrade process.
   Note:
• Use the WebSphere Application Server startServer command to start the server for the first time after installation. Do not use the BPMConfig -start command or the IBM BPM Quick Start console until after the server has started successfully for the first time.
• Websphere Application Server must have write permission to <profile_root>\bin shell scripts during initial server startup.
2. Check for and fix errors, as explained in Identifying and recovering from profile upgrade or bootstrapProcessServerData errors.
   
   
7. If you have a web server such as IBM HTTP Server (IHS) configured in your environment, some Business Space-based applications lose their web server target mappings during the profile upgrade. To restore the web server target mappings, complete the following steps:
   
   
1. Open the administrative console and go to Applications > All applications.
   
   
2. For each of the widget applications, BPMAdministrationWidgets_<nodeName>_<serverName>, HumanTaskManagementWidgets_<nodeName>_<serverName>, wesbWidget_<nodeName>_<serverName>, and BusinessRules_<nodeName>_<serverName>, complete the following steps:
1. In the All applications list, click the application name.
2. On the Configuration tab, click the Manage Modules link in the Modules section.
3. In the Clusters and servers list box, select both the existing deployment target (as listed in the Server column) and the web server deployment target.
4. In the modules list, click Select All > Apply > OK.
5. Save the configuration changes.
   
   
8. If you have a custom virtual host configured in your deployment environment, the Remote Artifact Loader and REST Services Gateway applications lose their virtual host mapping during the profile upgrade. To restore the custom virtual host mappings, complete the following steps:
   
   
1. Open the administrative console and go to Applications > All applications.
   
   
2. For both applications, RemoteAL61_<nodeName>_<serverName> and REST Services Gateway_<nodeName>_<serverName>, complete the following steps:
1. In the All applications list, click the application name.
2. On the Configuration tab, click the Virtual hosts link in the Web Module Properties section.
3. In the Virtual host list box, select the custom virtual host, for example, <deName>.Proxy_host.
4. Click OK.
5. Save the configuration changes.
   
   
9. Update the web server plug-in.
   
   Some new web modules have been added to the product applications in V8.5.0.2. These modules are mapped to the web server if the existing product applications are mapped. However, you must update the plugin-cfg.xml file for the web server with the new associations. In some cases, you might have to manually move the file to the web server after it has been generated in IBM BPM. Web server mappings are updated in the upgrade, and any web server plug-ins might need to be propagated (or generated and propagated). For more information, see the Plug-ins configuration documentation.
   
   
10. After an IBM Process Center environment is upgraded to V8.5.0.2, existing Process Designer users must follow the instructions for Updating the IBM Process Designer.
    
    
11. Clear the cache in browsers that are used to access the server. In addition, if you intend to access the server by using IBM Process Designer, clear the cache in the default browser.
    
    
12. Review the optional post-installation task information for additional actions you might need to take.
    
    
13. Important: When you upgrade to a fix pack, the IBM Process Portal application is replaced in your profiles. If you previously added any customization to the process application in Process Designer (for example, an IBM Connections server or an IBM Sametime server), and you still want to use those servers, you must complete the following tasks:
1. Define the servers again in the fix pack version of the Process Portal application.
2. Create a snapshot.
3. Activate the snapshot on Process Center.
4. Install the snapshot on Process Server.
   
   
14. Your IBM BPM environment is now upgraded and running at the V8.5.0.2 level. Perform any application validation testing you require at this time.

Identifying and recovering from profile upgrade or bootstrapProcessServerData errors

Check the profile upgrade and bootstrapProcessServerData log files for success or errors. The log files are in the following locations:

• Profile upgrade log: <profile_root>/logs/BPMConfig_<timestamp>.log
• bootstrapProcessServerData log: <profile_root>/logs/bootstrapProcesServerData.<deployment_target>.<timestamp>.log
• <profile_root> is the root directory of the profile. It is the stand-alone profile for IBM BPM Express and Integration Designer's UTE, and it's the deployment manager profile for IBM BPM Standard and IBM BPM Advanced.
• deployment_target is the application cluster name for a network deployment environment and it is the nodename_servername for a stand-alone environment.
• If both these log files do not exist or only one exists, then check the log files under <profile_root>/properties/service/productDir for error messages.

Confirming that the profiles were upgraded successfully
Check the log files for the following:

• Profile upgrade log for the message:
  'The BPMConfig.bat -upgrade -profile <profilePath>' command completed successfully.
• bootstrapProcessServerData log for the message:
  INFO:The bootstrapping of data completed successfully

Recovering from errors

• When you start the server for the first time after you install the fix pack, you might see an error message similar to the following message:
  
  runConfigActions script execution failed. Exit code: 1
  Exception caught while waiting for runConfigActions script to complete: <profile_root>\bin\runConfigActions.bat
  
  This error message indicates that a profile upgrade or bootstrapProcessServerData error has occurred.
  
  Note: For custom nodes, the bootstrapProcessServerData command is not invoked during node startup.
  
  
• Check the log files for profile upgrade and bootstrapProcessServerData actions, even if an error was not reported for runConfigActions.
• Profile upgrade log for the message:
  The 'BPMConfig.sh -upgrade -profile <profile>' command failed.
• bootstrapProcessServerData log file for any error or exception. You can check the wsadmin.traceout file under the same directory for further details.
  
  
Fix the errors and try to restart the server.

  

Rolling back the IBM BPM environment

If you updated the profiles with the fix pack, multiple steps are needed to roll back the changes. Otherwise, your environment can become out of sync and not function properly.
Note: The IBM BPM environment will return to the state it was in before the fix pack was installed. Any work done after installing the fix pack is lost.

Rolling back the environment requires that you successfully took a backup of your profiles and IBM BPM databases before the installation of the fix pack.

Procedure

To roll back the fix pack and restore the profiles, complete the following steps:

1. Export any custom enterprise applications that you have installed since you ran the backupConfig command. Make note of any changes you made after backing up the profiles.
   
   
2. Stop all the Java processes associated with the IBM BPM installations being rolled back.
1. Stop the servers for your environment.
• Standard and Advanced only:
1. Stop the single cluster or the three clusters in the following order: Support, Application, and then Messaging.
2. Stop any other servers, the node agents, and then the deployment manager.
• Express and Integration Designer UTE only: Stop all the stand-alone servers.
2. Stop any other associated JVMs such as the Profile Management Tool.
3. Disable the Windows service or another function that automatically restarts the servers when they are down until the upgrade process is complete.
   
   
3. Roll back the fix pack by using Installation Manager. See Rolling back V8.5.0 Fix Pack 2 (V8.5.0.2) on the Installing the fix pack tab for more details.
   
   
4. Restore the backup of all your BPM environment's databases.
   Note: Only the Process Server database is changed during the upgrade process, although your applications might change things in the other databases after the upgrade.
   
   
5. Run the restoreConfig command for each profile.
   restoreConfig backup_file
   
   
6. Clean the profile upgrade footprint to ensure that the profile will be upgraded and the system toolkits will be updated the next time you start the servers. To clean the profile upgrade footprint, delete these files if they exist: BPMConfigUpgrade8502_EXECUTED, BootstrapProcessServerData8502_EXECUTED, and BPMToolkitUpgrade_EXECUTED in the profile_root/workspace directory and cacheActionRegistry.xml in the profile_root/properties/service/productDir/BPM directory.
   
   
7. Start your IBM BPM environment. The environment is now rolled back to its previous state.
• Standard and Advanced only:
1. Start the deployment manager and each node agent.
2. Start the single cluster or the three clusters in the following order: Messaging, Application, and then Support.
• Express and Integration Designer UTE only: Start all the stand-alone application servers.
  
  
8. Reinstall any needed applications, and redo any other applicable configuration changes that you made since you ran the backupConfig command.

 

Additional information

• You can find additional information about these topics in the IBM Business Process Manager documentation.
• For a list of the most recent problems and solutions for this release, see the following documents:
• Release Notes for IBM Business Process Manager Standard Version 8.5 and its fix packs
• Release Notes for IBM Business Process Manager Express Version 8.5 and its fix packs
• Release Notes for IBM Business Process Manager Advanced Version 8.5 and its fix packs

Trademarks and service marks

For trademark attribution, visit the IBM Terms of Use Web site.