IBM Support

Best practices for using the WpsUpdate.py script with IBM Business Process Manager (BPM) Advanced: Process Server for z/OS V8.0.0

White Papers


Abstract

WpsUpdate.py is a script that you run when you configure an IBM BPM Advanced for z/OS cell. This script is used in Network Deployment topologies to repair inconsistencies in the configuration details of cluster members that are generated by using the Deployment Environment wizard.

Content

Preliminary notes
These best practices apply only to the version of WpsUpdate.py that is distributed with IBM Business Process Manager Advanced for z/OS V8.0.0. The function and usage of the script might vary in other releases.

The WpsUpdate.py script that was originally distributed in IBM Business Process Manager Advanced for z/OS V8.0.0 contains an error that prevents the -bootstrapURL parameter from being correctly validated. A corrected version of the script is provided with APAR PM77221.

WpsUpdate.py is intended to be used only when you initially configure an IBM Business Process Manager Advanced for z/OS cluster. If you want to modify server runtime properties after you have completed the initial configuration of the cluster and have deployed applications to it, follow the Modifying runtime server configuration properties procedures that are documented in the IBM Business Process Manager Information Center. Be aware that you might obtain undesirable results if you try to use the WpsUpdate.py script to adjust configuration settings after the cluster is in use.


WpsUpdate.py parameters
The full set of parameters that you can use with WpsUpdate.py is listed in the Updating the configuration values for cluster members procedure in the IBM Business Process Manager Information Center.

This white paper provides additional information about the behavior of some of these options.


The -ports parameter
The -ports parameter specifies a seed value that is used to calculate and adjust all the port numbers for a cluster member. The algorithm for calculating the port numbers is described in the Updating the configuration values for cluster members procedure in the IBM Business Process Manager Information Center.

When you use the -ports parameter, take note of the following effects on connection factories:

  • Topic connection factories:

  • If you specify the -ports parameter when you run the WpsUpdate.py script, the script replaces the value of the Provider Endpoints property for the following topic connection factories:
    • CommonEventInfrastructure_AllEventsTopicCF
    • PortalNotificationTopicConnectionFactory
    • TWClientConnectionFactory
    • TWClientConnectionFactoryNoTX
    • TaskChangeConnectionFactory
    • TopicConnectionFactory
    • cacheMessageConnectionFactory
    • eventMgrMessageConnectionFactory

    The script sets the Provider Endpoint property to the following string value:
    host_name:secure_SIB_port:BootstrapSecureMessaging,host_name:unsecure_SIB_port:BootstrapBasicMessaging

    In this string, host_name is the server name of the specific cluster member against which the WpsUpdate.py script is being run. When a remote client bootstraps into the service integration bus (SIB) service, the client is provided with this specific cluster member address. If the messaging engine for the requested bus is not active on that cluster member, the bootstrap request fails, even if the messaging engine is active on a different cluster member.

    To prevent a single point of failure, you must manually set the Provider Endpoints property for each connection factory to a value that presents more than one cluster member to client bootstrap requests. You can set the value in either of the following ways:
    • Include the addresses of several cluster members in the Provider Endpoints value. If the messaging engine is active at any of the listed addresses, the bootstrap request succeeds. For example, for a cluster that spans nvba.location.company.com and nvbb.location.company.com, the following Provider Endpoints value is appropriate for a secured transport chain:

    • nvba.location.company.com:12272:BootstrapSecureMessaging, nvbb.location.company.com:12272:BootstrapSecureMessaging
    • Configure the sysplex distributor so that the SIB ports can exploit a distributed virtual IP address, thereby enabling any active cluster member to service a bootstrap request. Using the example in the preceding list item, if the SIB ports are defined to be available on the address sysplexb.location.company.com, the following Provider Endpoints value are appropriate:

    • sysplexb.location.company.com:12272:BootstrapSecureMessaging

    You must update the Provider Endpoints property values by using the administrative console or administration scripting. You cannot use WpsUpdate.py to make this change.
  • Queue connection factories:

  • If you specify the -ports parameter when you run the WpsUpdate.py script, the script does not attempt to change the value of the Provider Endpoints property on any of the queue connection factories. The default port numbers are therefore retained in the Provider Endpoints value.

    To prevent a single point of failure, use the same solution as is described for topic connection factories.
  • Generic connection factories:

  • Generic connection factories are created by the Deployment Environment wizard with no value for the Provider Endpoints property. WpsUpdate.py does not change this setting, so corrections are not required.


