Contents


Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Part 9: Workload Management policy integration

Comments

Content series:

This content is part # of # in the series: Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Stay tuned for additional content in this series.

This content is part of the series:Integrating IBM Integration Bus with WebSphere Service Registry and Repository

Stay tuned for additional content in this series.

IBM Integration Bus version 9.0 introduced the ability to control the rate of processing within a message flow by attaching WLM policies to the flow. After a WLM policy is attached to a message flow, IBM Integration Bus modifies its behavior to ensure that it complies with the policy. This can be performed dynamically at runtime, enabling policies to be attached to and detached from message flows without restarting the execution group or the individual flows.

WSRR is a central point of reference for service metadata in your SOA, and is a key part of a successful SOA implementation. The service metadata that can be registered or stored in WSRR includes service definition documents such as WSDL, XSD and policy documents. By using WSRR to centrally manage and govern policies, as well as services, you can ensure that policies are applied consistently across your SOA.

This article describes a sample message flow that uses JMS Input nodes to listen to policy related events from WSRR. It responds to these events by automatically synchronizing those policies with IBM Integration Bus, including attaching them to message flows in response to WLM policies being attached to services in WSRR. The message flow also makes use of an HTTP Request node to invoke the WSRR REST API to retrieve the WLM policies from WSRR. To demonstrate this flow working, this article also describes how to use the new WLM policy authoring capabilities that have been introduced in WSRR V8.5 to allow you to author IBM Integration Bus WLM policies directly in the Service Registry Dashboard.

Policy Enforcement Business Scenario

The sample flow that is described within this article focuses on the policy enforcement scenario that was described in Part 1: Scenarios and configuration, as follows:

  • Business Problem

    You have service enabled a number of existing applications on legacy systems to make them available in new environments. However, these applications are still accessed through other channels such as native interfaces and messaging applications through WebSphere MQ. In order to ensure that existing consumers of these applications are not adversely impacted by requests coming in over the web service interface, you want to specify a limit on the volume of traffic that can be handled over this interface.

  • Solution

    IBM Integration Bus allows you to control the rate of processing within a message flow by attaching WLM policies to the flow. WLM policies enable you to increase, decrease or simply monitor the rate at which a message flow processes messages. A single WLM policy can be attached to multiple message flows. A WLM policy can also be updated at runtime and does not require any message flows to be restarted in order for the changes to take effect.

    IBM Integration Bus WLM policies are defined using WS-Policy, allowing them to be loaded and centrally managed in WSRR along with other types of WS-Policy that you use in your SOA. By registering your flows in WSRR and attaching WLM policies to them you can dynamically control the volume of traffic allowed through the flow in IBM Integration Bus at runtime.

  • Benefits

    This approach allows you control the volume of traffic passing through your message flows while still enabling you to centrally manage your services and policies in WSRR, giving you a single view onto the services in your SOA and the policies that apply to them.

IBM Integration Bus Workload Management Policies

IBM Integration Bus provides mechanisms to control the rate of processing within a message flow. IBM Integration Bus version 9.0 introduced the ability to configure these mechanisms by defining workload management policies. These policies can then be associated with message flows, enabling you to separate configuration data from the message flows themselves.

Out of the box, IBM Integration Bus allows these policies to be defined in the development environment (IBM Integration Toolkit) and the Web Management UI. Although these are powerful mechanisms, as usage matures, it is often desirable to apply a formal governed process to the creation, modification and deletion of these policies. WSRR provides a natural solution to this problem.

The workload management policies that can be defined in IBM Integration Bus provide three mechanisms that can be used to control the rate of processing in a message flow:

  • Limiting the rate of processing
  • Increasing the rate of processing
  • Handling unresponsive message flows

These scenarios are discussed in more detail below.

Limiting the rate of processing

When service enabling existing back end systems there is a risk that those systems will be unable to cope with the resulting increase in demand. Also, if the services that are used to access the back end systems are made public, the volume of traffic flowing over this channel can vary significantly.

The ability to limit the rate at which a message flow processes messages allows you protect backend systems from both a general increase in demand and temporary spikes in traffic. IBM Integration Bus allows you to specify a Maximum Rate parameter on a workload management policy. When the polcy is associated with a message flow whose message rate is too high, it tells IBM Integration Bus to delay retrieving messages from the input nodes to decrease the rate below the specified limit.

Increasing the rate of processing

Historically, you might have allowed for spikes in traffic to backend services by ensuring that the service had enough capacity to cope with the occasional increase in demand. This was achieved by allocating additional resources to run the service up front so that there was always spare capacity available. This additional capacity was sometimes referred to as headroom. The problem with this approach was that, most of the time, these additional resources were not being used.

Another approach to dealing with spikes in traffic is to dynamically allocate additional resources when the volume increases beyond a specified point. IBM Integration Bus allows you to specify an Additional Instances parameter on a workload management policy. When the policy is associated with a message flow whose and all available message flow threads are handling requests, it tells IBM Integration Bus to create additional threads that can be used by the message flow to increase the overall processing capacity of the flow.

It is still possible to specify that these additional threads should be created when the message flow is started, in effect allocating the additional resources up front. This is defined on a workload management policy by specifying a value of true for the Start additional instances when message flow starts parameter.

Dealing with unresponsive message flows

The ability to control the rate at which a message flow processes messages is very powerful, but it does not enable you to handle situations where a message flow becomes unresponsive or out of control. IBM Integration Bus allows you to specify Processing timeout and Processing timeout action parameters on a workload management policy. When the policy is associated with a message flow that does not complete before the processing timeout, it tells IBM Integration Bus take the specified action. Currently the only values that can be specified for the Processing timeout action parameter are None and Restart Execution Group.

JMS Input Node Overview

IBM Integration Toolkit provides support for interacting with JMS providers by providing the JMS Input node. While the JMS specification defines a standard API for interacting with JMS providers, each vendor implementation is different. As a result each JMS Input node must be configured to retrieve messages from a specific JMS provider.

Node Terminals

The terminals for the JMS Input node are shown in the following figure.

Figure 1. JMS Input node terminals
JMS Input node terminals

The terminals are described in the following table.

Table 1. Terminals on the XSL Transform node
TerminalDescription
FailureThe output terminal to which the message is routed if an error occurs. Even if the Validation property is set, messages that are propagated to this terminal are not validated.
OutThe output terminal to which the message is routed if it is retrieved successfully.
CatchThe output terminal to which the message is routed if an exception is generated downstream and caught by this node.

Node properties

The JMS Input node provides an extensive set of properties that can be configured using the Properties editor in IBM Integration Toolkit. Many of these properties have not been modified by the message flow described in this article. For brevity, only the properties of the JMS Input node that have been modified by the message flow are described in the following table.

Table 2. JMS Input Node Properties
PropertyEditor TabDescription
Subscription topicBasic

Specifies the name of the topic to that the node will subscribe to in order to receive JMS messages. If you specify a subscription topic when configuring the node, it operates in the publish/subscribe message domain only. It is not possible to specify both a Source queue and Subscription topic on the same JMS Input node. The value specified must conform to the standards of the JMS provider that the node is configured to use.

JMS provider nameJMS Connection Specifies the name of the JMS provider that will be used by the node. If you select a name from the list, the Initial context factory property is updated automatically with the relevant Java class. If you specify your own JMS provider name, you must also enter a value for the Initial context factory property. The name must match the name of a configurable service that is defined on the broker to which you deploy the message flow.
Initial context factoryJMS Connection

