Upgrading profiles from IBM Business Process Manager Version 8.5.0.x or 8.5.5 to IBM Business Process Manager Version 8.5.6.0 Cumulative Fix 2

Table of Contents

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

Upgrading IBM Business Process Manager V8.5.0.x or V8.5.5 profiles to IBM Business Process Manager V8.5.6.0 CF02 profiles

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

Restriction: IBM Business Process Manager V8.5.6 does not support the z/OS operating system and does not support 32-bit operating systems. If you are running on a 32-bit system and want to upgrade, you must either perform artifact migration as described in Migrating artifacts to IBM Business Process Manager V8.5.6 or contact IBM Support for help to migrate to IBM Business Process Manager V8.5.6 on a 64-bit operating system

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 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 profiles for IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.0.x or V8.5.5

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

Procedure

1. Verify that your target environment - including hardware, operating systems, and database prerequisites - is a supported operating environment for IBM Business Process Manager V8.5.6. See IBM Business Process Manager Advanced system requirements or IBM Business Process Manager Standard system requirements.
   Important: The minimum DB2 level has been increased to 9.7.0.5. If required, move to the new database version and make sure that IBM Business Process Manager is working correctly before you proceed with the upgrade.
   
   
2. 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.
   
   
3. Back up your IBM BPM profiles. V8.5 Refresh Pack 6 and the cumulative fix update 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 refresh pack can update. See Backing up and restoring administrative configuration files in the WebSphere Application Server product documentation.
   
   
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, although your applications might make changes in the other databases after the upgrade.
   
   
5. Advanced upgrade only: If you changed any of the following default XSL transformation files, back them up before you install the refresh pack. The files are in install_root/ProcessChoreographer/Staff directory, where install_root is the installation location of IBM BPM, and are named:
   EverybodyTransformation.xsl
   LDAPTransformation.xsl
   SystemTransformation.xsl
   UserRegistryTransformation.xsl
   VMMTransformation.xsl
   These files are overwritten during the installation of the refresh pack, and the changes that were applied to these files are lost. After you upgrade your installation and before you start the server or a cluster, replace the XSL transformation files with the backup versions.
   
   
6. 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.
   
   
7. Optional: If you want to use IBM WebSphere SDK Java Technology Edition 7 or 7.1 rather than the existing Java 6, you should install it before you upgrade. Start Installation Manager and click Install. On the Packages page, select IBM WebSphere SDK Java TE 7 or 7.1 and complete the installation process. New profiles you create will use Java 7 or 7.1.
   
   
8. Install the V8.5.6 refresh pack and cumulative fix onto the deployment manager installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
9. Install the V8.5.6 refresh pack and cumulative fix onto all managed node installations interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
10. Optional: If you enabled custom password encryption in your IBM BPM environment to protect passwords that are contained in your WebSphere Application Server configuration, you must enable the DBUpgrade script to support custom encryption.
1. From install_root/bin, open the script or batch file for the DBUpgrade command.
2. Find the "Enabling custom password encryption" comment block. Read the comments and then uncomment the properties.
3. Modify the value of the CUSTOMPWDPROPS property based on your custom encryption class name. Also add any additional system properties that your custom encryption class needs.
4. Modify the value of the CLASSPATH property and replace it with the full file path of your custom password encryption jar file.
   
   
11. Optional: If you created the IBM BPM V8.5.x environment without using the BPMConfig command or you do not have a complete configuration properties file, you must complete the following steps to generate the file:
1. Upgrade the profile to V8.5.6.
   On Windows: install_root\bin\BPMConfig.bat -upgrade -profile deployment_manager_profile_name
   On Linux or UNIX:: install_root/bin/BPMConfig.sh -upgrade -profile deployment_manager_profile_name
   
   
