Selecting the data transformation process for callout messages

Data mapping between web services and IMS applications

Data mapping is the process of relating parts of two existing data structures to one another. You can modify an existing IMS application or create a new IMS application to make the callout request message. If you are modifying an existing IMS application, because the data structure of the web service is already predefined, it is unlikely that the data structure of the web service is the same as the data structure that is used by the IMS callout application. Therefore, some data mapping must take place between the data structure of the IMS application that issues the callout and the input data structure of the external web service. Sometimes you must create a new data structure or modify an existing application.

IBM® Rational® Developer for System z® provides an XML to COBOL Mapping wizard for creating a mapping definition between the data structure of the web service (in an XSD schema format) and the existing data structure of the IMS application (for example, in a COBOL copybook format). A converter is then generated based on the mapping definition to allow the mapping and transformation to be taken place at run time. You can perform data mapping as part of the process of generating the web service artifacts. This approach is called the meet-in-middle approach.

Rational Developer for System z Version 8.5.1 and later also provides COBOL data structure generation support from web service WSDL files. In addition to generating the required web service artifacts (correlator file and XML converter driver), the generated COBOL data structure can be used in your IMS COBOL synchronous callout application. This approach is called the top-down approach.

Each web service can have one or more operations and each operation can have its own input and output data definition. The data definition for each operation is defined as an XML Schema Definition (XSD) schema inside the WSDL file of the web service.

Data transformation

XML data transformation is optional for both the callout request and response. Because IMS applications send and receive data in bytes, you can use the IMS Connect XML adapter to convert the data between bytes and XML for you. If your application design requires that the data is sent in format other than bytes, you must handle the data transformation yourself.

If you specify to use the IMS Connect XML adapter, the IMS application's data is converted to an XML message that is designated for the specified web service operation.

Sending callout request and receiving response data in bytes

The IMS Connect XML adapter requires an XML converter for each web service operation the IMS application is calling out to. To create the XML converter:

1. Use Rational Developer for System z to map the XSD schema of the input data structure of the web service operation with the data structure of the IMS callout application. Rational Developer for System z uses this mapping definition to create both the correlator file and the XML converter.
2. Deploy the XML converter in IMS Connect.

The Rational Developer for System z converter adds correlation information, also known as the service data prefix, to the callout message. This information helps SOAP Gateway correlate the callout request message to the web service.

Sending callout request and receiving response data in other formats

If you must send the data in the callout request in other formats such as XML, ensure that the callout request message is in an XML format that can be properly processed by SOAP Gateway and the target web service.

• Ensure that the LL and ZZ fields in the IMS callout request message are not in the resulting XML message.
• Ensure that the service data prefix information is added to the callout request message.

Dynamic converter specification

Starting in IMS 14, you can use the DFSCNVTR XML tag in the control data area in your ICAL call to specify the converter to use at run time instead of the one that is defined in the callout web service correlator file. You can specify a different XML converter to use if you modify your synchronous callout application after the callout web service is already deployed. IMS Connect uses this converter information in the DFSCNVTR tag for callout request processing, and passes this information along with the request to SOAP Gateway. When SOAP Gateway sends the callout response message back to IMS Connect, the converter information is sent along as well. Therefore, you do not need to redeploy the callout web service when data structure changes in the synchronous callout application, allowing for flexible and dynamic changes with no service interruption.