IBM Support

Profile upgrade instructions for IBM Business Process Manager Version 8.0.1 Fix Pack 1 (V8.0.1.1)

Product Readmes


Abstract

This document provides the instructions to upgrade existing profiles for the IBM Business Process Manager products to Version 8.0.1 Fix Pack 1 (V8.0.1.1).

Content

IBM Business Process Manager Standard, IBM Business Process Manager Express, and IBM Business Process Manager Advanced are collectively referred to as the IBM Business Process Manager products within this document.




Table of Contents

 


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".


Complete the following steps:

  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. (IBM Business Process Manager Advanced only) Back up the 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 8.0.1 Fix Pack 1 (8.0.1.1):  
    • EverybodyTransformation.xsl  
    • LDAPTransformation.xsl  
    • SystemTransformation.xsl  
    • UserRegistryTransformation.xsl
    • VMMTransformation.xsl


      These files are overwritten during the installation of V8.0.1 Fix Pack 1 (V8.0.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 versions. 

  3. Stop all the Java processes

    Before installing V8.0.1 Fix Pack 1 (V8.0.1.1), stop all Java processes that are associated with the 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 V8.0.1 Fix Pack 1 (V8.0.1.1) when a WebSphere Application Server-related Java process is running. 

  4. (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.
     
 



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 V8.0.1 Fix Pack 1 (V8.0.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 5 of this section.  

  3. Check for any errors as explained in the Identifying Profile Update Errors section before continuing. 

  4. Remove customized Business Process Definition engine queries involving the event manager.


    The following Business Process Definition engine queries have been re-written in V8.0.1 Fix Pack 1 (V8.0.1.1):
    <event-manager> 
     <scheduler>
       <loader-release-sync-queues-query>
       <loader-release-tasks-query>
       <loader-refresh-sync-queues-query>
       <loader-acquire-sync-queue-query>
       <loader-acquire-tasks-query>
       <loader-find-sync-queue-query>
       <loader-find-tasks-query>
       <engine-mark-task-executing-query>
       <engine-bulk-mark-task-executing-query>
       <engine-bulk-load-task-query>
       <engine-next-sync-queue-task-query>
     </scheduler>
    </event-manager>

    If you have customized any of these queries in, for example, the Custom100.xml file, then you must remove your customization before starting the stand-alone application server. For more information, see The 99Local.xml and 100Custom.xml configuration files topic in the information center.

  5. Depending on the platform, run one of the following commands to update the Process Server database:
    • On Microsoft Windows operating systems: profile_root\bin\bootstrapProcessServerData.bat 

    • On UNIX-based and Linux operating systems:
      profile_root/bin/bootstrapProcessServerData.sh
       

      The Business Process Choreographer, Business Space, CommonDB and Messaging Engine databases do not change when you upgrade from IBM Business Process Manager V8.0.1.0 to 8.0.1 Fix Pack 1.

  6. Restart the stand-alone application server. 
  


Steps for upgrading in a network deployment environment

Notes and restrictions when you upgrade in a network deployment environment


When you upgrade from IBM Business Process Manager Version 8.0.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, which the IBM Business Process Manager scripts depend on, see Configuring security with scripting in the WebSphere Application Server Information Center.  

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 V8.0.1 Fix Pack 1 (V8.0.1.1) onto 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 the fix pack installation process.  

  4. Check for any errors, as explained in the Identifying Profile Update Errors section, before continuing. 
 

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 V8.0.1 Fix Pack 1 (V8.0.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 the fix pack installation process.
      Log files are saved as: profile_root/logs/BPMProfileUpgrade.profile_name.time_stamp.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. Remove customized Business Process Definition engine queries involving the event manager.


    The following Business Process Definition engine queries have been re-written in V8.0.1 Fix Pack 1 (V8.0.1.1):     
    <event-manager>    
     <scheduler>   
       <loader-release-sync-queues-query>   
       <loader-release-tasks-query>   
       <loader-refresh-sync-queues-query>  <loader-acquire-sync-queue-query> 
       <loader-acquire-tasks-query>  <loader-find-sync-queue-query> 
       <loader-find-tasks-query>  <engine-mark-task-executing-query> 
       <engine-bulk-mark-task-executing-query>  <engine-bulk-load-task-query> 
       <engine-next-sync-queue-task-query> 
     </scheduler> 
    </event-manager>



    If you have customized any of these queries in, for example, the Custom100.xml file, then you must remove your customizations for each non-clustered server where the Business Process Definition engine is configured before starting the server. For more information, see The 99Local.xml and 100Custom.xml configuration files topic in the information center.

  4. 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:
      dmgr_profile_root\bin\bootstrapProcessServerData.bat -nodeName node_name -serverName server_name

    • On UNIX-based and Linux operating systems:
      dmgr_profile_root/bin/bootstrapProcessServerData.sh -nodeName node_name -serverName server_name 


      where node_name and server_name are the names of the managed node and the non-clustered server


      The Business Process Choreographer, Business Space, CommonDB and Messaging Engine databases do not change when you upgrade from IBM Business Process Manager V8.0.1.0 to 8.0.1 Fix Pack 1.

  5. 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  

  6. If any of the nodes contain cluster members, follow the steps described under Upgrading Clusters before starting the servers. 

  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 your nodes are correctly synchronized before starting the cluster members. 

  9. Start all the servers and cluster members as needed. 
 

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 profile_root/logs/BPMProfileUpgrade.profile_name.cluster_name.timestamp.log file for errors where profile_root is the root directory of the deployment manager profile.


      If there is an error, fix the cause, and then rerun step 3. 

  4. Remove customized Business Process Definition engine queries involving the event manager.


    The following Business Process Definition engine queries have been re-written in V8.0.1 Fix Pack 1 (V8.0.1.1):
    <event-manager> 
     <scheduler>
       <loader-release-sync-queues-query>
       <loader-release-tasks-query>
       <loader-refresh-sync-queues-query>   
       <loader-acquire-sync-queue-query>   
       <loader-acquire-tasks-query>   
       <loader-find-sync-queue-query>   
       <loader-find-tasks-query>   
       <engine-mark-task-executing-query> 
       <engine-bulk-mark-task-executing-query> 
       <engine-bulk-load-task-query>   
       <engine-next-sync-queue-task-query> 
     </scheduler> 
    </event-manager>

    If you have customized any of these queries in, for example, the Custom100.xml file, then you must remove your customization for each cluster where the Business Process Definition engine is configured before starting the cluster members. For more information, see The 99Local.xml and 100Custom.xml configuration files topic in the information center.

  5. 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:
      dmgr_profile_root\bin\bootstrapProcessServerData.bat -clusterName app_cluster_name 
    • On UNIX-based and Linux operating systems:
      dmgr_profile_root/bin/bootstrapProcessServerData.sh -clusterName app_cluster_name

      where app_cluster_name is the name of the application cluster.  

  6. 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 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 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 

  7. When all clusters have been successfully upgraded, restart the deployment manager.

  8. For each node, restart the node agent, and wait for the node synchronization to complete.  

  9. If you have disabled automatic synchronization, ensure that all of your nodes are correctly synchronized before starting the cluster members. 

  10. Start all the servers and cluster members, as needed. 
  


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/bpm/update/installconfig_product_ID_profileMaintenance.log file where product_ID is the product identifier, for example, "Adv.server".


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.
  


Recovering after profile update errorsRecovering after profile update errors


Stand-alone profiles and deployment manager profiles

  1. Make sure the stand-alone application server or the deployment manager is stopped.

  2. Change directories to the install_root directory where the profile update error has occurred and run one of the following commands as appropriate for your platform.
    • On Windows operating systems, run the following command:
      bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName profile_name -Dupgrade=true

    • On UNIX-based and Linux operating systems, run the following command:
      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. 

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, run the following command:
      bin\ws_ant.bat -f util\BPMProfileUpgrade.ant -profileName profile_name -Dupgrade=true


      On UNIX-based and Linux operating systems, run the following command:
      bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName profile_name -Dupgrade=true


      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=user_ID -Dpassword=password parameters, where user_ID is a user ID from the user registry that has administration authority and password is the password for that user ID. 
 


Rolling back V8.0.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.
 


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.

Original Publication Date

15 March 2013

[{"Product":{"code":"SSFTN5","label":"IBM Business Process Manager Advanced"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Installation \/ Configuration","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.0.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTDH","label":"IBM Business Process Manager Standard"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"","label":"Linux zSeries"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.0.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSFTBX","label":"IBM Business Process Manager Express"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Installation \/ Configuration","Platform":[{"code":"PF016","label":"Linux"},{"code":"","label":"Linux zSeries"},{"code":"PF033","label":"Windows"}],"Version":"8.0.1.1","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

BPM

Document Information

Modified date:
17 June 2018

UID

swg27038089