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 LoopBackRequest node to issue synchronous requests through a LoopBack® connector, to create, retrieve, update, and delete data in a backend data source.
  • 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 SalesforceRequest (no discovery) node to send a request to a Salesforce system, to create, update, retrieve, and delete Salesforce data.
  • 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 JMS Receive node receives the input message tree from the input node, and the result message tree from an external JMS queue. The node combines the two trees to produce the output message tree.

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.

The input message tree is shown. The root element is selected to be overwritten:
The input root element is selected to be overwritten.
The result message tree is shown. The root element is selected for insertion:
The result root element is selected for insertion.
The output message tree is shown. The output root has been replaced by the result root tree:
The output root tree is replaced by the result root tree.

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.

In the input message tree, the JMSTransport subtree is selected to be overwritten:
The input headers are selected to be overwritten.
In the result message tree, the JMSTransport subtree is selected for insertion:
The result headers are selected for insertion.
In the output message tree, the output JMSTransport subtree is replaced by the result JMSTransport subtree:
The output header tree is replaced by the result header tree.

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.

In the input message tree, the XMLNSC element is selected to be overwritten:
The input message body is selected to be overwritten.
In the result message tree, the XMLNSC element is selected for insertion:
The result message body is selected for insertion.
In the output message tree, the XMLNSC element has been replaced by the result XMLNSC element:
The output message body is replaced by the result message body.

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.

In the input message tree, the location is selected to be written to. This location does not yet exist:
The specified output data location does not yet exist but is selected to be written to.
In the result message tree, the Operation element is selected for insertion:
The Operation element is selected for insertion.
In the output message tree, the Operation element from the result message tree is inserted under the existing request element:
The Operation element from the result message is inserted into the output message tree under the request element.