At runtime, the JMS Input node needs a mechanism by which to obtain references to the connection factory and queue or topic that have been configured. The JMS specification establishes the convention that these references are obtained by looking them up in a name server using the Java Naming and Directory Interface (JNDI) API. The initial context factory specified is the vendor specific implementation class that the node will use to perform lookups against the target name server.

As discussed above, if you select a JMS provider name from the list, the initial context factory property is updated automatically with the relevant Java class. If you specify your own JMS provider name, you must also enter a value for the Initial context factory property.

The default value for the initial context factory property is com.sun.jndi.fscontext.RefFSContextFactory, which defines the file-based initial context factory for the WebSphere MQ JMS provider.

Message domainInput Message Parsing

Specifies the name of the parser that will be used to parse the response. If the field is blank then the default is BLOB. The following options are available:

  • DFDL
  • XMLNSC
  • JSON
  • BLOB
  • MIME
  • MRM
  • JMSMap
  • JMSStream
  • XMLNS
Application propertyMessage Selectors

A message selector allows the JMS Input node to filter the messages that it receives from the specified queue or topic so that it only receives the messages that it is interested in.

The value specified must be a string whose syntax is based on a subset of the SQL92 conditional expression syntax. Also, the value is only able to reference JMS message headers and properties, not values that are part of the message body. An example value for this property is OrderValue > 200.

HTTP Request Node Overview

IBM Integration Toolkit provides support for interacting with REST services by providing the HTTP Request node. This node allows you to use all or part of the input message as the request that is sent to the service. It can also be used to create an output message based on the input message, augmented by the contents of the service response, before propagating the message to subsequent nodes in the flow.

The node can be configured to construct either an HTTP or HTTPS request from the specified parts of the input message and send this request to the target service. It can then parse the response from the service and inject the content into the output tree for propagation to other nodes in the flow.

Node Terminals

The terminals for the HTTP Request node are shown in the following figure.

Figure 2. HTTP Request node terminals
HTTP Request node terminals

The terminals are described in the following table.

Table 3. Terminals on the HTTP Request node
TerminalDescription
InThe input terminal that accepts a message for processing by the node.
FailureThe output terminal to which the message is routed if a failure is detected during processing in the node.
OutThe output terminal to which the message is routed if it represents successful completion of the service request, and if further processing is required within this message flow.
ErrorThe output terminal to which messages that include an HTTP status code that is not in the range 200 through 299, including redirection codes (3xx) if you have not set the property Follow HTTP(s) redirection property, is routed.

Node properties

The HTTP Request node also provides an extensive set of properties that can be configured using the Properties editor in IBM Integration Toolkit. Again, many of these properties have not been modified by the message flow described in this article. For brevity, only the properties of the HTTP Request node that have been modified by the message flow are described in the following table.

Table 4. HTTP Request Node Properties
PropertyEditor TabDescription
Web Service URLBasicThe URL for the target service. This must be specified in the form http://hostname[:port]/[path] where:
  • http://hostname must be specified.
  • port has a default of 80. If you specify a value, you must include the : before the port number.
  • path has a default of /. If you specify a value, you must include the / before the path.

The value of the Web Service URL property can be specified programmatically using a compute node earlier in the message flow to insert elements into the input message or the local environment tree. A value specified programmatically overrides the value specified on the node. The locations that can be used to override the value specified on the node are:

  • X-Original-HTTP-URL in the HTTP Request header in the input message.
  • Destination.HTTP.RequestURL in the local environment tree.

The locations shown are listed in order of priority. That is, if a value is specified for the X-Original-HTTP-URL field, this overrides any value specified in the Destination.HTTP.RequestURL field.

If the specified URL starts with http://, the request node makes an HTTP request to the specified URL. If the specified URL starts with https://, the request node makes an HTTP over SSL (HTTPS) request to the specified URL, using the parameters that are specified on the SSL tab for the node.

HTTP methodHTTP Settings The HTTP method that the node will use when making requests. Valid values are POST, GET, PUT, DELETE, and HEADHEAD. By default, the HTTP Request node uses the HTTP POST method when it connects to the remote web server.
HTTP VersionHTTP SettingsSpecifies the HTTP version that the node will use when making requests. Valid values are 1.0 and 1.1.
Use CompressionHTTP SettingsThis property controls whether the content of the HTTP request is compressed. Valid values are none, gzip, zlib (deflate) and deflate. If the request is compressed, the Content-Encoding header is set to indicate that the content is compressed.
ProtocolSSL

This property specifies the protocol to use when making an HTTPS request. Both ends of an SSL connection must agree on the protocol to use. Therefore, the selected protocol must be one that the remote server can accept. The following options are available:

  • SSL. This option is the default. This option tries to connect using the SSLv3 protocol first, but enables the handshake to fall back to the SSLv2 protocol where the SSLv2 protocol is supported by the underlying JSSE provider.
  • SSLv3. This option tries to connect with the SSLv3 protocol only. Fallback to SSLv2 is not possible.
  • TLS. This option tries to connect with the TLS protocol only. Fallback to SSLv3 or SSLv2 is not possible.
Message DomainResponse Message Parsing

Specifies the name of the parser that will be used to parse the response. If the field is blank then the default is BLOB. The following options are available:

  • DFDL
  • XMLNSC
  • JSON
  • BLOB
  • MIME
  • MRM
  • XMLNS
Replace input message with web-service responseAdvanced If you select this check box, the web service response message is used as the output message for the node, replacing the original input message. If you clear this check box, you must specify a value for the Response message location in tree property.
Response message location in treeAdvanced Specifies the location in which the parsed elements from the web service response bit stream are stored. This property takes the form of an ESQL field reference.
Accept compressed responses by defaultAdvanced This property indicates whether the request node handles compressed responses by default. If the request header does not contain an Accept-Encoding header and this option is selected, the node sets the Accept-Encoding header to "gzip, deflate", and any compressed response that is received is decompressed by the node.

Accessing a secure service

If the service being accessed by the HTTP Request node requires the client to authenticate, a security profile must be associated with the node that allows credentials to be propagated to the target service. IBM Integration Bus provides a profile that is pre-configured to allow credential propagation and is specifically intended for use by request nodes. It is called the Default Propagation security profile. To configure this security profile on a node in a message flow you must use Broker Archive Editor in the IBM Integration Toolkit. This security profile has already been configured on all of the HTTP Request nodes contained within the sample flows provided with this article series. To verify this, perform the following steps:

  1. Open IBM Integration Toolkit.
  2. Open the Integration Development perspective.
  3. In the Application Development view, expand BARs and double click on WSRRIntegrationDemos.bar, as shown below:
    Figure 3. Opening the BAR file
    Opening the BAR file
    Opening the BAR file
  4. The file will be opened in the Broker Archive Editor. Select the Manage tab at the bottom of the editor.
  5. Expand WSRRIntegrationDemos => HTTPNode_WLMPolicy.msgflow -> HTTPNode_WLMPolicy.
  6. From the list of nodes in the flow select Retrieve Policy, as shown below:
    Figure 4. Selecting the node
    Selecting the node
    Selecting the node
  7. The properties for the node will be displayed in the Properties editor. The Security Profile property is towards the bottom of the list of properties on the Configure tab, as shown below:
    Figure 5. Security Profile property
    Security Profile property
    Security Profile property

