Profile upgrade instructions for V7.5.1 Fix Pack 1 (V7.5.1.1) IBM Business Process Manager (BPM) product installations with existing profiles

Table of Contents

• Common steps for all configurations
• Back up existing profiles
• Back up default XSL transformations
• Stop all the Java™ processes
• Stop Windows services

• Steps for upgrading a stand-alone environment (profile)

• Steps for upgrading in a network deployment environment
• Upgrading the deployment manager
• Upgrading managed nodes
• Upgrading clusters

• Identifying profile update errors
• Recovering after profile update errors
• Rolling back V7.5.1 Fix Pack 1 (V7.5.1.1)

Common steps for all configurations

Attention: The Installation Manager on the Microsoft Windows XP operating system does not recognize profile update errors. When you upgrade an installation on the Windows XP operating system, you must look at the Identifying Profile Update Errors section, even if Installation Manager ended with the following message: "The packages are updated".

Note: The database upgrade steps are different when you are upgrading from IBM Business Process Manager V7.5.0.x to 7.5.1 Fix Pack 1 compared to IBM Business Process Manager 7.5.1.0 to 7.5.1 Fix Pack 1. If you are migrating from Business Process Manager 7.5.0.x follow the instructions in the information center on Upgrading from IBM Business Process Manager V7.5 to IBM Business Process Manager V7.5.1

1. Back up existing profiles in IBM Business Process Manager.
   
   This fix pack updates the core product files and all the existing profiles that require a maintenance update.
   
   Before upgrading an existing installation, run the backupConfig command to back up the configuration files of each profile that the fix pack can update. See Backing up and restoring administrative configurations in the Information Center for more information about running this command.
   
   
2. Create backup copies of your existing databases. The database schema and content are changed during the upgrade process. Create a backup copy of the Process Center databases and copies of the databases in each runtime environment. Most databases provide a backup wizard or other user assistance for creating database backups. Contact your database administrator for more information
   
3. (IBM Business Process Manager Advanced only) Back up default XSL transformation files
   
   If you have applied any changes to the following default XSL transformation files, which are located in the <install_root>/ProcessChoreographer/Staff directory, back them up before installing IBM Business Process Manager Version 7.5.1 Fix Pack 1 (V7.5.1.1):
• EverybodyTransformation.xsl
• LDAPTransformation.xsl
• SystemTransformation.xsl
• UserRegistryTransformation.xsl
• VMMTransformation.xsl
  These files are overwritten during the installation of V7.5.1 Fix Pack 1 (V7.5.1.1) and the changes applied to these files are lost.
  
  After you upgrade your installation, and before you start the server or a cluster, replace the XSL transformation files with the backup version.
  
  
4. Stop all the Java processes
   
   Before installing V7.5.1 Fix Pack 1 (V7.5.1.1), stop all Java™ processes that are associated with Java SDK that is shipped with the IBM Business Process Manager products. These processes include the node agent process, the deployment manager process, and all server processes that belong to serviceable products, such as the IBM HTTP Server.
   
   Note: The product might not continue to run successfully if you install V7.5.1 Fix Pack 1 (V7.5.1.1) when a WebSphere Application Server-related Java process is running.
   
   
5. (For Windows Servers only) Stop the WebSphere Windows services
   
   WebSphere Application Server fix pack installation might update the WASServiceMsg.dll file. If any of the WebSphere servers (including node agents and deployment manager) are configured to start automatically using Windows services, the WASServiceMsg.dll file gets locked by the Microsoft Windows operating system.
   
   If you see a "WASServiceMsg.dll file can not be replaced" error during the fix pack installation of WebSphere Application Server, change the starting option for all the WebSphere services so that they start manually. Then, restart the Windows server before installing the WebSphere Application Server fix pack.
   
   Refer to the WASServiceMsg.dll is locked when installing fix packs document for more information.
   
   



Back to top

Steps for upgrading a stand-alone environment

For each stand-alone profile, complete the following steps:

1. Back up the configuration and stop the stand-alone server following the previous common steps instructions.
   
   
2. Install V7.5.1 Fix Pack 1 (V7.5.1.1) using either IBM Installation Manager or silent installation as explained in the fix pack installation instructions.
   Note: The stand-alone profile is automatically updated during fix pack installation. However, you must update the Process Server database as described in step 4.
   
   
