Deciding which nodes to use

WebSphere Message Broker includes a large number of message processing nodes that you can use within your message flows. It also provides an interface that you can use to define your own nodes, known as user-defined nodes.

Your decision about which nodes to use depends on the processing that you want to perform on your messages. The built-in nodes can be considered in several categories, and are displayed in the workbench grouped in those categories (although this grouping has no effect on their operation). You can also categorize user-defined nodes in the same way. The categories are:

Input and output
Input and output nodes define points in the message flow to which clients send messages (input nodes such as MQInput) and from which clients receive messages (output nodes such as MQOutput). Client applications interact with these nodes by putting messages to, or getting messages from, the I/O resource that is specified by the node as the source or target of the messages. Although a message flow must include at least one input node, it does not have to include an output node.
  • If you are creating a message flow that you want to deploy to a broker, you must include at least one input node to receive messages. The input node that you choose depends on the source of the input messages and where in the flow you want to receive the messages:
    MQInput
    If the messages arrive at the broker on a WebSphere MQ queue and the node is to be at the start of a message flow.
    MQGet
    If the messages arrive at the broker on a WebSphere MQ queue and the node is not to be at the start of a message flow.
    SCADAInput
    If the messages are sent by a telemetry device.
    HTTPInput
    If the messages are sent by a Web services client.
    Real-timeInput or Real-timeOptimizedFlow
    If the messages are sent by a JMS or multicast application.
    User-defined input node
    If the message source is a client or application that uses a different protocol or transport.
    Input node
    If you are creating a message flow that you want to embed in another message flow (a subflow) that you will not deploy as a standalone message flow, you must include at least one Input node to receive messages into the subflow.

    An instance of the Input node represents an in terminal. For example, if you have included one instance of the Input node, the subflow icon shows one in terminal that you can connect to other nodes in the main flow in the same way that you connect any other node.

    You can deploy only message flows that have at least one input node. If your message flow does not contain an input node, you are prevented from adding it to the broker archive file. The input node can be in the main flow, or in a message flow that is embedded in the main flow.

    You can use more than one input node in a message flow. For more information, see Using more than one input node.

  • If you want to send the messages produced by the message flow to a target application, you can include one or more output nodes. The one that you choose depends on the transport across which the target application expects to receive those messages:
    Publication
    If you want to distribute the messages using the publish/subscribe network for applications that subscribe to the broker across all supported protocols. A Publication node is an output node that use output destinations that are identified by subscribers whose subscriptions match the characteristics of the current message.
    MQOutput
    If the target application expects to receive messages on a WebSphere MQ queue, or on the WebSphere MQ reply-to queue specified in the input message MQMD.
    MQReply
    If the target application expects to receive messages on the WebSphere MQ reply-to queue specified in the input message MQMD
    SCADAOutput
    If a telemetry device is the target of the output messages, and the Publication node is not suitable
    HTTPReply
    If the messages are for a Web services client
    HTTPRequest
    If your message flow interacts with a Web service client
    Real-timeOptimizedFlow
    If the target application is a JMS or multicast application
    User-defined output node
    If the target is a client or application that uses a different protocol or transport
    Output node
    If you are creating a message flow that you want to embed in another message flow (a subflow) that you will not deploy as a standalone message flow, you must include at least one Output node to propagate messages to subsequent nodes that you connect to the subflow.

    An instance of the Output node represents an out terminal. For example, if you have included two instances of the Output node, the subflow icon shows two out terminals that you can connect to other nodes in the main flow in the same way that you connect any other node.

Message manipulation, enhancement, and transformation

Most enterprises have applications that have been developed over many years, on different systems, using different programming languages, and different methods of communication. WebSphere Message Broker removes the need for applications to understand these differences because it provides the ability to configure message flows that transform messages from one format to another.

For example, personal names are held in many forms in different applications. Surname first or last, with or without middle initials, upper or lower case: these are just some of the permutations. Because you can configure your message flow to know the requirements of each application, each message can be transformed to the correct format without modifying the sending or receiving application.

You can work with the content of the message to update it in several ways. Your choices here might depend on whether the message flow must handle predefined (modelled) messages, or self-defining messages (for example, XML), or both.

A message flow can completely rebuild a message, convert it from one format to another (whether format means order of fields, byte order, language, and so on), remove content from the message, or introduce specific data into it. For example, a node can interact with a database to retrieve additional information, or to store a copy of the message (whole or part) in the database for offline processing.

