Upgrading profiles from IBM Business Automation Workflow 18.0.0.x, 19.0.0.x or 20.0.0.x to IBM Business Automation Workflow 23.0.1

• Upgrading IBM Business Automation Workflow 18.0.0.x, 19.0.0.x, 20.0.0.x profiles to IBM Business Automation Workflow 23.0.1 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 Automation Workflow 18.0.0.x, 19.0.0.x, 20.0.0.1, or 20.0.0.x profiles to IBM Business Automation Workflow 23.0.1 profiles

You can upgrade from IBM Business Automation Workflow Enterprise 18.0.0.1, 18.0.0.2, 19.0.0.1, 19.0.0.2, 19.0.0.3, 20.0.0.1, or 20.0.0.2 to IBM Business Automation Workflow Enterprise 23.0.1, or from IBM Business Automation Workflow Express 18.0.0.1, 18.0.0.2, 19.0.0.1, 19.0.0.2, 19.0.0.3, 20.0.0.1, or 20.0.0.2 to IBM Business Automation Workflow Express 23.0.1.

Follow the procedure to back up your existing installation, install the fix onto the deployment manager and each managed node, upgrade your Process database, and restart the deployment manager and nodes.

Before you upgrade your production environment to Business Automation Workflow 23.0.1, you can clone your 18.0.0.x, 19.0.0.x, 20.0.0.1 or 20.0.0.2 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 you start the upgrade.

Important: do not put any custom jars into the system classpath of IBM Business Automation Workflow, the system classpath includes install_root/lib, install_root/lib/ext, install_root/plugins, install_root/java/jre/lib/ext, install_root/BPM /Lombardi/lib, install_root/BPM/Lombardi/plugins, and so on. Also, you cannot configure Dynatrace or similar products with IBM Business Automation, it affects the classloading of Business Automation Workflow.

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 later. Otherwise, the database version validation fails 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 23.0.1 can connect to Workflow Center 18.0.0.x, 19.0.0.x or 20.0.0.x. You can upgrade Workflow Server first and test your applications to make sure that they still work normally after the upgrade. Upgrade Workflow Center last. For more information, see Performing a rolling upgrade.

You can also use offline deployment between Workflow Server 23.0.1 and Workflow Center 18.0.0.x, 19.0.0.x or 20.0.0.x.

Important: Rolling upgrades do not apply if you are using case management and have case solution projects.  An upgraded Workflow Server environment will only accept case solution project installs when the case solution project is upgraded to 23.0.1, whether offline or online.  A case solution project can be upgraded to 23.0.1 in an upgraded 23.0.1 Workflow Center environment prior to installing to a 23.0.1 Workflow Server.

Note: Due to APAR JR61813, a pre-19.0.0.1 Workflow Center shows an error when attempts are made to retrieve installation messages during online deployment to a 19.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 Workflow Center.

To interact with Workflow Center, Process Designer must be at V8.5.7.202306 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 under system thresholds. When you upgrade to 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 23.0.1. Ensure that you have at least 18 GB of disk space, including temporary disk space, before the upgrade.
2. Stop all the Java™ processes associated with the IBM Business Automation Workflow products that are being upgraded.
   1. Stop the single cluster or the three clusters in the following order: Support, Application, and then Messaging.
      Note: Make sure that a graceful shutdown is performed to ensure that there are no in-doubt transactions. Otherwise, you could have problems with database locks when you upgrade 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: If you install the fix when a Java process related to WebSphere Application Server is running, the product might not continue to run successfully.
3. Back up your IBM Business Automation Workflow 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:

   • During the upgrade, the CaseEventEmitter WAR and CaseEventEmitter json files in the install_root/CaseManagement/analytics/ directory are overwritten. If you are using IBM Business Automation Insights and modified these files, back them up and restore the JSON file after the upgrade.

   • During the upgrade, the BPMEventEmitter WAR archive file and sample configuration files in the install_root/BPMN/analytics/configTemplates and install_root/BPM/Lombardi/tools/def directories are overwritten.

     In the install_root/BPM/analytics/configTemplates directory, if you customized the BPMEventEmitter.yml sample file, back it up to be able to retrieve it after the upgrade.

     In the install_root/BPM/Lombardi/tools/def directory, if you customized the BAIConfigure.properties sample file and used it with the EnableBAI.py script, back it up to be able to retrieve it after the upgrade.

   • If you need to restore a previous profile backup after you run the steps to upgrade your profile, you must complete all the steps in Rolling back the Business Automation Workflow environment. Otherwise, you cannot 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 Business Automation Workflow installation and profile directories. If you are applying patches to other products installed with Installation Manager, be sure to take backups of those products 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 need these files to recover from it. If you have either a full file system backup or all of these directories, 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 Business Automation Workflow environment.
   Important: Make a backup of your databases at the same time as you make the profile backup. The schema and table data change during the upgrade. If something goes wrong, make sure you gather the database data to restore.
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 by 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 reapply the custom theme after you finish the upgrade.
6. If you are upgrading from a swinging profiles environment, complete all but the last step in Applying an interim fix or cumulative fix by swinging profiles. Instead of running the next two steps in these upgrading instructions, use the same information to install the cumulative fix to the main product installation during the first step of the swinging profile instructions.
   Important: Do not complete the last step of the swinging profile instructions and restart the environment until you are told to in these upgrading instructions.