2. Export the configuration properties file.
   On Windows: install_root\bin\BPMConfig.bat -export -profile deployment_manager_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   On Linux or UNIX: install_root/bin/BPMConfig.sh -export -profile deployment_manager_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   The configuration properties file is named deployment_environment_name.properties and is in the output directory that you specified. You will refer to this file from the migration properties file in the next step.
   Tip: If you do not know the deployment environment name, you can find it by going to deployment_manager_profile/bin and running the following command:
   wsadmin -conntype none -lang jython -c "print AdminConfig.list('BPMDeploymentEnvironment')"
   The output is either nothing, if no deployment environment is configured, or a statement similar to the following:
   WASX7357I: By request, this scripting client is not connected to any  server process. Certain configuration and application operations will be available in local mode.
   'TestDe(cells/PCCell1|cell-bpm.xml#BPMDeploymentEnvironment_1401230195442)'
   The name right before cells/ is the deployment_environment_name, in this case TestDe.
   If you are using secure LDAP and you verify the exported properties file with the BPMConfig -validate command, you might see the following error: CWMCB0345E: LDAP protocol ldaps: is not supported. You can safely ignore this error.
   
   
12. Create a migration properties file using the template. This file will be used in the later upgrade commands. The template properties file to copy is in install_root/util/migration/resources/migration.properties. Ensure that the value of each of the following properties in the migration properties file is set correctly:
    - bpm.home: IBM BPM installation path
    - profile.name: Name of the deployment manager profile
    - target.config.property.file: Full path to the configuration properties file that you used to create your IBM BPM V8.5.x environment or that you generated in step 11.
    Important: Check the bpm.de.sourceInfo.versionInfo property in the configuration properties file and make sure that the source version is correct. If this property does not exist in the file, you do not need to add it.
    
    
13. If you have a DB2 for z/OS database, complete the following steps:
1. Run one of the following commands to generate the SQL file to update your database, where migration_properties_file is the migration properties file that you created in step 12.
   On Windows: install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -propertiesFile migration_properties_file
   On Linux or UNIX: install_root/bin/BPMGenerateUpgradeSchemaScripts.sh -propertiesFile migration_properties_file
   The SQL scripts are generated in the deployment_manager_profile/dbscripts/Upgrade directory, under the following subdirectory: cell_name.deployment_environment_name/database_type/database_name.schema_name.
   
   
2. Connect to the DB2 for z/OS database, and run these SQL scripts against the database using your preferred tool in this order.
   - upgradeSchema85x_ProcessServer.sql
   - createProcedure.sql
   
   
3. Open the install_root/util/dbUpgrade/upgrade.properties file and set the value of the database.is.db2zos property to true.
   
   
14. Run one of the following commands to upgrade your database, where migration_properties_file is the migration properties file that you created in step 12.
    Notes:
    If you have multiple deployment environments, complete this step for each deployment environment.
    Skip this step for AdvancedOnly deployment environments. There is no database schema update for AdvancedOnly environments upgraded from V8.5.x.
    
    On Windows: install_root\bin\DBUpgrade.bat -propertiesFile migration_properties_file
    On Linux or UNIX: install_root/bin/DBUpgrade.sh -propertiesFile migration_properties_file
    
    Important: Make sure that the DBUpgrade command has finished successfully before you move to the next step. The log is saved in deployment_manager_profile_root/logs/DBUpgrade_timestamp.log. Check the log for errors or exceptions. If running DBUpgrade was unsuccessful, correct the errors and restore your databases from the backup before running the command again.
    Tip: If you are using Oracle, you might see an error similar to the following error:
    Executing upgrade step: Upgrade 8.5.0 schema to 8.5.5 for database ProcessServerDatabase.
    Error executing SQL statement: ORA-60019: Creating initial extent of size 14 in tablespace of extent size 8
    On Oracle, IBM Business Process Manager stores large objects (LOBs) with the SECUREFILE option. For SECUREFILE, it is recommended to use a tablespace with the AUTOALLOCATE option. If you use UNIFORM SIZE extents, ensure that the UNIFORM SIZE is big enough. Given the default block size of 8K, specify a UNIFORM SIZE of at least 120K. IBM BPM does not explicitly prescribe the tablespace options; it relies on the default Oracle settings (such as AUTOALLOCATE) to automatically manage extents. If you use tablespaces with a UNIFORM SIZE less than 120K, create new tablespaces with the AUTOALLOCATE option and make it the default tablespace for IBM BPM database schema users.
    
    