WSRR JMS Notification

WSRR provides a pluggable framework that allows you to hook into the standard processing that takes place when operations are performed within the product. You can implement custom plugins for this framework that perform tasks such as validation, modification and notification. WSRR also provides a number of plugins for this framework out of the box. One of these plugins is the JMS Notification plugin.

The JMS Notification plugin publishes JMS messages to a set of pre-defined topics in response to operations that are performed within the product. These messages are published in response to both the successful completion of an operation and the failure of an operation. The relevant topic space has been partitioned so that the success and failure messages for each operation are published to different topics. This enables JMS clients to subscribe to the relevant topic to ensure that they only receive notifications for the operations and outcomes that they are interested in.

WSRR defines two topics that are specifically used to publish messages related to the creation and attachment of policies. These are the SRPolicyUpdateTopic and the SRPolicyAttachmentTopic and they are described in more detail in the sections that follow.

Policy update topic

Messages are published to the SRPolicyUpdateTopic when policy expressions are created, updated or deleted in WSRR. This can occur as the result of manually loading an existing WS-Policy document into WSRR or by authoring the policy directly within the product itself. The messages that are published are JMS TextMessages with an XML body that contains the details of the notification. An example of the XML contained in the body of a notification message generated when creating a policy in WSRR is shown in the following listing. The JNDI name of the SRPolicyUpdateTopic is jms/PolicyUpdateTopic.

Listing 1. Example policy creation notification
<policynotification>
    <action>CREATE</action>
    <bsrURI>f65c9ef6-f8cb-4b7a.ba78.61b4666178fe</bsrURI>
    <policyURI>#WLMPolicy_20_Msgs_Sec</policyURI>
    <wsuID>WLMPolicy_20_Msgs_Sec</wsuID>
</policynotification>

The following table describes the elements contained in the XML body of the notification message.

Table 5. Policy notification XML elements
Element NameDescription
action Indicates the action that triggered the notification. It is one of CREATE, UPDATE or DELETE .
bsrURI The bsrURI of the policy expression that was created, updated or deleted. A single policy document can contain multiple policy expressions.
policyURI The policy URI for the policy expression. This uniquely identifies the policy expression in WSRR. If the policy defined an identifier then the policy URI will be based on this. If not, the policy URI will be generated by WSRR.
wsuID The identifier specified for the policy expression, as defined by the the WS-Security Utility schema. WS-Policy documents loaded into WSRR do not have to specify an identifier.

Policy attachment topic

Messages are published to the SRPolicyAttachmentTopic when policies are attached to, or detached from, objects in WSRR. Again, the messages are JMS TextMessages with an XML body that contains the details of the notification. An example of the XML contained in the body of a notification message generated when attaching a policy to an object in WSRR is shown in the following listing. The JNDI name of the SRPolicyAttachmentTopic is jms/PolicyAttachmentTopic .

Listing 2. Example policy attachment notification
<policynotification>
    <targetBsrURI>18d38918-4d4f-4fb2.9149.ef049aef4938</targetBsrURI>
    <action>CREATE</action>
    <wsdlIdentifier/>
    <policyURIs>
        <policyURI>#WLMPolicy_20_Msgs_Sec</policyURI>
    </policyURIs>
</policynotification>

The following table describes the elements contained in the XML body of the notification message.

Table 6. Policy attachment notification XML elements
Element NameDescription
targetBsrURIThe bsrURI of the object that the policy expression was ttached to or detached from.
action Indicates the action that triggered the notification. It is either CREATE or DELETE where CREATE indicates that a policy expression was attached to an object and DELETE indicates that a policy expression was detached from an object.
wsdlIdentifier The element identifier of the object that the policy expression is being attached to or detached from. This element will only contain a value if the target object represents an element defined in a WSDL document. Note that the wsdlIdentifier cannot uniquely identify an object in the registry, so care must be taken if you use this forretrieval purposes.
policyURI The policy URI of the policy expression that is being attached to or detached from the object in WSRR. A policy attachment notification message may contain multiple policy URIs.

JMS properties

The notification messages that are published to the SRPolicyUpdateTopic and SRPolicyAttachmentTopic duplicate the XML elements that are contained in body of the message as JMS properties. This enables JMS clients to use message selectors to filter the messages that they receive to just those messages that they are interested in. For example, if a JMS client only wanted to receive notification messages from the SRPolicyUpdateTopic when a policy expression was created, it would specify a message selector of action='CREATE'.

WSRR REST API

WSRR provides a number of APIs that can be used to interact with the service metadata artifacts registered with the product, as follows:

  • Enterprise JavaBean (EJB) API
  • Web Service API
  • REST API

All of these APIs support publishing (creating and updating) service artifacts and the metadata that is associated with those artifacts, retrieving service metadata artifacts, deleting the artifacts and their metadata, and querying the content of WSRR. Basic create, retrieve, update, and delete operations, as well as governance operations and a flexible query facility based on XPath, are provided through these APIs.

The WSRR REST API allows for lightweight clients, that do not have support for EJB and web services, to perform actions on content and metadata by using HTTP requests. For example, the URL shown in the following listing can be pasted into a web browser to execute a query against WSRR. The XPath expression that will be used is passed as part of the URL in the query parameter. The query shown will return the metadata for every WSDLDocument object that exists in the target WSRR instance.

Listing 3. Example WSRR REST URL
https://localhost:9443/WSRR/8.0/Metadata/XML/GraphQuery?query=/WSRR/WSDLDocument

WSRR Policy Service

The WSRR REST API provides a number of capabilities that are specifically related to policies and policy attachments. The WSRR Policy Service allows you to retrieve the content of policy documents that are stored in WSRR, or policy attachment documents that contain information about what objects in WSRR policies are attached to.

To retrieve the content of policy documents from WSRR you need to know either the bsrURI or the policyURI of the policy expression that you are interested in. To retrieve a policy document using the bsrURI, you can invoke the WSRR Policy Service using the URL shown in the following listing:

Listing 4. Retrieving policy documents using the bsrURI
<SCHEME>://<HOSTNAME>:<PORT>/WSRR/8.0/PolicyService/Policy?bsrURI=<BSRURI>

Where:

  • <SCHEME> is either http or https depending on whether security is enabled on the target WSRR instance.
  • <HOSTNAME> is the hostname or IP address of the target WSRR instance.
  • <PORT> is the port number that the target WSRR instance is listening on for HTTP requests.
  • <BSRURI> is the bsrUri (id) of the policy expression that is defined in the policy document to be retrieved.

To retrieve a policy document using the policyURI, you can invoke the WSRR Policy Service using the URL shown in the following listing:

Listing 5. Retrieving policy documents using the policy URI
<SCHEME>://<HOSTNAME>:<PORT>/WSRR/8.0/PolicyService/Policy?uri=<POLICYURI>

Where:

  • <SCHEME> is either http or https depending on whether security is enabled on the target WSRR instance.
  • <HOSTNAME> is the hostname or IP address of the target WSRR instance.
  • <PORT> is the port number that the target WSRR instance is listening on for HTTP requests.
  • <POLICYURI> is the policy URI of the policy expression that is defined in the policy document to be retrieved.

Message Flow Description

