Profile upgrade instructions for IBM Business Process Manager Version 8.5 Refresh Pack 5

Upgrading IBM Business Process Manager V8.5.x to IBM Business Process Manager V8.5.5

To upgrade IBM Business Process Manager V8.5.x to V8.5.5, follow the instructions for your specific configuration to install the V8.5.5 refresh pack.

Restriction: IBM Business Process Manager V8.5.5 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.5 or contact IBM Support for help to migrate to IBM Business Process Manager V8.5.5 on a 64-bit operating system

The Process Center and Process Server versions do not need to match, and Process Server V8.5.5 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.5 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.

Note: For information on updating IBM Process Designer, see Updating IBM Process Designer.

Important: When you upgrade, the Process Portal application is replaced in your profiles. If you previously added any customizations 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 new version of the Process Portal application.
   
   
2. Create a snapshot.
   
   
3. Activate the snapshot on Process Center.
   
   
4. Install the snapshot on Process Server.

Back to top

Upgrading IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.x to V8.5.5

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

Procedure

1. Back up your IBM Business Process Manager profiles. V8.5 Refresh Pack 5 updates the core product files and all the existing profiles that require a maintenance update. Before you upgrade your existing installation, 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.
   Important: Each time you run the restoreConfig command to restore your profile and you want to redo the upgrade, you must clean the profile upgrade footprint. If you do not do this, the profile might not be upgraded and the IBM BPM system toolkits might not be updated. To clean the profile upgrade footprint, delete these files:
   BootstrapProcessServerData8550_EXECUTED and BPMConfigUpgrade8550_EXECUTED in the profile_root/workspace directory
   cacheActionRegistry.xml in the profile_root/properties/service/productDir/BPM directory
   
   
2. Back up your Process Server database.
   
   
3. For Advanced 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 Business Process Manager 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.
   
   
4. 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.
   
   
5. Stop all Java™ processes that are associated with the Java SDK that is installed with IBM Business Process Manager. These processes include the stand-alone server process, and all server processes that belong to serviceable products, such as the IBM HTTP Server.
   Important: The product might not continue to run successfully if you install the refresh pack when a Java process related to WebSphere Application Server is running.
   
   
6. (For Windows servers only) Stop the WebSphere Windows services.
   
   
7. Install the V8.5.5 refresh pack onto the deployment manager installation. Follow the Installation instructions for IBM Business Process Manager Version 8.5 Refresh Pack 5 and make sure to install APAR JR51260, APAR JR51113, and APAR JR51616 after the fix pack installation.
   
   
8. Install the V8.5.5 refresh pack onto all managed node installations. Follow the Installation instructions for IBM Business Process Manager Version 8.5 Refresh Pack 5.
   
   
9. Optional: If you created the IBM Business Process Manager 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.5.
   On Microsoft Windows operating systems: install_root\bin\BPMConfig.bat -upgrade -profile deployment_manager_profile_name
   On UNIX-based and Linux operating systems: install_root/bin/BPMConfig.sh -upgrade -profile deployment_manager_profile_name
   Important: Upgrading the profile using BPMConfig can be a time-consuming task. Be patient and wait for the process to complete, even if it takes several minutes and you do not see any visible progress.
   
   
2. Export the configuration properties file.
   On Microsoft Windows operating systems: install_root\bin\BPMConfig.bat -export -profile deployment_manager_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   On UNIX-based and Linux operating systems: 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.
   
   
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 Business Process Manager 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 Business Process Manager V8.5.x environment or that you generated in step 9.
    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. 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 10.
   On Microsoft Windows operating systems: install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -propertiesFile migration_properties_file
   On UNIX-based and Linux operating systems: 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.
   
   
12. Run one of the following commands to upgrade your database, where migration_properties_file is the migration properties file that you created in step 10.
    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 Microsoft Windows operating systems: install_root\bin\DBUpgrade.bat -propertiesFile migration_properties_file
    On UNIX-based and Linux operating systems: install_root/bin/DBUpgrade.sh -propertiesFile migration_properties_file
    If the DBUpgrade command fails, see JR51260: DBUpgrade fails with CWMCB0258E, CWMCB0260E, or CWMCB0345E errors when you upgrade IBM BPM v8.5.0.x to IBM BPM V8.5.5.0.
    
    
13. For Advanced only: If you backed up your default XSL transformation files in step 3, replace the XSL transformation files with the backup versions.
    
    
14. Restart the deployment manager server. It takes a few minutes to complete the profile upgrade and run the bootstrapProcessServerData command.
    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 Business Process Manager V8.5.x to the V8.5.5 refresh pack.
    
    
15. Check for errors, as described in Identifying and recovering from profile update or bootstrapProcessServerData errors, before you continue.
    
    
16. 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 Business Process Manager. For more information, see the Plug-ins configuration documentation.
    
    
17. For each managed node in the network deployment environment, complete the following steps:
1. Restart the node agent. It takes a few minutes to complete the profile upgrade. Allow for node synchronization to complete. Note: The managed profile is updated automatically during the first server startup after the refresh pack installation.
   
   
2. Check for errors, as described in Identifying and recovering from profile update or bootstrapProcessServerData errors, before you continue.
   
   
3. Restart the cluster member servers.

Back to top

Upgrading IBM Business Process Manager Express V8.5.x to V8.5.5

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