3. Check for any errors as explained in the Identifying profile update errors section before continuing
   
   
4. Depending on the platform, run one of the following commands to update the Process Server database:
   
   On Windows operating systems:
   BPM\Lombardi\tools\updateSystemData.bat -profileName <profile_name>
   
   On UNIX-based and Linux operating systems:
   BPM/Lombardi/tools/updateSystemData.sh -profileName <profile_name>
   
   where <profile_name> is the name of the stand-alone profile. If you are not using one of the shipped Java Database Connectivity Database (JDBC) drivers from the <install_root>/jdbcdrivers directory, you must also supply the “-dbJDBCClasspath <path>” parameter where <path> is the directory that contains your custom JDBC driver.
   
   There is no database change to the BPC, Business Space, CommonDB and Messaging Engine database for upgrading from BPM 7.5.1.0 to 7.5.1.1
5. Restart the stand-alone application server.

Back to top

Steps for upgrading in a network deployment environment

Notes and restrictions when upgrading in a network deployment environment

When you upgrade from IBM Business Process Manager Version 7.5.1 in a Network Deployment environment, you must complete some additional steps. Complete the appropriate steps for your environment.

• The deployment manager must be the highest level in the cell. Upgrade the installation that contains the deployment manager before upgrading the nodes.
  
  
• In a cluster where Business Process Choreographer is configured, you cannot start cluster members at different version levels at the same time.
  
  
• You must stop all members at the older version before starting any of the upgraded members.
  
  
• After an upgraded member has been started, you must no longer start ‘old' members.
  
  
• You must not upgrade more than one installation at a time.
  
  
• The deployment manager should be up and running when managed nodes are upgraded. This step is necessary because the fix pack installer must connect to the central configuration repository on the deployment manager to make the updates.
  

Note: The only exception to this rule is for managed nodes that are hosted by the same installation as their deployment manager profile. In this scenario, the managed node configuration is updated as part of the deployment manager profile.


• When you apply the fix pack in a Network Deployment environment, the connection to the deployment manager requires you to provide a user ID and password because WebSphere administrative security is enabled. The IBM Installation Manager does not prompt for these credentials when you start updating an installation that contains managed profiles. However, depending on your configuration, you might have to enter the credentials in a separate prompt near the end of the upgrade process.
  
  Note: The credential panel displays twice during the upgrade process and has a default time out period of one minute. If you miss this prompt, your security configuration is set up such that a prompt is not displayed or if you are running the silent installation script, follow the instructions in the Identifying profile update errors section.
  
  For more information on how to configure security for WebSphere administration scripts, for which the IBM Business Process Manager scripts depend, see Configuring security with scripting in the WebSphere Application Server Information Center.



Back to top




---

Upgrading the deployment manager

To upgrade the deployment manager, complete the following steps:

1. Back up your configuration.
   
   
2. Stop all the Java processes that are associated with the IBM Business Process Manager installation as documented in the previous common steps instructions.
   
   
3. Install V7.5.1 Fix Pack 1 (V7.5.1.1) on the deployment manager installation using either IBM Installation Manager or silent installation, as explained in the fix pack installation instructions. The deployment manager profile is automatically updated during fix pack installation.
   
   
4. Check for any errors, as explained in the Identifying profile update errors section, before continuing.
   



Back to top




---

Upgrading managed nodes

To upgrade managed nodes, complete the following steps:

1. Start the deployment manager. The deployment manager must be running when you apply the fix pack to an installation with a managed profile.
   
   Note: The only exception to this rule is for managed profiles that are hosted by the same installation as their deployment manager profile. The managed node configuration is updated as part of the deployment manager profile in this scenario and a separate log file is not written.
   
   Skip step 2 in this section for managed nodes that are hosted by the same installation as their deployment manager.
   
   
2. Complete the following steps if the managed profile is hosted by an installation other than its deployment manager profile:
   
   
1. Ensure that all the servers and their node agents are stopped.
   
   
2. Install V7.5.1 Fix Pack 1 (V7.5.1.1) using either the IBM Installation Manager or silent installation as explained in the fix pack installation instructions.
   
   Note: When you apply the fix pack in a Network Deployment environment, the connection to the deployment manager requires a user ID and password because WebSphere administrative security is enabled. Depending on your configuration, you might have to enter the credentials in a separate prompt near the end of the update process. Refer to the security information in the Notes and restrictions for details.
   
   The managed node (profile) is automatically updated during fix pack installation.
   Log files are saved as: <profile_root>/logs/BPMProfileUpgrade.<profile_name>.<timestamp>.log where <profile_root> is the root directory of the managed profile.
   
   
