GroupScatter node

Use the GroupScatter node to mark the beginning of a fan-out of requests that are part of a group.

The group nodes provide the ability to create fan-out and fan-in style static and dynamic aggregation scenarios that are stateless and perform well without requiring an IBM® MQ queue manager to be available for the integration server. The GroupScatter node, which is analogous to the AggregateControl node, is responsible for creating a new group, and enables downstream nodes to send requests that are marked as part of the group.

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 and reply application model. Grouping 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 reconciles incoming messages as replies to groups, or stores unknown messages to reconcile with groups that might still be under construction.
The GroupComplete node delivers groups that have been completed or timed-out groups and unknown messages that have reached their timeout limit. The GroupComplete node marks the end of a grouping fan-in action (GroupGather). The node collects replies and combines them into a single reply message.

The GroupScatter node is contained in the Routing drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:

GroupScatter node icon

Terminals and properties

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

Terminal	Description
In	When a message is received on the In terminal, a new group is created by using either the node settings or local environment overrides.
Out	The original message is propagated to the output terminal, and group information is written to the local environment.
Failure	If the Failure terminal is wired and an exception occurs in the node that does not originate from the downstream flow, the message, with its exception list, is propagated down this terminal.
Group Created	If the Group created terminal is wired, a message is propagated down this terminal, with the detailed group information, after the group has been committed. The purpose of this terminal is to allow logging and debugging of groups.

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 GroupScatter node Description properties are described in the following table:

Property	M	C	Default	Description
Node name	No	No	The node type (GroupScatter)	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 GroupScatter 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 that are participating in the same group processing. Note: All nodes with the same group name must be deployed to the same integration server. Group nodes cannot be used to orchestrate groups across multiple integration servers. You can use the same group name across different integration servers and integration nodes.
Group timeout	Yes	Yes	5.0	The amount of time, in seconds, to wait for replies to arrive at the fan-in process. 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, this setting can 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; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.

Behavior

Out terminal

When a message is received from the In terminal, a new group is created and a unique group ID is assigned to it. The received message is propagated to the Out terminal, and the following group information is written to the local environment:

LocalEnvironment
    WrittenDestination
        GroupScatter
            GroupName (CHARACTER)
            GroupId (BLOB)
            GroupCreationTime (INTEGER)
            Timeout (INTEGER)

Where GroupName is the Group name attribute that is specified on the node, the GroupCreationTime is the time, in milliseconds, since the group was constructed in the GroupScatter node, and Timeout is the number of seconds that specifies the group commit time when the group will time out.

If creating a new group would exceed the limit for in-flight and in-construction groups that is set by the group director, an exception is issued.

Group Created terminal

After the message has been propagated from the Out terminal and the group has been committed, a new copy of the original message is sent from the Group Created terminal with the information about the group that has just been created and committed. This following information is stored in the LocalEnvironment tree:

LocalEnvironment
    WrittenDestination
        GroupScatter
            GroupName (CHARACTER)
            GroupId (BLOB)
            GroupCreationTime (INTEGER)
            Timeout (INTEGER)
            GroupCommitTime (INTEGER)
            Requests
                ReplyId (BLOB)
                RequestSendTime (INTEGER)
                FolderName (CHARACTER)
            Requests
                …
            …

Where the GroupCommitTime is the time at when the group was sealed for requests and the timeout timer starts.

Overrides

Local environment overrides

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

Table 1. Local environment overrides for the GroupScatter node
Setting	Description
Timeout	Overrides the Group timeout property on the node (in units of seconds); for example: `SET LocalEnvironment.Destination.GroupScatter.Timeout = 180;`

Environment overrides

Before the GroupScatter node commits the group, the node adds the following branches to the group if they are present in the Environment tree. You can therefore specify correlation logic for transports that have not been enabled explicitly, including those where the request and reply correlation information might be contained in the message body itself.

Environment
    Destination
        GroupScatter
            Context (FOLDER/TREE)
            UserRequests
                ReplyId (BLOB)
                RequestSendTime (DECIMAL)
                FolderName (CHARACTER)
            UserRequests
                …
            …

Note: Note that any subtree that is attached to the Context element is serialized and stored as part of the group immediately before the group is committed. The state of the tree should be generated at the point of rollback and as such, the environment tree should be used.

Transactions

The GroupScatter node does not change its behavior based on the transaction mode of the flow. The group is committed when execution returns to the GroupScatter node after the message is propagated from the Out terminal. If an unhandled exception is thrown back to the GroupScatter node downstream of the Out terminal, the partially constructed group is discarded.

Note: If an exception is thrown downstream of the Group Created terminal and this exception is uncaught, it rolls back the transaction and cancels any transactional requests that were sent with the group, but the group itself is not discarded.

Activity log

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

When a group is created: Inserts include the group creation time, group name, and group ID.
When a group is committed: Inserts include the group name, group ID, group creation time, group commit time, and the total number of requests that were made (including user requests).
When a group is discarded because of an exception: Inserts include the group name, group ID, creation time, rollback time, and the total number of requests that have been made so far.