Upgrading profiles from IBM Business Process Manager Version 8.6.x to IBM Business Automation Workflow V18.0.0.2

Table of Contents

• Upgrading IBM Business Process Manager Server V8.6.x profiles to IBM Business Automation Workflow V18.0.0.2 profiles
  • Procedure
• Identifying and recovering from profile upgrade or toolkit upgrade errors
• Rolling back the Business Automation Workflow environment
• Additional information
• Trademarks and service marks

Upgrading IBM Business Process Manager Server V8.6.x profiles to IBM Business Automation Workflow V18.0.0.2

To upgrade from IBM Business Process Manager Server V8.6.x to IBM Business Automation Workflow V18.0.0.2, follow the instructions to back up your existing installation, install the fix onto the deployment manager and each managed node, upgrade your Process Server database, and restart the deployment manager and nodes.

IBM Business Process Manager Server Express cannot be upgraded to IBM Business Automation Workflow V18.0.0.2. You can use artifact migration as described in Migrating artifacts to IBM Business Automation Workflow.

If you are using stand-alone LDAP and want to use the new case management features with the embedded Content Platform Engine, you must switch to the file registry before you upgrade.

Before you upgrade your production environment to Business Automation Workflow V18.0.0.2, you can clone your V8.6.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 system requirements.
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.

IBM Workflow Center and Workflow Server versions do not need to match, and Workflow Server V18.0.0.2 can connect to an earlier version of IBM Process Center V8.5.x or V8.6.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 Workflow Server V18.0.0.2 and an earlier version of Process Center V8.5.x or V8.6.

To interact with Workflow Center, Process Designer must be at V8.5.7 CF2018.12 and IBM Integration Designer must be at V18.0.0.2.

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.

Procedure

1. Verify that your target environment - including hardware, operating systems, and database prerequisites - is a supported operating environment for IBM Business Automation Workflow V18.0.0.2. See IBM Business Automation Workflow system requirements.
   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.
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 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.
   • 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.
   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.
   2. Customization to the 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.
      
6. Add a local IBM Business Automation Workflow V18.0.0.1 delta repository into Installation Manager and install the cumulative fix 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 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 are upgrading from a swinging profiles environment, complete the following steps. For more information about swinging profiles, see Swinging profiles between product installations.
   • Create a TAR file for the new level IBM Business Automation Workflow installation on the primary computer.
   • Copy the TAR file to the clone computer and decompress it.
   • On the clone computer, modify the wasprofile.properties file in the new decompressed directory.
     Change the following lines:
     WS_CMT_LOG_HOME=${WAS_install_root}/logs/manageprofiles
     WS_PROFILE_REGISTRY=${WAS_install_root}/properties/profileRegistry.xml
     WS_WSPROFILE_DEFAULT_PROFILE_HOME=${WAS_install_root}/profiles
     to:
     WS_CMT_LOG_HOME=common_profile_dir/logs/manageprofiles
     WS_PROFILE_REGISTRY=common_profile_dir/properties/profileRegistry.xml
     WS_WSPROFILE_DEFAULT_PROFILE_HOME=common_profile_dir/profiles
     where common_profile_dir is the directory where you put the IBM Business Automation Workflow user data.
   • If you have a symbolic link to install_root, point to the new decompressed directory on the clone computer. For example:
     rm /opt/BPMCommonArea/BPMLink
     ln -s /opt/CLONE_18002 /opt/BPMCommonArea/BPMLink