The -bootstrapURL parameter
The -bootstrapURL parameter specifies the bootstrap URL, and its value takes the following form:
corbaloc:iiop:host_name:bootstrap_port

The -bootstrapURL value is inserted into the following files:
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/nodes/node_name/servers/server_name/performance-data-warehouse/config/system/50AppServer.xml
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/nodes/node_name/servers/server_name/process-server/config/system/50AppServer.xml

These files are updated for all cluster members in the cluster. Therefore, when you specify the host_name string in the -bootstrapURL value, be sure to use a generic host name that applies to all the members of the cluster; for example, an address that is associated with a dynamic virtual IP address (DVIPA). To enable the sysplex distributor to route requests to available cluster members, specify the bootstrap_port number on a VipaDistribute statement in the TCP definitions.

If you omit -bootstrapURL when you run WpsUpdate.py, the script generates its own value by using the host name and bootstrap port that are extracted from the cluster member name service. As with the SIB bootstrap address, this address is specific to the cluster member against which WpsUpdate.py is being run. Although, the change is still applied to all the cluster members. This approach creates a single point of failure because the cluster member needs to be available on the generated host name to prevent failures from occurring when clients attempt to bootstrap.

To prevent a single point of failure, always specify the -bootstrapURL parameter when you run WpsUpdate.py. For the value, specify a generic host name that is associated with a DVIPA address, and a bootstrap port number that has been defined on a VipaDistribute statement in the TCP definitions. This approach enables client bootstrap requests to be routed to any active cluster member that is running in the sysplex.



Sysplex Distributor
In addition to -bootstrapURL, there are other WpsUpdate.py parameters for which you might want to consider using Sysplex Distributor to spread incoming requests across cluster members.


The -appServerName parameter
The -appServerName parameter takes the form of a host name; for example:
-appServerName sysplexp.location.company.com

The -appServerName value is updated in various places in the following file:
WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/nodes/node_name/servers/server_name/process-server/config/system/99Local.xml

The -appServerName value that you specify is linked with the HTTP port of the cluster member to denote the location of various IBM Business Process Manager applications. The URLs in the 99Local.xml file usually contain the local host name of the cluster member. If you prefer this address to be associated with a DVIPA and have the HTTP port specified on a VipaDistribute statement in the TCP definitions, include the -appServerName parameter when you run WpsUpdate.py.

The -appServerName value is applied only to the cluster member against which WpsUpdate.py is being run. Thus, you must specify the-appServerName parameter (with the same generic host name value) whenever you run WpsUpdate.py against a cluster member.


The -procsvrDBURL parameter
The -procsrvDBURL parameter specifies the Process Center application URL, and its value takes the following form (assuming DB2 for z/OS is being used as the server database):
jdbc:db2:db_host_name:db_port/db_location_name

For example:
-procsrvDBURL jdbc:db2:sysplexp.location.company.com:446/DSNV10PP

The -procsrvDBURL value is updated in the following files:
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/clusters/cluster_name/process-server/config/system/98Database.xml
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/nodes/node_name/servers/server_name/process-server/config/system/98Database.xml

The host name is originally derived from the values entered during the configuration of the cluster, either directly into the administrative console pages or from the referenced database design file. If the host name was originally set to a sysplex value, then further action is not required.

The bootstrapProcessServerData.sh script uses the URL to connect to the IBM Business Process Manager Process Server database during cluster configuration. Because the script is not run on a regular basis, it is not essential to practice high availability by specifying a sysplex host name in the URL; you need only ensure that the referenced DB2 subsystem is available when the script is run. If DB2 is configured in a data sharing group and the DB2 port is configured for Sysplex Distributor, you can use the -procsrvDBURL parameter to set a sysplex host name if required.


