GroupGather node

Use the GroupGather node to fan in responses that are part of a group.

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 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 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 GroupGather node is contained in the Routing drawer of the palette, and is represented in the IBM App Connect Enterprise Toolkit by the following icon:

GroupGather node icon

Terminals and properties

When you have put an instance of the GroupGather 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 GroupGather node terminals are described in the following table.

Terminal	Description
In	A message received is treated as a potential reply to an in-flight group
Out	Propagates the originally received message to the output terminal along with group information for the matched Group written to the `LocalEnvironment.WrittenDestination.GroupGather` folder.
Unknown	Propagates the originally received message to the unknown terminal along with the Group unknown message information written to the `LocalEnvironment.WrittenDestination.GroupGather` folder.
Failure	If wired and an exception occurs within the node, which does not originate from the downstream flow then the message, with its exception list is propagated down this terminal.

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 GroupGather 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 GroupGather 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.
Unknown message timeout	Yes	Yes	5.0	The amount of time, in seconds, to wait for for unknown replies. The default value is 5.0 seconds. You can specify a timeout for the group in seconds, in units of seconds accurate to tenths of a second. You can set this property to -1 for the group to wait indefinitely, however -1 is not recommended as this might cause memory issues.

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

In terminal

When a message is received at the in terminal it is treated as a potential reply to an in-flight group. The copy of the message body is serialized and stored in memory, either as a reply to a known in-flight group, or as an unknown message that can be matched against a group that may be created soon. The reply ID for the message is read from a LocalEnvironment override, or can be inferred from the transport used if the message was sent using one of the transports that have built-in support for the group nodes.

It is recommended that the flows downstream of the out and unknown terminals be lightweight to prevent tying up a reply processing message thread for too long.

Out terminal

When a reply is received and it is successfully matched to an active group, the original message is propagated to the out terminal with information about the group that it was added to:

LocalEnvironment
    WrittenDestination
        GroupGather
            GroupName (CHARACTER)
            GroupId (BLOB)
            Reply
                ReplyId (BLOB)
                OriginalRequestSendTime (INTEGER)
                FolderName (CHARACTER)
                ReplyReceiptTime (INTEGER)

where ReplyReceiptTime is the time that the reply was matched, and saved to an active group.

Unknown terminal

When a reply is received and it cannot be matched to an active group, the original message is propagated to the Unknown terminal with the following information written to the Local Environment:

LocalEnvironment
    WrittenDestination
        GroupGather
            GatherTime (INTEGER)
            Reply
                UnknownReplyId (BLOB)

where GatherTime is the time the GroupGather node attempted to match the message to an active group. This is to allow the flow designer to diagnose issues where poor performance in the portion of the flow preceeding the GroupGather node which may lead to timeouts and unknown messages occurring.

Local environment overrides

You can override the following node properties dynamically in the local environment. You can set the following values under LocalEnvironment.Destination.GroupGather.

Table 1. Local environment overrides for the GroupGather node
Setting	Description
ReplyId	When creating a group the flow designer can specify custom requests that may correspond to transports that are not currently natively supported by the group nodes. Correspondingly the GroupGather node looks for the following LocalEnvironment variable to determine the reply ID: `LocalEnvironment.Destination.GroupGather.ReplyId` If this override is not present the node attempts to find a suitable reply ID based on the reply protocol of the message. If a suitable reply ID cannot be found an exception is thrown.
Unknown timeout	The flow designer may want to override the unknown message timeout on a per message basis. This can be done by setting the following override: `LocalEnvironment.Destination.GroupGather.UnknownTimeout` This override is interpreted in the same manner as the Unknown message timeout node attribute in that it has a resolution of 0.1s and may be set to a value of -1 to mean wait indefinitely.

Transactions

The node is non-transactional. Regardless of the transaction mode on the flow, when a message has entered the GroupGather node the alterations made to the reply group or unknown message are listed immediately. The state is not rolled back if an exception originates from a downstream node.

Activity log

Entries are made into the activity log with the following inserts:

On the receipt of a known reply – Inserts include the group name, group ID, folder name, request ID, original request send time, and reply receipt time.
On the receipt of an unknown reply – Inserts include the group name, reply ID and receipt time.