RouteToLabel node

This topic contains the following sections:

Purpose

Use the RouteToLabel node in combination with one or more Label nodes to dynamically determine the route that a message takes through the message flow, based on its content. The RouteToLabel node interrogates the LocalEnvironment of the message to determine the identifier of the Label node to which to route the message.

You must precede the RouteToLabel node in the message flow with a Compute node that populates the LocalEnvironment of the message with the identifiers of one or more Label nodes introducing the next sequence of processing for the message. The destinations are set up as a list of label names in the LocalEnvironment tree in a specific location. This excerpt of ESQL from the Airline Reservations sample (linked to below) provides an example of how to set up the LocalEnvironment content in a Compute node:

IF InputRoot.XML.PassengerQuery.ReservationNumber<>'' THEN
   SET OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelname = 'SinglePassenger';
ELSE
   SET OutputLocalEnvironment.Destination.RouterList.DestinationData[1].labelname = 'AllReservations';
END IF;

The label names can be any string value, and can be explicitly specified in the Compute node, taken or cast from any field in the message, or retrieved from a database. A label name in the LocalEnvironment must match the Label Name property of a corresponding Label Node.

When you configure the Compute node, you must also select a value for the Compute Mode property from the drop-down list that includes LocalEnvironment.

Design your message flow such that a RouteToLabel node logically precedes one or more Label nodes within a message flow, but do not physically wire the RouteToLabel node with a Label node. The connection is made by the broker, when required, according to the contents of LocalEnvironment.

The RouteToLabel node is represented in the workbench by the following icon:

RouteToLabel node icon

Using this node in a message flow

Look at the following sample to see how you can use this node:

Configuring the RouteToLabel node

When you have put an instance of the RouteToLabel node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.

Configure the RouteToLabel node as follows:

  1. Set Mode. This defines how the RouteToLabel node removes destinations from the LocalEnvironment associated with the message. You can set one of two values:
    • Route To First removes the first item from LocalEnvironment. The current message is routed to the Label node identified by labelName in that list item.
    • Route To Last (the default) removes the last item from LocalEnvironment. The current message is routed to the Label node identified by labelName in that list item.
  2. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  3. Click Apply to make the changes to the RouteToLabel node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Terminals and properties

The RouteToLabel node terminals are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the message is routed if a failure is detected during processing.

The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog 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 RouteToLabel node Basic properties are described in the following table.

Property M C Default Description
Mode Yes No Route To Last How the RouteToLabel node processes the items within LocalEnvironment associated with the current message

The RouteToLabel node Description properties are described in the following table.

Property M C Default Description
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.