7. 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)
8. 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)
9. If you have a Db2 for z/OS database, complete the following steps:
   Important: Skip this step for AdvancedOnly deployment environments.
   Important: IBM Business Automation Workflow supports universal table spaces (UTS) only. You must convert non-UTS table spaces to UTS table spaces before you upgrade the profiles. For more information, see Altering table spaces. For better table space conversion, upgrade the DB2 function level to V12R1M508 or later to upgrade your IBM Business Automation Workflow profile.
   For DOSDB and TOSDB, the Db2 for z/OS administrator needs to precheck the following table spaces: DOSDATTS, DOSIDXTS, DOSLOBTS in DOSDB and TOSDATTS, TOSIDXTS, TOSLOBTS in TOSDB. If there are tables in these table spaces, you can upgrade them to Partition-by-growth (PBG) UTS with Converting deprecated table spaces to fully supported types.  If there is no data in these table spaces, drop them, and then create new UTS table spaces in a new Db2 for z/OS server. To migrate old table spaces to a new table space, see Dropping and re-creating a table space to change its attributes.
   
   Tip: If you try to move all the tables from old multiple-table-segmented table spaces to the newly created UTS table space, do not drop the old multiple-table-segmented table space until all the tables are moved and the REORG job runs successfully. If you leave only one table in the old multiple-table-segmented table space, which means you move the other tables to newly created UTS table spaces, and try to convert the old multiple-table-segmented table spaces to PBG UTS table space, you can do it directly.
   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]
      If there is only one deployment environment, you can omit the -de parameter.
      
      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.sc1900hema_name
   2. Connect to the Db2 for z/OS database, and run these SQL scripts against the database by using your preferred tool in this order:
      1. upgradeSchema19003_ProcessServer.sql
      2. createProcedure_ProcessServer.sql
   3. If the embedded IBM Content Navigator (ICN) component is enabled, run the following script manually against the ICN database to update the navigator tables:
      deployment_manager_profile/dbscripts/Upgrade/cell_name.deployment_environment_name/database_type/database_name.schema_name/upgradeSchema2103_NavigatorDB.sql
      
      The version number (such as 19003 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. 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 and Performance Data Warehouse databases. See DBUpgrade command-line utility (Important: for SQLServer and Oracle,  do not use BAW database users to validate, you can use database system user, for example, sa for SQLServer or SYS for oracle).
    • 
      If you see some debug output on the console, such as, No method getDelegate for java.net.URLClassLoader@dddc56e7, ignoring, you can safely ignore it.
11. 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]
      
      If there is only one deployment environment, you can omit the -de parameter.
      
      Important: Make sure that the DBUpgrade command has finishes 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 DBUpgrade ran unsuccessfully, correct the errors, and restore your databases from the backup before you run 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 large 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 tablespace 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 by using the modified files.
      Important: Removing required schema changes from the upgrade scripts can corrupt the database.
      
      Note: If you are using an SQL server and you are upgrading from IBM Business Automation Workflow 19.0.0.2 or earlier, ensure that you enabled the READ_COMMITTED_SNAPSHOT database flag. To enable the flag, run the SQL command: ALTER DATABASE @DB_NAME@ SET READ_COMMITTED_SNAPSHOT ON
      You can also enable the flag manually:
      1. Open SQL Server Management Studio.
      2. Select your database.
      3. Go to Properties > Options.
      4. Scroll down until you find the Is Read Committed Snapshot On option.
      5. Set the option to true.
12. If you are not using Db2 for z/OS, and no permission is granted to the ICN database connection user to create tables and indexes, run the following script against the ICN DB manually to update the ICN database:
    deployment_manager_profile/dbscripts/Upgrade/cell_name.deployment_environment_name/database_type/database_name.schema_name/upgradeSchema_NavigatorDB.sql
13. 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 launch. 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.
    • Warning: Do 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 22.0.2.
14. Check for and fix errors, as described in Identifying and recovering from profile upgrade or toolkit upgrade errors before you continue.
15. Update the web server plug-in.
    New web modules are added to the product applications. If the existing product applications are mapped, these modules are mapped to the web server. 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 is generated. For more information, see the Plug-ins configuration documentation.
16. 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.
17. Ensure that node synchronization is completed. It can take several minutes to complete when you update 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.
18. To prevent performance problems, customize the settings for system maintenance including options to prevent issues when you import or install snapshots after the upgrade. See Configuring notifications and actions for system maintenance.
19. Review the optional Post-upgrade tasks for more actions you might need to take. Make the changes and perform synchronization before you restart the clusters to avoid starting the environment again after these changes.
20. 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.
21. Optional: If you did not configure case management when you installed 18.0.0.x and you want to configure it for the first time now, review and perform the following substeps as needed.
    Notes:
    • To use case management, you must use federated repositories.
    • You cannot configure case management for an AdvancedOnly deployment environment.
    1. If you are using a Db2 for z/OS database, follow the instructions in the topic Configuring IBM Business Automation Workflow case management for Db2 for z/OS. If you complete step 6 in Configuring IBM Business Automation Workflow case management for Db2 for z/OS, you can omit step 21.3.
    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.
