IBM Support

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

Product readme


Abstract

This document provides the instructions to upgrade existing profiles for the IBM Business Process Manager products to Version 8.0.1 Fix Pack 2 from IBM Business Process Manager Versions 8.0.1.0 and later.

Content

Note: For links to a dynamic list of known issues, see the Known issues section.



Table of Contents

 
Important:
  • The Process Center and online Process Server versions must mach exactly, or the two will not be able to connect. If the Process Server version is higher than the Process Center version, the Process Server can be used only in offline mode. For example, if the Process Server moves to V8.0.1 Fix Pack 2, it can no longer be an online Process Server in Process Center if the Process Center is still at V8.0.1 Fix Pack 1. You can deploy new snapshots to the higher-level Process Server by using offline server mode, in which you create a deployment package and install it manually on Process Server.

    If the Process Center version is higher than the Process Server version, you cannot deploy any applications to the Process Server in offline or in online mode. Follow the Steps for performing a rolling upgrade to roll out maintenance incrementally in an IBM Business Process Manager installation that consists of a Process Center and multiple Process Servers.
  • Depending on the source version and topology, instructions for updating the database vary. The product might not continue to run successfully if you do not follow these instructions.
  • Clear the cache in any browsers that are used to access the server. In addition, if you intend to access the server using IBM Process Designer, clear the cache in the default browser.

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.


Steps for upgrading a stand-alone environment (profile)