The following examples show how important message transformation can be:

  • An order entry application has a Part ID in the body of the message, but its partner stock application expects it in the message header. The message is directed to a message flow that knows the two different formats, and can therefore reformat the information as it is needed.
  • A data-entry application creates messages containing stock trade information. Some applications receiving this message need the information as provided, but others need additional information added to the message about the price to earnings (PE) ratio. The stock trade messages are directed to a message flow that passes the message unchanged to some output nodes, but calculates and adds the extra information for the others. The message flow does this by looking up the current stock price in a database, and uses this value and the trade information in the original message to calculate the PE value before passing on the updated message.

You can also create message flows that interact with each other using these nodes. Although the default operation of one message flow does not influence the operation of another message flow, you can force this by configuring your message flows to store and retrieve information in an external source such as a database.

Compute
You can manipulate message content, transform the message in some way, and interact with a database to modify the content of the message or the database content and pass on one or more new messages using the Compute node. You can use this node to manipulate predefined and self-defining messages.

Use the ESQL editor to create an ESQL module, specific to this node, that contains the statements defining the actions to perform against the message or database. Do not use the ESQL code that you develop for use in a Compute node in any other type of node.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

Start of changeYou can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.End of change

If your message manipulation requirements are complex, complete these within a single Compute node. Fewer, more complex Compute nodes perform better than a larger number of simpler nodes, because the broker parses the message on entry to each Compute node.

Mapping
You can create a new message from the input message by mapping the content of elements of the output message from elements of the input message, or from database content, using the Mapping node. You can also extract parts of the message, and optionally change their content, to create a new output message that is a partial copy of the message received by the node. The Mapping node handles only predefined messages.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

Using a mapping editor, you can develop mappings to perform simple manipulations on predefined messages in the Mapping node. Do not use the mappings that you develop for use in a Mapping node in any other type of node.

Extract
You can use the Extract node to create a new output message from specified elements of the input message. You can extract parts of the message, and optionally change their content, to create a new output message that is a partial copy of the message received by the node. The Extract node handles only predefined messages.

Using a mapping editor, you can develop mappings to perform simple manipulations on predefined messages in the Extract node. Do not use the mappings that you develop for use in an Extract node in any other type of node.

Database
Use the Database node to interact with a database identified by the node properties. The Database node handles both predefined and self-defining messages. Using an ESQL editor, you can code ESQL functions to update database content from the message, insert new information into the database, and delete information from the database, perhaps based on information in the message. Do not use the ESQL code that you develop for use in a Database node in any other type of node.

This node provides a very flexible interface with a wide range of functions. It also has properties that you can use to control the way in which the interaction participates in transactions.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

You can only update a database from this node; you cannot update any message content. If you want to update message content, use the Compute or Mapping node.

DataDelete, DataInsert, DataUpdate
The DataDelete, DataInsert, and DataUpdate nodes are specialized forms of the Database node that provide a single mode of interaction (deletion of one or more rows, insertion of one or more rows, or update of one of more existing rows respectively). The DataDelete, DataInsert, and DataUpdate nodes handle only predefined messages. Use a mapping editor to develop mappings to perform these functions. Do not use the mappings that you develop for these nodes in any other type of node. These nodes also let you control the transactional characteristics of the updates that they perform.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

You can only update databases from these nodes: you cannot update any message content. If you want to update message content, use the Compute or Mapping node.

Warehouse
The Warehouse node provides a store interface that you can use to store all or part of the message in a database, for example, for audit reasons. The Warehouse node handles only predefined messages. Use a mapping editor to develop mappings to perform this action. Do not use the mappings that you develop for a Warehouse node in any other type of node.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

You can only update a database from this node; you cannot update any message content. If you want to update message content, use the Compute or Mapping node.

User-defined
You can include a user-defined node to interact with a database.

You can control the way in which the database is accessed by this node by specifying user and password information for the datasource that you specify in the node property. Use the mqsisetdbparms command to initialize and maintain these values.

The following table summarizes what you can update in these nodes.

Node Update database? Update message? Update LocalEnvironment? Message set required?
Compute Yes Yes Yes No
Database Yes No Yes No
DataDelete Yes No Yes Yes
DataInsert Yes No Yes Yes
DataUpdate Yes No Yes Yes
Extract Yes Yes Yes Yes
Mapping Yes Yes Yes Yes
Warehouse Yes No Yes Yes
XMLTransformation

If you want to transform an input XML message into another format using XMLT style sheets, use the XMLTransformation node. It is imperative that the data can be parsed into a XML message. The result of the transformation is output as a BLOB message. The style sheet, using the rules defined within it, can sort the data; select data elements to include or to exclude based on some criteria, and transform the data into some other data format.

