Upgrading profiles from IBM Business Process Manager Version 8.5.x to IBM Business Process Manager V8.5.7 Cumulative Fix 2016.12

Table of Contents

• Upgrading IBM Business Process Manager V8.5.x profiles to IBM Business Process Manager cumulative fix 2016.12 profiles
• 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
• Identifying and recovering from profile upgrade or toolkit upgrade errors
• Rolling back the IBM BPM environment
• Additional information
• Trademarks and service marks

Upgrading IBM Business Process Manager V8.5.x profiles to IBM Business Process Manager CF 2016.12 profiles

To upgrade IBM Business Process Manager V8.5.x profiles to V8.5.7 CF2016.12 profiles, follow the instructions for your specific edition (IBM Business Process Manager Advanced, IBM Business Process Manager Standard, or IBM Business Process Manager Express).

If you are upgrading from V8.5.5.0 or later, before you upgrade your production environment to V8.5.7 CF2016.12, you can clone your 8.5.x environment, including both the deployment environment and database, and test the upgrade. See Testing the upgrade from IBM Business Process Manager V8.5.5 or V8.5.6 to V8.5.7.

Restriction: Beginning with V8.5.5, IBM Business Process Manager does not support the z/OS operating system and does not support 32-bit operating systems. If you are upgrading from V8.5.0 on a 32-bit system or z/OS, you must use artifact migration as described in Migrating artifacts to IBM Business Process Manager V8.5.7.

The Process Center and Process Server versions do not need to match, and Process Server V8.5.7 CF2016.12 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.7 CF2016.12 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. Make sure that your IBM Integration Designer is at V8.5.7. Even though you might be able to connect IBM Integration Designer V8.5.7 to a Process Center at the previous release level, you should not publish any process applications that have gone through artifact migration.

The Java Database Connectivity (JDBC) drivers for your database should be installed in a custom location. Otherwise, upgrading IBM BPM can also update the default JDBC drivers for the product and might cause problems. Make sure that IBM BPM points to a custom location containing the JDBC drivers provided by your database vendor for your particular database version. For instructions, see Updating JDBC drivers.

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

To upgrade from IBM Business Process Manager Advanced or IBM Business Process Manager Standard V8.5.x to V8.5.7 CF2016.12, follow the instructions to back up your existing installation, install the cumulative fix (and the 8.5.7 refresh pack if you are updating from an earlier version) 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.7. See IBM Business Process Manager Advanced system requirements or IBM Business Process Manager Standard system requirements.
   Important: The minimum DB2 level was increased to 9.7.0.5 in IBM BPM V8.5.6.0. 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 Quick Start console.
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. The cumulative fix and the refresh pack update the core product files and all the existing 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.
   Important: If you need to restore a previous profile backup after running the steps to upgrade your profile, you must complete all the steps in Rolling back the IBM BPM environment. Otherwise, you will not be able to rerun the upgrade properly.
   Tip: You might also want to back up all the files that are mentioned in Backing up IBM Installation Manager agent data and shared files for recovery with IBM Business Process Manager (BPM), and your IBM BPM installation and profile directories. If you are applying patches to other products installed with Installation Manager, be sure to take backups of those as well. This data is not required for a normal rollback. However, if you have an Installation Manager failure or a problem that corrupts the file system data, you will need these files to recover from it. Having either a full file system backup or all of these directories ensures that you can roll back to a consistent state for all products that were installed with Installation Manager.
   
   
4. Back up all databases associated with this IBM BPM environment.
   Important: Make a backup of your databases at the same time as you make the profile backup.
   
   
5. During the upgrade, Process Portal content and snapshots can be updated. For information about the improved Process Portal application that is introduced in IBM BPM 8.5.7, see Process Portal: What's New in IBM Business Process Manager V8.5.7. The Process Portal application for IBM BPM 8.5.6 and earlier is now referred to as Heritage Process Portal.
   Note: If you need to use the Heritage Process Portal while training users for the new Process Portal, use the /HeritagePortal context root instead of the /ProcessPortal context root.
   
   