15. Optional: If you enabled custom password encryption in your IBM BPM environment to protect passwords that are contained in your WebSphere Application Server configuration, you must enable the BPMConfig script to support custom encryption.
1. From install_root/bin, open the script or batch file for the BPMConfig command.
2. Find the "Enabling custom password encryption" comment block. Read the comments and then uncomment the properties.
3. Modify the value of the CUSTOMPWDPROPS property based on your custom encryption class name. Also add any additional system properties that your custom encryption class needs.
   
   
16. Start the deployment manager server. It takes a few minutes to complete the profile upgrade and run the bootstrapProcessServerData command when the server starts for the first time. This time 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.
    Notes:
    The deployment manager profile is updated automatically during the first server startup after the refresh pack installation.
    The Business Process Choreographer, Business Space, CommonDB, and Messaging Engine databases are not changed when you upgrade from IBM BPM V8.5.x to the V8.5.6 refresh pack.
    
    
17. Check for and fix errors, as described in Identifying and recovering from profile upgrade, bootstrapProcessServerData, or toolkit update errors, before you continue.
    
    
18. Advanced upgrade only: If you backed up your default XSL transformation files in step 5, replace the XSL transformation files with the backup versions.
    
    
19. Update the web server plug-in.
    Some new web modules have been added to the product applications in the refresh pack. These modules are mapped to the web server if the existing product applications are mapped. However, the plugin-cfg.xml file for the web server must be updated 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. For more information, see the Plug-ins configuration documentation.
    
    