For each stand-alone profile, 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 configuration files in the product documentation for more information about running this command.

  2. Create backup copies of your existing databases. Database schema and content are changed during the upgrade process. Create a backup copy of the Process Center and Process Server 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. If you are updating IBM Business Process Manager Advanced edition, 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 2 (V8.0.1.2):  
    • EverybodyTransformation.xsl  
    • LDAPTransformation.xsl  
    • SystemTransformation.xsl  
    • UserRegistryTransformation.xsl
    • VMMTransformation.xsl

      These files are overwritten during the installation of V8.0.1 Fix Pack 2 (V8.0.1.2), 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. 

  4. Stop all the Java™ processes.

    Before installing V8.0.1 Fix Pack 2 (V8.0.1.2), stop all of the 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 2 (V8.0.1.2) when a WebSphere Application Server-related Java process is running. 

  5. (For Windows servers only) Stop the WebSphere Windows services.

  6. Install V8.0.1 Fix Pack 2 (V8.0.1.2) 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 8 of this section.  

  7. Check for errors, as explained in Identifying profile update errors, before continuing. 

  8. Database upgrade : Depending on the source version and topology, instructions for updating the database vary. The product might not continue to run successfully if you do not follow the correct instructions.
    • Upgrading from V8.0.0 to V8.0.1 Fix Pack 2

      If you are upgrading from IBM Business Process Manager V8.0.0 to V8.0.1 Fix Pack 2 using a database other than DB2 for z/OS, follow the instructions in this section. If you are using DB2 for z/OS, follow the instructions in Upgrading DB2 for z/OS databases from V8.0.0 to V8.0.1 Fix Pack 2.

      Run the following command on the installation that hosts the deployment manager to generate the SQL scripts that are needed for updating the database schemas:
      Windows install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -upgrade source_version profile_name
      Linux Unix install_root/bin/BPMGenerateUpgradeSchemaScripts.sh -upgrade source_version profile_name

      The source_version variable is the version from which you are upgrading; for example, 8.0.0.0. This value must be specified as four digits separated by periods.

      The profile_name variable is the name of the stand-alone profile.

      If you are prompted for information about your database setup, specify the relevant values for your environment. When prompted, enter Y to confirm that you want to generate the scripts.

      Tip: If you enter incorrect information, you can run the BPMGenerateUpgradeSchemaScripts command again before proceeding. The BPMGenerateUpgradeSchemaScripts command creates or updates the SQL scripts in a profile_root/dbscripts/component_name subdirectory for each product component. The scripts that are generated are used in the steps that follow, as relevant. Logs are also written to the profile_root/upgrade/logs directory.

      Update the Process Server database as follows:
      Run the following command to update the Process Server database:
      Windows BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name
      Linux Unix BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName profile_name 

      The profile_name variable is the name of the stand-alone profile. For more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.

      Note: If the profile that you are upgrading is not the default profile, you might encounter the problem that is documented in APAR JR48842. Install the interim fix or follow the work around that is documented under "Local fix."

      Business Process Choreographer (for Advanced profile only):

      This topic applies only to the IBM Business Process Manager Advanced configuration. If you have configured Business Process Choreographer, you must upgrade the BPEDB database manually to create the SCHEMA_STATUS table.
      1. Change to the directory where the Business Process Choreographer database scripts are generated:
        Windows cd profile_root\dbscripts\ProcessChoreographer\db_type\db_name\schema_name
        Linux Unix cd profile_root/dbscripts/ProcessChoreographer/db_type/db_name/schema_name

        The profile_root variable is the root directory of the deployment manager profile, db_type is the database type, db_name is the database name, and schema_name is the (possibly empty) schema name.
      2. Run the upgradeSchema_SchemaStatus.sql script to create the SCHEMA_STATUS table in the Business Process Choreographer database. If the table already exists, there will be an error that you can ignore.
    • Upgrading from V8.0.1 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2

      If you are upgrading from IBM Business Process Manager V8.0.0 or V8.0.1 Fix Pack 1 without APAR JR46470 installed to V8.0.1 Fix Pack 2, follow the instructions in this section.

      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 are not changed when you upgrade from IBM Business Process Manager V8.0.1.0 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2.



  9. If you are upgrading from IBM Business Process Manager V8.0.0.0, V8.0.1.0, or V8.0.1 Fix Pack 1 without APAR JR46470 installed, remove the customized Business Process Definition engine queries that involve the event manager.

    The following Business Process Definition engine queries were rewritten in V8.0.1 Fix Pack 1 (V8.0.1.1) APAR JR46470:

    <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, for example, in the 100Custom.xml file, you must remove your customization before starting the stand-alone application server. For more information, see The 99Local.xml and 100Custom.xml configuration files in the product documentation.

  10. Optional: To enable the BPD instance deletion performance improvements of APAR JR46456, follow the steps below to update the stored procedures in your Process Server database:
    1. Find the file upgradeSchema_ProcessServer.sql in the following directory:

      On Microsoft Windows operating systems: install_root\dbscripts\ProcessServer\db_type
      On UNIX-based and Linux operating systems: install_root /dbscripts/ProcessServer/db_type

    2. Run the SQL statements between /* START of phase ProcUpgradeTo8012 */ and /* END of phase ProcUpgradeTo8012 */ to update the stored procedures.
      Note: The statement termination character is GO in the upgrade SQL file; replace it as needed.

  11. Restart the stand-alone application server.

  12. If you have a web server such as IBM HTTP Server (IHS) configured in your environment, some Business Space-based applications lose their web server target mappings and virtual host setting during the profile update if these applications are not mapped to the default virtual host default_host. To restore the web server target mappings, complete the following steps:
    1. Open the administrative console and go to Applications > All applications.

    2. For each of the widget applications, BPMAdministrationWidgets_<nodeName>_<serverName>, HumanTaskManagementWidgets_<nodeName>_<serverName>,
      wesbWidget_<nodeName>_<serverName>,
      BusinessRules_<nodeName>_<serverName>,
      BSpaceEAR_<nodeName>_<serverName>,
      BSpaceForms_<nodeName>_<serverName>,
      BSpaceHelp_<nodeName>_<serverName>,
      mm.was_<nodeName>_<serverName>, and
      PageBuilder2_<nodeName>_<serverName>, complete the following steps:
      1. In the All applications list, click the application name.

      2. On the Configuration tab, click the Manage Modules link in the Modules section.

      3. In the Clusters and servers list box, select both the existing deployment target, as listed in the Server column, and the web server deployment target.

      4. In the modules list, click Select All > Apply > OK.

      5. Save the configuration changes.

13. Update the web server plug-in. Some new web modules may have been added to the product applications since the IBM Business Process Manager version you are upgrading from. 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 in IBM Business Process Manager. Web server mappings are updated in the upgrade, and any web server plug-ins might need to be propagated (or generated and propagated). For more information, see the Plug-ins configuration documentation.