1. Customization that you applied to the Process Portal deployed as a snapshot must be redone on the latest version after you update your environments. For example, Setting up collaboration features for business users for Heritage Process Portal.
   
   
2. Customization to the Process Portal or Heritage Process Portal mentioned in Customizing and rebranding interfaces can be overwritten. Make a local copy of your changes before you upgrade or keep a record of your modifications. After the upgrade, perform any needed customization using the updated application content. If you used the BPMUpdateTheme task to apply a custom theme, you will have to run the BPMUpdateTheme task again to re-apply the custom theme after the cumulative fix is applied.
   
   
6. Install the cumulative fix (and the 8.5.7 refresh pack, if required) onto the deployment manager installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
7. Install the cumulative fix (and the 8.5.7 refresh pack, if required) onto all managed node installations interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
8. If you have a DB2 for z/OS database, complete the following steps:
1. To ensure that you can successfully run the SQL scripts for the DB2® for z/OS® schema upgrade, alter the following table spaces to increase the buffer pool size to 8K:
   WLPT33
   WLPT34
   WLPT52
   WLPT53
   WLPT145
   To do so, drop the table spaces and create them again with 8k buffer pools.
   Note: You should move the data to a temporary table space before dropping it. Then, copy it back when you re-create the table space.
   
   Example SQL to re-create table spaces:
   SET CURRENT SQLID = 'ZASIPS';
   
   DROP TABLESPACE ZACELLDB.WLPT33;
   DROP TABLESPACE ZACELLDB.WLPT52;
   
   CREATE TABLESPACE WLPT33
   IN ZACELLDB
   USING STOGROUP ZADBSTO
   SEGSIZE 32
   LOCKMAX SYSTEM
   LOCKSIZE ROW
   DEFINE YES
   CCSID UNICODE
   BUFFERPOOL BP8K1;
   
   CREATE TABLESPACE WLPT52
   IN ZACELLDB
   USING STOGROUP ZADBSTO
   SEGSIZE 32
   LOCKMAX SYSTEM
   LOCKSIZE ROW
   DEFINE YES
   CCSID UNICODE
   BUFFERPOOL BP8K1;
   
   
2. Run one of the following commands to generate the SQL file to update your database.
   On Windows: install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -profileName deployment_manager_profile [-de deployment_environment_name]
   On Linux or UNIX: install_root/bin/BPMGenerateUpgradeSchemaScripts.sh -profileName deployment_manager_profile [-de deployment_environment_name]
   You can omit the -de parameter if there is only one deployment environment.
   
   Tip: You are prompted to enter new values for the database specifications. If you press Enter, the default values are used.
   
   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
   
   
3. Connect to the DB2 for z/OS database, and run these SQL scripts against the database using your preferred tool in this order:
   Note: If you used the saved search acceleration tools to optimize a process search, you must change createProcedure_ProcessServer.sql to drop the LSW_BPD_INSTANCE_DELETE_PIVOT procedure by commenting in the corresponding SQL statement.
   
   1. upgradeSchema85x_ProcessServer.sql
   2. createProcedure_ProcessServer.sql
   
   You can safely ignore SQL exceptions about deleting rows from an empty table. You can also ignore errors about creating duplicate indexes.
   
   
4. Open the install_root/util/dbUpgrade/upgrade.properties file and set the value of the database.is.db2zos property to true.
   
   
9. Optional: Run the DBUpgrade -validate command to make sure that your configured database user has sufficient permissions to upgrade the database.
• On Windows: install_root\bin\DBUpgrade.bat -validate -profileName deployment_manager_profile [-de deployment_environment_name] -bpmSchemaAdminUser bpmSchemaAdminUser -bpmSchemaAdminPassword bpmSchemaAdminPassword
• On Linux or UNIX: install_root/bin/DBUpgrade.sh -validate -profileName deployment_manager_profile  [-de deployment_environment_name] -bpmSchemaAdminUser bpmSchemaAdminUser -bpmSchemaAdminPassword bpmSchemaAdminPassword
  
  where bpmSchemaAdminUser is a database user with permission to read the database catalog tables. See DBUpgrade command-line utility.
  
  
10. Run one of the following commands to upgrade your database.
    Notes: If you have multiple deployment environments, complete this step for each deployment environment. You must complete this step for each Advanced, Standard, and Express deployment environment. Skip this step for AdvancedOnly deployment environments. There is no database schema update for AdvancedOnly deployment environments upgraded from V8.5.x.
