| Note: Before adding to the processing-rule configuration on your MPGW, you must enable the appliance to be monitored, as documented in Chapter 13 of the ITCAM for SOA Installation and Configuration Guide Configuring processing rules for DataPower Multi-Protocol Gateways A DataPower Multi-Protocol Gateway service (available only on XI-50 appliances) handles SOA messages in a variety of transport protocols and message formats. Its strength lies in its ability to process virtually any incoming message - perhaps even transforming the message into a completely different format - before forwarding it to a back-end server to handle the core business logic. You can use a Multi-Protocol Gateway to provide an HTTP front end that receives, for example, a SOAP message, transforms it into a proprietary XML format, and places it on a queue for the Message Queue (MQ) transport protocol. Unlike a Web Service Proxy, a Multi-Protocol Gateway is not restricted to processing messages that are described by WSDL documents. It is this flexibility and the absence of WSDL that makes configuring a Multi-Protocol Gateway so fundamentally different from configuring a Web Service Proxy. The Web Service Proxy knows the service port name and namespace and the operation name and namespace of a SOAP message because of the WSDL. The Multi-Protocol Gateway, however, has no way of knowing what part of an arbitrary XML message or binary message is important to identify the conceptual operation. ITCAM for SOA can recognize the conceptual attributes of "service port name", "service port namespace", "operation name", and "operation namespace", when you provide this information. You do this by writing the necessary logic into an XSLT processing rule in your DataPower Multi-Protocol Gateway configuration. DataPower gateways receive a request message from a client, process it in some way, and forward it to a back-end server. The DataPower gateway usually receives a response message from that server, processes the response in some way, and forwards that response back to the client. When you monitor this message flow with ITCAM for SOA, you must add to the processing logic for each of these message flows as follows: - At the end of each transaction, typically on response rules and error rules, you must call the dp:wsm-agent-append() function (represented by the green callouts in the diagram). This function reports the various attributes about this transaction to the ITCAM for SOA data collector.
- To include this message in ITCAM for SOA operational-flow topology displays, then you must also add XSL logic to handle the ITCAM for SOA KD4SoapHeaderV2 SOAP header, and call the dp:exter-correlator() function for each request and response message in the transaction (represented by the yellow callouts in the diagram).
Details and illustrations of each of the above steps
wsm-agent-append() The wsm-agent-append() function reports the various attributes of this transaction to the ITCAM for SOA data collector. At any point prior to invoking this function, you must construct a processing variable containing a \<dpwsm:wsa-record\> nodeset and provide it as an argument to this method (the first green callout in the diagram). Among other things, this nodeset contains the various attributes that identify this message, the attributes that are derived from the WSDL in a Web Services Proxy. Refer to the DataPower Extension Elements and Functions Catalog for the contents of this nodeset. Most of the elements in this nodeset can be allowed to take their default values from the processing context. However, due to the absence of WSDL, the following elements must be set explicitly in your XSL. - ws-operation: the namespace-qualified operation name. For example, "{www.mynamespace.com}myOperation"
- service-port: the namespace-qualified name of the service port
- is-one-way: set to true() if this operation is one-way, or false() otherwise.
- webservice: This identifier contains an enumeration value identifying the format of the message being processed.
- 8 refers to a SOAP message
- 9 refers to an XML message
- 10 refers to a non-XML or binary message
You should not set explicit values for any of the following elements, because they are calculated automatically by various processing tasks: - ws-correlator-sfid
- ws-client-socode
- ws-dp-socode
- ws-server-socode
- ws-client-hopcount
- ws-server-hopcount
- start-time
- duration-ms
- front-latency-ms
- back-latency-ms
- request-size
- response-size
Your processing rules should call wsm-agent-append() as close as possible to the end of the response processing rules and error processing rules. If you intend for this transaction to appear in ITCAM for SOA operational flow topology views, you also must call exter-correlator() as described below, before calling wsm-agent-append(). exter-correlator() The exter-correlator() function invokes a proprietary algorithm to calculate a correlator that allow ITCAM for SOA to track relationships among related Web Services. This correlator allows each one of several concurrent messages to be tracked independently and accurately, without errors from heuristic algorithms. When you monitor a Web Service Proxy, the correlator is handled by the soapreq.xsl and soaprsp.xsl style sheets shipped with the appliance firmware. When you monitor a Multi-Protocol Gateway, you must invoke the logic necessary to calculate and propagate the correlator. This process generally is as simple as extracting a string, calling this function, and attaching the result. STEP 1: Receive an incoming correlator, if one is present (the first yellow callout). If your MPGW will be receiving SOAP messages from a Web application server that is monitored by ITCAM for SOA, then you should include logic to receive an attached correlator string, if one is available. The ITCAM for SOA data collector on the sending server will add a standard SOAP header named{http ://www.ibm.com/KD4Soap}KD4SoapHeaderV2 to each message that is sent. Your XSL should check for the presence of this header, and if it is present, extract the text node from within this element.
STEP 2: Calculate the correlator for the flow of this message through the MPGW (the second yellow callout). Before you can do this, you must identify the message (the first green callout) by setting the following context variables: - var://service/wsm/operation
- This is the namespace-qualified operation name. For example: {www.mynamespace.com}myOperation
- var://service/wsm/service-port
- This is the namespace-qualified name of the service port.
- var://service/soap-oneway-mep
- This variable should be set to true() if this operation is one-way, or false() otherwise.
- var://service/wsm/service
- This identifier contains an enumeration value identifying the format of the message being processed.
- 8 refers to a SOAP message
- 9 refers to an XML message
- 10 refers to a non-XML or binary message
STEP 3: Invoke the dp:exter-correlator() function (the second yellow callout), providing the incoming correlator string as the first argument. If you have no incoming correlator, you must use the literal string NEW_CORRELATOR instead. The second argument asserts the type of message that is being monitored. Specify 0 to indicate a request message. 
The return value from the dp:exter-correlator() function is the new correlator. STEP 4: Attach this string to the data collectors on the back-end servers (the third yellow callout). If you are sending SOAP messages, add XSL logic to construct a {http ://www.ibm.com/KD4Soap}dKD4SoapHeaderV2 header and add it to the SOAP Header section of the outbound message.
When processing a response message or an error message, follow the same logic:
- Extract an incoming correlator if one is present (the first, rightmost, yellow callout on the response path)
- Calculate a new correlator (the second yellow response callout), passing in the newly-extracted correlator and the constant 1 to represent a response message
- Attach the newly-calculated correlator if your response is a SOAP message (the third yellow response callout). This must take place before calling the dp:wsm-agent-append() function (the green response callout).
On an error processing rule, the processing-rule context will automatically populate the error details and the response will be identified as a fault in ITCAM for SOA. Troubleshooting Due to limitations of the implementation, the Service Port Name Type attribute (SPNAMETYPE) will always be set to 1 (WSDL Port Name), regardless of the values used in the var://service/wsm/service variable and the webservice element. Accurate values are necessary for correct calculation of various other identifiers within the context, however, so they should be set accurately.
Log the return code from dp:wsm-agent-append(). If there is an error in this function, or a problem with the set of data you collected for it to log, the return value from this function will describe the error. To debug problems with this function, your XSL logic must make this return value available. If your return value says "error - no record", this does not reflect an error in your XSL; it simply indicates that there are no subscriptions active for this domain at the moment. You may either activate the ITCAM for SOA data collector or set the "Buffer mode" setting for this domain to "buffer" (see http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.itcamsoa.doc/kd4inmst147.htm#optionalsettings). All other troubleshooting tools and techniques, including the multistep probe and the log files on both the appliance and on the ITCAM for SOA Data Collector are still useful in troubleshooting issue with monitoring the MPGW service. |
