GroupComplete node

Use the GroupComplete node to collect all the replies and requests that were sent as part of a group and combine them into a single message.

The group nodes provide the ability to create fan-out/fan-in style static and dynamic aggregation scenarios that are stateless and highly performant without requiring an IBM® MQ queue manager to be available for the integration server. The GroupComplete node is responsible for attempting to reconcile incoming messages as replies to groups, or storing unknown messages for reconcilement with groups that may still be in construction. The GroupGather and GroupComplete nodes are together somewhat analogous to the Aggregate Reply node, however those group nodes are in separate threads and transactions.

For more information about the difference between group nodes and aggregation nodes, see Group nodes and aggregation nodes.

This topic contains the following sections:

Purpose

Grouping (a style of aggregation) is an extension of the request/reply application model. It combines the generation and fan-out of a number of related requests into a group with the fan-in of the corresponding replies, and compiles those replies into a single reply message.

The grouping function is provided by the following three nodes:
  • The GroupScatter node marks the beginning of a fan-out of requests that are part of a group. This node is responsible for creating a new group, and enables downstream nodes to send requests that are marked as part of the group.
  • The GroupGather node is responsible for attempting to reconcile incoming messages as replies to groups, or storing unknown messages for reconcilement with groups that may still be in construction.
  • The GroupComplete node is responsible for outputting groups that have been completed or timed out groups and unknown messages that have reached their timeout limit. It marks the end of a grouping fan-in (GroupGather). It collects replies and combines them into a single reply message.

The GroupComplete node is contained in the Routing drawer of the palette, and is represented in the IBM App Connect Enterprise Toolkit by the following icon:

GroupComplete node icon

Terminals and properties

When you have put an instance of the GroupComplete node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The GroupComplete node terminals are described in the following table.

Terminal Description
Out Propagates completed group messages in the format described below.
Timeout Propagates timed out partially completed group messages in the format described below.
Unknown Propagates timed out unknown reply messages in the format described below.
Failure The output terminal to which the message is routed if an error occurs.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The GroupComplete node Description properties are described in the following table:

Property M C Default Description
Node name No No The node type (AggregateControl) The name of the node.
Short description No No   A brief description of the node.
Long description No No   Text that describes the purpose of the node in the message flow.
The GroupComplete node Basic properties are described in the following table:
Property M C Default Description
Group name Yes Yes   The name that uniquely identifies all the group nodes participating in the same group processing.
Note: All nodes with the same group name must be deployed within the same integration server; group nodes cannot be used to orchestrate groups across multiple integration servers. The same group name can be reused across different integration servers and integration nodes.
The Monitoring properties of the node are described in the following table.
Property M C Default Description
Events No No None Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.

Behaviour

Out terminal

When a group is completed, or an early completion is successfully requested, a message will be sent from the out terminal containing all the details about the completed group. The full message format is described in the sections Completed group message format and Completed-early group message format below.

Unknown terminal

When an unknown message exceeds its specified timeout limit it is no longer eligible to be added to an in-flight group. A message is sent from the unknown terminal containing all the details about the timed-out unknown message.

Output message formats

The output message format varies from completed groups, completed-early groups, timed-out groups, and timed-out unknown reply messages. In all cases the group data is written to the message tree, there is no information written to the Environment, or Local Environment.

Completed group message format

The output message format for completed groups is as follows:
Root
    ComIbmGroupCompleteNode
        Group
            GroupProperties
                GroupId (BLOB)
                GroupName (CHARACTER)
                GroupCreationTime (DECIMAL)
                GroupCompleteTime (DECIMAL)
                GroupOutputTime (DECIMAL)
                GroupStatus (CHARACTER)
            Context (TREE)
            Replies
                <FolderName>
                    ReplyId (BLOB)
                    RequestSendTime (INTEGER)
                    ReplyReceiptTime (INTEGER)
                    Reply
                        Root (TREE)
                …

For a completed group the value of GroupStatus is Completed. The GroupCreationTime corresponds to the time that the group was created in the GroupScatter node. The GroupCompleteTime is the time at which all the expected replies were added to the group and the group was marked as complete. The GroupOutputTime is the time at which the group was received by the GroupComplete node.

The Context tree is the Context that was specified as an Environment override on the GroupScatter node.

The exact order in which each reply appears underneath the Replies folder is unspecified.

Completed-early group message format

The output message format for completed early groups is as follows:
Root
    ComIbmGroupCompleteNode
        Group
            GroupProperties
                GroupId (BLOB)
                GroupName (CHARACTER)
                GroupCreationTime (DECIMAL)
                GroupCompleteTime (DECIMAL)
                GroupOutputTime (DECIMAL)
                GroupStatus (CHARACTER)
            Context (TREE)
            Replies
                <FolderName>
                    ReplyId (BLOB)
                    RequestSendTime (INTEGER)
                    ReplyReceiptTime (INTEGER)
                    Reply
                        Root (TREE)
                …
            OutstandingRequests
                <FolderName>
                    ReplyId (BLOB)
                    RequestSendTime (INTEGER)
                …

For a completed early group the GroupStatus will be CompletedEarly. The GroupCompleteTime is the time at which the early completion request was processed by the GroupGather node. The GroupCreationTime and GroupOutputTime are the same as in the Completed group message format.

The Context tree is the Context that was specified as an Environment override on the GroupScatter node.

The exact order in which each reply appears underneath the Replies folder is unspecified.

Timed-out group message format

The output message format for timed-out groups is as follows:
Root
    ComIbmGroupCompleteNode
        Group
            GroupProperties
                GroupId (BLOB)
                GroupName (CHARACTER)
                GroupCreationTime (DECIMAL)
                GroupCompleteTime (DECIMAL)
                GroupOutputTime (DECIMAL)
                GroupStatus (CHARACTER)
            Context (TREE)
                Replies
                    <FolderName>
                        ReplyId (BLOB)
                        RequestSendTime (INTEGER)
                        ReplyReceiptTime (INTEGER)
                        Reply
                            Root (TREE)
                    …
                OutstandingRequests
                    <FolderName>
                        ReplyId (BLOB)
                        RequestSendTime (INTEGER)
                    …

For a timed-out groups the GroupStatus is TimedOut. The GroupTimeoutTime value is the time at which the group was marked as timed out and sent for output. The GroupCreationTime and GroupOutputTime are the same as in the Completed group message format.

The exact order in which each reply appears underneath the Replies folder is unspecified.

Timed-out unknown reply message format

The output message format for timed-out unknown replies is as follows:
Root
    ComIbmGroupCompleteNode
        UnknownMessage
            ReplyId (BLOB)
            GroupName (CHARACTER)
            MessageTimeoutTime (INTEGER)
            Reply
                Root (TREE)

Message tree parser

Unlike the AggregateReply node, the messages that are sent by the GroupComplete node are created using an XMLNSC parser. Reply bodies are represented using the same type of parser that original stored their replies. This means that the output of a GroupComplete terminal could be directly serialized to an XMLNSC message, assuming the replies can be serialised into a valid XML element.

Transactions

The node is non-transactional. However, if the message flow interacts with a database or another external resource, such as an IBM MQ queue, these interactions are performed in a transaction. If the message flow rolls back to the GroupComplete node due to an exception, the message is propagated to the failure terminal. No retries at processing the group will be made and the group data will be discarded after propagating to the failure terminal.

Activity log

Entries are made into the activity log with the following inserts:
  • When a completed or complete-early group is processed by the node.
  • When a timed-out group is processed by the node.
  • When a timed-out unknown message is processed by the node.