• On Windows: install_root\bin\DBUpgrade.bat  -profileName deployment_manager_profile [-de deployment_environment_name]
• On Linux or UNIX: install_root/bin/DBUpgrade.sh  -profileName deployment_manager_profile [-de deployment_environment_name]
  
  You can omit the -de parameter if there is only one deployment environment.
  
  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.7 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.
  
  Note: The DBUpgrade command has two parameters that you can use to avoid trouble. You can run DBUpgrade -generateSQLOnly to generate the SQL files without running them. You can then edit the generated SQL files manually and run the DBUpgrade command again with the -omitSQLGeneration parameter to upgrade the database using the modified files.
  
  
11. Start the deployment manager server. It takes time to complete the profile upgrade and run the BPMUpdateSystemApp and bootstrapProcessServerData commands 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 fix is installed.
• The Business Process Choreographer, Business Space, CommonDB, and Messaging Engine databases are not changed when you upgrade to V8.5.7 CF2016.12.
  
  
12. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit upgrade errors, before you continue.
    
    
13. 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.
    
    
14. Optional: When you upgrade from IBM BPM V8.5.0 or IBM BPM V8.5.5, 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.
    Tip: In the administrative console, go to Security > SSL certificate and key management > Key stores and certificates. In Keystore usages, select All.
    
    
15. 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 upgrade errors, before you continue.
   
   
16. 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.
    
    
17. Review the optional Post-upgrade 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.
    
    
18. 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.
    Note: The Process Portal index is rebuilt on server restart. In the SystemOut.log file, look for the CWLLG0764I and CWLLG0765I messages that identify the start and completion of the index rebuild.
    Important: While the index is being rebuilt, the search facility in Process Portal is unavailable.
    
    
19. After the IBM Process Center environment is upgraded, existing Process Designer users must follow the instructions for Updating IBM Process Designer.
    
    
20. Your IBM BPM environment is now upgraded to 8.5.7 CF2016.12. Perform any application validation testing you require at this time.

Upgrading stand-alone profiles for IBM Business Process Manager Express

To upgrade from IBM Business Process Manager Express V8.5.x to V8.5.7 CF2016.12, follow the instructions to back up your profiles and Process Server database, install the cumulative fix (and the 8.5.7 refresh pack if you are updating from an earlier version), 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 Business Process Manager V8.5.7. See IBM Business Process Manager Express system requirements.
   Important: The minimum DB2 level was increased to 9.7.0.5 in IBM BPM V8.5.6.0. 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 server.
2. Stop any other associated JVMs, such as the Profile Management Tool or the Quick Start console.
3. 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 cumulative fix and the refresh pack update the core product files and all the existing 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.
   Important: If you need to restore a previous profile backup after running the steps to upgrade your profile, you must complete all the steps in Rolling back the IBM BPM environment. Otherwise, you will not be able to rerun the upgrade properly.
   Tip: You might also want to back up all the files that are mentioned in Backing up IBM Installation Manager agent data and shared files for recovery with IBM Business Process Manager (BPM), and your IBM BPM installation and profile directories. If you are applying patches to other products installed with Installation Manager, be sure to take backups of those as well. This data is not required for a normal rollback. However, if you have an Installation Manager failure or a problem that corrupts the file system data, you will need these files to recover from it. Having either a full file system backup or all of these directories ensures that you can roll back to a consistent state for all products that were installed with Installation Manager.
   
   
4. Back up all databases associated with this IBM BPM environment.
   Important: Make a backup of your databases at the same time as you make the profile backup.
   
   
5. During the upgrade, Process Portal content and snapshots can be updated. For information about the improved Process Portal application that is introduced in IBM BPM 8.5.7, see Process Portal: What's New in IBM Business Process Manager V8.5.7. The Process Portal application for IBM BPM 8.5.6 and earlier is now referred to as Heritage Process Portal.
   Note: If you need to use the Heritage Process Portal while training users for the new Process Portal, use the /HeritagePortal context root instead of the /ProcessPortal context root.
   
   