The WLM policy message flow listens for policy related notifications from WSRR and then takes the appropriate action in IBM Integration Bus based on the content of the event. It uses a number of JMS Input nodes to listen for notifications published to the SRPolicyUpdateTopic and SRPolicyAttachmentTopic. Each of these input nodes is configured to ensure that it will only receive a notification message in response to a specific action performed in WSRR, such as the creation of a policy. This allows the various paths through the message flow to be kept separate, ensuring that each is as simple as possible.

Some of the paths through the message flow need to retrieve additional information from WSRR to perform the relevant processing. In each case, an HTTP Request node is used to retrieve the required data from WSRR using the WSRR REST API. A high level view of the interaction between WSRR and the message flow running in IBM Integration Bus is shown in the following figure.

Figure 6. High level interaction between WSRR and IBM Integration Bus
High level interation between WSRR and IBM Integration Bus
High level interation between WSRR and IBM Integration Bus

Each JMS Input node in the flow corresponds to the entry point for:

  • A new policy being created in WSRR
  • A policy being deleted in WSRR
  • A policy being attached to an object in WSRR
  • A policy being detached from an object in WSRR

The following figure shows the actual message flow. Each of the paths through the message flow are discussed in detail in the sections that follow.

Figure 7. The WLM Policy Message Flow
The WLM Policy Message Flow
The WLM Policy Message Flow

Policy Creation Processing

This path through the WLM policy message flow handles policy creation notification events from WSRR. The sections that follow describe each of the nodes in this path through the message flow in detail.

Policy Created node

This path through the flow starts with the Policy Created JMS Input node. To ensure that it only receives policy creation notification messages from WSRR, it is configured to listen for notification messages published to the SRPolicyUpdateTopic and it specifies a message selector of action='CREATE'. The following table shows the values of the properties that have been specified on the Policy Created node.

Table 7. Policy Created Node Properties
PropertyValue
Subscription topicjms/PolicyUpdateTopic
JMS provider nameClient for WebSphere Application Server
Initial context factorycom.ibm.websphere.naming.WsnInitialContextFactory
Message DomainXMLNSC
Application propertyaction='CREATE'

The Policy Created node is connected to the Process Create Message node in the WLM policy message flow using the out terminal.

Process Create Message node

The Process Create Message node is an instance of a Java Compute node. This node processes the policy creation notification messages that are passed to it by the Policy Created node, extracting the bsrURI of the policy that was created in WSRR. The following listing shows the code required to do this.

Listing 6. Extracting the bsrURI of the Policy
MbElement rootElement = inMessage.getRootElement();
MbElement wsrrElement = rootElement.getFirstElementByPath("XMLNSC/policynotification");
String bsrURI = (String)wsrrElement.evaluateXPath("string(bsrURI)");

The message flow needs to use the bsrURI to retrieve the content of the policy that was created in WSRR using the WSRR REST API. To do this, it must construct the URL that will be used to invoke the WSRR policy service and insert it into the Destination.HTTP.RequestURL field of the local environment tree. It determines the scheme, host and port to use for the URL by programmatically querying the endpointAddress property from the DefaultWSRR configurable service object in IBM Integration Bus and extracting the values. This task is performed by the WSRRConfigurationUtils utility class. It must also insert the bsrURI as a query parameter in to the relevant fields of the local environment tree. The following listing shows the code that is required to perform these tasks.

Listing 7. Programmatically specifying the REST URL
private static final String REST_URL_POLICY_SERVICE_ROOT =
    "/WSRR/8.0/PolicyService/Policy";
    
WSRRConfigurationUtils wsrrConfig = WSRRConfigurationUtils.getInstance();

URI wsrrUrl = new URI( wsrrConfig.getScheme()
                     , null, wsrrConfig.getWsrrHost()
                     , wsrrConfig.getWsrrPort()
                     , REST_URL_POLICY_SERVICE_ROOT
                     , null
                     , null
                     );
environmentRoot.evaluateXPath("?Destination/?HTTP/?RequestURL[set-value('"
    + wsrrUrl.toString() + "')]");
environmentRoot.evaluateXPath("?Destination/?HTTP/?QueryString/?bsrURI[set-value('"
    + bsrURI + "')]");

The HTTP Request node does not use the configuration on the BrokerRegistry object to determine which keystore and truststore to use when sending the HTTP request. The location of the keystore and truststore, along with their passwords, must be configured programmatically in the local environment before the HTTP Request node is invoked in the flow. The WSRRConfigurationUtils utility class is used to retrieve this information from a user defined configurable service called WSRRREST.

The credentials that need to be propagated by the HTTP Request node to WSRR when invoking the REST API need to be defined programmatically on the output message. Again, the WSRRConfigurationUtils utility class is used to retrieve this information.

The following listing shows the code that is required to perform these tasks. The Process Create Message node then passes the message to the out terminal, which is wired to the Retrieve Policy node.

Listing 8. Configuring additional properties
// Create a folder in the local environment to hold the response from the REST query
environmentRoot.createElementAsLastChild(MbBLOB.PARSER_NAME);
 
// Specify the location of the keystore and truststore used by the HTTP Request node
environmentRoot.evaluateXPath("?Destination/?HTTP/?KeystoreFile[set-value('"
    + wsrrConfig.getKeystoreFile() + "')]");
environmentRoot.evaluateXPath("?Destination/?HTTP/?KeystorePassword[set-value('"
    + wsrrConfig.getKeystorePassword() + "')]");
environmentRoot.evaluateXPath("?Destination/?HTTP/?TruststoreFile[set-value('"
    + wsrrConfig.getTruststoreFile() + "')]");
environmentRoot.evaluateXPath("?Destination/?HTTP/?TruststorePassword[set-value('"
    + wsrrConfig.getKeystorePassword() + "')]");

// Create the message assembly to return
MbMessage outMessage = new MbMessage(inMessage);
MbElement rootElement = outMessage.getRootElement();
rootElement.evaluateXPath("?Properties/?IdentitySourceType[set-value("
    + "'usernameAndPassword')]");
rootElement.evaluateXPath("?Properties/?IdentitySourceToken[set-value('"
    + wsrrConfig.getUserId() + "')]");
rootElement.evaluateXPath("?Properties/?IdentitySourcePassword[set-value('"
    + wsrrConfig.getPassword() + "')]");
outAssembly = new MbMessageAssembly( inAssembly
                                   , environment
                                   , inAssembly.getExceptionList()
                                   , outMessage
                                   );
outTerminal = getOutputTerminal("alternate");

Retrieve Policy node

The Retrieve Policy node is instance of an HTTP Request node. Its behaviour is determined by a combination of the entries that were programmatically created by the previous node and the properties defined on the node itself. The following table shows the values of the properties that have been specified on the node.

Table 8. Retrieve Policy Node Properties
PropertyValue
HTTP methodGET
HTTP Version1.1
Use Compressiongzip
ProtocolSSL
Message DomainBLOB
Replace input message with web-service responseUnchecked
Response message location in treeInputLocalEnvironment
Accept compressed responses by defaultChecked

The Retrieve Policy node will invoke the WSRR policy service and write the retrieved policy to the location configured on the node. It is worth noting that the message domain configured on the node is BLOB. As a result, the response from the REST call will not be parsed by the node. It will simply be written as a byte array to the specified location. The out terminal is wired to the Create Policy node.

Create Policy node