The Xalan-Java transformation engine (http://xml.apache.org/xalan-j) is used as the underlying transformation engine. For details about XMLT, refer to http://www.w3.org/TR/xslt.

You can deploy style sheets and XML files to broker execution groups, to facilitate style sheet and XML file maintenance.

Decision making

You can use nodes that determine the order and flow of control within the message flow in various ways to make decisions about how messages are processed by the flow. You can also use nodes (TimeoutControl and TimeoutNotification) that determine the time, and frequency of occurrence, of events within the message flow. Routing is independent of message transformation, although the route a message takes might determine exactly what transformation is performed on it.

For example, a money transfer application always sends messages to one other application. You might decide that every message with a transfer value of more than $10,000 must also be sent to a second application, to enable all high-value transactions to be recorded.

In another example, a national auto club offers a premier service to specific members for orders above a threshold value. Most orders are routed through the usual channels, but, if the membership number and order value meet certain criteria, the order gets special treatment.

You can also establish a more dynamic routing option by building additional routing information into the message when it is processed. Optional sets of rules are set up to receive messages according to values (destinations) set into the message. You can establish these rules such that a message is processed by one or more of the optional sets of rules, in an order determined by the added message content.

Use the following nodes to make decisions about the route that a message follows through the message flow:

Check
You can inspect the message characteristics to determine its structure, and route the message according to whether it meets the required characteristics.
Filter
You can code an ESQL statement to determine the next node to which the message is sent by this node. Do not use the ESQL code that you develop for use in a Filter node in any other type of node.

The node's terminals are true, false, unknown, and failure; the message is propagated to the true terminal if the test succeeds, and to the false terminal if it fails. If the statement cannot be resolved (for example, it tests the value of a field that does not appear in the input message), the message is propagated to the unknown terminal. If any other error is detected, the message is propagated to the failure terminal.

The test in the ESQL statement can depend on message content, database content, or a combination of these.

If you reference a database, you can control the way in which it is accessed by this node by specifying user and password information for each datasource defined in the registry on the broker system. On distributed systems, use the mqsisetdbparms command to initialize and maintain these values.

On z/OS, use the broker started task ID to access the database.

Use this node in preference to the Compute node to provide this function; although you can configure the Compute node to control message selection and routing, the Filter node performs better.

FlowOrder
You can connect the terminals of this node to force the message to be processed by one sequence of nodes, followed by a second sequence of nodes.
Passthru
Use the Passthrough node in a subflow as the first node that follows the Input node to identify the subflow in which it is included. For example, if you develop an error processing subflow to include in several message flows, you might want to modify that subflow. However, you might want to introduce the modified version initially to just a subset of the message flows in which it is included. Set a value for the instance of the Passthrough node that identifies which version of the subflow you have included.
RouteToLabel and Label
You can define a list of destinations in a Compute node that are acted on by the RouteToLabel node, which interrogates the destinations and passes the message on to the corresponding Label node.
ResetContentDescriptor
You can set new message properties that are used when the message bit stream is next parsed by a subsequent node in the message flow.

You might want a batch job to run every day at a specific time, or you might want information to be processed and published at fixed intervals (for example, currency exchange rates are calculated and sent to banks), or you might want to take a specified recovery action if certain transactions are not completed within a defined time. For all these cases two timeout nodes (TimeoutControl and TimeoutNotification) are provided.

TimeoutControl
Use a TimeoutControl node and a TimeoutNotification node together in a message flow to control events that occur at a specific time or at defined time intervals. The TimeoutControl node receives an input message that contains a timeout request. This input message is validated and stored (all or a part of the message) to be propagated by an associated TimeoutNotification node in the message flow. The input message is also propagated unchanged to the next node in the message flow.
Note: More than one TimeoutControl node can be associated with each TimeoutNotification node.
TimeoutNotification
Use a standalone TimeoutNotification node to generate messages that are propagated at configured times or time intervals to the next node in the message flow for further processing.
Collating requests

You can collate related requests and responses using the AggregateControl, AggregateReply, and AggregateRequest nodes. Use these nodes to generate several requests in response to one input message, and to control and coordinate the responses that are received in response to those requests, and to combine the information provided by the responses to continue processing.

Error handling and reporting

You can use nodes that affect error handling and reporting:

Trace
When you include a Trace node, you can generate one or more trace entries to record what is happening in the message flow at this point.
TryCatch
When you include a TryCatch, you can control the error processing when exceptions are thrown.
Throw
When you include a Throw node, you can force an exception to be thrown, and specify the identity of the exception, to make it easier to diagnose the problem.

With the exception of the Compute, Extract, and Mapping nodes, the input message received by a node and the output message sent on by the node are identical.

Related concepts
Message flows overview
End-user application support
LocalEnvironment tree
Related tasks
Setting up DB2
Designing a message flow
Accessing databases from message flows
Creating a message flow
Defining message flow content
Using nodes for decision making
Deploying
Related reference
mqsisetdbparms command
Built-in nodes
End-user application support