Message collections

A message collection is a single message that contains multiple messages derived from one or more sources.

You can use a Collector node to group together messages from one or more sources into a message collection, so that they can be processed together by downstream nodes. You can also manually build a message collection using a Compute node.

Structure of a message collection

A message collection tree contains sub-trees that hold the content of the individual messages received by the Collector node. The message assembly that is propagated from the Collector node to other nodes in your message flow contains the following four components:
  • Message (including transport headers)
  • Local environment
  • Global environment
  • Exception list
The following figure shows an example of the message tree structure of a message collection.
This is a diagram of the tree for a message collection. Its contents are described in the surrounding text.
The message collection in this example contains two messages, one received from IBM® MQ, and one from a file input source.

A message collection has a Properties header and a single folder element named Collection. A message collection can also have zero or more attributes that are name/value pairs; the name of an attribute must be unique within a message collection. These are shown as <name> / <value> in the figure. A standard attribute for the message collection is an attribute called CollectionName. If you use a Collector node to generate a message collection, the value for the collection name is generated based on the values you configure in the node. The collection name attribute is not compulsory.

Within the Collection folder in the message collection tree structure are folders, shown as <folder name> in the diagram. These folders contain the message tree of each message added to the message collection. Each of these folders has a name, but this name does not have to be unique within the message collection. The value for the <folder name> is derived from the source of the input message.

Nested message collections are not permitted. You cannot therefore use a message collection as a source message for another message collection. For example, If you attempt to pass a message collection to a input terminal on a Collector node, an error is generated.

The LocalEnvironment, Environment and ExceptionList trees are not included in the structure, but are instead carried separately as a part of the message assembly. There is no concept of a LocalEnvironment associated with each message in a message collection.

Generating a message collection using a Collector node

You can use the Collector node to make multiple synchronous or asynchronous requests in parallel. The results of these requests can be joined together downstream if required. This is different from the behavior of the aggregation nodes where there is a fixed pattern of request/response and where reply messages are grouped by request id. In contrast, the collector node does not need an initial fan-out stage and can group together unrelated input messages by correlating their content. You can configure dynamic input terminals on a Collector node to receive messages from different sources. You can also configure properties on the Collector node, known as event handlers, to determine how messages are added to a message collection, and when a message collection is complete.

Processing a message collection

A message collection is supported by the following nodes only:
  • Compute
  • JavaCompute
  • CICSRequest
Errors are generated by other nodes if they receive a message collection.
You can use ESQL or XPath expressions to access the content of messages in a message collection by referencing the folder names preceded by InputRoot.Collection. To access the contents of a message in a message collection using ESQL you can use code similar to the following ESQL:
InputRoot.Collection.folder1.XMLNSC
In XPath, the root element is the body of the message. The root element for a message collection is the Collection element. Therefore, to access the contents of a message in a message collection using XPath, you must use an expression similar to the following XPath: 
/folder1/XMLNSC
Examples of XPath expressions that you can use to access the message collection are:
  • /*: returns a list of all the messages in the message collection.
  • /@*: returns a list of all the attributes of the message collection.
  • /@Name: returns the value of the attribute Name.

You might not be able to determine the order of the messages within a message collection. If you generate a message collection using the Collector node, the messages are arranged in the same order as the messages arrived at the node.