3. Check for any errors, as explained in the Identifying profile update errors section, before continuing.
   
   
3. Depending on the platform, run one of the following commands to update the Process Server database for each non-clustered server where the Business Process Definition engine is configured:
   
   On Windows operating systems:
   BPM\Lombardi\tools\updateSystemData.bat -profileName <profile_name> -nodeName <node_name> -serverName <server_name>
   
   On UNIX-based and Linux operating systems:
   BPM/Lombardi/tools/updateSystemData.sh -profileName <profile_name> -nodeName <node_name> -serverName <server_name>
   
   where <profile_name> is the name of the deployment manager profile and <node_name> and <server_name> are the names of the managed node and the non-clustered server. If you are not using one of the shipped JDBC drivers from the <install_root>/jdbcdrivers directory, you must also supply the “-dbJDBCClasspath <path>” parameter where <path> is the directory that contains your custom JDBC driver.
   
   There is not a database change to the Business Process Choreographer, Business Space, CommonDB and Messaging Engine database when you upgrade from IBM Business Process Manager 7.5.1.0 to 7.5.1 Fix Pack 1
   
4. If Business Space is configured on a non-clustered server on this node, manual steps are required for updating existing Business Space templates and spaces. Complete the following steps:
1. In the custom profile where the managed server is located, open the <profile_root>\BusinessSpace\<node_name>\<server_name>\mm.runtime.prof\public\oobLoadedStatus.properties file and update the importTemplates.txt or importSpaces.txt properties:
   
   importTemplates.txt=true
   importSpaces.txt=true
   
   
2. If you have created the Business Space database after it was deleted, or if you need to reload the theme for any other reason, update the following property:
   
   importThemes.txt=true
   
5. If any of the nodes contain cluster members, follow the steps described under Upgrading clusters before starting the servers.
   
   
6. For each node, restart the node agent and wait for the node synchronization to complete.
   
   
7. If you have disabled automatic synchronization, ensure that all your nodes are correctly synchronized before starting the cluster members.
   
   
8. Start all the servers and cluster members, as needed.



Back to top




---

Upgrading clusters

After upgrading the deployment manager and the managed nodes containing cluster members, follow these steps to upgrade each of the clusters in your Network Deployment environment before starting the cluster members (servers).

1. Stop the deployment manager, if it is running.
   
   
2. On the deployment manager, change directories to <install_root>.
   
   
3. Depending on the platform, run one of the following commands for each cluster:
   
   On Windows operating systems:
   For English locales: bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true -Dcluster=<cluster_name>
   
   
   For non-English locales: bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true "-Dcluster=<cluster_name>"
   
   On UNIX-based and Linux operating systems:
   bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true -Dcluster=<cluster_name>
   
   where <profile_name> is the name of the deployment manager profile and <cluster_name> is the name of the cluster.
   
   Check the following log file for errors: <profile_root>/logs/BPMProfileUpgrade.<profile_name>.<cluster_name>.<timestamp>.log where <profile_root> is the root directory of the deployment manager profile.
   
   If there is an error, fix the cause, then rerun step 3.
   
   
4. Depending on the platform, run one of the following commands to update the Process Server database for each cluster where the Business Process Definition engine is configured:
   
   On Windows operating systems:
   BPM\Lombardi\tools\updateSystemData.bat -profileName <profile_name> -clusterName <cluster_name>
   
   On UNIX-based and Linux operating systems:
   BPM/Lombardi/tools/updateSystemData.sh -profileName <profile_name> -clusterName <cluster_name>
   
   where <profile_name> is the name of the deployment manager profile and <cluster_name> is the name of the cluster. If you are not using one of the shipped JDBC drivers from the <install_root>/jdbcdrivers directory, you must also supply the “-dbJDBCClasspath <path>” parameter where <path> is the directory that contains your custom JDBC driver.
   
   
5. For each cluster where Business Space is configured, manual steps are required for updating existing Business Space templates and spaces. Complete the following steps:
1. Identify the custom profile for the oobLoadedStatus properties file:
1. In deployment manager profile, open the <deployment_manager_profile_root>\BusinessSpace\<cluster_name>\mm.runtime.prof\config\ConfigService.properties file.
   
   
2. Look for the name of the cell, node and server in the com.ibm.mashups.directory.templates or com.ibm.mashups.directory.spaces properties.
   
   
   For example, in com.ibm.mashups.directory.templates = config/cells/Cell01/nodes/Node01/servers/Server1/mm/templates, you can locate the custom profile by the Cell01 cell name and the Node01 node name.
   
   