The Create Policy node is another instance of a Java Compute node. It extracts the content of the policy document that was retrieved from WSRR. It then performs a simple check to ensure that it is an IBM Integration Bus WLM policy. This involves checking that the policy document declares the namespace for IBM Integration Bus WLM policies. The following listing shows the code required to perform these tasks. If the content of the policy document could not be retrieved from WSRR, or the policy document was not an IBM Integration Bus WLM policy, the message is passed to the alternate terminal. Because this terminal is not wired to any further nodes in the message flow, this effectively ends the processing of the message.

Listing 9. Extracting the policy content
private static final String NAMESPACE_WLM_POLICY =
    "http://www.ibm.com/xmlns/prod/websphere/iib/9.0.0/policy/wlm";

byte[] policyContentBytes =
    (byte[])(environmentRoot.getFirstElementByPath("BLOB").getValue());

if (policyContentBytes != null && policyContentBytes.length > 0) {
    String policyContent = new String(policyContentBytes);
    if (policyContent.indexOf(NAMESPACE_WLM_POLICY) != -1) {
        ...
    } else {
        outTerminal = getOutputTerminal("alternate");
    }
} else {
    outTerminal = getOutputTerminal("alternate");
}

Having extracted the content of the policy document and verified that it is an IBM Integration Bus WLM policy, the message flow now needs to create the policy in IBM Integration Bus itself. To do this, it must extract the name that will be used for the policy in IBM Integration Bus from the policy URI contained in the notification message. It then uses a utility class, WLMPolicyManager, to create the policy in IBM Integration Bus. The following listing shows the code required to perform these tasks. After the policy is created, the message is passed to the out terminal. If a valid policy name cannot be extracted from the policy URI, the message is passed to the alternate terminal. Because both of these terminals are not wired to any further nodes in the message flow, the processing of the message effectively ends.

Listing 10. Creating the policy in IBM Integration Bus
WLMPolicyManager policyMgr = WLMPolicyManager.getInstance();
            
MbElement rootElement = inMessage.getRootElement();
MbElement wsrrElement = rootElement.getFirstElementByPath("XMLNSC/policynotification");

String bsrURI = (String)wsrrElement.evaluateXPath("string(bsrURI)");
String policyURI = (String)wsrrElement.evaluateXPath("string(policyURI)");
String policyName = policyMgr.getWLMPolicyName(policyURI, bsrURI);

if (policyName != null && !policyName.isEmpty()) {
    policyMgr.createWLMPolicy(policyName, policyContent);
    outTerminal = getOutputTerminal("out");
} else {
    outTerminal = getOutputTerminal("alternate");
}

The WLMPolicyManager::createWLMPolicy method uses the BrokerProxy class provided by IBM Integration Bus to create the policy. It first checks to make sure that a WLM policy of the same name does not already exist in IBM Integration Bus. The following listing shows the code that is required to perform these tasks.

Listing 11. Using the BrokerProxy class
private static final String WLM_POLICY_TYPE = "WorkloadManagement";

BrokerProxy brokerProxy = BrokerProxy.getLocalInstance();

PolicyProxy policyProxy = brokerProxy.getPolicy(WLM_POLICY_TYPE, policyName);
if (policyProxy == null) {
    brokerProxy.createPolicy(WLM_POLICY_TYPE, policyName, policyContent);
}

Policy Deletion Processing

This path through the WLM policy message flow handles policy deletion notification events from WSRR. The sections that follow describe each of the nodes in this path through the message flow in detail.

Policy Deleted node

This path through the flow starts with the Policy Deleted JMS Input node. To ensure that it only receives policy deletion notification messages from WSRR, it is configured to listen for notification messages published to the SRPolicyUpdateTopic and it specifies a message selector of action='DELETE'. The following table shows the values of the properties that have been specified on the Policy Deleted node:

Table 9. Policy Deleted Node Properties
PropertyValue
Subscription topicjms/PolicyUpdateTopic
JMS provider nameClient for WebSphere Application Server
Initial context factorycom.ibm.websphere.naming.WsnInitialContextFactory
Message DomainXMLNSC
Application propertyaction='DELETE'

The Policy Deleted node is connected to the Process Delete Message node in the WLM policy message flow using the out terminal.

Process Delete Message node

The Process Delete Message node is an instance of a Java Compute node. This node processes the policy deletion notification messages that are passed to it by the Policy Deleted node. It extracts the name of the policy that was deleted from the policy URI contained in the notification message. It then uses the WLMPolicyManager utility class to delete the policy in IBM Integration Bus. The following listing shows the code required to perform these tasks. After the policy is deleted, the message is passed to the out terminal. If a valid policy name cannot be extracted from the policy URI, the message is passed to the alternate terminal. Because both of these terminals are not wired to any further nodes in the message flow, this effectively ends the processing of the message.

Listing 12. Deleting the policy in IBM Integration Bus
MbElement rootElement = inMessage.getRootElement();
MbElement wsrrElement = rootElement.getFirstElementByPath("XMLNSC/policynotification");
 
String bsrURI = (String)wsrrElement.evaluateXPath("string(bsrURI)");
String policyURI = (String)wsrrElement.evaluateXPath("string(policyURI)");
String policyName = policyMgr.getWLMPolicyName(policyURI, bsrURI);
            
if (policyName != null && !policyName.isEmpty()) {
    policyMgr.deleteWLMPolicy(policyName);
    outTerminal = getOutputTerminal("out");
} else {
    outTerminal = getOutputTerminal("alternate");
}

The WLMPolicyManager::deleteWLMPolicy method uses the BrokerProxy class provided by IBM Integration Bus to delete the policy. It first checks to make sure that a WLM policy with the specified name exists in IBM Integration Bus. The following listing shows the code required to perform these tasks.

Listing 13. The deleteWLMPolicy method
private static final String WLM_POLICY_TYPE = "WorkloadManagement";

BrokerProxy brokerProxy = BrokerProxy.getLocalInstance();

PolicyProxy policyProxy = brokerProxy.getPolicy(WLM_POLICY_TYPE, policyName);
if (policyProxy != null) {
    brokerProxy.deletePolicy(policyProxy);
}

Policy Attachment Processing

This path through the WLM policy message flow handles policy attachment notification events from WSRR. The sections that follow describe each of the nodes in this path through the message flow in detail.

Policy Attached node

This path through the flow starts with the Policy Attached JMS Input node. To ensure that it only receives policy attachment notification messages from WSRR, it is configured to listen for notification messages published to the SRPolicyAttachmentTopic, and it specifies a message selector of action='CREATE'. The following table shows the values of the properties that are specified on the Policy Attached node.

Table 10. Policy Attached Node Properties
PropertyValue
Subscription topicjms/PolicyAttachmentTopic
JMS provider nameClient for WebSphere Application Server
Initial context factorycom.ibm.websphere.naming.WsnInitialContextFactory
Message DomainXMLNSC
Application propertyaction='CREATE'

The Policy Attached node is connected to the Process Attach Message node in the WLM policy message flow using the out terminal.

Process Attach Message node

The Process Attach Message node is an instance of a Java Compute node. This node processes the policy attachment notification messages that are passed to it by the Policy Attached node. It extracts the name of the policy that was attached from the policy URI contained in the notification message. It then uses the WLMPolicyManager utility class to determine if the policy exists in IBM Integration Bus. The following listing shows the code that is required to perform these tasks. If a policy with the specified name does not exist in IBM Integration Bus, the message is passed to the alternate terminal. Because this terminal is not wired to any further nodes in the message flow, the processing of the message effectively ends.

