Web service consumer (callout) scenario

SOAP Gateway enables IMS applications to make synchronous or asynchronous callout requests to external web services and, optionally, to receive responses back.

A synchronous callout request is a request from an IMS application that expects the response message from the external web service to return in the same transaction.

An asynchronous callout request is a request from an IMS application that either does not expect a response from the web service, or expects the response to return in a separate transaction. The response might be returned to the same or a different IMS application. The key benefit of having the response return asynchronously is not to hold up the dependent regions.

A synchronous callout request from an IMS application is issued by making an ICAL call to put the message in the hold queue, or transaction pipe (also known as tpipe). An asynchronous callout request from an IMS application is issued by making an ISRT ALTPCB call to insert a callout message into the alternate program communication block (ALTPCB) and to an OTMA destination descriptor. The OTMA destination descriptor contains the name of the destination tpipe where the synchronous and asynchronous callout request messages are queued.

For synchronous callout requests, SOAP Gateway communicates with IMS Connect to pull the messages from the hold queue and to send the response messages from the external web services back to IMS Connect and to the appropriate callout requester.

The following figure shows the SOAP Gateway runtime environment when IMS applications are enabled as web service consumers that issue asynchronous callout requests to an external web services. It demonstrates how SOAP Gateway supports both the synchronous and asynchronous callout function. The numbers in the figure correspond to the description that follows.

Figure 1. SOAP Gateway runtime environment for the IMS applications as web service consumers scenario (asynchronous callout)

1. A client starts IMS application 1.
2. IMS application 1 issues an ICAL call for a synchronous callout request, or inserts an asynchronous callout message into the alternate program control block (ALTPCB).
3. SOAP Gateway establishes a TCP/IP connection with IMS Connect and sends a request from the hold queue (the tpipe) to IMS Connect. The tpipe name is obtained from the connection bundle file. When SOAP Gateway starts, it scans through the correlator files for callout connection bundle information, and identifies the tpipes that are defined in those callout connection bundles.
4. IMS Connect retrieves the callout message as part of the request processing for SOAP Gateway. IMS Connect calls the adapter and converter for XML processing if necessary.
5. After the converter converts the callout message successfully, the IMS Connect XML adapter sends the callout request message back to SOAP Gateway.
6. SOAP Gateway receives the callout request message in XML, and parses the message to retrieve the service and payload data. Based on the service name and operation name values, SOAP Gateway obtains from its cache the corresponding correlator file and the web service information for invoking the web service. The request message for the web service is built. SOAP Gateway sends an acknowledgment to IMS Connect, and the message is removed from the corresponding tpipe.
7. SOAP Gateway sends the callout request message to the web service by using the SOAP/HTTP protocol.
8. The response is sent back to IMS (optional for asynchronous callout requests).
   1. For synchronous callout requests, the response is sent back to the original IMS application that is waiting in the IMS dependent region.
   2. For asynchronous callout requests, if a response is expected, the response is sent back as a separate IMS transaction. The response might be handled by the original, or a different, application.