3. Use the name of the cell, node and server to locate the custom profile.
   
   
2. In the custom profile, open the <custom_profile_root>\BusinessSpace\<cluster_name>\mm.runtime.prof\public\oobLoadedStatus.properties file and update the importTemplates.txt or importSpaces.txt properties:
   
   importTemplates.txt=true
   importSpaces.txt=true
   
3. If you have created the Business Space database after it was deleted, or if you need to reload the theme for any other reason, update the following property:
   
   importThemes.txt=true
   
   
6. When all clusters have been successfully upgraded, restart the deployment manager.
   
   
7. For each node, restart the node agent and wait for the node synchronization to complete.
   
   
8. If you have disabled automatic synchronization, ensure that all of your nodes are correctly synchronized before starting the cluster members.
   
   
9. Start all the servers and cluster members, as needed.

Back to top

Identifying profile update errors

If a "The packages are updated with warnings" error message is displayed on the Installation Manager summary panel (GUI installation) or on the command line (silent installation), check the <install_root>/logs/wbi/install.FP7511/installconfig_<product_ID>_profileMaintenance.log file where <product_ID> is the product identifier, for example, "bpmPC".

If it contains the Result of executing [...]BPMProfileMaintenance.ant was: false message, then a profile update error has occurred.

Log files for profile upgrade are saved as <profile_root>/logs/BPMProfileUpgrade.<profile_name>.<timestamp>.log where <profile_root> is the root directory of the managed profile.

If multiple profiles in the installation are being updated, search for the first occurrence of "profileName=" prior to the error to determine which profile is associated with this error.

Fix the cause and then follow the appropriate steps in the Recovering after profile update errors section.

When you upgrade an installation on the Microsoft Windows XP operating system, you must check the installconfig_<product_ID>_profileMaintenance.log file, even if the Installation Manager reported that the packages are updated.

Note: For Network Deployment environments, the most likely cause of an error is that a connection to the deployment manager cannot be established.

Back to top

Recovering after profile update errors

Stand-alone profiles and deployment manager profiles

1. Make sure that the stand-alone application server or the deployment manager is stopped.
   
   
2. Change directories to <install_root> where the profile update error has occurred and run one of the following commands as appropriate for your platform:
   
   On Windows operating systems:
   bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true
   
   On UNIX-based and Linux operating systems:
   bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true
   
   Where <profile_name> is the name of the stand-alone profile or deployment manager profile that had update errors.



Back to top




---

Federated profiles

1. Make sure that the deployment manager has been started. This step is necessary because the BPMProfileUpgrade.ant script must connect to the central configuration repository on the deployment manager to make the updates.
   
   
2. Change directories to <install_root> where the profile update error has occurred and run one of the following commands as appropriate for your platform:
   
   On Windows operating systems:
   bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true -Duser=<AdminuserID> -Dpassword=<Adminpassword>
   
   On UNIX-based and Linux operating systems:
   bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName <profile_name> -Dupgrade=true -Duser=<AdminuserID> -Dpassword=<Adminpassword>
   
   where <profile_name> is the name of the federated profile that had update errors.
   
   If you are updating a federated node when WebSphere administrative security is enabled, you must also supply the “-Duser=<AdminuserID> -Dpassword=<Adminpassword>” parameters, where <userID> is a user ID from the user registry that has administration authority and <Adminpassword> is the password for that user ID.



Back to top




---

Rolling back V7.5.1 Fix Pack 1

You can use the IBM Installation Manager for WebSphere Software to roll back this fix pack.

If you roll back the fix pack, the IBM Installation Manager does not roll back fix pack updates from profiles because you might have configured the profile after installing the maintenance.

Warning: Profiles might not be usable after rolling back the fix pack.

To restore an original profile, use the restoreConfig command to restore your backup.

Before running the restoreConfig command, export any custom enterprise applications that you have installed since you ran the backupConfig command. After you run the restoreConfig command, re-install the exported enterprise applications and redo any other applicable configuration changes that you made since you ran the backupConfig command.

Restore all the databases to the backup that was created prior to upgrading the database. Most databases provide a backup wizard or other user assistance for creating database backups. Contact your database administrator for more information.

Back to top

Additional information

You can find additional information on any of these topics in the IBM Business Process Manager Information Center.

Trademarks and service marks:

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

Back to top