Listing 14. Extracting the bsrURI of the Policy
MbElement rootElement = inMessage.getRootElement();
MbElement wsrrElement = rootElement.getFirstElementByPath("XMLNSC/policynotification");

String targetBsrURI = (String)wsrrElement.evaluateXPath("string(targetBsrURI)");
String policyURI = (String)wsrrElement.evaluateXPath("string(policyURIs/policyURI)");
String policyName = policyMgr.getWLMPolicyName(policyURI, targetBsrURI);
            
if (policyMgr.wlmPolicyExists(policyName)) {
        ...
} else {
    outTerminal = getOutputTerminal("alternate");
}

Having determined that the attached policy is a WLM policy that exists in IBM Integration Bus, the message flow now needs to retrieve the name of the service in WSRR that the policy was attached to. The targetBsrURI contained in the notification message is the id of the Service Level Definition for the service. The message flow needs to use the WSRR REST API to query the name of the service that this is the SLD for. To do this, it must construct the URL that will be used to invoke the WSRR REST API and insert it into the Destination.HTTP.RequestURL field of the local environment tree. It must also insert the XPath expression that defines the query to be executed against WSRR as a query parameter in to the relevant field of the local environment tree. Finally, it must specify that the name property for any matching objects must be returned by the query. This is also specified as a query parameter. The following listing shows the code required to perform these tasks.

Listing 15. Programmatically specifying the REST URL
private static final String REST_URL_PROPERTY_QUERY_ROOT =
    "/WSRR/8.0/Metadata/XML/PropertyQuery";
private static final String REST_URL_XPATH_QUERY_PARAM =
    "/WSRR/GenericObject[gep63_provides(.)[@bsrURI=''{0}'']]";
private static final String REST_URL_XPATH_NAME_PARAM = "name";

WSRRConfigurationUtils wsrrConfig = WSRRConfigurationUtils.getInstance();

URI wsrrUrl = new URI( wsrrConfig.getScheme()
                     , null
                     , wsrrConfig.getWsrrHost()
                     , wsrrConfig.getWsrrPort()
                     , REST_URL_PROPERTY_QUERY_ROOT
                     , null
                     , null
                     );

environmentRoot.evaluateXPath("?Destination/?HTTP/?RequestURL[set-value('"
    + wsrrUrl.toString() + "')]");

MbElement queryParam = (MbElement)((List)environmentRoot.evaluateXPath(
    "?Destination/?HTTP/?QueryString/?query")).get(0);

String formattedXPath =
    MessageFormat.format(REST_URL_XPATH_QUERY_PARAM, new Object[] {targetBsrURI});

queryParam.setValue(formattedXPath);
environmentRoot.evaluateXPath("?Destination/?HTTP/?QueryString/?p1[set-value('"
    + REST_URL_XPATH_NAME_PARAM + "')]");

Before the Process Attach Message node can forward the request onto an HTTP Request node, it needs to perform several other tasks. These are the same tasks performed by the Process Create Message node when processing create notification messages and the code is similar to that shown in the following listing. The Process Attach Message passes the message to the out terminal, which is wired to the Query Attached Object Name node.

Query Attached Object Name node

The Query Attached Object Name node is instance of an HTTP Request node. Its behaviour is determined by a combination of the entries that were programmatically created by the previous node and the properties defined on the node itself. The following table shows the values of the properties that have been specified on the node.

Table 11. Query Attached Object Name Node Properties
PropertyValue
HTTP methodGET
HTTP Version1.1
Use Compressiongzip
ProtocolSSL
Message DomainXMLNSC
Replace input message with web-service responseUnchecked
Response message location in treeInputLocalEnvironment.XMLNSC.WSRR.REST.Response
Accept compressed responses by defaultChecked

The Query Attached Object Name node will invoke the WSRR REST API and write the results to the location configured on the node. The out terminal is wired to the Attach Policy node.

Attach Policy node

The Attach Policy node processes the results returned by the query performed against WSRR. It attempts to extract the name of the service returned by the query and performs a check to ensure that a valid name was returned. The following listing shows the code that is required to perform these tasks. If the name of the service could not be extracted from the query results, the message is passed to the alternate terminal. Because this terminal is not wired to any further nodes in the message flow, the processing of the message effectively ends.

Listing 16. Extracting the policy content
MbElement wsrrElement = environmentRoot.getFirstElementByPath("XMLNSC/WSRR");
String flowName = (String)wsrrElement.evaluateXPath(
    "string(REST/Response/resources/resource/properties/property[@name='name']/" + 
    "attribute::value)");
if (flowName != null && !flowName.isEmpty()) {
        ...
} else {
    outTerminal = getOutputTerminal("alternate");
}

Having extracted the name of the service from the query results, the message flow now needs to attach the WLM policy to the message flow in IBM Integration Bus with this name. The WLM policy message flow assumes that the name of the service registered in WSRR matches the name of the flow running in IBM Integration Bus. This basic mapping has been used to keep the sample as simple as possible. In reality, you would probably capture the IBM Integration Bus specific metadata in WSRR by modifying the WSRR model. It extracts the name of the policy that was attached from the policy URI contained in the notification message. It then uses the WLMPolicyManager utility class to attach the policy in IBM Integration Bus. The following listing shows the code that is required to perform these tasks. After the policy is attached, the message is passed to the out terminal. Because this terminal is not wired to any further nodes in the message flow, this effectively ends the processing of the message.

Listing 17. Attaching the policy in IBM Integration Bus
MbElement msgRoot = inMessage.getRootElement();
MbElement policyNotificationElement =
    msgRoot.getFirstElementByPath("XMLNSC/policynotification");

String targetBsrURI =
    (String)policyNotificationElement.evaluateXPath("string(targetBsrURI)");
String policyURI =
    (String)policyNotificationElement.evaluateXPath("string(policyURIs/policyURI)");
String policyName = policyMgr.getWLMPolicyName(policyURI, targetBsrURI);
            
String appName = getMessageFlow().getApplicationName();
policyMgr.attachWLMPolicy(policyName, appName, flowName);
outTerminal = getOutputTerminal("out");

The WLMPolicyManager::attachWLMPolicy method uses the MessageFlowProxy class provided by IBM Integration Bus to attach the policy to the message flow. It first checks to make sure that the specified WLM policy is not already attached to the message flow. The following listing shows the code that is required to perform these tasks.

Listing 18. The attachWLMPolicy method
ApplicationProxy appProxy = egProxy.getApplicationByName(appName);
MessageFlowProxy mfProxy = appProxy.getMessageFlowByName(flowName);

String currentWlmPolicyName = mfProxy.getWlmPolicy();
if (!currentWlmPolicyName.equals(policyName)) {
    mfProxy.setWlmPolicy(policyName);
}

Policy Detachment Processing

This path through the WLM policy message flow handles policy detachment notification events from WSRR and the processing performed is almost identical to the processing performed when handling policy attachment notification events. As a result, the sections that follow will only describe the differences in the configuration of the nodes or the processing that takes place.

Policy Detached node

This path through the flow starts with the Policy Detached JMS Input node. To ensure that it only receives policy detachment notification messages from WSRR, it is configured to listen for notification messages published to the SRPolicyAttachmentTopic and it specifies a message selector of action='DELETE'.

Detach Policy node

