IBM Support

Upgrading profiles from IBM Business Process Manager V8.5.x to IBM Business Automation Workflow V19.0.0.3

Product Readmes


Abstract

This document provides the instructions for upgrading existing profiles for the IBM Business Process Manager (BPM) Advanced and Standard products Version 8.5.0.x, 8.5.5, 8.5.6.x, 8.5.7.0, 8.5.7 Cumulative Fix 2016.06, 8.5.7 Cumulative Fix 2016.09, 8.5.7 Cumulative Fix 2016.12, 8.5.7 Cumulative Fix 2017.03, or 8.5.7 Cumulative Fix 2017.06 to IBM Business Automation Workflow Version 19.0.0.3.

Content

The following tabs primarily provide information about IBM Business Automation Workflow V19.0.0.3. However, the Upgrading IBM Case Manager tab provides information about upgrading IBM Case Manager V5.3.3 to IBM Business Automation Workflow V19.0.0.3.


Table of Contents

Upgrading IBM Business Process Manager V8.5.x profiles to IBM Business Automation Workflow V19.0.0.3

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

IBM Business Process Manager Express cannot be upgraded to IBM Business Automation Workflow V19.0.0.3. Use migration instead. See Migrating and upgrading in the documentation.

If you installed IBM Business Process Manager Version V8.5.x or earlier using administrator privileges, you need administrator access to complete upgrading.

If you are upgrading from IBM BPM V8.5.5.0 or later, before you upgrade your production environment to Business Automation Workflow V19.0.0.3, you can clone your V8.5.x environment, including both the deployment environment and database, and test the upgrade. See Testing the IBM Business Automation Workflow upgrade.

If you are using an unsupported operating system or database version, you must upgrade to a supported version before starting the upgrade. See IBM Business Automation Workflow detailed system requirements. If you are using an unsupported operating system type like Solaris, you must either switch to a supported operating system type before you upgrade or use artifact migration as described in Migrating artifacts to IBM Business Automation Workflow instead of upgrading. For V8.5.5.0 and later, you can use hardware migration to switch the operating system type of your source version before upgrading. See Migrating Business Automation Workflow to the same version on new hardware.
Important: If you already have a version of Db2 installed and you create the deployment environment without deferring schema creation, you must have Db2 AWSE 10.5.0.0 or above. Otherwise, the database version validation will fail with an error; for example CWMCB0316E: Your database system is not the required version. The minimum supported version is 10.5.0.0 but the current version is 10.1.0.2.
Restriction: Beginning with V8.5.5, IBM BPM 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 Automation Workflow for instructions.

New databases are required for the Content Platform Engine (CPE) and IBM Content Navigator components that are used by the new case management features. The AdvancedOnly deployment environments don't require these databases, but all other deployment environment types do. These new databases are created when you perform steps 14 - 16 below. The three required schemas can share one database or use three separate databases.

IBM Workflow Center and Workflow Server versions do not need to match, and Workflow Server V19.0.0.3 can connect offline to an earlier version of IBM 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.
Important: Because of APAR JR59022, Workflow Server V19.0.0.3 cannot be connected online to Process Center V8.5.x. You can use offline deployment while performing your rolling upgrade.

Note: Due to APAR JR61813, a pre-V19.0.0.1 Workflow Center will show an error when attempts are made to retrieve installation messages during online deployment to a V19.0.0.1 or later Workflow Server. You can ignore the error and check the Workflow Server logs to determine the deployment status. This issue can be resolved by upgrading the Workflow Center.

To interact with Workflow Center V19.0.0.3, Process Designer must be at V8.5.7 CF2019.12 and IBM Integration Designer must be at V8.5.7 or later.

To prevent performance problems, use the System Maintenance Status feature in the Process Admin Console to actively monitor that the data generated for key process-related artifacts is below system thresholds. When upgrading an already well-tuned environment, make sure to adapt the default maintenance settings to match your system requirements. For more information, see Configuring notifications and actions for system maintenance .
Note: If the number of named snapshots exceeds the critical threshold, the system disables snapshot installation by default. To address this issue, you must delete unused named snapshots, or increase the critical threshold.
- To delete named snapshots, run the BPMDeleteSnapshot command .
- To increase the critical threshold, change the default maintenance setting.

For Oracle and SQL Server databases, the Java Database Connectivity (JDBC) drivers are removed from their original location during the upgrade. The JDBC drivers for your database must be installed in a custom location. Make sure that Business Automation Workflow points to a custom location containing the JDBC drivers provided by your database vendor for your particular database version. For instructions, see Configuring JDBC drivers. If your Oracle database is configured with SSL in Business Automation Workflow or Business Process Manager, you must disable SSL before starting the upgrade. See Enabling and Disabling Oracle SSL.