1. Customization that you applied to the Process Portal deployed as a snapshot must be redone on the latest version after you update your environments. For example, Setting up collaboration features for business users for Heritage Process Portal.
   
   
2. Customization to the Process Portal or Heritage Process Portal mentioned in Customizing and rebranding interfaces can be overwritten. Make a local copy of your changes before you upgrade or keep a record of your modifications. After the upgrade, perform any needed customization using the updated application content. If you used the BPMUpdateTheme task to apply a custom theme, you will have to run the BPMUpdateTheme task again to re-apply the custom theme after the cumulative fix is applied.
   
   
6. Install the cumulative fix (and the refresh pack, if required) onto the stand-alone installation interactively or silently:
• Upgrading an installation interactively
• Upgrading an installation silently by using the command line (imcl)
  
  
7. Optional: Run the DBUpgrade -validate command to make sure that your configured database user has sufficient permissions to upgrade the database.
• On Windows: install_root\bin\DBUpgrade.bat -validate -profileName stand-alone_profile -bpmSchemaAdminUser bpmSchemaAdminUser -bpmSchemaAdminPassword bpmSchemaAdminPassword
• On Linux or UNIX: install_root/bin/DBUpgrade.sh -validate -profileName stand-alone_profile -bpmSchemaAdminUser bpmSchemaAdminUser -bpmSchemaAdminPassword bpmSchemaAdminPassword
  
  where bpmSchemaAdminUser is a database user with permission to read the database catalog tables. See DBUpgrade command-line utility.
  
  
8. Run one of the following commands to upgrade your database.
• On Windows: install_root\bin\DBUpgrade.bat
  -profileName stand-alone_profile
• On Linux or UNIX: install_root/bin/DBUpgrade.sh  -profileName stand-alone_profile
  
  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.7 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.
  
  Note: The DBUpgrade command has two parameters that you can use to avoid trouble. You can run DBUpgrade -generateSQLOnly to generate the SQL files without running them. You can then edit the generated SQL files manually and run the DBUpgrade command again with the -omitSQLGeneration parameter to upgrade the database using the modified files.
  
  
9. For each stand-alone profile in the IBM BPM Express installation, start the stand-alone application server. It takes time to complete the profile upgrade and run the BPMUpdateSystemApp and bootstrapProcessServerData commands 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 stand-alone profile is updated automatically during the first server startup after the fix is installed.
• The Business Space and Messaging Engine databases are not changed when you upgrade to V8.5.7 CF2016.12.
• The Process Portal index is rebuilt on server restart. In the SystemOut.log file, look for the CWLLG0764I and CWLLG0765I messages that identify the start and completion of the index rebuild.
  Important: While the index is being rebuilt, the search facility in Process Portal is unavailable.
  
  
10. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit upgrade errors, before you continue.
    
    
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 BPM. For more information, see the Plug-ins configuration documentation.
    
    
12. Optional: When you upgrade from IBM BPM V8.5.0 or IBM BPM V8.5.5, 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.
    Tip: In the administrative console, go to Security > SSL certificate and key management > Key stores and certificates. In Keystore usages, select All.
    
    
13. Review the optional Post-upgrade tasks for additional actions you might need to take. Make the changes and restart the stand-alone server to pick up these changes.
    
    
14. After the IBM Process Center environment is upgraded, existing Process Designer users must follow the instructions for Updating IBM Process Designer.
    
    
15. Your IBM BPM environment is now upgraded to V8.5.7 CF2016.12. Perform any application validation testing you require at this time.

Identifying and recovering from profile upgrade or toolkit upgrade errors

Use the following information to check for the success of the upgrade commands. In IBM BPM Advanced or IBM BPM Standard, these commands are run during deployment manager startup and update all deployment environments at once. In IBM BPM Express, these commands are run during stand-alone server startup.
In the log locations, 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).

• Profile upgrade
  Log location: profile_root/logs/BPMConfig_timestamp.log
  Success message:  'The BPMConfig.bat -upgrade -profile <profilePath>' command completed successfully.
• bootstrapProcessServerData command
  Log location: profile_root/logs/bootstrapProcessServerData.log
  Success message: The bootstrapping of data completed successfully
• BPMUpdateSystemApp command
  Log location: profile_root/logs/BPMUpdateSystemApp_timestamp.log
  Success message: execute Cumulative BPMUpdateSystemApp completed successfully.

If not all of these log files exist, check the log files under profile_root/properties/service/productDir for error messages.

Recovering from startup errors

When you start the server for the first time after you install the cumulative 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 upgrade error occurred. Take these actions:

1. Check the profile upgrade log and confirm that the commands completed successfully.
   If the commands did not run successfully, note the errors and review them to see if they explain the failure.
2. Check the bootstrapProcessServerData command log and confirm that the command completed successfully.
   Note: For managed nodes, the bootstrapProcessServerData command is not run during node startup.
   If the command did not run successfully, note the errors and review them to see if they explain the failure.