Important: Clear the cache in any browsers that are used to access the server. In addition, if you intend to access the server using IBM Process Designer, clear the cache in the default browser.



Steps for upgrading in a network deployment environment (profile)


When you upgrade from IBM Business Process Manager Version V8.0.1.0 or V8.0.1 Fix Pack 1 in a network deployment environment, you must complete some additional steps. Complete the appropriate steps for your environment.


Notes and restrictions when you upgrade in a network deployment 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.
  • If your configuration contains managed nodes 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 update.
  • 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 is displayed twice during the upgrade process and has a default timeout period of one minute. If you miss this prompt, if 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 Identifying profile update errors.

You can also set the user name and password for the SOAP connection in the soap.client.props file, which is located in the custom_profile_root /properties directory, with the appropriate values so that there is no credential prompt window pop-up during the upgrade. For example:

com.ibm.SOAP.securityEnabled=true
com.ibm.SOAP.loginUserid=was_admin_user
com.ibm.SOAP.loginPassword=was_admin_password


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 product documentation.  



Upgrading the deployment manager


To upgrade the deployment manager, complete the following steps:
  1. Back up all existing profiles in the IBM Business Process Manager configuration, including managed nodes that do not share the installation for the deployment 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 configuration files in the product documentation for more information about running this command.

  2. Create backup copies of your existing databases. Database schema and content are changed during the upgrade process. Create a backup copy of the Process Center and Process Server 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. If you are updating IBM Business Process Manager Advanced edition, 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 2 (V8.0.1.2):  
    EverybodyTransformation.xsl
    LDAPTransformation.xsl
    SystemTransformation.xsl
    UserRegistryTransformation.xsl
    VMMTransformation.xsl

    These files are overwritten during the installation of V8.0.1 Fix Pack 2 (V8.0.1.2) 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.

  4. Stop all of the Java processes.  

    Before installing V8.0.1 Fix Pack 2 (V8.0.1.2), stop all of the 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 2 (V8.0.1.2) when a WebSphere Application Server-related Java process is running. 

  5. (For Windows servers only) Stop the WebSphere Windows services.

  6. Install V8.0.1 Fix Pack 2 (V8.0.1.2) onto the deployment manager installation using either IBM Installation Manager or silent installation, as explained in fix pack installation instructions.

    The deployment manager profile is updated automatically 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 deployment management profile. 
    Any managed nodes profiles that are hosted by the same installation as their deployment manager profile are also upgraded at this time, and the logs are saved with the deployment manager logs.

  7. Check for errors, as explained in Identifying profile update errors, 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. In this scenario, the managed node configuration is updated as part of the deployment manager profile and a separate log file is not written.

  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 2 (V8.0.1.2) 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. For details, refer to the security information in Notes and restrictions when you upgrade in a network deployment environment.

      The managed node (profile) is updated automatically during the fix pack installation process, but clusters are not upgraded automatically.
      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 errors, as explained in Identifying profile update errors, before continuing. 
  3. For each node, start the node agent and wait for the node synchronization process to complete.

    If you have disabled automatic synchronization, ensure that all of your nodes are correctly synchronized before continuing by initiating a full synchronization. See File synchronization service settings in the WebSphere Application Server product documentation.



Upgrading clusters


