Upgrading profiles from IBM Business Process Manager Version 8.5.6.x to IBM Business Process Manager Version 8.5.6.0 Cumulative Fix 2

Table of Contents

• Upgrading IBM Business Process Manager V8.5.6.0 or V8.5.6.0 CF01 profiles to IBM Business Process Manager V8.5.6.0 Cumulative Fix 2 profiles
• Upgrading deployment environment profiles for IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.6.x
• Upgrading stand-alone profiles for IBM Business Process Manager Express V8.5.6.x
• Identifying and recovering from profile upgrade or toolkit update errors
• Rolling back the IBM BPM environment

Upgrading IBM Business Process Manager V8.5.6.0 or V8.5.6.0 CF01 profiles to IBM Business Process Manager V8.5.6.0 Cumulative Fix 2 profiles

To upgrade IBM Business Process Manager V8.5.6.0 or V8.5.6.0 CF01 profiles to V8.5.6.0 CF02 profiles, follow the instructions in this document for your specific edition (Advanced or Standard, or Express).

The Process Center and Process Server versions do not need to match, and Process Server V8.5.6.0 CF02 can connect to an earlier version of Process Center V8.5.x. You can upgrade Process Server first and test your applications to make sure that they still work normally after the upgrade. Upgrade Process Center last. For more details, see Performing a rolling upgrade.

You can also use offline deployment between Process Server V8.5.6.0 CF02 and an earlier version of Process Center V8.5.x.

Not including Process Server, the tools and related user interfaces that interact with Process Center must be at the same version and release level as Process Center. The repository does not support the previous release; only the current release. Even though you might be able to connect an installation of IBM Integration Designer at the current release level to a Process Center at the previous release level, you should not publish any process applications that have gone through artifact migration.

Back to top

Upgrading deployment environment profiles for IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.6.x

To upgrade IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.6.x profiles, follow these instructions to back up your existing installation, install the fix onto the deployment manager and each managed node, and restart the deployment manager and nodes.

Procedure

1. Stop all the Java™ processes associated with the IBM Business Process Manager (BPM) products that are 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 or the IBM BPM Quick Start..
4. If you have a Microsoft 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.
   Important: The product might not continue to run successfully if you install the fix when a Java process related to WebSphere Application Server is running.
   
   
2. Back up your IBM BPM profiles. The cumulative fix 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 can update. See Backing up and restoring administrative configuration files in the WebSphere Application Server product documentation.
   
   
3. If you customized the Process Portal themes, back up your customizations. When the profile is upgraded, the import settings for Business Space system artifacts are changed in the oobLoadedStatus.properties file and your customizations are overwritten. After you have finished upgrading, re-import and merge the customizations with the deployed theme.
   
   
4. Back up all databases associated with this IBM BPM environment. It is important that you make a backup of your databases at the same time as you make the profile backup.
   Note: Only the Process database is changed during this upgrade process, to add or update IBM BPM toolkits and process applications. There are no database schema changes. Your applications might make changes in the other databases after the upgrade.
   
   
5. Install the V8.5.6 cumulative fix onto the deployment manager installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
6. Install the V8.5.6 cumulative fix onto all managed node installations interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
7. Start the deployment manager server. It takes a few minutes to complete the profile upgrade and the toolkit update 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: The deployment manager profile is updated automatically during the first server startup after the fix is installed.
   
   
8. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit update errors, before you continue.
   
   
9. For each managed node in the network deployment environment, complete the following steps:
   
   
1. Start the node agent.
   Note: The managed profile is updated automatically during the first server startup after the fix is installed.
   
   
2. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit update errors, before you continue.
   
   
10. Ensure that node synchronization is completed.
    Check the administrative console under System Administration > Nodes to confirm that node synchronization was successful. If there is a problem, use the syncNode command to perform synchronization.
    
    
11. Review the optional Post-installation tasks 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.
    
    
12. Use the Ripplestart option to start the single cluster or to start your three clusters in this sequence: Messaging, Application, and then Support. Follow the instructions for Starting a cluster.
    
    
13. After an IBM Process Center environment is upgraded, existing Process Designer users must follow the instructions for Updating IBM Process Designer.
    
    
14. Optional: If you are upgrading from V8.5.6.0, then creating, updating, and downloading external Enterprise Content Manager (ECM) documents is disabled after you apply the fix if your applications meet all the following criteria:
• You use the Document List or Document Viewer coach views to create, update, or download the documents.
• You use an external ECM server instead of the internal IBM BPM document store.
• The properties of the ECM server definition have "Always use this connection information" selected.
  See the steps for JR53209 on the Post-installation tasks tab if your applications are affected.
  
  
15. Important: When you upgrade, 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.
   
   
16. Your IBM BPM environment is now upgraded to V8.5.6.2. Perform any application validation testing you require at this time.

Back to top

Upgrading stand-alone profiles for IBM Express V8.5.6.x

To upgrade IBM Express V8.5.6.x profiles, follow the instructions to back up your profiles and Process Server database, install the fix, and restart your server.

Procedure

1. Stop all the stand-alone services 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 or the IBM BPM Quick Start.. If you have a Microsoft 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.
   
   
   Important: The product might not continue to run successfully if you install the fix when a Java process related to WebSphere Application Server is running.
   
   
