TimeoutNotification node

Use the TimeoutNotification node to manage timeout-dependent message flows.

The TimeoutNotification node is available in the following operation modes:
  • Developer
  • Application Integration Suite
  • Standard
  • Advanced
  • Express
  • Scale
  • Adapter
For more information, see Operation modes.

Information about the state of in-flight messages is held on storage queues that are controlled by WebSphere® MQ, so you must install WebSphere MQ on the same computer as your integration node if you want to use the capabilities provided by the TimeoutNotification node. The storage queues that hold the state information are owned by the queue manager that is associated with the integration node, and you specify this queue manager by using the -q property of the mqsicreatebroker command. For more information about the queues that are required by the TimeoutNotification node, see Configuring the storage of events for timeout nodes.

This topic contains the following sections:

Purpose

The TimeoutNotification node is an input node that you can use in two ways:

  • A TimeoutNotification node can be paired with one or more TimeoutControl nodes.

    The TimeoutNotification node processes timeout request messages that are sent by the TimeoutControl nodes with which it is paired, and propagates copies of the messages (or selected fragments of the messages) to the next node in the message flow.

  • A TimeoutNotification node can be used as a stand-alone node.

    Generated messages are propagated to the next node in the message flow at time intervals that are specified in the configuration of this node.

The TimeoutNotification node is contained in the Timer drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

Timeout Notification node icon

Using this node in a message flow

Use a TimeoutControl node and a TimeoutNotification node together in a message flow for an application that requires events to occur at a particular time, or at regular intervals; for example, when you want a batch job to run every day at midnight, or you want information about currency exchange rates to be sent to banks at hourly intervals.

You can use more than one TimeoutControl node with a TimeoutNotification node. Timeout requests that are initiated by those TimeoutControl nodes are all processed by the same TimeoutNotification node if the same Unique Identifier is used for the TimeoutNotification node and each of the TimeoutControl nodes. However, do not use the same Unique identifier for more than one TimeoutNotification node.

You can use TimeoutControl nodes with a TimeoutNotification node that is in a separate message flow only if the following conditions are met: 
  • The same Unique identifier is used for your TimeoutNotification node and each of your TimeoutControl nodes
  • The message flow that contains your TimeoutControl nodes and the message flow that contains your TimeoutNotification node are deployed to the same integration server

Timeout request messages are stored for processing on a queue used by the TimeoutNotification node. By default, this queue is the SYSTEM.BROKER.TIMEOUT.QUEUE. However, you can use a Timer configurable service to specify an alternative timeout queue, which provides greater control over the storage of messages. For information about using an alternative timeout queue, see Configuring the storage of events for timeout nodes.

When a TimeoutNotification node is started as a result of the integration node starting, or by the message flow that contains the node starting, it scans its internal timeout store and purges any non-persistent timeout requests. Notifications are issued for any persistent timeout requests that are now past and that have the IgnoreMissed property set to False.

If you use a TimeoutNotification node to generate a WebSphere MQ message to an output node, such as theMQOutput node, provide a valid MQMD. You must also provide a valid MQMD if the TimeoutNotification node is running in automatic mode (as a stand-alone node). If the TimeoutNotification node is running in controlled mode (that is, it is paired with one or more TimeoutControl nodes), you must provide a valid MQMD only if the stored messages do not already have an MQMD. The following ESQL shows how to provide a valid MQMD:
CREATE NEXTSIBLING OF OutputRoot.Properties DOMAIN 'MQMD';
SET OutputRoot.MQMD.Version = MQMD_CURRENT_VERSION;
SET OutputRoot.MQMD.Format = 'XML';

Terminals and properties

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

Terminal Description
Failure The output terminal to which the message is propagated if a failure is detected during processing in this node. Nodes can be connected to this terminal to process these failures. If this terminal is not connected to another node, messages are not propagated and no logging or safe storage of data occurs.
Out The output terminal to which messages are propagated after timeouts expire.
  • If the TimeoutNotification node is running in Automatic mode (that is, there are no TimeoutControl nodes paired with this node), the propagated messages contain only a Properties folder and a LocalEnvironment that is populated with the timeout information.
  • If the TimeoutNotification node is running in Controlled mode (that is, TimeoutControl nodes that are paired with this node store timeout requests), the propagated messages contain what was stored by the TimeoutControl nodes, which might be entire request messages or fragments of them.