After upgrading the deployment manager and the managed nodes, including any non-clustered managed servers (see the next section), complete the following 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 the install_root directory.

  3. Depending on the platform, run one of the following commands for each cluster:
    On Windows operating systems:

    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 deployment manager profile and cluster_name is the name of the cluster in the deployment environment.
    For example : If you have a three-cluster environment, run the command three times by changing the cluster name:
    bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName Dmgr01 -Dupgrade=true -Dcluster=TestDE.AppTarget
    bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName Dmgr01 -Dupgrade=true -Dcluster=TestDE.Messaging
    bin/ws_ant.sh -f util/BPMProfileUpgrade.ant -profileName Dmgr01 -Dupgrade=true -Dcluster=TestDE.Support

    Check the profile_root/logs/BPMProfileUpgrade.profile_name.cluster_name.timestamp.log file for errors, where profile_rootis the root directory of the deployment manager profile.

    If there is an error, fix the cause and rerun step 3. You can run this command multiple times.

  4. If you are upgrading from IBM Business Process Manager V8.0.0.0, V8.0.1.0, or V8.0.1.1 without APAR JR46470 installed, remove the customized Business Process Definition engine queries that involve the event manager.

    The following Business Process Definition engine queries were rewritten in V8.0.1 Fix Pack 1 (V8.0.1.1) APAR JR46470:

    <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, for example, in the 100Custom.xml file, 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 in the product documentation.

  5. Database upgrade : Depending on the source version and topology, instructions for updating the database vary. The product might not continue to run successfully if you do not follow the correct instructions.
    • Upgrading from V8.0.0 to V8.0.1 Fix Pack 2

      If you are upgrading from IBM Business Process Manager V8.0.0 to V8.0.1 Fix Pack 2 using a database other than DB2 for z/OS, follow the instructions in this section. If you are using DB2 for z/OS, follow the instructions in Upgrading DB2 for z/OS databases from V8.0.0 to V8.0.1 Fix Pack 2.

      Run the following command on the installation that hosts the deployment manager to generate the SQL scripts that are needed for updating the database schemas:
      Windows install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -upgrade source_version profile_name
      Linux Unix install_root/bin/BPMGenerateUpgradeSchemaScripts.sh -upgrade source_version profile_name

      The source_version variable is the version from which you are upgrading; for example, 8.0.0.0. This value must be specified as four digits separated by periods.
      The profile_name variable is the name of the deployment manager profile.

      If you are prompted for information about your database setup, specify the relevant values for your environment. When prompted, enter Y to confirm that you want to generate the scripts.

      Tip: If you enter incorrect information, you can run the BPMGenerateUpgradeSchemaScripts command again before proceeding. The BPMGenerateUpgradeSchemaScripts command creates or updates the SQL scripts in a profile_root/dbscripts/component_name subdirectory for each product component. The scripts that are generated are used in the steps that follow, as relevant. Logs are also written to profile_root/upgrade/logs.

      Update the Process Server database as follows:
      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:

      Run the following command on the installation that hosts the deployment manager:
      Windows BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name -nodeName node_name -serverName server_name
      Linux Unix BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName profile_name -nodeName node_name -serverName server_name

      The profile_name variable is the name of the deployment manager profile, the server_name variable is the name of any cluster member where Business Process Definition Engine is configured (this is generally referred as the Application Cluster member), and the node_name variable is the name of the node where the cluster member is hosted. This command should be run only once per database, irrespective of the number of cluster members.

      If Performance Data Warehouse is configured on a different cluster, for example, when you are using one of the "Remote Support" topology patterns, you must also supply the -perfServerName  <pdw_server-name> and -perfNodeName <pdw_node_name> parameters, where the <pdw_server-name> variable is the name of any Performance Data Warehouse cluster member, and the <pdw_node_name> variable is the name of the node where the cluster member is hosted. For example:
      upgradeProcessData.sh -profileName MyDMgr1  -nodeName TestNode1 -serverName  TestEnv.AppTarget.TestNode1.0 -perfNodeName TestNode1 -perfServerName TestEnv.Support.TestNode1.0 

      For more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.

      Note: If the profile you are upgrading is not the default profile, you might encounter the problem that is documented in APAR JR48842. Install the interim fix or follow the work around documented under "Local fix."

      Business Process Choreographer (for Advanced profile only):

      This topic applies only to the IBM Business Process Manager Advanced configuration. If you have configured Business Process Choreographer, you must upgrade the BPEDB database manually to create the SCHEMA_STATUS table.
      1. Change to the directory where the Business Process Choreographer database scripts are generated:
        Windows  cd profile_root\dbscripts\ProcessChoreographer\db_type\db_name\schema_name
        Linux Unix cd profile_root/dbscripts/ProcessChoreographer/db_type/db_name/schema_name

        The profile_root varaible is the root directory of the deployment manager profile, db_type is the database type, db_name is the database name, and schema_name is the (possibly empty) schema name.
      2. Run the upgradeSchema_SchemaStatus.sql script to create the SCHEMA_STATUS table in the Business Process Choreographer database. If the table already exists, there will be an error that you can ignore.
    • Upgrading from V8.0.1 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2 :

      If you are upgrading from IBM Business Process Manager V8.0.1 or V8.0.1 Fix Pack 1 (8.0.1.1) to V8.0.1 Fix Pack 2, follow the instructions in this section.

      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_nameis the name of the application cluster.

      The Business Process Choreographer, Business Space, CommonDB, and Messaging Engine databases are not changed when you upgrade from IBM Business Process Manager V8.0.1.0 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2.

  6. Optional: To enable the BPD instance deletion performance improvements of APAR JR46456, complete the following steps to update the stored procedures in your Process Server database:
    1. Find the file upgradeSchema_ProcessServer.sql in the following directory:
      On Microsoft Windows operating systems: install_root\dbscripts\ProcessServer\db_type
      On UNIX-based and Linux operating systems: install_root /dbscripts/ProcessServer/db_type

    2. Run the SQL statements between /* START of phase ProcUpgradeTo8012 */ and /* END of phase ProcUpgradeTo8012 */ to update the stored procedures.

      Note: The statement termination character is GO in the upgrade SQL file; replace it as needed.

  7. Optional: Upgrade the Business Space templates and spaces.
    Property values in the oobLoadedStatus.properties file will determine whether the Business Space templates and spaces will be updated to the new version in the Business Space database during the cluster member startup.

    Identify the custom profile for the oobLoadedStatus.properties file.
    You will find the oobLoadedStatus.properties file under custom_profile(node) where Business Space is configured for the cluster. For example, in a four-cluster deployment environment, Business Space is configured on the web cluster.

    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
     
    If you need to reload the theme for any other reason, you can update the following property:
    importThemes.txt=true

    Next time you start the cluster member, the Business Space database will be updated and the above flags will be changed automatically to false.

    Note:  For the existing environment, the values for the above properties will be false. If you do not want to change your customization, you can leave them set to false. 

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

  9. If you have a four-cluster topology, move the IBM_BPM_Process_Portal_Notification application from the WebApp cluster to the AppTarget cluster, or the collaboration function that is implemented within the application does not properly initialize when a coach is loaded. Complete the following steps:
    1. Open the administrative console on the deployment manager and go to Applications > Application Types > WebSphere enterprise applications.

    2. Click IBM_BPM_Process_Portal_Notification_<webClusterName>, where <webClusterName> is the name of the Web cluster in the deployment environment.

    3. On the Configuration tab, click the Manage Modules link in the Modules section.

    4. In the Clusters and servers list box, select the name of the application cluster in the deployment environment.

    5. In the modules list, click Select All > Apply > OK.

    6. Save the configuration changes.

  10. If you have a web server such as IBM HTTP Server (IHS) configured in your environment, some Business Space-based applications lose their web server target mappings and virtual host setting during the profile update if these applications are not mapped to the default virtual host default_host. To restore the web server target mappings, complete the following steps:
    1. Open the administrative console on the deployment manager and go to Applications > All applications.

    2. For each of the widget applications, BPMAdministrationWidgets_<appClusterName>, HumanTaskManagementWidgets_<appClusterName>, wesbWidget_<appClusterName>, BusinessRules_<appClusterName>, BSpaceEAR_<appClusterName>, BSpaceForms_<appClusterName>, BSpaceHelp_<appClusterName>, mm.was_<appClusterName>, and
      PageBuilder2_<appClusterName>, complete the following steps:
      1. In the All applications list, click the application name.

      2. On the Configuration tab, click the Manage Modules link in the Modules section.

      3. In the Clusters and servers list box, select both the existing deployment target (as listed in the Server column) and the Web server deployment target.

      4. In the modules list, click Select All > Apply > OK.

      5. Save the configuration changes.

  11. Update the web server plug-in. Some new web modules may have been added to the product applications since the IBM Business Process Manager version you are upgrading from. 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 in IBM Business Process Manager. Web server mappings are updated in the upgrade, and any web server plug-ins might need to be propagated (or generated and propagated). For more information, see the Plug-ins configuration documentation.

  12. For each node, restart the node agent and wait for the node synchronization to complete.
    If you have disabled automatic synchronization, ensure that all of your nodes are correctly synchronized before continuing by initiating a full synchronization. See File synchronization service settings in the WebSphere Application Server product documentation.

  13. Start all the non-clustered managed servers and cluster members. If you are working with a deployment environment, starting the deployment environment starts all the cluster members in the correct sequence.