Procedure

  1. Verify that your target environment - including hardware, operating systems, and database prerequisites - is a supported operating environment for IBM Business Automation Workflow V19.0.0.3. Ensure that you have at least 18 GB of disk space, including temporary disk space, before upgrading. For more information, see IBM Business Automation Workflow detailed system requirements.
  2. Important: The minimum Db2 level was increased to 10.5 in IBM BPM V8.6 CF2018.03. 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.
  3. 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.
      Note: You should ensure that a graceful shutdown is performed to ensure that there are no in-doubt transactions. Otherwise, you could have problems with database locks when upgrading the database.
    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.
  4. Back up your IBM BPM profiles. The cumulative fix updates 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. 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 Business Automation Workflow environment. Otherwise, you will not be able to rerun the upgrade properly.
    • If you are running zLinux, 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 also back up 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. If you need to roll back and cannot roll back WebSphere Application Server to the previous version, you can restore from the backup.
    • If you think you might need to roll back, it is a good idea 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 also back up 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.
  5. Back up all databases associated with your existing IBM BPM environment.
    Important: Make a backup of your databases at the same time as you make the profile backup. The schema and table data will change during the upgrade. Make sure you gather the database data to restore if something goes wrong.
  6. For IBM BPM Advanced only: If you customized event sequencing, back up the install_root/properties/eventsequencing.properties file.
  7. During the upgrade, Process Portal content and snapshots can be updated. For information about the improved Process Portal application that was introduced in IBM BPM V8.5.7, see Process Portal: What's New in IBM Business Process Manager V8.5.7. The Process Portal application for IBM BPM V8.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 you finish the upgrade.
  8. Install the cumulative fix onto the deployment manager installation interactively or silently:
  9. Install the cumulative fix onto all managed node installations interactively or silently:
  10. If Java 7 is installed in your source environment, you must run the following additional two commands (where sdk_name is either 1.8_64 or 1.8_64_bundled):
    • On Windows:
      install_root\bin\managesdk.bat -setCommandDefault -sdkname sdk_name
      install_root\bin\managesdk.bat -setNewProfileDefault -sdkname sdk_name
    • On Linux or UNIX:
      install_root/bin/managesdk.sh -setCommandDefault -sdkname sdk_name
      install_root/bin/managesdk.sh -setNewProfileDefault -sdkname sdk_name

    To determine the Java 8 SDK name for your environment, you can run the following command:
    install_root/bin/managesdk.sh -listAvailable
  11. If you have a Db2 for z/OS database, complete the following steps:
    Note: You can skip this step if you have an AdvancedOnly deployment environment.
    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

      The version number (such as 85x in the example) refers to the source version, the version that you are upgrading from.
      Note: In the createProcedure_ProcessServer.sql file, the at sign (@) is used as a statement termination character. When you use the DB2 command line processor to run the SQL commands in this file, use the -td parameter to define @ as the statement termination character.
      You can safely ignore SQL exceptions about deleting rows from an empty table. You can also ignore errors about creating duplicate indexes.
  12. If Java 7 is installed in your source environment, run the following command to switch your default profile to Java 8 before you run DBUpgrade: (If your default profile is a managed node profile, you must first make the deployment manager the default profile by running manageprofiles -setDefaultName -profileName dmgr_profile_name)

    managesdk.bat/sh -enableProfile -profileName profile_name -sdkName sdk_name -enableServers

    See the managesdk command for instructions.
  13. The Oracle and SQL Server database JDBC drivers that previously came with IBM BPM have been removed. You must reconfigure your drivers if you were using these default drivers or drivers located in the ${WAS_INSTALL_ROOT}/jdbcdrivers/Oracle or ${WAS_INSTALL_ROOT}/jdbcdrivers/SQLServer directories. Follow the instructions in Configuring JDBC drivers.
    Important:
    • In a network deployment environment, complete the BPMConfig command in Step 6 for the deployment manager node and all the managed nodes.
    • Do not restart the deployment environment as instructed in Step 7. Ensure the environment remains stopped through this procedure.
    • For Oracle databases, during the upgrade, ensure you have included JDBC drivers for the Java 8 version in the custom directory.
  14. If your IBM BPM environment uses a secure Db2 data source connection over SSL, you must run a command to support both secure and insecure connections before you update the database. From the Db2 database server, run this command:
    db2set -i DB2 DB2COMM=SSL,TCPIP
  15. Run the BPMConfig command to generate the data sources and database creation scripts for IBM Content Navigator and the Content Platform Engine (CPE) design object store (DOS) and target object store (TOS) components. Required: This step is required unless you are using an AdvancedOnly deployment environment or DB2 for z/OS databases.

    If you already have an external CPE configured for the BPM document store, this command will skip the creation of the CPE data sources and database scripts. As a result, you should skip step 15. If you plan to use case management, the DOS and TOS object stores must use the same external CPE as the BPM document store.

    The *.datasource.db.dir property is used in the database creation SQL files for various database objects. This directory should exist on the database server.

    Complete the following steps regardless of whether you intend to use the case management features or plan to use an external CPE and IBM Content Navigator:
    1. Create a response file based on the samples provide in Sample case configuration response files for the BPMConfig command. The table space names in the response file must be specified using all uppercase characters. Otherwise, you may encounter problems later when you update data sources or work with the Content Platform Engine (CPE).
    2. Run the following command:
      • Windows: install_root\bin\BPMConfig.bat -update -profile deployment_manager_profile -de deployment_environment_name -caseConfigure -responseFile response_file
      • Linux or UNIX: install_root/bin/BPMConfig.sh -update -profile deployment_manager_profile -de deployment_environment_name -caseConfigure -responseFile response_file

      If you make a mistake, you can rerun the command before proceeding to the next steps. The command creates the required data sources as well as generating the SQL files used in the next steps. If your database administrator requires different values for your databases, modify your response file above and run the command again to generate new database creation SQL files.

      You can also run this command interactively by omitting the -responseFile parameter (although this is not supported for Oracle databases). The table space names must be specified using all uppercase characters. Otherwise, you may encounter problems later when you update data sources or work with the Content Platform Engine (CPE).
  16. Prepare the databases for the Content Platform Engine. Required: This step is required unless you are using an AdvancedOnly deployment environment, DB2 for z/OS databases, or an external CPE that is already configured for the BPM document store.
    • For Db2:
      Create databases for the design object store (DOS) and the target object store (TOS). Find the database creation files in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/DB2/database_name
      where database_name is the DOS and TOS database names.
      Run the following files on the database computer:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createTablespace_ECM_DOS.sql
      createTablespace_ECM_TOS.sql
      (The last two SQL files are in the same folder if DOS and TOS are in the same database, and in different folders otherwise. If DOS, TOS, and ICN share the same database, you need to run the createDatabase_ECM script only once.)
    • For Oracle:
      Create two users and table spaces for the design object store (DOS) and target object store (TOS). Find the table space creation file in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/Oracle/database_name/db_user
      where db_user is the DOS and TOS database users.
      Run the following file on the database computer:
      createUserTablespace_ECM.sql
    • For SQL Server:
      Create databases for the design object store (DOS) and the target object store (TOS). Find the database creation files in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/SQLServer/database_name/schema_name
      where database_name is the DOS and TOS databases and schema_name is the DOS and TOS users.
      Run the following files on the database computer:
      createDatabase_ECM.sql
      createUser.sql
      (These files are in the same folder if DOS and TOS are in the same database, and in different folders otherwise. If DOS, TOS, and ICN share the same database, you need to run the createDatabase script only once.)
  17. Prepare the databases for IBM Content Navigator (ICN). Required: This step is required unless you are using an AdvancedOnly deployment environment or DB2 for z/OS databases.
    • For Db2:
      Find the database creation files in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/DB2/database_name
      Run the following files on the database computer:
      Note: If ICN shares a database with DOS or TOS, don't run createDatabase_ICN.sql, because the createDatabase_ECM script from the previous step creates the database.
      createDatabase_ICN.sql
      createTablespace_ICN.sql
    • For Oracle:
      Find the user and table space creation files in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/Oracle/database_name/db_user
      Run the following files on the database computer:
      createUser.sql
      createTablespace_ICN.sql
    • For SQL Server:
      Find the database creation files in dmgr_profile_root/dbscripts/cell_name.deployment_environment_name/SQLServer/database_name/scheme_name
      Run the following files on the database computer:
      Note: If ICN shares a database with DOS or TOS, don't run createDatabase_ICN.sql, because the createDatabase_ECM.sql file from the previous step creates the database.
      createDatabase_ICN.sql
      createUser.sql
  18. Optional: Run the DBUpgrade -validate command to make sure that your configured database user has sufficient permissions to upgrade the database.
    Important: Skip this step for AdvancedOnly deployment environments.
    If you are using Db2 for Z/OS or SQL Server with Windows authentication, the validation is not performed and you can skip this step.
    • 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 for both the Process Server and Performance Data Warehouse databases. See DBUpgrade command-line utility.

      You will see some debug output on the console, such as,  No method getDelegate for java.net.URLClassLoader@dddc56e7, ignoring. You can safely ignore it.
  19. Run one of the following commands to upgrade your database.
    Notes: If you have multiple deployment environments, you must complete this step for each Advanced and Standard deployment environment. Skip this step for AdvancedOnly deployment environments. There is no database schema update for AdvancedOnly deployment environments.
    If you are running Db2 and using 8.5.7 CF2017.06 and you installed the JR59587 fix,
    you must drop the LSW_TMP_IDS table (in BPMDB) before running DBUpgrade.
    • 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.

      Warning: The DBUpgrade command must be run prior to starting the deployment manager and upgrading the profiles. If the upgrade steps are performed out of order,  it can lead to a corrupted environment even though you may see success messages for the upgrade commands. If you have performed profile upgrade (by using the BPMConfig command or by starting the deployment manager) prior to running the DBUpgrade command,  you must follow the upgrade rollback steps and retry the upgrade, as described in the section Rolling back the Business Automation Workflow environment.

      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.6.0.201803 for database ProcessServerDatabase.
      Error executing SQL statement: ORA-60019: Creating initial extent of size 14 in tablespace of extent size 8

      On Oracle, Business Automation Workflow 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. The product 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 Business Automation Workflow database schema users.

      Note: The DBUpgrade command has two parameters that you can use to make table space updates or when you are working on a problem with the help of IBM Support. 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.
      Important: Removing required schema changes from the upgrade scripts can corrupt the database.
  20. For IBM BPM Advanced only: If you customized event sequencing, restore the install_root/properties/eventsequencing.properties file from the backup you made in step 5.
  21. Start the deployment manager server.
    • On Windows, go to the dmgr_profile_root\bin directory and run startManager.bat.
    • On Linux or UNIX, go to the dmgr_profile_root/bin directory and run startManager.sh.
      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. The result of each activity is logged with either INSTCONFSUCCESS or INSTCONFFAILED. If an activity failed, see Identifying and recovering from profile upgrade or toolkit upgrade errors.
      Notes:
    • The deployment manager profile is updated automatically during the first server startup after the fix is installed. The Java version for the deployment manager is switched to Java 8.
    • Warning: You should not attempt to bypass the automated upgrade tasks. If these tasks are not performed successfully, it could lead to environment corruption. The use of a runConfigActions.disableAtServerStartup file can corrupt an IBM Business Automation Workflow environment.
    • The Business Process Choreographer, Business Space, CommonDB, and Messaging Engine databases are not changed when you upgrade to V19.0.0.3.
  22. If you want to enable your IBM Business Automation Workflow environment to use a secure Db2 data source connection over SSL, follow the instructions in Enabling a NIST SP800-131a compliant environmentNote: If your previous environment was connected to the Oracle database using SSL over TCP/IP and you disabled SSL before upgrading, you can re-enable SSL as described in the document Disabling and re-enabling Oracle SSL authentication.
  23. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit upgrade errors, before you continue.
  24. Update the web server plug-in.
    Some new web modules have been added to the product applications. 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. For more information, see the Plug-ins configuration documentation.
  25. 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 (one per 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.
  26. Switch the Java edition that is used for the node and cluster members to Java 8. Repeat this step for each managed node of the deployment manager. For more information, read the WebSphere Application Server topic managesdk command.
    1. Make sure that the deployment manager is still running. Synchronize the managed node by running the syncNode command as shown in the following example:
      install_root/bin/syncNode.sh dmgrHostName.ibm.com 8879 -profileName Node1Profile -user AdminUser -password AdminPassword
      Use the deployment manager host name and SOAP port number for your environment.
      Important: It can take several minutes for syncNode to complete when updating the system applications. Do not stop this task or run a duplicate node synchronization, because it could affect the configuration data for the node. You can check syncNode.log for the progress of the related operations.
    2. Run the managesdk -listAvailable command to display a list of all SDK names in your environment, as shown in the following example:
      install_root/bin/managesdk.sh -listAvailable
      Make sure that Java 8 is installed.
    3. To switch to Java 8, run the -enableProfile command from the bin directory of the installation that hosts the managed node, as shown in the following example (where sdk_name is either 1.8_64 or 1.8_64_bundled):
      install_root/bin/managesdk.sh -enableProfile -profileName Node1Profile -sdkName sdk_name -user AdminUser -password AdminPassword -enableServers
      To determine the Java 8 SDK name for your environment, you can run the following command:
      install_root/bin/managesdk.sh -listAvailable
      The deployment manager profile will be switched automatically during the profile upgrade.
    4. Synchronize the managed node by running the syncNode command again, for example:
      install_root/bin/syncNode.sh dmgrHostName.ibm.com 8879 -profileName Node1Profile -user AdminUser -password AdminPassword
      Use the deployment manager host name and SOAP port number for your environment.
    5. Validate the changes by running the managesdk -listEnabledProfileAll command as shown in the following example:
      install_root/bin/managesdk.sh -listEnabledProfileAll
      CWSDK1004I: Profile DmgrProfile :
      CWSDK1006I: PROFILE_COMMAND_SDK = 1.8_64
      CWSDK1008I: Node MyCellManager01 SDK name: 1.8_64
      CWSDK1009I: Server dmgr SDK name: 1.8_64

      CWSDK1004I: Profile Node1Profile :
      CWSDK1006I: PROFILE_COMMAND_SDK = 1.8_64
      CWSDK1008I: Node my-Node01 SDK name: 1.8_64
      CWSDK1009I: Server BPMDE.SingleCluster.Node01.0 SDK name: 1.8_64
      CWSDK1009I: Server nodeagent SDK name: 1.8_64
      CWSDK1001I: Successfully performed the requested managesdk task.
  27. For each managed node in the network deployment environment, complete the following steps:
    1. Start the node agent.
      • On Windows, go to the node_profile_root\bin directory and run startNode.bat.
      • On Linux or UNIX, go to the node_profile_root/bin directory and run startNode.sh.
        Note: The managed node 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.
  28. Ensure that node synchronization is completed. It can take several minutes to complete when updating the system applications. Do not terminate this task abruptly or run a duplicate node synchronization, because it could affect the configuration data for the node. You can check the node agent log or syncNode.log for progress of the related operations.
    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.
  29. To prevent performance problems, customize the settings for system maintenance including options to prevent issues when importing or installing snapshots after upgrade. See Configuring notifications and actions for system maintenance.
  30. 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.
  31. 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 and stopping 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.
  32. Optional: To use case management, follow these instructions to enable it.
    Notes:
    • To use case management, you must configure IBM Business Automation Workflow with an external Content Platform Engine.
    • To use case management, you must use federated repositories.
    • You cannot configure case management for an AdvancedOnly deployment environment.
    • If you want to configure case management later or if you don't intend to use case management, skip this step.
    1. If you are using a Db2 for z/OS database, follow the instructions in the Knowledge Center topic Configuring IBM Business Automation Workflow case management for Db2 for z/OS. If you perform step 6 in the Knowledge Center topic, you can omit step 31.3 below.
    2. Choose between an embedded or external Content Platform Engine. To use the embedded one, run the createObjectStoreForContent command. If you already have an external Content Platform Engine, follow the instructions in Configuring IBM Business Automation Workflow with an existing external Content Platform Engine.
    3. Follow the instructions in Enabling the case management features.
    4. Follow the instructions in Configuring your system for case management.
  33. After Process Center is upgraded to Workflow Center, existing Process Designer users must follow the instructions for Updating desktop IBM Process Designer. For IBM Integration Designer, see Upgrading IBM Integration Designer.
  34. Your IBM BPM environment is now upgraded to IBM Business Automation Workflow V19.0.0.3. 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 command. These commands are run during deployment manager startup and update all deployment environments at once. Profile upgrade is also run during the startup of each managed node.
In the log locations, profile_root is the root directory of the server that is starting up, either the deployment manager profile or managed node profile.
  • 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 upgrade, 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 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 decrease the maximum heap size, the value reverts to the default when you upgrade. If you increase it, the value is preserved.
  • When the profile upgrade is run for a second time after a prior failure, you will see the following exception:
     
    java.lang.NullPointerException
       at com.ibm.bpm.config.capability.standard.ComponentCaseManager.getResolvedNetworkSharedDirectory(ComponentCaseManager.java:1139)
       at com.ibm.bpm.config.capability.standard.ComponentCaseManager.updateCaseManagerProperties(ComponentCaseManager.java:1046)
       at com.ibm.bpm.config.capability.standard.ComponentCaseManager.installApplications(ComponentCaseManager.java:894)
     
    This exception can occur when the profile upgrade fails while case management applications are being installed. If you encounter this error, you must rollback the upgrade and start over, as described in the section Rolling back the Business Automation Workflow environment. (Note, however,  that you should review the failure for the first profile upgrade attempt and ensure that it does not happen again.)
  • If the bootstrapProcessServerData command fails with a NoClassDefFoundError or a NoSuchMethodError , make sure there are no IBM BPM product JAR files in install_root/lib/ext other than these four files:
    bpm.security.tai.jar
    jcrypt.jar
    ssi4bpm-server.jar
    wp.auth.tai.jar
  • 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, 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.
  • If you cannot create a decision table after upgrading, see Cannot create decision table editor after upgrading to CF 2018.03.

Rolling back the Business Automation Workflow environment


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

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

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

Procedure

To roll back the upgrade 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 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. If your custom JDBC driver location is install_root/jdbcdrivers/database_product, you must remove the database_product directory before you roll back.
  4. Roll back the upgrade using the Installation Manager. See Rolling back the upgrade for instructions.
    Important: When you installed the new version of IBM WebSphere Application Server, your embedded version of IBM WebSphere SDK Java Technology Edition was switched from Java 6 to Java 8.  If your previous version of IBM BPM requires Java 6, you must roll back the IBM WebSphere Application server to the previous version.
  5. Restore the backup of all your IBM BPM environment databases.
  6. Run the restoreConfig command for each profile.
  7. 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. 

    After you roll back, if you see an error when running the servicedeploy command, you can fix it by running the following script:
    install_root/serviceDeploy/clearServiceDeployCfg
    Running this script with no parameters fixes the error.
  8. 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 upgraded from 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.
  9. Switch the Java edition that is used for existing profiles back to your previous version.
    1. Run the managesdk -listAvailable command to display a list of all SDK names in your environment.
      install_root/bin/managesdk.sh -listAvailable
    2. Switch the SDK version for the deployment manager profile or stand-alone profile by running the following command. Use the  supported SDK version, 1.6_64,  1.7_64 or 1.8_64, for your version of IBM BPM.
      install_root/bin/managesdk.sh -enableProfile -profileName DmgrProfile -sdkName 1.7_64 (or 1.6_64)  -enableServers
    3. In a network deployment environment, complete the following steps:
      1. Start the deployment manager.
      2. Synchronize the managed nodes by running the syncNode command.
      3. Run the -enableProfile command from the bin directory of the IBM BPM installation that hosts the managed node.
        managesdk.sh -enableProfile -profileName Node1Profile -sdkName 1.7_64 (or 1.6_64) user AdminUser -password AdminPassword -enableServers
      4. Synchronize the managed nodes by running the syncNode command again.
      5. Validate the changes by running the managesdk -listEnabledProfileAll command.
         
  10. Start your IBM Business Process Manager environment.
    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.
  11. Reinstall needed applications or snapshots, and redo any other applicable configuration changes that you made since you ran the backupConfig command.
If you see an error that starts with text similar to:
Failed to extract zip com.ibm.bpm.CMN.atlas_087_all.all 85.7000.201602251534. File C:\IBM\BPM\jdbcdrivers/SQLServer/xa/x64/sqljdbc_xa.dll already exists.
You must remove the files from install_root/jdbcdrivers/SQLServer and try the rollback again.

Additional information



You can find additional information on any of these topics in the IBM Business Automation Workflow product documentation.

Trademarks and service marks



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

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SS8JB4","label":"IBM Business Automation Workflow"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"18.0.0.1;18.0.0.2;19.0.0.1;19.0.0.2;19.0.0.3","Edition":"All Editions","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTN5","label":"IBM Business Process Manager Advanced"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Upgrade","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5.7.CF201706;8.5.7.CF201703;8.5.7.CF201612;8.5.7.CF201609;8.5.7.CF201606;8.5.7;8.5.6.2;8.5.6.1;8.5.6;8.5.5;8.5.0.2;8.5.0.1;8.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTDH","label":"IBM Business Process Manager Standard"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Upgrade","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.5.7.CF201706;8.5.7.CF201703;8.5.7.CF201612;8.5.7.CF201609;8.5.7.CF201606;8.5.7;8.5.6.2;8.5.6.1;8.5.6;8.5.5;8.5.0.2;8.5.0.1;8.5","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

IBM BPM, IBM Case Manager

Document Information

Modified date:
09 December 2020

UID

ibm11103469