Procedure

1. Back up your IBM Business Process Manager profiles. The V8.5.5 refresh pack updates the core product files and all the existing profiles that require a maintenance update. Before you upgrade your existing installation, 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.
   Important: Each time you run the restoreConfig command to restore your profile and you want to redo the upgrade, you must clean the profile upgrade footprint. If you do not do this, the profile might not be upgraded and the IBM BPM system toolkits might not be updated. To clean the profile upgrade footprint, delete these files:
   BootstrapProcessServerData8550_EXECUTED and BPMConfigUpgrade8550_EXECUTED in the profile_root/workspace directory
   cacheActionRegistry.xml in the profile_root/properties/service/productDir/BPM directory
   
   
2. Back up your Process Server database.
   
   
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. Stop all Java processes that are associated with the Java SDK that is installed with IBM Business Process Manager. These processes include the node agent process, the deployment manager process, and all server processes that belong to serviceable products, such as the IBM HTTP Server.
   Important: The product might not continue to run successfully if you install the refresh pack when a Java process related to WebSphere Application Server is running.
   
   
5. (For Windows servers only) Stop the WebSphere Windows services.
   
   
6. Install the V8.5.5 refresh pack onto the stand-alone installation. Follow the Installation instructions for IBM Business Process Manager Version 8.5 Refresh Pack 5 and make sure to install APAR JR51260, APAR JR51113, and APAR JR51616 after the fix pack installation.
   
   
7. Optional: If you created the IBM Business Process Manager 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.5.
   On Microsoft Windows operating systems: install_root\bin\BPMConfig.bat -upgrade -profile stand-alone_profile_name
   On UNIX-based and Linux operating systems: install_root/bin/BPMConfig.sh -upgrade -profile stand-alone_profile_name
   Important: Upgrading the profile using BPMConfig can be a time-consuming task. Be patient and wait for the process to complete, even if it takes several minutes and you do not see any visible progress.
   
   
2. Export the configuration properties file.
   On Microsoft Windows operating systems: install_root\bin\BPMConfig.bat -export -profile stand-alone_profile_name -de deployment_environment_name -outputDir path_to_configuration_files
   On UNIX-based and Linux operating systems: 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.
   
   
8. 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 Business Process Manager 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 Business Process Manager V8.5.x environment or that you generated in step 7.
   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.
   
   
9. Run one of the following commands to upgrade your database, where migration_properties_file is the migration properties file that you created in step 8.
   On Microsoft Windows operating systems: install_root\bin\DBUpgrade.bat -propertiesFile migration_properties_file
   On UNIX-based and Linux operating systems: install_root/bin/DBUpgrade.sh -propertiesFile migration_properties_file
   If the DBUpgrade command fails, see JR51260: DBUpgrade fails with CWMCB0258E, CWMCB0260E, or CWMCB0345E errors when you upgrade IBM BPM v8.5.0.x to IBM BPM V8.5.5.0.
   
   
10. For each stand-alone profile in the IBM Business Process Manager Express installation, complete the following steps:
1. Restart the stand-alone application server. It takes a few minutes to complete the profile upgrade.
   
   
2. Check for errors, as described in Identifying and recovering from profile update or bootstrapProcessServerData 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 Business Process Manager V8.5.x to the V8.5.5 refresh pack.
   
   
11. 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 Business Process Manager. For more information, see the Plug-ins configuration documentation.

Back to top

Identifying and recovering from profile update or bootstrapProcessServerData errors

After you install the V8.5 Refresh Pack 5 and start the server, it is advisable to check the log files even if an error is not reported.

When you start the server for the first time after you install the refresh 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: 

This error message indicates that a profile update or bootstrapProcessServerData error occurred. The log files for profile upgrade and bootstrapProcessServerData actions are saved in the profile_root/logs directory, where profile_root is the home directory of the profile.

Note: For custom nodes, the bootstrapProcessServerData command is not run during node startup.
Check the following log files:
Profile update log: profile_root/logs/BPMConfig_timestamp.log. Check for an error message similar to the following message: The 'BPMConfig.sh -upgrade -profile <profile>' command failed.
bootstrapProcessServerData command log: profile_root/logs/bootstrapProcessServerData.deployment_target.time_stamp.log. Check for any errors or exceptions. You can check the wsadmin.traceout file in the same directory for further details.
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 UNIX-based and Linux operating systems, but bootstrapProcessServerData.bat should be updated for Microsoft Windows operating systems.

Back to top

Rolling back the IBM Business Process Manager V8.5 Refresh Pack 5

You can use the IBM Installation Manager to roll back the V8.5 Refresh Pack 5.

If you roll back the refresh pack, the IBM Installation Manager does not roll back the refresh pack updates from profiles because you might have configured the profile after you installed the refresh pack.

Important: Profiles might not be usable after you roll back the refresh pack.

To restore an original profile, use the restoreConfig command to restore your backup.

Procedure

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

1. Roll back the refresh pack using the Installation Manager.
   
   
2. Export any custom enterprise applications that you installed since you ran the backupConfig command.
   
   
3. Shut down the server.
   
   
4. Restore the backup of your Process Server database.
   
   
5. Run the restoreConfig command.
   
   
6. Reinstall the exported enterprise applications, 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 on 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.