The Detach Policy node processes the results returned by the query performed against WSRR, extracting the name of the service returned by the query. Having extracted the name from the query results, the message flow needs to detach the WLM policy from the message flow in IBM Integration Bus with this name. It extracts the name of the policy that was detached from the policy URI contained in the notification message. It then uses the WLMPolicyManager utility class to detach the policy in IBM Integration Bus. The WLMPolicyManager::detachWLMPolicy method uses the MessageFlowProxy class provided by IBM Integration Bus to detach the policy to the message flow. It achieves this by setting the name of the WLM policy on the message flow to an empty string. It first checks to make sure that the specified WLM policy is the one that is currently attached to the message flow. The following listing shows the code for the detachWLMPolicy method.

Listing 19. The detachWLMPolicy method
ApplicationProxy appProxy = egProxy.getApplicationByName(appName);
MessageFlowProxy mfProxy = appProxy.getMessageFlowByName(flowName);

String currentWlmPolicyName = mfProxy.getWlmPolicy();
if (currentWlmPolicyName.equals(policyName)) {
    mfProxy.setWlmPolicy("");
}

Additional Configuration

Before testing the WLM policy message flow some additional configuration steps need to be performed. These are described in the sections that follow:

Configuring the Client for WebSphere Application Server

By default, WSRR makes use of the Service Integration Bus (SIBus) in WebSphere Application Server as its JMS provider. To communicate with this JMS provider, the JMS Input nodes in the WLM policy message flow have all been configured to use the Client for WebSphere Application Server. This corresponds to the WebSphere_WAS_Client configurable service in IBM Integration Bus. However, additional configuration needs to be performed on this configurable service in the JMS Input nodes can successfully connect to the SIBus in WebSphere. The steps that follow describe how to configure the WebSphere_WAS_Client configurable service:

  1. Create a directory on your IBM Integration Bus machine to hold a number of files that are required by the WebSphere_WAS_Client configurable service, for example, /root/WebSphere_WAS_Client.
  2. Copy the com.ibm.ws.sib.client.thin.jms_8.5.0.jar and com.ibm.ws.ejb.thinclient_8.5.0.jar files from your WebSphere installation to the directory created above on your IBM Integration Bus machine. These files are located in the <WAS_INSTALL_ROOT>>/runtimes directory. These JAR files contain the implementation classes that are used by IBM Integration Bus to communicate with the SIBus and the naming service in WebSphere.
  3. The WebSphere_WAS_Client object configurable service needs to be updated so that it knows where to find these JAR files. To do this, use the mqsichangeproperties command:
    mqsichangeproperties <BROKER_NAME> 
                         -c JMSProviders 
                         -o WebSphere_WAS_Client
                         -n jarsURL
                         -v <JARS_DIR>

    Where:
    • <BROKER_NAME> is the name of the broker (Integration Node).
    • <JARS_DIR> is the directory that you created above.
  4. Repeat this process by using the mqsichangeproperties to modify the following attributes on the WebSphere_WAS_Client configurable service:
    Table 12. Description of the properties for the WebSphere_WAS_Client Configurable Service
    Attribute NameAttribute Value
    connectionFactoryNamejms/SRConnectionFactory
    initialContextFactorycom.ibm.websphere.naming.WsnInitialContextFactory
    jmsProviderXASupporttrue
    jndiBindingsLocationcorbaloc:iiop:<WAS_HOSTNAME>:<WAS_BOOTSTRAP_PORT>
  5. Copy the sas.client.props and ssl.client.props files from your WebSphere installation to the directory created above on your IBM Integration Bus machine. These files are located in the <WAS_INSTALL_ROOT>/profiles/<PROFILE>/properties directory. The properties in these files are used to configure the behaviour of the SIBus and WebSphere naming client classes contained in the two JARs that were copied.
  6. The ssl.client.props file defines several properties that specify the location of the keystore and truststore that should be used by the client classes when establishing SSL connections to WebSphere.Modify these properties to point to the trust store that was created when you performed the basic configuration steps in Part 1: Scenarios and configuration. Modify the following properies in the ssl.client.props file:

    Table 13. Changes to the ssl.client.props file
    Property NameProperty Value
    com.ibm.ssl.keyStoreThe full path to the key store file. For the purposes of configuring this message flow, you can actually use the trust store that was created in Part 1: Scenarios and configuration as both the keystore and truststore.
    com.ibm.ssl.keyStorePasswordThe password for the key store.
    com.ibm.ssl.keyStoreTypeJKS
    com.ibm.ssl.trustStoreThe full path to the trust store file.
    com.ibm.ssl.trustStorePasswordThe password for the trust store.
    com.ibm.ssl.trustStoreTypeJKS
  7. The JMS Input nodes use the JVM embedded in IBM Integration Bus to execute the client classes. Specify the com.ibm.CORBA.ConfigURL and com.ibm.SSL.ConfigURL system properties in order for the JVM to find the sas.client.props and ssl.client.props files at runtime. To do this, use the mqsichangeproperties command:
    mqsichangeproperties <BROKER_NAME>
                         -e <EXECUTION_GROUP_NAME> 
                         -o ComIbmJVMManager
                         -n jvmSystemProperty
                         -v"-Dcom.ibm.CORBA.ConfigURL=file:<SAS_CLIENT_PROPS_PATH>
                            -Dcom.ibm.SSL.ConfigURL=file:<SSL_CLIENT_PROPS_PATH>"

    Where:
    • <BROKER_NAME> is the name of the broker (Integration Node).
    • <EXECUTION_GROUP_NAME> is the name of the broker (Integration Node).
    • <SAS_CLIENT_PROPS_PATH> is the full path to the sas.client.props file.
    • <SSL_CLIENT_PROPS_PATH> is the full path to the ssl.client.props file.
    Note: There is no space between the -v parameter and the double quote.
  8. If security is enabled in the target WebSphere instance, the JMS Input nodes will be forced to authenticate when they attempt to access the naming service. To configure the userid and password that should be used, use the mqsisetdbparms command:
    Listing 20.
    mqsisetdbparms <BROKER_NAME>
                   -n jndi::com.ibm.websphere.naming.WsnInitialContextFactory
                   -u <USER_ID>
                   -p <PASSWORD>

    Where:

    • <BROKER_NAME> is the name of the broker (Integration Node).
    • <USER_ID> is the id of a user who is authorized to access the naming service in WebSphere, such as a WSRR Administrator.
    • <PASSWORD> is the password for this user.
  9. If security is enabled in the target WebSphere instance, the JMS Input nodes will also be forced to authenticate when they attempt to connect to the SIBus. To configure the user ID and password that should be used, use the mqsisetdbparms command:
    Listing 21.
    mqsisetdbparms <BROKER_NAME>
                   -n jms::jms/SRConnectionFactory
                   -u <USER_ID>
                   -p <PASSWORD>

Creating the WSRRREST configurable service

Various properties need to be specified programmatically for use by the HTTP Request nodes in the flow. The values for these properties could have been hard coded into the flow. A better solution is to create a user defined configurable service in IBM Integration Bus and retrieve the properties dynamically at run time. This is the approach taken within this message flow. To create the configurable service, you need to use the mqsicreateconfigurableservice command as shown below:

Listing 22. Creating the WSRRREST configurable service
mqsicreateconfigurableservice <BROKER_NAME> -c UserDefined -o WSRRREST

Where:

  • <BROKER_NAME> is the name of the broker (Integration Node).

To create the required properties on the WSRRREST configurable service, use the mqsichangeproperties command:

Listing 23. Creating the required properties
mqsichangeproperties <BROKER_NAME>
                    -c UserDefined
                    -o WSRRREST
                    -n keystoreFile
                    -v <KEY_STORE_FILE>

Where:

  • <BROKER_NAME> is the name of the broker (Integration Node).
  • <KEY_STORE_FILE> is the full path to key store file.

Repeat this process to create the following properties on the WSRRREST configurable service:

Table 14. WSRRREST Configurable Service Properties
Property NameValueTH3TH4
keystorePasswordThe password for the key store.
truststoreFileThe full path to the trust store file.
truststorePasswordThe password for the trust store.
userIdThe id of a user who is authorized to access the required artefacts in WSRR.
userPasswordThe password for this user.

You should restart the broker (Integration Node) at this point to ensure that all of your changes take effect.

Testing the Message Flow

To verify that the WLM policy message flow is working correctly, you need to create a WLM policy in WSRR using the new authoring capabilities provided by the Service Registry Dashboard. You also need to attach the WLM policy to the SLD for the Math Service. The sections that follow describe the how to perform these tests.

Creating a WLM policy

  1. In a Web browser, log on to the Service Registry Dashboard for your WSRR instance.
  2. Change to the SOA Governance view and then select the Overview page.
  3. Select Create a Workload Management Policy in the Actions widget, as shown below:
    Figure 8. The SOA Governance View
    The SOA Governance View
    The SOA Governance View
  4. The Create a Workload Management Policy dialog will be displayed. Enter a name for the policy, for example, WLMPolicy_10_Msgs_Sec.
  5. In the Target and Limits section, enter a value for the Maximum Rate property, for example, 10. The dialog should similar to this:
    Figure 9. Creating a WLM Policy
    Creating a WLM Policy
    Creating a WLM Policy
  6. Click Finish.
  7. The WLM policy will be created and you will taken to the Browse page, which will display the details of the WLMPolicy_10_Msgs_Sec policy.
  8. In another web browser, or a different tab on the same web browser, log on to the IBM Integration Bus web user interface.
  9. In the navigation tree, expand Policy => WorkloadManagement.
  10. You should see the WLMPolicy_10_Msgs_Sec policy listed, as shown below:
    Figure 10. Synchronized policy in IBM Integration Bus
    Synchronized policy in IBM Integration Bus
    Synchronized policy in IBM Integration Bus

This verifies that the WLM policy message flow has successfully processed the policy creation notification message from WSRR by retrieving the content of the policy document and creating the policy in IBM Integration Bus.

Attaching a WLM policy to an SLD

  1. In a Web browser, log on to the Service Registry Dashboard for your WSRR instance.
  2. Change to the SOA Governance view and then select the Overview page.
  3. Select WLMPolicy_10_Msgs_Sec.xml in the Collection widget.
  4. You will be taken to the Browse page, which will display the details of the WLMPolicy_10_Msgs_Sec policy document in the Detail widget. In this widget, under Policy Expressions, select WLMPolicy_10_Msgs_Sec.
  5. The Detail widget will be updated to display the details of the WLMPolicy_10_Msgs_Sec policy expression. Select Action => Manage Policy Attachments...:
    Figure 11. Manage Policy Attachments
    Manage Policy Attachments
    Manage Policy Attachments
  6. The Manage Policy Attachments dialog will be displayed. Click Attach to Specific Items.
  7. Ensure that Service Level Definition is selected in the Type drop down and click Find....
  8. The Search Results dialog will be displayed. Check the checkbox for SLD - MathService v1.0 and click Finish .
  9. The Manage Policy Attachments dialog will be updated to indicate that the WLMPolicy_10_Msgs_Sec policy expression will be attached to the SLD - MathService v1.0 SLD. Click Finish to create the attachment.
  10. In another web browser, or a different tab on the same web browser, log on to the IBM Integration Bus web user interface.
  11. In the navigation tree, expand Servers => <EXECUTION_GROUP_NAME> => Applications => WSRRIntegrationDemos => Resources and then select MathService.
  12. The main content pane will be updated to display the overview tab for the MathService message flow. Select the Policies tab.
  13. The list of WLM policies in IBM Integration Bus will be displayed. The selected radio button should indicate that the WLMPolicy_10_Msgs_Sec policy is attached to the MathService message flow, as shown below:
    Figure 12. Attached policy in IBM Integration Bus
    Attached policy in IBM Integration Bus
    Attached policy in IBM Integration Bus

This verifies that the WLM policy message flow has successfully processed the policy attachment notification message from WSRR by attaching the policy to the MathService message flow in IBM Integration Bus.

Monitoring the effect at runtime

To verify that IBM Integration Bus is enforcing the attached WLM policy, you need to turn on statistics for the MathService message flow and then analyze the Message Rate chart in the IBM Integration Bus web user interface. You will also need to use a load generation tool to generate traffic against the MathService flow. Describing which load generation tool to use and how to use it is outside of the scope of this article. The steps that follow describe how to turn on statistics for the message flow and view the relevant chart.

  1. In a Web browser, log on to the IBM Integration Bus web user interface.
  2. In the navigation tree, expand Servers => <EXECUTION_GROUP_NAME> => Applications => WSRRIntegrationDemos => Resources and then select MathService.
  3. The main content pane will be updated to display the overview tab for the MathService message flow. Select the Statistics tab.
  4. Back in the navigation tree, click the twisty next to the MathService and select Statistics on, as shown below:
    Figure 13. Turning on statistics
    Turning on statistics
    Turning on statistics
  5. After a short delay, the charts in the main content pane should start to update. The Message Rate is the chart at the top of the pane. Start generating load against the MathService using your load generation tool.
  6. While the tool is generating load, attach and detach various WLM policies to and from the SLD in WSRR. Use the Message Rate chart to verify that the WLM policies are being enforced by IBM Integration Bus. The chart shown below is an example of what you should see. In this example, the first dip in the message rate occurred when a WLM policy was attached to the SLD in WSRR, specifying a maximum rate of 10 messages per second. The message rate then increased when the policy was detached from the SLD. The second dip in the message rate occurred when a WLM policy was attached to the SLD in WSRR, specifying a maximum rate of 50 messages per second.
    Figure 14. The Message Rate Chart
    The Message Rate Chart
    The Message Rate Chart

Conclusion

This article described an example message flow that is able to listen policy Related notifications from WSRR and respond to them by automatically synchronizing WLM policies in WSRR with IBM Integration Bus. This includes the ability to create, delete, attach and detach WLM policies in IBM Integration Bus in response to users performing equivalent tasks in WSRR. It also described how the new WLM policy authoring capabilites in WSRR v8.5 are used to author WLM policies directly in the Service Registry Dashboard.

While this article has focussed on the policy related notifications that are generated by WSRR, it would be possible to implement message flows in IBM Integration Bus that can respond to other notification events.

Acknowledgements

The author thanks the following people for all of their help with the development of the sample messages flows in this series:

  • John Hosie
  • Ben Thompson
  • Matt Golby-Kirk
  • Trevor Dolby
  • Andreas Martens
  • Graham Haxby
  • Andrew Coleman
  • John Reeve

The author also thanks David Seager for his help with reviewing this article.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=970913
ArticleTitle=Integrating IBM Integration Bus with WebSphere Service Registry and Repository: Part 9: Workload Management policy integration
publish-date=04302014