Testing the upgrade from IBM Business Process Manager V8.5.5 to V8.5.6

Before you upgrade your production environment from IBM® Business Process Manager V8.5.5 to V8.5.6, you can clone your 8.5.5 environment, including both the deployment environment and database, and test the upgrade.

Note: This document applies to upgrading only from V8.5.5.0 or later.

About this task

You can do most of the following steps while your existing environment is online. Nothing is written to the existing environment, so your current environment can run in parallel while you upgrade the cloned environment and run tests on it.

Procedure

Export the configuration from the IBM BPM 8.5.5 deployment environment using the following command:

BPMConfig –export –profile profile_name -de de_name -outputDir output_directory

Important: Specify a different output directory for each deployment environment. In the case where a cell has multiple deployment environments, a unique output directory is required for each deployment environment.

The configuration files are placed in the output directory that you specify.

Table 1. Configuration files for each deployment environment
Sample name	Description
`de_name`.properties	This properties file contains the configuration information from your source environment. You use this file when you configure the target environment. For more information, see the reference topic about configuration properties for the BPMConfig command.
fileRegistry.xml	If you use a file-based user registry, the user registry file is copied from the source environment to be added to the target environment.
ltpa.jceks	If you use LTPA, the LTPA key file is copied from the source environment to be added to the target environment.
ldap_additional_properties.xml	If you use a federated repository and an unencrypted LDAP connection in the source environment, additional properties of the LDAP server are copied from the source environment to the output directory, where they are later used automatically to create the target environment. Restriction: If you extend the federated repository to use a custom login property (such as `userPrincipalName`) in addition to the default `uid` property in the source environment, LDAP is not configured for the target environment, with the following warning: `CWMCB0600W: LDAP could not be configured! You may configure LDAP separately after BPMConfig has terminated successfully.` If you see this warning, manually configure LDAP with the login properties you want to use after the migration is complete.
Application-config-bpc.xml and resources-bpc.xml	If you have Business Process Choreographer configured in the source environment, the configuration files are copied from the source environment to the output directory, where they are later used automatically to create the target environment.
Support-config-bpc.xml	If you have Business Process Choreographer Archive Manager configured on the support cluster in the source environment, the configuration is copied from the source environment to the output directory, where it is later used automatically to create the target environment.

Copy the output directory to the computer where you want to create the new deployment environment.

Install IBM BPM V8.5.6 on the environment where you are going to test the upgrade.
Create the cloned environment using the exported configuration files.
1. Use the IBM BPM Configuration editor to update the exported properties file. Make sure that it will point to the cloned databases instead of the source databases. Make other updates if required.
  Notes:
  - Keep the same cell name, cell administrator, and deployment environment administrator.
  - Make sure that bpm.de.deferSchemaCreation is set to true in the properties file.
  - If possible, use the same LDAP server as the source environment.
  - If the IBM BPM system is integrated with other services, you must reconfigure that part of the environment after the deployment environment is created and point to the test environment for those services.
2. Run the following command to validate that all database connections are correctly configured.
```
BPMConfig -validate -db output_directory/updated_properties_file
```
3. Run the following command to create the cloned environment on the test machine.
```
BPMConfig –create –de output_directory/updated_properties_file
```
If you are testing upgrade for an Advanced or AdvancedOnly deployment environment, you must extract the advanced applications and service integration bus (SIB) messages; otherwise, you can skip this step.
1. Update the install_root_8.5.5/util/migration/resources/migration.properties file to point to your source environment. Update the following properties:
```
admin.username=admin
admin.password=admin

bpm.home=E:/bpm8550
profile.name=DmgrProfile

source.application.cluster.name=
source.support.cluster.name=
source.messaging.cluster.name=
```
2. If you want to keep the SIB messages in the cloned database consistent with the SIB messages that you are going to extract in the next step, run the BPMManageApplications command to disable the automatic starting of applications and schedulers.
```
BPMManageApplications -autoStart false -source -propertiesFile migration_properties_file
```
  Stop the environment, back up the databases, and start the environment before you continue.
  If you are testing and do not care about the gap between the SIB messages in the database and the extracted SIB messages, manually create an empty file named app_cluster_name.BPMManageApplications.false.success in the dmgr_profile/logs folder to skip this step.
3. Run the BPMExtractSourceInformation command to extract the advanced applications and SIB messages and create a snapshot in the specified folder.
```
BPMExtractSourceInformation -backupFolder folder_path  -propertiesFile migration_properties_file
```
Back up and clone your existing databases. Normally you should back up databases while the server is offline, but you can back up the databases online for testing purposes only.
1. Use your database utility to back up each of your source databases, and restore them to another database instance or schema. Clone each of the IBM BPM databases. You must make sure that they match the database information that you specified when you updated the BPMConfig properties file in step 3, including the following properties:
  - installPath
  - hostname
  - port
  - database name
  - schema
  - user
  - password
2. Manually drop the existing messaging engine tables in the cloned messaging database before you start the target deployment environment.
  Tip: The messaging engine table names use the SIB prefix.
If you are testing upgrade for an Advanced or AdvancedOnly deployment environment, you must deploy the advanced applications and SIB messages that you extracted in step 4; otherwise, you can skip this step.
1. Update the install_root_8.5.6/util/migration/resources/migration.properties file to point to your target environment. Update the following properties:
```
admin.username=admin
admin.password=admin

bpm.home=E:/bpm8550
profile.name=DmgrProfile

source.application.cluster.name=
source.support.cluster.name=
source.messaging.cluster.name=
# Use the properties file that you used to create the deployment environment
target.config.property.file=
```
2. Run the BPMManageApplications command to disable the automatic starting of applications and schedulers.
```
BPMManageApplications -autoStart false -target -propertiesFile migration_properties_file
```
3. Start the environment. Add a deployment_environment_name.DBUpgrade.success file in the deployment_manager_profile/logs folder to skip the check for database upgrading, because the database version is the same as in the cloned deployment environment and does not need to be upgraded.
4. In the backup folder that was generated when you ran the BPMExtractSourceInformation command, open the snapshot_folder/cell_name/Applications folder and remove all IBM BPM system applications that should not be deployed to the target again by the BPMMigrate command. Applications that should be removed include:
  - Business.Rules.Manager
  - IBM_BPM_DocStoreAdmin
  - IBM_BPM_DocumentStore
  - IBM_BPM_WebPD
  - RemoteAL61
  - HTM_PredefinedTaskMsg
  - HTM_PredefinedTasks
5. Run the BPMMigrate command to deploy applications, import SIB messages, and re-create scheduler tasks.
```
BPMMigrate -backupFolder folder_path  -propertiesFile migration_properties_file
```
6. Run the BPMManageApplications command again to enable the automatic starting of applications and schedulers.
```
BPMManageApplications -autoStart true -target -propertiesFile migration_properties_file
```
7. Restart the servers.
Complete other configuration customization. You might need to do other customization on the cloned environment to make it consistent with the source. For example:
- Copy 100Custom.xml from your source environment to the cloned environment.
- Copy customized data sources or authentication aliases.
- Copy business space customization.
- Copy other services that the IBM BPM system needs to integrate with.
See the migration topics under Moving your custom configuration to the target environment for details.
Use the upgrading documentation and test the upgrading procedure against your cloned environment, including database upgrade, profile upgrade during server startup, and validating the results.