Upgrading non-clustered managed servers



IBM Business Process Manager deployment environments do not create non-clustered managed servers. This is not a common configuration; if you did not manually create any non-clustered managed servers in your configuration, skip this section.

To upgrade non-clustered managed servers, complete the following steps:

  1. If you are upgrading from IBM Business Process Manager V8.0.0.0, V8.0.1.0, or V8.0.1 Fix Pack 1 without APAR JR46470 installed, remove the customized Business Process Definition engine queries that involve the event manager.

    The following Business Process Definition engine queries were rewritten in V8.0.1 Fix Pack 1 (V8.0.1.1) APAR JR46470:

    <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, for example, in the 100Custom.xml file, 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 in the product documentation.

  2. Database upgrade : Depending on the source version and topology, instructions for updating the database vary. The product might not continue to run successfully if you do not follow the correct instructions.
    • Upgrading from V8.0.0 to V8.0.1 Fix Pack 2

      If you are upgrading from IBM Business Process Manager V8.0.0 to V8.0.1 Fix Pack 2 using a database other than DB2 for z/OS, follow the instructions in this section. If you are using DB2 for z/OS, follow the instructions in Upgrading DB2 for z/OS databases from V8.0.0 to V8.0.1 Fix Pack 2.

      Run the following command on the installation that hosts the deployment manager to generate the SQL scripts that are needed for updating the database schemas:
      Windows install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -upgrade source_version profile_name

      Linux Unix install_root/bin/BPMGenerateUpgradeSchemaScripts.sh -upgrade source_version profile_name

      The source_version variable is the version from which you are upgrading; for example, 8.0.0.0. This value must be specified as four digits separated by periods.
      The profile_name variable is the name of the deployment manager profile.

      If you are prompted for information about your database setup, specify the relevant values for your environment. When prompted, enter Y to confirm that you want to generate the scripts.

      Tip: If you enter incorrect information, you can run the BPMGenerateUpgradeSchemaScripts command again before proceeding. The BPMGenerateUpgradeSchemaScripts command creates or updates the SQL scripts in a profile_root/dbscripts/component_name subdirectory for each product component. The scripts that are generated are used in the steps that follow, as relevant. Logs are also written to profile_root/upgrade/logs directory.

      Update the Process Server database as follows:
      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:

      Run the following command on the installation that hosts the deployment manager:
      Windows BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name -nodeName node_name -serverName server_name
      Linux Unix BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName profile_name -nodeName node_name -serverName server_name
      where the profile_name variable is the name of the deployment manager profile, the server_name variable is the name of the non-clustered managed server, and the node_name variable is the name of the node where the server is hosted.
      For example:
      upgradeProcessData.sh -profileName MyDMgr1  -nodeName TestNode1 -serverName  TestEnv.AppTarget.TestNode1.0

      For more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.

      Note: If the profile that you are upgrading is not the default profile, you might encounter the problem documented in APAR JR48842. Install the interim fix or follow the work around that is documented under "Local fix."

      Business Process Choreographer (for Advanced profile only):

      This topic applies only to the IBM Business Process Manager Advanced configuration.If you have configured Business Process Choreographer, you must upgrade the BPEDB database manually to create the SCHEMA_STATUS table.
      1. Change to the directory where the Business Process Choreographer database scripts are generated:
        Windows cd profile_root\dbscripts\ProcessChoreographer\db_type\db_name\schema_name
        Linux Unix cd profile_root/dbscripts/ProcessChoreographer/db_type/db_name/schema_name

        The profile_root variable is the root directory of the deployment manager profile, db_type is the database type, db_name is the database name, and schema_name is the (possibly empty) schema name.
      2. Run the upgradeSchema_SchemaStatus.sql script to create the SCHEMA_STATUS table in the Business Process Choreographer database. If the table already exists, there will be an error that you can ignore.
    • Upgrading from V8.0.1 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2

      If you are upgrading from IBM Business Process Manager V8.0.1 or V8.0.1 Fix Pack 1 (8.0.1.1) to V8.0.1 Fix Pack 2, follow the instructions in this section.

      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 are not changed when you upgrade from IBM Business Process Manager V8.0.1.0 or V8.0.1 Fix Pack 1 to V8.0.1 Fix Pack 2.

  3. Optional: To enable the BPD instance deletion performance improvements of APAR JR46456, follow the steps below to update the stored procedures in your Process Server database:
    1. Find the file upgradeSchema_ProcessServer.sql in the following directory:


      On Microsoft Windows operating systems: was_home\dbscripts\ProcessServer\db_type
      On UNIX-based and Linux operating systems: was_home/dbscripts/ProcessServer/db_type

    2. Run the SQL statements between /* START of phase ProcUpgradeTo8012 */ and /* END of phase ProcUpgradeTo8012 */ to update the stored procedures.
      Note: The statement termination character is GO in the upgrade SQL file; replace it as needed.

  4. Optional: Upgrade the Business Space templates and spaces. Property values in the oobLoadedStatus.properties file will determine whether the Business Space templates and spaces will be updated to the new version in the Business Space database during the managed server startup.

    Identify the custom profile for the oobLoadedStatus.properties file. You will find the oobLoadedStatus.properties file under custom_profile(node) where Business Space is configured for the managed server.

    In the custom profile, open the custom_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

    If you need to reload the theme for any other reason, you can update the following property:
    importThemes.txt=true

    Next time you start the managed server, the Business Space database will be updated and the above flags will be changed automatically to false.

    Note: For the existing environment, the values for the above properties will be false. If you do not want to change your customization, you can leave them set to false.

  5. If you have a web server such as IBM HTTP Server (IHS) configured in your environment, some Business Space-based applications lose their web server target mappings and virtual host setting during the profile update if these applications are not mapped to the default virtual host default_host. To restore the web server target mappings, complete the following steps:
    1. Open the administrative console on the deployment manager and go to Applications > All applications.

    2. For each of the widget applications, BPMAdministrationWidgets_<nodeName>_<serverName>, HumanTaskManagementWidgets_<nodeName>_<serverName>, wesbWidget_<nodeName>_<serverName>, BusinessRules_<nodeName>_<serverName>, BSpaceEAR_<nodeName>_<serverName>, BSpaceForms_<nodeName>_<serverName>,
      BSpaceHelp_<nodeName>_<serverName>,
      mm.was_<nodeName>_<serverName>, and
      PageBuilder2_<nodeName>_<serverName>, complete the following steps:
      1. In the All applications list, click the application name.

      2. On the Configuration tab, click the Manage Modules link in the Modules section.

      3. In the Clusters and servers list box, select both the existing deployment target (as listed in the Server column) and the Web server deployment target.

      4. In the modules list, click Select All > Apply > OK.

      5. Save the configuration changes.

  6. Update the web server plug-in. Some new web modules may have been added to the product applications since the IBM Business Process Manager version you are upgrading from. 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 in IBM Business Process Manager. Web server mappings are updated in the upgrade, and any web server plug-ins might need to be propagated (or generated and propagated). For more information, see the Plug-ins configuration documentation.

  7. For each node, start the node agent and wait for the node synchronization to complete.
    If you have disabled automatic synchronization, ensure that all your nodes are correctly synchronized before continuing by initiating a full synchronization. See File synchronization service settings in the WebSphere Application Server product documentation.


