Integration node calls existing web service

Possible uses

• You want to call a web service to do some processing as part of your message flow.
• You have an existing web service and you want to provide a different interface to it. This could be an alternative web services interface or a IBM® MQ interface.
• You have an existing web service and you want to change its implementation in some way without changing its interface; that is, the integration node acts as an intermediary to the web service. For instance a message flow could be used to enable auditing, or to transparently propagate the web service response to another application.

Design steps

1. Import WSDL to create a message set containing definitions for the SOAP messages described by the WSDL.
2. Create a message flow to invoke the web service. If the SOAP domain is used, the message flow uses a SOAPRequest node, SOAPAsyncRequest node, or a SOAPAsyncResponse node. The nodes are configured by using the WSDL imported in Step 1. If required, you can create a skeleton flow from scratch by dropping the WSDL onto a blank message flow editor canvas. If you use the SOAP domain, you must create the message flow by using transport nodes, and an XML or MIME domain. For example, if the WSDL binding specifies HTTP transport, and the request message is SOAP, you can use an HTTPRequest node with the XMLNSC domain. You can then configure the node manually with the endpoint information for the web service.
3. Build a BAR file for deployment. The BAR file contains your message flow and the message set that contains the imported WSDL. The SOAP domain always requires the WSDL to be deployed, because messages are verified against it at run time; also WSDL information is included in the logical tree. The message set includes XML Schema definitions that can be used for message validation in the SOAP, XMLNSC, or MRM domains.

At run time

Your message flow creates an appropriately formatted web service request, invokes the web service, and parses the web service response. If you use the SOAP domain, your message flow uses the SOAP logical tree model. If you do not use the SOAP domain, your message flow uses the logical tree for your selected domain; for example, you use the MIME domain if your web service messages use SOAP with Attachments.

Example 1

Web service intermediary

In this example a client application uses a web service called Account, which is made available by another organization. The client is widely distributed in your company. The client uses an operation called getBalance, but the Account service is being modified to change the definition of the getBalance operation. You can construct message flows to provide an interface to the Account service, instead of modifying the client. The message flows can call the Account service to do the work, and the new web service delegates to the original web service. The client can now continue to use the Account service, by using the new message flows.

In the examples of typical message flow patterns shown here, the intermediate request node calls the Account service:

• Using SOAPInput, SOAPRequest, and SOAPReply nodes:
  
• Using SOAPInput, SOAPAsyncRequest, SOAPAsyncResponse, and SOAPReply nodes:
  
• Using HTTPInput, HTTPRequest, and HTTPReply nodes:
  

In the message flows in the example, Compute1 modifies the original getBalance message as required by the modified Account service, while Compute2 restores the response message to the original format. If you have imported or generated WSDL, you have a message model for the getBalance operation. If you have a message model defined for the getBalance operation, you can use Mapping nodes instead of Compute nodes.

HTTP details

If you use HTTP transport nodes, as shown in the example, you can configure the HTTPRequest node to generate HTTP headers from the headers that are received by the HTTPInput node. This configuration enables cookies and other application-specific headers to be passed through the message flow. The HTTPReply node can be used task to extract headers from the web service response, to return to the originating client. To create this configuration, select Generate default HTTP headers from on both the HTTPRequest and HTTPReply nodes. Typically, you do not need the original request message to generate the reply to the client, and can select Replace input message with web service response on the HTTPRequest node. If you do want to preserve data from the input request, you can store this in the LocalEnvironment in Compute1, and retrieve it in Compute2 for inclusion in the reply.

Example 2

Using a web service

In this example, a IBM MQ message flow implements a process for the Human Resource department of your company. As part of this processing, the message flow calls a web service to retrieve employee ID numbers. Employee ID numbers are maintained in the company's employee directory, which is accessed through a web service.

In the examples of typical message flow patterns shown here the intermediate request node retrieves the employee ID:

• Using MQInput, SOAPRequest and MQOutput nodes:
  
• Using MQInput, SOAPAsyncRequest, SOAPAsyncResponse, and MQOutput nodes:
  
• Using MQInput, HTTPRequest, and MQOutput nodes:
  

In the message flows in the example, Compute1 prepares the web service request message and Compute2 processes the response. For example, by incorporating the employee ID in another message. If you have a message model defined, you can use Mapping nodes instead of Compute nodes in these examples.

HTTP details

If you use HTTP transport nodes, as shown in the example, you typically clear the Replace input message with web service response in the HTTPRequest node properties. The response from the corporate directory server is placed in a temporary location in the message tree. The temporary location is specified in the Response message location in tree property in the same node. In Compute2, you can code ESQL to retrieve the result, and update the final message.

Using the SOAP domain for these scenarios is preferred. For more information about choosing a domain for web services, see IBM Integration Bus and web services.