3. Check the BPMUpdateSystemApp command log and confirm that the command completed successfully.
   Note: For managed nodes, the BPMUpdateSystemApp command is not run during node startup.
   If the command did not run successfully, note the errors and review them to see if they explain the failure.
4. Search the IBM BPM support site for possible reasons for the failure. Engage IBM support if you cannot find a solution.
5. Once the issue is resolved, restart the failing server to trigger another attempt of the upgrade step.

Known issues:

• 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.
  
• 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 bootstrapProcessServerData command again. Note that bootstrapProcessServerData.sh should be updated for UNIX or Linux, but bootstrapProcessServerData.bat should be updated for Windows.
  
• When you run the BPMConfig.sh -upgrade -profile command while upgrading to IBM® Business Process Manager V8.5.7, you might see a UTLS0005W message. The warning message is similar to the following text:
  [com.ibm.ws.runtime.InstalledOptionalPackageRepository/WARNING]: UTLS0005W: The MANIFEST attributes for an Installed Optional Package in shared library IBM_BPM_Process_Server_Shared_Library conflict with and will override those within the MANIFEST attributes of shared library IBM_BPM_Process_Server_Shared_Library.
  This warning can safely be ignored.

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 and might need to be redone.

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

Important: Unless you restore the profiles and databases from backup, profiles might not be usable after you roll back the cumulative fix.

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. Also, ensure that you have .zip files for offline deployment and the .twx files for online deployment for all process applications and toolkits that you deployed since you backed up the Process Server database.
   
   
2. Stop all the Java processes associated with the IBM BPM products being rolled back.
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 Quick Start console.
4. 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 cumulative fix using the Installation Manager. See Rolling back the cumulative fix for instructions.
   
   
4. Restore the backup of all your IBM BPM environment databases.
   
   
5. Run the restoreConfig command for each profile.
   
   
6. Run one of the following commands to clear the OSGi configuration area:
   On Windows: install_root\bin\osgiCfgInit.bat -all
   On Linux or UNIX: install_root/bin/osgiCfgInit.sh -all
   
   Otherwise, the OSGi cache might still refer to IBM BPM classes from the version that was installed before the rollback, which can cause problems in the rolled back (old) environment. 
   
   
7. If you rolled back to a version earlier than V8.5.6 (V8.5.0.x or V8.5.5), then, before you can start the deployment environment, you must define a JVM argument for the WebSphere server JVMs that run Business Space.
   
   
• If you are running IBM BPM Advanced or IBM BPM Standard, in the administrative console, go to Servers > Server Types > WebSphere application servers. For each IBM BPM application cluster member, 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,
   
   
• If you are running IBM BPM Express, perform the following steps:
1. Go to the stand-alone profile root. Run:
   wsadmin -lang jython -connType none
2. In the wsadmin command window, run the following command to select the server that you need to update:
   wsadmin>AdminTask.listServers('[-serverType APPLICATION_SERVER ]')
3. Substituting the correct node name and server name, run the following command to show the current JVM properties for the server that you need to update:
   wsadmin>AdminTask.showJVMProperties('[-nodeName Node1 -serverName server1]')
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 run a command like the following, substituting the correct node name and server name:
   wsadmin>AdminTask.setJVMProperties('[-nodeName Node1 -serverName server1 -verboseModeClass false -verboseModeGarbageCollection true -verboseModeJNI false -initialHeapSize 768 -maximumHeapSize 2048 -runHProf false -hprofArguments  -debugMode false -debugArgs "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=7779" -executableJarFileName  -genericJvmArguments "${IBMSCMX} ${IBMGCPOLICY_GENCON} ${IBMJITPMC} -Xss2048k -Dsun.net.http.allowRestrictedHeaders=true  -Xdisableexplicitgc -Declipse.bundle.setTCCL=false" -disableJIT false]')
5. Save your changes.
   wsadmin>AdminConfig.save()
   
   
8. Start your IBM BPM environment. For IBM BPM Express, start the IBM BPM application server.
   For IBM BPM Advanced or IBM BPM Standard:
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.
   
   The environment is now rolled back to its previous state.
   
   
9. Reinstall needed applications or snapshots, and redo any other applicable configuration changes that you made since you ran the backupConfig command.

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.