Important: Clear the cache in any browsers that are used to access the server. In addition, if you intend to access the server using IBM Process Designer, clear the cache in the default browser.

Upgrading DB2 for z/OS databases from V8.0.0 to V8.0.1 Fix Pack 2



If you are using DB2® on z/OS, you must manually alter a set of table spaces and upgrade the database schema before you upgrade the database data:
  1. To ensure that you can successfully run the SQL files for the DB2 for z/OS schema upgrade, alter the following table spaces to increase the buffer pool size to 8K:
    WLPT36
    WLPT44
    WLPT64
    For information about altering table spaces, see Altering table spaces (DB2 for z/OS V10) in the DB2 Information Center.

  2. From the install_root/profiles/profile_name/dbscripts/ProcessServer/DB2zOS/database_name directory, copy the script named upgradeSchema800_ProcessServer.sql to your working directory.

    Review the script, and, if necessary, edit the file to replace the following symbolic variables with the actual values for the schema name, database name, storage group, and buffer pool for large objects and tables: @SCHEMA@, @DB_NAME@, @STOGRP@, @BPLOB4K@, @BPTABLE4K@, and @BPTABLE8K@. Then connect to the DB2 for z/OS database, and run the script against the database by using your preferred tool.

  3. From the install_root/profiles/profile_name/dbscripts/PerformanceDW/DB2zOS/database_name directory, copy the script named upgradeSchema800_PerformanceDW.sql to your working directory.

    Review the script, and, if necessary, edit the file to replace the following symbolic variables with the actual values for the schema name, database name, storage group, and buffer pool for large objects and tables: @SCHEMA@, @DB_NAME@, @STOGRP@, @BPLOB4K@, @BPTABLE4K@, and @BPTABLE8K@. Then connect to the DB2 for z/OS database, and run the script against the database by using your preferred tool.

  4. Go to the install_root/BPM/Lombardi/tools/upgrade/UpgradeProcessData directory and set the database.is.db2zos property to true in the upgrade.properties file. For example:
    database.is.db2zos=true

  5. Run the following command to update the Process Server database:

    • On Windows operating systems: BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name

    • On UNIX-based and Linux operating systems:
      BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName profile_name

    where profile_nameis either the name of the stand-alone profile or the name of the deployment manager profile, depending on your environment. For more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.