The -perfDWDBURL parameter
The -perfDWDBURL parameter specifies the Performance Data Warehouse application URL and its value takes the following form (assuming DB2 for z/OS is being used as the server database):
jdbc:db2:db_host_name:db_port/db_location_name

For example:
-perfDWDBURL jdbc:db2:sysplexp.location.company.com:446/DSNV10PP

The -perfDWDBURL value is updated in the following files:
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/clusters/cluster_name/performance-data-warehouse/config/system/98Database.xml
  • WAS_root/DeploymentManager/profiles/default/config/cells/cell_name/nodes/node_name/servers/server_name/performance-data-warehouse/config/system/98Database.xml

The host name is originally derived from the values entered during the configuration of the cluster, either directly into the administrative console pages or from the referenced database design file. If the host name was originally set to a sysplex value, then further action is not required.

The bootstrapProcessServerData.sh script uses the URL to connect to the IBM Business Process Manager Performance Data Warehouse database during cluster configuration. Because the script is not run on a regular basis, it is not essential to practice high availability by specifying a sysplex host name in the URL; you need only ensure that the referenced DB2 subsystem is available when the script is run. If DB2 is configured in a data sharing group and the DB2 port is configured for Sysplex Distributor, you can use the -perfDWDBURL parameter to set a sysplex host name if required.



Example: Running WpsUpdate.py
This example shows how to run the WpsUpdate.py script to configure each of the cluster members in a cluster. Typically, only a few of the parameters that are available to the script are required. (In the example, each parameter is shown on a separate line to aid readability.)

The example makes the following assumptions:
  • The Installation Manager installation image is located at /was/V8IMbpm4.
  • The Deployment Manager configuration file system is located at /WebSphere/V8T5DM.
  • The cluster is called T5DepEnv.AppTarget.
  • The cluster consists of two cluster members: T5DepEnv.AppTarget.T5NodeMVP0.0 on node T5NodeMVP0 and T5DepEnv.AppTarget.T5NodeMVP1.0 on node T5NodeMVP1.
  • The cluster is configured across two z/OS LPARs: T5NodeMVP0 on mvp0.location.company.com and T5NodeMVP1 on mvp1.location.company.com.
  • Both LPARs are members of a sysplex with a generic host name sysplexp.location.company.com.
  • The seed port number for the two cluster members is 20560. Both cluster members use the same port numbers.
  • The bootstrap port number is 20563.
  • The HTTP and bootstrap ports are both defined on a VipaDistribute parameter in the TCP definitions.
  • It is not a requirement that the database connections for the bootstrapProcessServerData.sh script be configured for high availability (there is no need for database URLs to specify a sysplex host name).

Run the WpsUpdate.py script as follows:
  1. Navigate to the Deployment Manager profile:
    cd /WebSphere/V8T5DM/DeploymentManager/profiles/default/bin
  2. Run the script against cluster member T5DepEnv.AppTarget.T5NodeMVP0.0:
    ./wsadmin.sh
    -conntype NONE
    -f /was/V8IMbpm4/zOS-config/samples/WpsUpdate.py
    -lang jython
    -node T5NodeMVP0
    -server T5DepEnv.AppTarget.T5NodeMVP0.0
    -cluster T5DepEnv.AppTarget
    -ports 20560
    -boostrapURL corbaloc:iiop:sysplexp.location.company.com:20563
    -appServerName sysplexp.location.company.com
  3. Run the script against cluster member T5DepEnv.AppTarget.T5NodeMVP1.0:
    ./wsadmin.sh
    -conntype NONE
    -f /was/V8IMbpm4/zOS-config/samples/WpsUpdate.py
    -lang jython
    -node T5NodeMVP1
    -server T5DepEnv.AppTarget.T5NodeMVP1.0
    -cluster T5DepEnv.AppTarget
    -ports 20560
    -boostrapURL corbaloc:iiop:sysplexp.location.company.com:20563
    -appServerName sysplexp.location.company.com
  4. Fully synchronize both of the nodes.

[{"Product":{"code":"SSFTN5","label":"IBM Business Process Manager Advanced"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Installation \/ Configuration","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"8.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
17 June 2018

UID

swg27036922