2. Back up your IBM BPM profiles. The cumulative fix 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 can update. See Backing up and restoring administrative configuration files in the WebSphere Application Server product documentation.
   
   
3. If you customized the Process Portal themes, back up your customizations. When the profile is upgraded, the import settings for Business Space system artifacts are changed in the oobLoadedStatus.properties file and your customizations are overwritten. After you have finished upgrading, re-import and merge the customizations with the deployed theme.
   
   
4. Back up all databases associated with this IBM BPM environment. It is important that you make a backup of your databases at the same time as you make the profile backup.
   Note: Only the Process database is changed during this upgrade process, to add or update IBM BPM toolkits and process applications. There are no database schema changes. Your applications might make changes in the other databases after the upgrade.
   
   
5. Install the cumulative fix onto the stand-alone installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
6. For each stand-alone profile in the IBM BPM Express installation, complete the following steps:
1. Start the stand-alone application server. It takes a few minutes to complete the profile upgrade and toolkit update 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.
   
   
2. Check for errors, as described in Identifying and recovering from profile upgrade or toolkit update errors, before you continue.
   Note: The stand-alone profile is updated automatically during the first server startup after the fix is installed.
   
   
7. After an IBM Process Center environment is upgraded, existing Process Designer users must follow the instructions for Updating IBM Process Designer.
   
   
8. Optional: If you are upgrading from 8.5.6.0, then creating, updating, and downloading external Enterprise Content Manager (ECM) documents is disabled after you apply the fix if your applications meet all the following criteria:
• You use the Document List or Document Viewer coach views to create, update, or download the documents.
• You use an external ECM server instead of the internal IBM BPM document store.
• The properties of the ECM server definition have "Always use this connection information" selected.
  See the steps for JR53209 on the Post-installation tasks tab if your applications are affected.
  
  
9. Review the optional Post-installation tasks for additional actions you might need to take.
   
   
10. Important: When you upgrade, 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.
   
   
11. Your IBM BPM environment is now upgraded to V8.5.6.2. Perform any application validation testing you require at this time.

Back to top

Identifying and recovering from profile upgrade or toolkit update errors

Check the log files for success or errors. The log files are in the following locations:

• Profile upgrade log: profile_root/logs/BPMConfig_timestamp.log.
• Toolkit update log: profile_root/logs/BPMUpdateSystemApp_timestamp.log

where profile_root is the root directory of either the deployment manager profile (Standard or Advanced) or the stand-alone profile (Express)

If both these log files do not exist or only one exists, 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.
• Toolkit update log for the message:
  Cumulative BPMUpdateSystemApp completed successfully

Recovering from errors
When you start the server for the first time after you install the fix, 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: 

This error message indicates that a profile upgrade or toolkit update error occurred.

Note: For managed nodes, the toolkit update is not run during node startup.

Check the log files for profile upgrade and toolkit update actions, even if an error was not reported for runConfigActions.

• Check the profile upgrade log for the message: The 'BPMConfig.sh -upgrade -profile <profile>' command failed.
• Check the toolkit update log for any errors or exceptions

Rerunning the BPMConfig - upgrade command
If you want to test that a particular update step has been fixed, you can rerun this command manually to test your fix.
To rerun the BPMConfig -upgrade command, use the following syntax:

• On Windows: install_root\bin\BPMConfig.bat -upgrade -profile profile_name
• On Linux or UNIX: install_root/bin/BPMConfig.sh -upgrade -profile profile_name

  where profile_root is the root directory of either the deployment manager profile (Standard or Advanced) or the stand-alone profile (Express)

Back to top

Rolling back the IBM BPM environment

If you updated the profiles with the cumulative fix, 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 was installed. Any work done after installing the fix is lost.

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

Procedure

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

1. Ensure that you have EAR files for any applications that you 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 products being rolled back.
1. Stop the servers for your environment.
1. Standard and Advanced only:
• Stop the single cluster or the three clusters in the following order: Support, Application, and then Messaging.
• Stop any other servers, the node agents, and then the deployment manager.
2. Express only: Stop all the stand-alone servers.
2. Stop any other associated JVMs, such as the Profile Management Tool or the IBM BPM Quick Start..
3. 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.
   
   
3. Roll back the fix using the Installation Manager. See Rolling back the cumulative fix on the Installation Instructions tab for more details.
   
   
4. Restore the backup of all your IBM BPM environment databases.
   Note: Only the Process database is changed during the upgrade process, although your applications might make changes in the other databases after the upgrade.
   
   
5. Run the restoreConfig command for each profile.
   restoreConfig backup_file
   
   
6. Clean the profile upgrade footprint in the deployment manager or stand-alone profile to ensure that the profile will be upgraded and the system toolkits will be updated the next time you upgrade. To clean the profile upgrade footprint:
• Delete the BPMToolkitUpgrade_EXECUTED and BPMConfigUpgrade8560_EXECUTED files if they exist in the profile_root/workspace directory
• Delete the BPMToolkitUpgrade and BPMConfigUpgrade8560 entries from the
  profile_root/properties/service/productDir/BPM/cacheActionRegistry.xml file
  
  
7. If you rolled back because of issues with the BPMUpdateSystemApp command, go to the profile_root/properties/service/productDir/BPM directory and manually delete the twximport.properties file
   where profile_root is the root directory of either the deployment manager profile (for IBM BPM Advanced or IBM BPM Standard) or the stand-alone profile (for IBM BPM Express).
   
   
8. Start your IBM BPM environment. The environment is now rolled back to its previous state.
1. Standard and Advanced only:
• Start the deployment manager and each node agent.
• Start the single cluster or the three clusters in the following order: Messaging, Application, and then Support.
2. Express only: Start all the stand-alone servers.
   
   
9. Reinstall needed applications or snapshots, and redo any other applicable configuration changes that you made since you ran the backupConfig command.

Back to top

Additional information

You can find additional information about any of these topics in the IBM Business Process Manager product documentation.

Trademarks and service marks

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