If the TimeoutNotification node is used as the input node to a message flow that generates a WebSphere MQ message (for example, by using an MQOutput node), the message flow must create the necessary MQ headers and data (for example, MQMD).
Catch The output terminal to which the message is propagated if an exception is thrown downstream. If this terminal is not connected to another node, the following events occur:
  1. The TimeoutNotification node writes the error to the local error log.
  2. The TimeoutNotification node repeatedly tries to process the request until the problem that caused the exception is resolved.

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 Description properties of the TimeoutNotification node are described in the following table.

Property M C Default Description
Node name No No The node type: TimeoutNotification 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 Basic properties of the TimeoutNotification node are described in the following table.

Property M C Default Description mqsiapplybaroverride command property
Unique Identifier Yes Yes None A value that uniquely identifies the TimeoutNotification node. Specify the same value in the Unique Identifier for the TimeoutControl nodes with which this node is paired (if there are any). The maximum length of this identifier is 12 characters.

This name is also used to identify a Timer configurable service (if one exists) to be used by the node.

Do not use the same Unique Identifier for more than one TimeoutNotification node.

 uniqueIdentifier
Transaction Mode No No Yes The transaction mode for the node. If the transaction mode is Automatic, a transaction is based on the persistence of the stored messages, which is controlled by the Request Persistence property of the TimeoutControl node with which it is paired. You can set this property to one of the following values:
  • Select Yes if you want a transaction to be started.
  • Select No if you do not want a transaction to be started.
  • Select Automatic only if you have set Operation Mode to Controlled. Whether a transaction is started depends on the persistence of the stored timeout requests, which is controlled by the value of Request Persistence in the TimeoutControl node with which it is paired.
  
Operation Mode No No Automatic This property indicates whether this node is paired with any paired TimeoutControl nodes. Valid values are:
  • If you select Automatic the node is not paired with any TimeoutControl nodes. The node generates timeout requests with an interval that is controlled by the setting of the Timeout Value property, which must be a positive integer.
  • If you select Controlled the node processes all timeout requests that have been stored by the TimeoutControl nodes with which it is paired.
  
Timeout Interval No Yes 1 The interval (in seconds) between timeout requests. This property is relevant only if Operation Mode is set to Automatic.

The value of this property must be a positive integer.

If the Operation Mode is set to Automatic, the value of the Timeout Interval property is overridden by the Timeout interval property, if set, in the Timer configurable service.

 timeoutInterval

The properties of the Parser Options for the TimeoutNotification node are described in the following table.

Property M C Default Description
Parse Timing No No On Demand This property controls when the timeout message is parsed. Valid values are On Demand, Immediate, and Complete.

By default, this property is set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand.

Build tree using XML schema data types No No Cleared This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML Schema. You can select this property only if you set the Validate property on the Validation tab to Content or Content and Value.
Use MQRFH2C Compact Parser for MQRFH2 Domain No No Cleared This property controls whether the MQRFH2C Compact Parser, instead of the MQRFH2 parser, is used for MQRFH2 headers.
Use XMLNSC Compact Parser for XMLNS Domain No No Cleared This property controls whether the XMLNSC Compact Parser is used for messages in the XMLNS Domain. If you set this property, the message data appears under XMLNSC in nodes that are connected to the output terminal when the input RFH2 header or default properties Domain is XMLNS.
Retain Mixed Content No No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in a timeout message. If you select the check box, elements are created for mixed text. If you clear the check box, mixed text is ignored and no elements are created.
Retain Comments No No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in a timeout message. If you select the check box, elements are created for comments. If you clear the check box, comments are ignored and no elements are created.
Retain Processing Instructions No No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in a timeout message. If you select the check box, elements are created for processing instructions. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements No No Blank This property is used to specify a list of elements in the timeout message that are to be opaquely parsed by the XMLNSC parser. Opaque parsing is performed only if validation is not enabled (that is, if Validate is None); entries that are specified in Opaque Elements are ignored if validation is enabled.

The Validation properties of the TimeoutNotification node are described in the following table.

If a message is propagated to the Failure terminal of the node, it is not validated. For more information, see Validating messages and Validation properties.
Property M C Default Description mqsiapplybaroverride command property
Validate No Yes None This property controls whether validation takes place. Valid values are None, Content, and Content And Value. validateMaster
Failure Action No No Exception This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.  
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.