9. 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.
      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
   2. Connect to the Db2 for z/OS database, and run these SQL scripts against the database using your preferred tool in this order:
      1. upgradeSchema860_ProcessServer.sql
      2. createProcedure_ProcessServer.sql
      
      The version number (such as 860 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.
10. 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
11. Prepare the databases for IBM Content Navigator.
    Note: Steps 11-13 are about configuring case management and are required, even if you do not intend to use the case management features. If you have an external Content Platform Engine already configured, you can skip step 12. You will set up the external engine in Step 29.
    If you have a Db2 for z/OS database or you have an AdvancedOnly deployment environment, skip steps 11-13. Otherwise, you must do steps 11-13, even if you do not intend to use case management.
    
    Find the files to create a database for your database type in install_root/BPM/dbscripts/database_type/Create.
    • For Db2, you have two options. You can create three databases: one for IBM Content Navigator (in this step), one for the design object store, and one for the target object store (in the next step). Or, you can create a common database for all three components. This step and the next assume that you are creating three separate databases.
      Find the following files:
      createDatabase_ICN.sql
      createTablespace_ICN.sql
      
      Replace the following parameters:
      @DB_NAME@ is the database name of the IBM Content Navigator (ICN) database, for example, ICNDB.
      @ECMClient_SCHEMA@ is the schema used by ICN, for example ICNSA.
      @ECMClient_DBUSER@ is the user name for the database.
      @ECMClient_TBLSPACE@ is the table space used by ICN. The default value is WFICNTS.
      
      Copy the files to the database computer and run the files to create the database.
      createDatabase_ICN.sql
      createTablespace_ICN.sql
    • For Oracle, you must create three users: one for IBM Content Navigator (in this step), one for the design object store, and one for the target object store (in the next step).
      Find the following files:
      createUser.sql
      createTablespace_ICN.sql
      
      Replace the following parameters:
      @DB_NAME@ is the Oracle instance name, for example, orcl.
      @DB_DIR@ is the directory, which you must create before running the SQL files. The DB_DIR directory is the data directory of your database.
      @ECMClient_TBLSPACE@ is the table space used by IBM Content Navigator (ICN). The default value is WFICNTS. You can set it in the SQL files.
      @ECMClient_SCHEMA@ is the schema used by IBM Content Navigator (ICN).
      @DB_USER@ is the same as the schema name.
      @DB_PASSWD@ is the password for the user.
      
      Copy the files to the database computer and run the files to create the database.
      createUser.sql
      createTablespace_ICN.sql
      Tip: If you want to use an existing table space for all three Oracle users, you must modify the deployment_manager_profile/config/cells/cell_name/deployment_environment_name/CaseManagerConfig.properties file and the related SQL script.
    • For SQL Server, you have two options. You can create three databases: one for IBM Content Navigator (in this step), one for the design object store, and one for the target object store (in the next step). Or, you can create a common database for all three components. This step and the next assume that you are creating three separate databases.
      Find the following files:
      createDatabase_ICN.sql
      createUser.sql
      
      Replace the following parameters:
      @DBNAME@ is the name of the ICN database, for example, ICNDB.
      @DBUSER@ is the user name for the database.
      @DB_LOGIN@ is the login name of the database user.
      
      Copy the files to the database computer and run the files to create the database.
      createDatabase_ICN.sql
      createUser.sql
12. Prepare the databases for IBM Enterprise Content Management. If you have an external Content Platform Engine already configured, skip this step.
    • For Db2, create two directories, for creating databases for the design object store (DOS) and the target object store (TOS). Call the directories dos and tos.
      
      Find the following database creation files in install_root/BPM/dbscripts/DB2/Create.
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createDatabase_ECM.sql
      createTablespace_ECM.sql
      
      Copy all three files into the dos directory and replace the following parameters:
      In Windows, use the backslash ("\") to replace the forward slash as the file separator.
      @DB_NAME@ is the database name, for example DOSDB.
      @DB_DIR@ is the data directory of your database, for example, BPMINST\Node0000.
      Important: Make sure that the @DB_NAME@\@DB_DIR@ path already exists on your database computer.
      @ECM_DATA_TS@ is the data table space used by DOS. The default value is WFDOSDATATS.
      @ECM_IDX_TS@ is the index table space used by DOS. The default value is WFDOSINDEXTS.
      @ECM_LOB_TS@, is the LOB table space used by DOS. The default value is WFDOSLOBTS.
      @DB_USER@ is the user name for the database.
      @DOS_SCHEMA@ is the schema for DOS, for example, DOSSA.
      @TOS_SCHEMA@ is the schema for TOS, for example, TOSSA.
      @SCHEMA@ is the schema for DOS, for example, DOSSA.
      
      Copy the files to the database computer:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createDatabase_ECM.sql
      createTablespace_ECM_sql
      
      Run the following files:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createTablespace_ECM.sql
      
      For the second time, get the following database files from install_root/BPM/dbscripts/DB2/Create:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createDatabase_ECM.sql
      createTablespace_ECM.sql
      
      Copy all three files into the tos directory and replace the following parameters:
      Remove the mdkir lines from the createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX). All the directories should have been created when you ran the command the first time.
      In Windows, use the backslash ("\") to replace the forward slash as the file separator.
      @DB_NAME@ is the database name, for example TOSDB.
      @DB_DIR@ is the data directory of your database, for example, BPMINST\Node0000.
      @ECM_DATA_TS@ is the data table space used by TOS. The default value is WFTOSDATATS.
      @ECM_IDX_TS@ is the index table space used by TOS. The default value is WFTOSINDEXTS.
      @ECM_LOB_TS@, is the LOB table space used by TOS. The default value is WFTOSLOBTS,
      @DB_USER@ is the user name for the database.
      @DOS_SCHEMA@ is the schema for DOS, for example, DOSSA.
      @TOS_SCHEMA@ is the schema for TOS, for example, TOSSA.
      @SCHEMA@ is the schema for TOS, for example, TOSSA.
      
      Copy the files to the database computer:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createDatabase_ECM.sql
      createTablespace_ECM_sql
      
      Run the following files:
      createDatabase_ECM.bat (for Windows) or createDatabase_ECM.sh (for Linux or UNIX)
      createTablespace_ECM.sql
    • For Oracle, create two users and table spaces for the design object store (DOS) and target object store (TOS). Find the database creation SQL file in install_root/BPM/dbscripts/Oracle/Create and make a copy of it.
      createUserTablespace_ECM.sql
      
      Replace the following parameters:
      In Windows, use the backslash ("\") to replace the forward slash as the file separator.
      @ECM_DATA_TS@ is the data table space used by DOS or TOS. The default value for DOS is WFDOSDATATS. The default value for TOS is WFTOSDATATS.
      @DB_NAME@ is the Oracle instance name, for example, orcl.
      @DB_DIR@ is the data directory of your database.
      Important: Make sure that the @DB_NAME@\@DB_DIR@ path already exists on your database computer.
      @DB_USER@ is the DOS user name or TOS user name. for example, dosuser or tosuser.
      @DB_PASSWD@ is the password for the user.
      
      Copy the file to the database computer and run it:
      createUserTablespace_ECM.sql
    • For SQL Server, create two directories, for creating databases for the design object store (DOS) and the target object store (TOS). Call the directories dos and tos.
      
      Find the following database creation files in install_root/BPM/dbscripts/SQLServer/Create:
      createDatabase_ECM.sql
      createUser.sql
      
      Copy the files into the dos directory and replace the following parameters:
      In Windows, use the backslash ("\") to replace the forward slash as the file separator.
      @DB_NAME@ is the database name, for example DOSDB.
      @DB_DIR@ is the data directory of your database.
      Important: Make sure that the @DB_NAME@\@DB_DIR@ path already exists on your database computer.
      @DOS_SCHEMA@ is the schema used by DOS, for example, DOS.
      @TOS_SCHEMA@ is the schema used by TOS, for example, TOS.
      
      In the createUser.sql file, uncomment the following lines:
      --EXEC sp_addrolemember 'db_securityadmin', @DB_USER@;
      --EXEC sp_addsrvrolemember @DB_USER@, 'bulkadmin';
      so they look like this:
      EXEC sp_addrolemember 'db_securityadmin', @DB_USER@;
      EXEC sp_addsrvrolemember @DB_USER@, 'bulkadmin';
      
      Copy the files to the database computer and run them:
      createDatabase_ECM.sql
      createUser.sql
      
      For the second time, get the following database files from install_root/BPM/dbscripts/SQLServer/Create:
      createDatabase_ECM.sql
      createUser.sql
      
      Copy the files into the tos directory and replace the following parameters:
      In Windows, use the backslash ("\") to replace the forward slash as the file separator.
      @DB_NAME@ is the database name, for example TOSDB.
      @DB_DIR@ is the data directory of your database.
      @DOS_SCHEMA@ is the schema used by DOS, for example, DOS.
      @TOS_SCHEMA@ is the schema used by TOS, for example, TOS.
      
      In the createUser.sql file, uncomment the following lines:
      --EXEC sp_addrolemember 'db_securityadmin', @DB_USER@;
      --EXEC sp_addsrvrolemember @DB_USER@, 'bulkadmin';
      so they look like this:
      EXEC sp_addrolemember 'db_securityadmin', @DB_USER@;
      EXEC sp_addsrvrolemember @DB_USER@, 'bulkadmin';
      
      Copy the files to the database computer and run them:
      createDatabase_ECM.sql
      createUser.sql
      
      During this step, you can safely ignore any SQL0554N An authorization ID cannot grant a privilege or authority to itself. SQLSTATE=4250 errors.
13. Run the following command to collect the data source information for IBM Content Navigator (ICN). The command also collects the data source information for the design object store (DOS) and target object store (TOS) components for the embedded Content Platform Engine.
    • On Windows: install_root\bin\BPMConfig.bat -update -profile deployment_manager_profile deployment_environment_name -caseConfigure
    • On Linux or UNIX: install_root/bin/BPMConfig.sh -update -profile deployment_manager_profile -de deployment_environment_name -caseConfigure
      Make sure that the names of the table spaces are the same as the values that you entered in the SQL files in the two previous steps. You can open deployment_manager_profile/config/cells/cell_name/deployment_environment_name_CaseManagerConfig.properties to check or modify the table space names.
      You can also run this command silently using a response file. See Sample case configuration response files for the BPMConfig command.
      If you change parameters, you can rerun the command.
14. 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.
15. 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.
    • 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.6.0.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 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.
16. If you are upgrading with swinging profiles, run the BPMEnablePostInstaller command on the deployment manager to run the required post-installation scripts. Use this command only if your environment is configured for swinging profiles. See  BPMEnablePostInstaller command-line utility for V19.x.
17. 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 Business Process Choreographer, Business Space, CommonDB, and Messaging Engine databases are not changed when you upgrade to V18.0.0.2.
18. 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 environment.
19. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit upgrade errors, before you continue.
20. 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.
21. If you are upgrading with swinging profiles, and you have managed nodes on separate computers from the deployment manager, run the BPMEnablePostInstaller command on each node to run the required post-installation scripts. Use this command only if your environment is configured for swinging profiles.
22. 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.
23. 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.
24. 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.
25. 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.
26. 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.
27. Optional: To use case management, follow these instructions to enable it.
    Note: Steps 27-27 are about configuring case management. If you have a Db2 for z/OS database or an AdvancedOnly deployment environment, or you want to configure case management later, or if you do not intend to use case management, skip these steps.
    1. Update the location of the network shared directory by running BPMConfig -update -networkDirectory. For a single-node cluster, specify a location in the local file system. In a three-cluster environment, you can do the same, or specify a virtual or shared drive. The network shared directory must be visible to and writable by all nodes, so make sure it is mapped to all server nodes in the cluster.
       For example:
       BPMConfig -update -profile DmgrProfileName -de DE_NAME -networkDirectory /mnt/nfsshare/LDEPS -component ContentNavigator
       BPMConfig -update -profile DmgrProfileName -de DE_NAME -networkDirectory /mnt/nfsshare/LDEPS -component CaseManager
    2. By default, Case Process Designer is disabled. If you want to enable it, run the following command:
       BPMConfig -update -profile DmgrProfileName -de DE_NAME -enablePD true -component CaseManager
    3. By default, the version control system (VCS) is disabled. If you want to enable it, run the following command:
       BPMConfig -update -profile DmgrProfileName -de DE_NAME -enableVCS true -component CaseManager [-vcsSandboxPath <vcsSandboxPath> -vcsHearbeatInterval <vcsHearbeatInterval> -vcsCommitTimeout <vcsCommitTimeout> -vcsDeliverTimeout <vcsDeliverTimeout> [-vcsAdditionalParameters <vcsAdditionalParameters>]
       For more information about the options, run BPMConfig -help update.
    4. By default, IBM Content Navigator uses eForms only. If you want to enable IBM Forms, run the following command:
       BPMConfig -update -profile DmgrProfileName -de DE_NAME -caseForms -type ibmForms [-ibmFormsRenderApp <ibmFormsRenderApp> -translatorURL <translatorURL> -ibmFormsDirectory <ibmFormsDirectory>]
       For more information about the options, run BPMConfig -help update.
28. Optional: If you are going to use the embedded Content Platform Engine for case management, follow these instructions.
    Important: If you are using a SOAP connection, the command can take longer to complete than the specified SOAP timeout value. Although the command continues to run until it is finished, you might see the exception java.net.SocketTimeoutException: Read timed out. To prevent this exception, set a higher value for the com.ibm.SOAP.requestTimeout property in the profile_root/properties/soap.client.props file.
    1. Run the AdminTask to create the target object store and design object store.
       • If you use VMM with the file registry, first create a group using the WebSphere administrative console, for example, adminGroup2. Add the deployment environment administrator into this group.
         Then run the createObjectStoreForContent command to configure the embedded Content Platform Engine.
         - The command must be run on the deployment manager node.
         - The command must be run in connected mode.
         - The wsadmin command must connect to the SOAP_CONNECTOR_ADDRESS of the application cluster member or the single cluster member.
         - The -clusterName parameter is the name of the application cluster or the name of the single cluster for the deployment environment.
         For example:
         wsadmin -user admin -password admin lang -host localhost -port 8881 -lang jython
         print AdminTask.createObjectStoreForContent(['-clusterName', 'appCluster', '-PEWorkflowSystemAdminGroup', 'adminGroup2','-creationUser','deadmin','-password','deadmin_pw'])
         where 'appCluster' is the name of the application cluster in this deployment environment, and 'deadmin' is the deployment environment admin user.
         For more details about this command, see createObjectStoreForContent command.
       • If you use VMM with LDAP, run the AdminTask to configure the embedded Content Platform Engine, as in the following example.
         The -PEWorkflowSystemAdminGroup must be an LDAP group, the -creationUser must be a member of that LDAP group, and the -port must be the application server SOAP port.
         For example:
         wsadmin -lang jython -user deadmin -password deadmin -host localhost -port 8880
         print AdminTask.createObjectStoreForContent(['-clusterName', 'appCluster', '-PEWorkflowSystemAdminGroup', 'managerGroup1','-creationUser','managergroup1user1','-password','managergroup1user1_pw'])
    2. Configure your system before you use the case management features in development or production. See Configuring your system for case management.
    3. Restart the deployment environment.
29. Optional: If you are going to use an external Content Platform Engine for case management, follow these instructions. (For more information about using an external engine rather than the embedded engine, see Configuring an external Content Platform Engine for case management.)
    1. If you never used an external Content Platform Engine in your source environment, run the setBPMExternalECM command. If you did, run the updateBPMExternalECM command.
    2. Copy the four JAR files (pe.jar, peResource.jar, jace.jar, eeapi.jar) from BPM/filenet/lib to the same folder on all computers that have managed nodes.
    3. Restart the deployment environment.
    4. Run the case management configuration tool to configure the integration with IBM Content Navigator and the external Content Platform Engine. See Configuring the development environment by using the command line.
    5. Restart the deployment environment.
30. Optional: To use the IBM Administration Console for Content Platform Engine (ACCE), you must first register the ACCE plug-in to IBM Content Navigator, because the DocStoreAdmin component is removed in V18.0.0.2. See Running the development environment case configuration tasks for instructions. After the ACCE plug-in is registered, you can access the console through a web browser. For example:
    https://localhost:9443/navigator/?desktop=acce
31. After Process Center is upgraded to Workflow Center, existing Process Designer users must follow the instructions for Updating desktop IBM Process Designer.
32. Your IBM BPM environment is now upgraded to IBM Business Automation Workflow V18.0.0.2. 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. 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 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 with the upgrade, 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. Roll back the upgrade using the Installation Manager. See Rolling back the upgrade 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 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.
7. Start your IBM Business Process Management 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.
8. 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 Automation Workflow product documentation. Trademarks and service marks

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