Identifying profile update errors




If the error message " The packages are updated with warnings" 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 message Result of executing [...]BPMProfileMaintenance.ant was: false , a profile update error has occurred.

Log files for profile upgrade are saved as profile_roo t/ 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 problem and then follow the appropriate steps in Recovering after profile update errors.

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


Identifying and recovering from bootstrap errors



The log files for bootstrapProcessServerData actions are saved in the < profile_root >/logs directory, where profile_rootis the root directory of the profile, with the name bootstrapProcesServerData_ <timestamp > .log file. You can consult this log file for any error or exception, and you can also check the wsadmin.trace file under the same directory for further details.

The new version of system applications such as System Data toolkit and Process Portal might already have been imported into the database by the bootstrapProcessServerData command. You must manually uninstall these snapshots if you want to roll them back to IBM Business Process Manager V8.0.1.


Rolling back V8.0.1 Fix Pack 2 (8.0.1.2)




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.

Complete the following steps:
  1. Export any custom enterprise applications that you have installed since you ran the backupConfig command.

  2. Shut down all of the Java virtual machines (JVM) that are associated with the environment including the Development Manager, node agents, cluster members for a network deployment environment or the stand alone server for a stand alone profile.

  3. Run the restoreConfig command.

  4. Manually restore the relevant database to its state prior to the upgrade using the tools that are provided by the appropriate database vendor.
    Note
    : The fix pack rollback process does not restore the database changes that were made during the upgrade process.

  5. Reinstall 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 product documentation.

Trademarks and service marks




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

Original publication date

2013/11/1

Cross reference information
Segment Product Component Platform Version Edition
Business Integration IBM Business Process Manager Standard Installation / Configuration AIX, Linux, Linux zSeries, Solaris, Windows 8.0.1.2
Business Integration IBM Business Process Manager Express Installation / Configuration Linux, Linux zSeries, Windows 8.0.1.2

Product Alias/Synonym

BPM

Document information

More support for: IBM Business Process Manager Advanced
Installation / Configuration

Software version: 8.0.1.2

Operating system(s): AIX, Linux, Solaris, Windows

Reference #: 7039082

Modified date: 31 October 2013