22. If you are using an external Content Platform Engine, follow these instructions to upgrade it to 23.0.1.
    1. Using wsadmin connected to the deployment manager, run the updateBPMExternalECM command.
    2. Copy the four JAR files (pe.jar, peResource.jar, jace.jar, eeapi.jar) from install_root/BPM/filenet/lib on the deployment manager to the same folder on all computers that have managed nodes.
    3. Copy the ejb-lookup.jar file from the Business Automation Workflow directory install_root/CaseManagement/configure/deploy (for example, /opt/IBM/WebSphere/AppServer/CaseManagement/configure/deploy) to the Content Platform Engine WebSphere Application Server directory install_root/lib/ext (for example: /opt/IBM/WebSphere/AppServer/lib/ext).
    4. Restart the deployment environment.
23. If you are using an external Content Navigator, follow these instructions to upgrade to 23.0.1.
    1. Using wsadmin connected to the deployment manager, run the setExternalNavigator command.
    2. Restart the deployment environment.
24. If you are using case management, follow these instructions to upgrade to 23.0.1.
    1. Run the IBM Business Automation Workflow Case Configuration tool and configure the profile either from the GUI (see Running the development environment case configuration tasks) or the command line (see Configuring the development environment by using the command line). Use the profile that you used earlier to configure IBM Business Automation Workflow. For example:
       • Windows: C:\Program Files\ibm\Workflow\v18.0\profiles\DmgrProfile\CaseManagement\De1\profiles\ICM_dev.cfgp
       • Linux or UNIX: /opt/ibm/Workflow/v18.0/profiles/DmgrProfile/CaseManagement/De1/profiles/ICM_dev/ICM_dev.cfgp
         where De1 is the name of the deployment environment.
         • Note: On AIX, if IBM SDK is updated to version 8.0.6.25 or later, the Eclipse launcher might be unable to load libjgskit.so and libjgsk8iccs_64.so. You must export the LIBPATH variable before you run the configmgr_cl command. To export LIBPATH, use the following command, where <baw_install_root> is your Business Automation Workflow installation path: LIBPATH=$LIBPATH:<baw_install_root>/java/jre/lib/ppc64:<baw_install_root>/java/jre/lib/icc.
    2. Edit the Configure Case Integration with IBM Business Automation Workflow Task by using the GUI or the configibmbpm.xml file. Ensure that the context root for Process Server application and Content Platform Engine (CPE) Workflow services application (ICMBPMServices) is correct. Save the task.
    3. If you are using an external Content Platform Engine, edit the Deploy the Content Platform Engine Gateway Service Task by using the GUI or the deploygateway.xml file. Ensure that the IBM Business Automation Workflow server cluster name is correct. Save the task.
    4. Run all tasks in this profile. Right-click the profile and select Run all tasks or run configmgr_cl execute -profile myprofile.
       Note: One of the tasks is "Register the Administration Console for Content Platform Engine (ACCE) Plug-in." The ACCE was added in V18.0.0.2. If you are using an embedded Content Platform Engine, then after the ACCE plug-in is registered, you can access the console through a web browser. For example:
       https://localhost:9443/navigator/?desktop=acce
    5. Restart the deployment environment.
    6. Upgrade the existing solutions. See Upgrading and converting case solutions.
25. If you are using IBM Business Automation Insights, restore the JSON file that you backed up in step 3. After the upgrade, your Case event emitter application must be updated. For more information, see Installing and configuring the Case event emitter. The installation also creates a lib folder. This folder contains the JAR files that need to be configured as shared libraries for your Case event emitter application. For more information, see Post-installation steps.
26. After Workflow Center is upgraded, existing Process Designer users must follow the instructions for Updating desktop IBM Process Designer.
27. Your IBM Business Automation Workflow environment is now upgraded to 22.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.

• Profile upgrade
  Log location: profile_root/logs/BPMConfig_upgrade_profileName_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.

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. If you cannot find a solution, engage IBM support.
5. Once the issue is resolved, restart the failing server to trigger another attempt of the upgrade step.

• If you decrease the maximum heap size, the value reverts to the default when you upgrade. If you increase it, the value is preserved.
• 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 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: bootstrapProcessServerData.sh should be updated for UNIX or Linux, but bootstrapProcessServerData.bat should be updated for Windows.
• When the  BPMConfig.sh -upgrade -profile command is executed during the deployment manager startup, 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.
• You may see a "BPM/navigator/lib/httpclient.jar exists" error when you try to upgrade from v20.0.0.2 with DT188879 installed. See Upgrading IBM Business Automation Workflow from v20.0.0.2 may result in "BPM/navigator/lib/httpclient.jar exists" error.

Rolling back the Business Automation Workflow environment

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 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 by 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 Business Automation Workflow 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