20. As part of upgrading the IBM BPM deployment environment to V8.5.6.0, a truststore for connections to IBM Blueworks Live (one per WebSphere cell, named BlueWorksLiveTrustStore) and a keystore for IBM BPM (one per IBM BPM deployment environment, named IBMBPMKeyStore-de_name) are added to the configuration. The truststore and the keystore use the same password as the WebSphere CellDefaultKeyStore initially. If the WebSphere default keystore is not found, then the documented WebSphere default keystore password is used. You are advised to assign separate passwords to the BlueWorksLiveTrustStore truststore and to the IBMBPMKeyStore-de_name keystore.
    
    
21. 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, bootstrapProcessServerData, or toolkit update errors, before you continue.
   
   
22. 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.
    
    
23. 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.
    
    
24. Use the Ripplestart option to start the single cluster or to start your three clusters in this sequence: Messaging, Application, and then Support. See Starting a cluster.
    
    
25. After an IBM Process Center environment is upgraded, existing Process users must follow the instructions for Updating IBM Process Designer.
    
    
26. Optional: If you want to use IBM WebSphere SDK Java Technology Edition 7 or 7.1 rather than the existing Java 6, switch existing profiles. Follow the instructions in Switching the edition of Java used in IBM BPM.
    
    
27. Optional: When you upgrade, the cleanup of shared business objects is automatically disabled. If you are using shared business objects in the source version, you might want to change the cleanupMaxVersionCount property to explicitly enable cleanup. See Cleaning up shared business objects for instructions.
    
    
28. Optional: 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.
  
  
29. 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 (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.
   
   
30. 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 Business Process Manager Express V8.5.0.x or V8.5.5

To upgrade IBM Business Process Manager Express V8.50.x or V8.5.5 profiles, follow the instructions to back up your profiles and Process Server database, install the V8.5.6 refresh pack and cumulative fix, upgrade your Process Server database, and restart your server.

Procedure

1. Verify that your target environment - including hardware, operating systems, and database prerequisites - is a supported operating environment for IBM BPM V8.5.6. See IBM Business Process Manager Express system requirements.
   Important: The minimum DB2 level has been increased to 9.7.0.5. If required, move to the new database version and make sure that IBM BPM is working correctly before you proceed with the upgrade.
   
   
2. Stop all the Java™ processes associated with the IBM BPM (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.
   
   
3. Back up your IBM BPM profiles. The V8.5.6 refresh pack and the cumulative fix update 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 refresh pack can update. See Backing up and restoring administrative configuration files in the WebSphere Application Server product documentation.
   
   
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, although your applications might make changes in the other databases after the upgrade.
   
   
5. 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.
   
   
6. Optional: If you want to use IBM WebSphere SDK Java Technology Edition 7 or 7.1 rather than the existing Java 6, you should install it before you upgrade. Start Installation Manager and click Install. On the Packages page, select IBM WebSphere SDK Java TE 7 or 7.1 and complete the installation process. New profiles you create will use Java 7 or 7.1.
   
   
7. Install the V8.5.6 refresh pack and cumulative fix onto the stand-alone installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
8. Optional: If you enabled custom password encryption in your IBM BPM environment to protect passwords that are contained in your WebSphere Application Server configuration, you must enable the DBUpgrade script to support custom encryption.
1. From install_root/bin, open the script or batch file for the DBUpgrade command.
2. Find the "Enabling custom password encryption" comment block. Read the comments and then uncomment the properties.
3. Modify the value of the CUSTOMPWDPROPS property based on your custom encryption class name. Also add any additional system properties that your custom encryption class needs.
4. Modify the value of the CLASSPATH property and replace it with the full file path of your custom password encryption jar file.
   
   
9. Optional: If you created the IBM BPM V8.5.x environment without using the BPMConfig command or you do not have a complete configuration properties file, you must complete the following steps to generate the file:
1. Upgrade the profile to V8.5.6.
   On Windows: install_root\bin\BPMConfig.bat -upgrade -profile stand-alone_profile_name
   On Linux or UNIX: install_root/bin/BPMConfig.sh -upgrade -profile stand-alone_profile_name
   
   
2. Export the configuration properties file.
   On Windows: install_root\bin\BPMConfig.bat -export -profile stand-alone_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   On Linux or UNIX: install_root/bin/BPMConfig.sh -export -profile stand-alone_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   The configuration properties file is named deployment_environment_name.properties and is in the output directory that you specified. You will refer to this file from the migration properties file in the next step.
   Tip: For a typical installation, the deployment_environment_name is always ProcessCenter or ProcessServer. For a custom installation, if you do not know the name, you can find it by going to stand-alone_profile/bin and running the following command:
   wsadmin -conntype none -lang jython -c "print AdminConfig.list('BPMDeploymentEnvironment')"
   The output is either nothing, if no deployment environment or Process Server database is configured and you do not need to upgrade, or a statement similar to the following:
   WASX7357I: By request, this scripting client is not connected to any  server process. Certain configuration and application operations will be available in local mode.
   'TestDe(cells/PCCell1|cell-bpm.xml#BPMDeploymentEnvironment_1401230195442)'
   The name right before cells/ is the deployment_environment_name, in this case TestDe.
   If you are using secure LDAP and you verify the exported properties file with the BPMConfig -validate command, you might see the following error: CWMCB0345E: LDAP protocol ldaps: is not supported. You can safely ignore this error.
   
   
10. Create a migration properties file using the template. This file will be used in the later upgrade commands. The template properties file to copy is in install_root/util/migration/resources/migration.properties. Ensure that the value of each of the following properties in the migration properties file is set correctly:
    - bpm.home: IBM BPM installation path
    - profile.name: Name of the deployment manager profile
    - target.config.property.file: Full path to the configuration properties file that you used to create your IBM BPM V8.5.x environment or that you generated in step 8.
    Important: Check the bpm.de.sourceInfo.versionInfo property in the configuration properties file and make sure that the source version is correct. If this property does not exist in the file, you do not need to add it.
    
    
11. Run one of the following commands to upgrade your database, where migration_properties_file is the migration properties file that you created in step 9.
    On Windows: install_root\bin\DBUpgrade.bat -propertiesFile migration_properties_file
    On Linux or UNIX: install_root/bin/DBUpgrade.sh -propertiesFile migration_properties_file
    Important: Make sure that the DBUpgrade command has finished successfully before you move to the next step. The log is saved in profile_root/logs/DBUpgrade_timestamp.log. Check the log for errors or exceptions. If running DBUpgrade was unsuccessful, correct the errors and restore your databases from the backup before running the command again.
    Tip: If you are using Oracle, you might see an error similar to the following error:
    Executing upgrade step: Upgrade 8.5.0 schema to 8.5.5 for database ProcessServerDatabase.
    Error executing SQL statement: ORA-60019: Creating initial extent of size 14 in tablespace of extent size 8
    On Oracle, IBM Business Process Manager stores large objects (LOBs) with the SECUREFILE option. For SECUREFILE, it is recommended to use a tablespace with the AUTOALLOCATE option. If you use UNIFORM SIZE extents, ensure that the UNIFORM SIZE is big enough. Given the default block size of 8K, specify a UNIFORM SIZE of at least 120K. IBM BPM does not explicitly prescribe the tablespace options; it relies on the default Oracle settings (such as AUTOALLOCATE) to automatically manage extents. If you use tablespaces with a UNIFORM SIZE less than 120K, create new tablespaces with the AUTOALLOCATE option and make it the default tablespace for IBM BPM database schema users.
    
    
12. Optional: If you enabled custom password encryption in your IBM BPM environment to protect passwords that are contained in your WebSphere Application Server configuration, you must enable the BPMConfig script to support custom encryption.
1. From install_root/bin, open the script or batch file for the BPMConfig command.
2. Find the "Enabling custom password encryption" comment block. Read the comments and then uncomment the properties.
3. Modify the value of the CUSTOMPWDPROPS property based on your custom encryption class name. Also add any additional system properties that your custom encryption class needs.
   
   
13. 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 run the bootstrapProcessServerData command when the server starts for the first time. This time 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, bootstrapProcessServerData, or toolkit update errors, before you continue.
   Notes:
   The stand-alone profile is updated automatically during the first server startup after the refresh pack installation.
   The Business Space and Messaging Engine databases are not changed when you upgrade from IBM BPM V8.5.x to the V8.5.6 refresh pack.
   
   
14. Update the web server plug-in.
    Some new web modules have been added to the product applications in the refresh pack. These modules are mapped to the web server if the existing product applications are mapped. However, the plugin-cfg.xml file for the web server must be updated 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. For more information, see the Plug-ins configuration documentation.
    
    
15. As part of upgrading the IBM BPM deployment environment to V8.5.6.0, a truststore for connections to IBM Blueworks Live (one per WebSphere cell, named BlueWorksLiveTrustStore) and a keystore for IBM BPM (one per IBM BPM deployment environment, named IBMBPMKeyStore-de_name) are added to the configuration. The truststore and the keystore use the same password as the WebSphere NodeDefaultKeyStore initially. If the WebSphere default keystore is not found, then the documented WebSphere default keystore password is used. You are advised to assign separate passwords to the BlueWorksLiveTrustStore truststore and to the IBMBPMKeyStore-de_name keystore.
    
    
16. After an IBM Process Center environment is upgraded, existing Process users must follow the instructions for Updating IBM Process Designer.
    
    
17. Optional: If you want to use IBM WebSphere SDK Java Technology Edition 7 or 7.1 rather than the existing Java 6, switch existing profiles. Follow the instructions in Switching the edition of Java used in IBM BPM.
    
    
18. Optional: When you upgrade, the cleanup of shared business objects is automatically disabled. If you are using shared business objects in the source version, you might want to change the cleanupMaxVersionCount property to explicitly enable cleanup. See Cleaning up shared business objects for instructions.
    
    
19. Optional: 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.
  
  
20. Review the optional Post-installation tasks for additional actions you might need to take.
    
    
21. 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.
   
   
22. 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, bootstrapProcessServerData, 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
• Log for bootstrapProcessServerData command: profile_root/logs/bootstrapProcessServerData.log.

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

If all these log files do not exist or only some of them exist, 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
• 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, toolkit update, or bootstrapProcessServerData error occurred.

Note: For managed nodes, the toolkit update and bootstrapProcessServerData command are not run during node startup.

Check the log files for profile upgrade, toolkit update, and bootstrapProcessServerData 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 and bootstrapProcessServerData command log for any errors or exceptions

If you are using a DB2 database and the bootstrapProcessServerData command fails with the error DB2 SQL Error: SQLCODE=-1476, SQLSTATE=40506, SQLERRMC=-964, you must increase the default log file size using the following SQL statement (where @DB_NAME@ specifies the name of your Process Server database):
UPDATE DB CFG FOR @DB_NAME@ USING LOGFILSIZ 16384 DEFERRED;
After you have run the SQL statement, restart the deployment manager or stand-alone server.

Note: If you are upgrading multiple deployment environments, you might encounter an out-of-memory error when the bootstrapProcessServerData command is run. To solve this problem, increase the maximum heap size in the script
install_root/BPM/Lombardi/tools/bootstrapProcessServerData.sh
Then restart the deployment manager or run the bootstrapProcesssServerData command for each deployment environment again. Note that bootstrapProcessServerData.sh should be updated for Linux or UNIX-based operating systems, but bootstrapProcessServerData.bat should be updated for Microsoft Windows operating systems.

Rerunning the BPMConfig - upgrade and bootstrapProcessServerData commands
If you want to test that a particular update step has been fixed, you can rerun these commands 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)

To rerun the bootstrapProcessServerData command, use the following syntax in a network deployment environment:

• On Windows: install_root\profiles\profile_name\bin\bootstrapProcessServerData.bat -clusterName cluster_name
• On Linux or UNIX: install_root/profiles/profile_name/bin/bootstrapProcessServerData.sh -clusterName cluster_name

Use the following syntax in a stand-alone environment:

• On Windows: install_root\profiles\profile_name\bin\bootstrapProcessServerData.bat
• On Linux or UNIX: install_root/profiles/profile_name/bin/bootstrapProcessServerData.sh

where cluster_name is the name of the application cluster in the IBM BPM deployment environment

Back to top

Rolling back the IBM BPM environment

If you updated the profiles with the refresh pack and 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 fixes were installed. Any work done after installing the fixes is lost.

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

Procedure

To roll back the refresh pack and cumulative 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 refresh pack and the cumulative 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 this 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 to ensure that the deployment manager or stand-alone profile will be upgraded and the system toolkits will be updated the next time you upgrade. To clean the profile upgrade footprint:
• Delete the BPMConfigUpgrade8560_EXECUTED, BootstrapProcessServerData8560_EXECUTED, and BPMToolkitUpgrade_EXECUTED files if they exist in the profile_root/workspace directory
• Delete the BBPMConfigUpgrade8560, BootstrapProcessServerData8560, and BPMToolkitUpgrade entries from the
  profile_root/properties/service/productDir/BPM/cacheActionRegistry.xml file
  
  
7. 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.
   
   
8. Reinstall needed applications and snapshots, and redo any other applicable configuration changes that you made since you ran the backupConfig command.
   
   
9. Before you can start the deployment environment, you must define a JVM argument for the WebSphere server JVMs that run Business Space. In the administrative console, go to Servers > Server Types > WebSphere application servers. For each IBM BPM application cluster member (IBM BPM Standard and IBM BPM Advanced), or for the single IBM BPM application server (IBM BPM Express), perform the following steps:
1. In the Name column, select the server link.
   
   
2. In the Server Infrastructure section, expand Java and Process Management and select Process definition.
   
   
3. In the Additional Properties section, select Java Virtual Machine.
   
   
4. If "-Declipse.bundle.setTCCL=false" is not shown among the existing entries in the Generic JVM arguments field, add it to any existing entries and save your changes.
   
   
5. Synchronize your changes to the managed nodes.
   
   
6. To pick up the configuration changes, restart the IBM BPM application cluster (for IBM BPM Standard or Advanced) or the single IBM BPM application server (for IBM BPM Express).

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.