Creating a flow that uses message collections

Use a Collector node in your message flow to group messages from one or more sources into a message collection. You can add dynamic input terminals to your Collector node for each message source that you want to configure for your message flow.

Before you begin

  • For background information, read Message collections.
  • If you are using message collections on an integration server that is managed by an integration node, ensure that you have installed IBM® MQ. Information about the state of in-flight messages is held on storage queues that are controlled by IBM MQ, and you must install IBM MQ on the same computer as your integration node if you want to use the capabilities provided by the aggregation nodes. For more information about using IBM MQ with IBM App Connect Enterprise, see Installing IBM MQ.

    If you are using message collections on an independent integration server, you can use a remote default queue manager to control the system queues, without the need to install IBM MQ on the same machine as the integration server. Interactions between an independent integration server and IBM MQ can use a client connection to a remote queue manager, by using a default policy setting. For information about using a remote default queue manager, see Using a remote default queue manager and Configuring an integration server to use a remote default queue manager.

About this task

You can also use a Compute node to create a message collection by using ESQL, which is useful if messages must be grouped together for parsing, or if the message collection must be constructed to represent a particular data structure, such as a CICS® Transaction Server for z/OS® channel data structure. For more information about using ESQL to create a message collection, see Creating a message collection by using ESQL.

To create a message flow to generate and process message collections, complete the following steps:

Procedure

  1. Create a message flow.
  2. Add the input nodes in the editor view.
    The input nodes receive the messages from which message collections are generated. You can use any of the built-in nodes, or user-defined input nodes. Configure and connect them as described.
    1. Add an input node for each source of input messages for your message flow, for example an MQInput node and a JMSInput node.
    2. Select each input node in turn to display its properties in the Properties view.
    3. Specify the source of input messages for each node. For example, specify the name of an IBM MQ queue in the Basic property Queue Name from which the MQInput node retrieves messages.
    4. Optional: Specify values for any other properties that you want to configure for each node.
  3. Add the Collector node in the editor view.
    The Collector node receives messages from input nodes or other nodes in the message flow. You must add a dynamic input terminal to the Collector node for each input message source before you can connect the input nodes or any upstream nodes to the Collector node. Configure and connect them as described.
    1. Add a Collector node to your message flow.
    2. Right-click the Collector node and click Add Input Terminal to add a new dynamic input terminal to the Collector node. Add a new input terminal for each input source that you plan to add to your message flow; for more information about adding dynamic input see Adding an input terminal to a Collector node for each input source.
    3. Connect the out terminal of each input node to a different dynamic input terminal of the Collector node. This represents the simplest configuration; if appropriate, you can include other nodes between the input node and the Collector node. For example, you might want to store the request for audit purposes (in a Database node), or add a unique identifier to the message (in a Compute node).
  4. Add processing nodes to your message flow.
    You can process message collections from a Collector node by using the following nodes only:
    • Compute
    • JavaCompute
    • .NETCompute

    You must connect a Compute, JavaCompute, or .NETCompute node to the Collector node in your message flow. Use these nodes to process the message collection and propagate other messages. You can use ESQL or XPATH to access the contents of the individual messages in the message collection for processing. To process a message collection:

    1. Add a Compute, JavaCompute, or .NETCompute node to your message flow.
    2. Add code to your message flow node to create single output messages from the message collection.
    3. Optional: Specify values for any other properties that you want to configure for this processing node.
    4. Connect the out terminal of the processing node to the in terminal of an output node or other processing node.
    5. Optional: Add other message flow nodes to your message flow for further processing.
  5. Include one or more output nodes for your message flow. These can be any of the built-in nodes, or a user-defined output node. An output node cannot process a message collection, therefore ensure that you connect the output node to a processing node that propagates single output messages. To configure an output node:
    1. Select each output node in turn to display its properties in the Properties view.
    2. Specify the destination properties for each node. For example, specify the name of an IBM MQ queue in the Basic property Queue Name to which the MQOutput node sends messages.
    3. Optional: Specify values for any other properties that you want to configure for each node.
  6. Include processing for handling errors and expired message collections:
    1. Optional: Add processing nodes to your message flow to handle expired message collections. Connect these nodes to the Expire terminal of the Collector node.
    2. Optional: Add processing or error handling nodes to handle any exceptions in your message flow. Connect these nodes to the Catch terminal of the Collector node
    If an error is detected downstream of the Collector node, the integration node throws an exception. The message collection is propagated to the Catch terminal of the Collector node. Connect the Catch terminal to a sequence of nodes that handles the errors, to avoid losing any data, and ensure that no further exceptions can be generated during error processing. The message flow node that is connected to the Catch terminal must be a Compute, JavaCompute, or .NETCompute node to handle the message collection.
  7. Press Ctrl-S or click File > Save name (where name is the name of this message flow) to save the message flow and validate its configuration.

Results

To control when complete message collections are propagated, you must add additional message flow nodes to your message flow. For more information, see Using control messages with the Collector node.

What to do next

Next: Configure the Collector node.