Combining a result message with an input message when fetching data from external systems
Some nodes can fetch data in the middle of a message flow, and merge the result data with the input message to augment or overwrite sections of the input message.
The following nodes can fetch data in the middle of a message flow and merge the result with the input message:
- Use the CICSRequest node to call CICS® Transaction Server for z/OS® programs over TCP/IP-based IP InterCommunications protocol (IPIC).
- Use the CORBARequest node to call an external CORBA application over Internet Inter-Orb Protocol (IIOP).
- Use the FileRead node to read one record, or the entire contents of a file, from within a message flow.
- Use the IMSRequest node to send a request to run a transaction on a local or remote IMS system, and wait for a response.
- Use the JMSReceive node to consume or browse JMS messages from a JMS queue in the middle of a message flow.
- Use the RESTAsyncRequest node with the RESTAsyncResponse node to construct a pair of message flows that interact asynchronously with an external REST API.
- Use the RESTRequest node to issue synchronous requests to external REST APIs.
- Use the TCPIPClientReceive node to receive data over a client TCP/IP connection.
- Use the TCPIPServerReceive node to receive data over a server TCP/IP connection.
When you use one of these nodes in the middle of a message flow, you can fetch data from external resources. The result data is merged with the input message according to the values of the Output data location and, if it exists on the node, the Result data location properties.
The input root is first copied to the output root, and the result data is then copied to the location on the output tree specified by Output data location. The default value is $OutputRoot, which replaces the copied message tree with the result data, and propagates none of the input message.
The default value for Result data location, if it exists on the node, is $ResultRoot, which copies the entire result message to the output data location. If you specify a value underneath $ResultRoot, the specified subtree of the result message is inserted into the output tree.
The following examples use the JMSReceive node and show the effect of possible different values specified for Output data location and Result data location.
Example 1: Replacing the whole message tree
- Output data location = $OutputRoot
- Result data location = $ResultRoot
These values are the default values, and cause the input message to be overwritten with the result message.
Example 2: Replacing the message headers
- Output data location = $OutputRoot/JMSTransport
- Result data location = $ResultRoot/JMSTransport
The input root is copied to the output root, and then the headers are overwritten by the headers of the result message.
Example 3: Replacing the message body
- Output data location = $OutputRoot/XMLNSC
- Result data location = $ResultRoot/XMLNSC
The input root is copied to the output root, and then the message body is overwritten by the body of the result message.
Example 4: Inserting a subtree of the result message
- Output data location = $OutputRoot/XMLNSC/request/Operation
- Result data location = $ResultRoot/XMLNSC/request/Operation
The input root is copied to the output root, and then the Operation subtree of the result message is inserted into the output tree underneath the request element. The input message tree does not contain an Operation element, but its location is determined by the Output data location value.