IBM Support

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

Product Readmes


Abstract

This document provides the instructions to upgrade existing Process Center or Process Server profiles for the IBM Business Process Manager products to Version 8.0.1 Fix Pack 3 from IBM Business Process Manager Versions 8.0.0.0 and later.

Content


Table of Contents  
Important:
  • The Process Center and online Process Server versions must match 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 3, it can no longer be an online Process Server in Process Center if the Process Center is still at V8.0.1 Fix Pack 2. You can deploy new snapshots to the higher-level Process Server by using an 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.

  • 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 3 (V8.0.1.3):  


    EverybodyTransformation.xsl

    LDAPTransformation.xsl
    SystemTransformation.xsl
    UserRegistryTransformation.xsl
    VMMTransformation.xsl


    These files are overwritten during the installation of V8.0.1 Fix Pack 3 (V8.0.1.3) 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 3 (V8.0.1.3), stop all Java processes that are associated with the Java SDK, which is shipped with the IBM Business Process Manager products. These processes include the stand-alone server 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 3 (V8.0.1.3) 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 3 (V8.0.1.3) 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:


    - Follow the instructions in Upgrading DB2 for z/OS databases to V8.0.1 Fix Pack 3 if you are upgrading IBM Business Process Manager using DB2 for z/OS.


    - Follow the instructions below if you are upgrading from IBM Business Process Manager using a database other than DB2 for z/OS.

    1. Generate the database upgrade SQL scripts:
      Run the following command on the installation of the stand-alone server 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


      Where:
      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 the 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.


    2. Complete the Process Server database upgrade:
      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.
      The logs are saved under the install_root/profiles/PROFILE_NAME/logs . See Identifying and recovering from bootstrap errors for any errors.

    3. Business Process Choreographer (for Advanced profiles that were upgraded from V8.0.0.0 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 stand-alone profile, the db_type variable is the database type, the db_name variable is the database name, and the schema_name variable 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.


  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. Restart the stand-alone application server.

  11. 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, which is default_host.


    To restore the web server target mappings, complete the following steps:
    a. Open the administrative console and go to Applications > All applications.


    b. 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:
    i. In the All applications list, click the application name.


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


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


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


    v. Save the configuration changes.


    To restore the virtual host setting, complete the following steps:
    a. Open the administrative console and go to Applications > All applications.


    b. 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:
    i. In the All applications list, click the application name.


    ii. On the Configuration tab, click the Virtual Hosts link in the Web Module Properties section.


    iii. In the web modules list, click Select All.


    iv. Expand the Apply Multiple Mappings section, select the correct virtual host in the Virtual Host dropdown list, and click Apply > OK.


    v. Save the configuration changes.

  12. 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 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 that 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 3 (V8.0.1.3):  
    EverybodyTransformation.xsl
    LDAPTransformation.xsl
    SystemTransformation.xsl
    UserRegistryTransformation.xsl
    VMMTransformation.xsl


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

    The profile_name variable is the deployment manager profile and the cluster_name variable 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.


    Note: You must redo context root customization for each deployment environment in which you customized the context root in the source environment. For information about how to customize the context root prefix, see BPMConfig command-line utility in the product documentation.

  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.


    - Follow the instructions in Upgrading DB2 for z/OS databases to V8.0.1 Fix Pack 3 if you are upgrading IBM Business Process Manager using DB2 for z/OS.


    - Follow the instructions below if you are upgrading from IBM Business Process Manager using a database other than DB2 for z/OS.

    1. Generate database upgrade SQL scripts.

      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:

      install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -upgrade source_version profile_name
      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. This 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.


    2. Complete the Process Server database upgrade for all fix pack versions ( 8.0.0 or 8.0.1.x to 8.0.1.3)
      Depending on the platform, run one of the following commands to update the Process Server database for each IBM Business Process Manager deployment environment: This command should be run only once per database, irrespective of the number of cluster members.

      * For a single-cluster environment:
           Run the following command on the installation that hosts the deployment manager:

           BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name -nodeName node_name -serverName server_name
           BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName
      profile_name -nodeName node_name -serverName server_name

          Example:
            upgradeProcessData.sh -profileName MyDMgr1  -nodeName TestNode1 -serverName  TestEnv.AppTarget.0

      Where 
      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 to as the application cluster member).
      The node_name variable is the name of the node where the cluster member is hosted.

      * For an environment with 3 or more clusters:

      Run the following command on the installation that hosts the deployment manager:

           BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat
      -profileName MyDMgr1  -nodeName
      TestNode1 -serverName  TestEnv.AppTarget.TestNode1.0    -perfNodeName TestNode1 -perfServerName TestEnv.Support.TestNode1.0

      In an environment with 3 or more clusters, when the Performance Data Warehouse is configured on a different cluster (for example, when you are using one of the "Remote Support" topology patterns), you must additionally 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 more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.
      The logs are saved under the install_root/profiles/PROFILE_NAME/logs directory. See Identifying and recovering from bootstrap errors for any errors.


    3. Business Process Choreographer (for Advanced profiles that were upgraded from V8.0.0.0 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.
    • 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 stand-alone profile, the db_type variable is the database type, the db_name variable is the database name, and the schema_name variable is the (possibly empty) schema name.

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




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

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

  8. 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, which is default_host.


    To restore the web server target mappings, complete the following steps:
    a. Open the administrative console on the deployment manager and go to Applications > All applications.


    b. 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:
    i. In the All applications list, click the application name.


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


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


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


    v. Save the configuration changes.


    To restore the virtual host setting, complete the following steps:
    a. Open the administrative console on the deployment manager and go to Applications > All applications.


    b. 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:


    i. In the All applications list, click the application name.


    ii. On the Configuration tab, click the Virtual Hosts link in the Web Module Properties section.


    iii. In the web modules list, click Select All.


    iv. Expand the Apply Multiple Mappings section, select the correct virtual host in the Virtual Host dropdown list, and click Apply > OK.


    v. Save the configuration changes.

  9. If you chose the three-cluster "Remote Messaging and Remote Support" pattern or the four-cluster "Remote Messaging, Remote Support, and Web" pattern for the deployment environment, then you must now move the IBM_BPM_Process_Portal_Notification_<clusterName> application from the support cluster to the application cluster. Complete the following steps:
    1. Open the administrative console on the deployment manager and go to Applications > Application Types > WebSphere enterprise applications.

    2. For a "Remote Messaging and Remote Support" deployment environment, click IBM_BPM_Process_Portal_Notification_<supportClusterName>, where <supportClusterName> is the name of the support cluster in the deployment environment. For a "Remote Messaging, Remote Support, and Web" deployment environment, 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. 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.

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

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


    - Follow the instructions in Upgrading DB2 for z/OS databases to V8.0.1 Fix Pack 3 if you are upgrading IBM Business Process Manager using DB2 for z/OS.


    - Follow the instructions below if you are upgrading from IBM Business Process Manager using a database other than DB2 for z/OS.

    1. Generate database upgrade SQL scripts.

      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:

      install_root\bin\BPMGenerateUpgradeSchemaScripts.bat -upgrade source_version profile_name
      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. This 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.


    2. Complete the Process Server database upgrade for all fix pack versions ( 8.0.0 or 8.0.1.x to 8.0.1.3)
      Depending on the platform, run one of the following commands to update the Process Server database.  Run the following command on the installation that hosts the deployment manager:

           BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat -profileName profile_name -nodeName node_name -serverName server_name
           BPM/Lombardi/tools/upgrade/UpgradeProcessData/upgradeProcessData.sh -profileName
      profile_name -nodeName node_name -serverName server_name

          Example:
            upgradeProcessData.sh -profileName MyDMgr1  -nodeName TestNode1 -serverName  processServer1

      Where 
      The profile_name variable is the name of the deployment manager profile.
      The server_name variable is the name of server where Business Process Definition Engine is configured .
      The node_name variable is the name of the node where the cluster member is hosted.

      * For an environment with Process Server and PDW components are hosted by different server.

      Run the following command on the installation that hosts the deployment manager:

           BPM\Lombardi\tools\upgrade\UpgradeProcessData\upgradeProcessData.bat
      -profileName MyDMgr1  -nodeName TestNode1 -serverName  AppTarget.TestNode1.0    -perfNodeName TestNode1
       -perfServerName PDW.TestNode1.0

      For more information about the parameters that you can use with the upgradeProcessData command, see upgradeProcessData command-line utility.
      The logs are saved under the install_root/profiles/PROFILE_NAME/logs directory. See Identifying and recovering from bootstrap errors for any errors.


    3. Business Process Choreographer (for Advanced profiles that were upgraded from V8.0.0.0 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.
    • 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 stand-alone profile, the db_type variable is the database type, the db_name variable is the database name, and the schema_name variable is the (possibly empty) schema name.

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


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

  4. 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, which is default_host. To restore the web server target mappings, complete the following steps:
    a. Open the administrative console on the deployment manager and go to Applications > All applications.


    b. 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:
    i. In the All applications list, click the application name.


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


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


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


    v. Save the configuration changes.


    To restore the virtual host setting, complete the following steps:
    a. Open the administrative console on the deployment manager and go to Applications > All applications.


    b. 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:
    i. In the All applications list, click the application name.


    ii. On the Configuration tab, click the Virtual Hosts link in the Web Module Properties section.
    iii. In the web modules list, click Select All.
    iv. Expand the Apply Multiple Mappings section, select the correct virtual host in the Virtual Host dropdown list, and click Apply > OK.

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

  6. 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 or V8.0.1.x to V8.0.1 Fix Pack 3



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. Alter the following table spaces to increase the buffer pool size to 8K to ensure that you can successfully run the SQL files for the DB2 for z/OS schema upgrade:
    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.

    1. 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@.
    2. 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.

    1. 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@.
    2. 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
      The profile_name variable is 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 the product_IDvariable 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_root/logs/BPMProfileUpgrade.profile_name.timestamp.log, where the profile_root variable 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.


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


      The profile_name variable 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


      The profile_name variable 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 the profile_root variable is 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.


If the latest bootstrapProcesServerData_<new_timestamp>.log file is missing, the bootstrap might not be completed successfully. Please check if you have followed all database upgrade steps carefully.


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 the previous version of IBM Business Process Manager.


Rolling back V8.0.1 Fix Pack 3 (8.0.1.3)




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. Use the IBM Installation Manager for WebSphere Software to roll back the product binaries to the previous level.

  4. Run the restoreConfig command to restore the profile backup taken before installing 8.0.1.3.

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

  6. Install the exported enterprise applications from Step 1, 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

16 August 2014

[{"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.3","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":"Installation \/ Configuration","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.3","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":"PF033","label":"Windows"}],"Version":"8.0.1.3","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Product Synonym

BPM

Document Information

Modified date:
17 June 2018

UID

swg27042246