Deciding which nodes to use

Before you start:

Read the concept topic about message flow nodes.

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.

    Start of changeThe use of message flows that contain MQeInput nodes in WebSphere Message Broker Version 6.0 is deprecated. Redesign your message flows to remove the MQe nodes and replace them with MQ nodes that are configured to your own specifications and coordinated with your MQe Gateway configuration. For more details, see Migrating a message flow that contains WebSphere MQ Everyplace nodes.End of change

    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
    Start of changeIf the messages are sent by a JMS or multicast application. The Real-timeInput node is an input node and the Real-timeOptimizedFlow node is a complete message flow that provides a high performance publish/subscribe message flow.End of change
    Start of changeJMSInputEnd of change
    Start of changeIf the messages are sent by a JMS application.End of change
    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.

    Start of changeThe use of message flows that contain MQeOutput nodes in WebSphere Message Broker Version 6.0 is deprecated. Redesign your message flows to remove the MQe nodes and replace them with MQ nodes that are configured to your own specifications and coordinated with your MQe Gateway configuration. For more details, see Migrating a message flow that contains WebSphere MQ Everyplace nodes.End of change

    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
    Start of changeJMSOutputEnd of change
    Start of changeIf the messages are for a JMS destination.End of change
    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.

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.

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.

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 (Apache Xalan-java XSLT processor) is used as the underlying transformation engine. For details about XMLT, refer to W3C XSL Transformations.

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

Start of changeJMSMQTransformEnd of change
Start of changeUse the JMSMQTransform node to transform a message with a JMS message tree into a message that has a message tree structure compatible with the format of messages that are produced by the WebSphere MQ JMS provider.

The JMSMQTransform node can be used to send messages to legacy message flows and to interoperate with WebSphere MQ JMS and WebSphere Message Broker publish subscribe.

End of change
Start of changeMQJMSTransformEnd of change
Start of changeUse the MQJMSTransform node to receive messages that have a WebSphere MQ JMS provider message tree format, and transform them into a format that is compatible with messages that are to be sent to JMS destinations.

The MQJMSTransform node can be used to send messages to legacy message flows and to interoperate with WebSphere MQ JMS and WebSphere Message Broker publish subscribe.

End of change
Start of changeMQOptimizedFlowEnd of change
Start of change

Use the MQOptimizedFlow node to replace a publish/subscribe message flow that consists of an MQInput node connected to a Publication node and that uses the JMS over WebSphere MQ transport. The MQOptimizedFlow node cannot be used on z/OS systems.

Use the MQOptimizedFlow node to improve performance, particularly where a single publisher produces a persistent publication for a single subscriber.

End of change
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
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:

Start of changeValidateEnd of change
Start of changeUse the Validate node to check that the message that arrives on its input terminal is as expected. You can check that the message has the expected message template properties (that is, the message domain, message set and message type) and that the content of the message is correct. You can check the message against one or more of message domain, message set or message type.

The Validate node replaces the Check node which is deprecated in WebSphere Message Broker Version 6.0 and subsequent releases. The Validate node works in the same way as the Check node, but it has additional Validation properties to allow the validation of message content by parsers that support that capability.

End of change
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 data source 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.
Start of changePassthroughEnd of change
Start of changeUse the Passthrough node to enable versioning of a subflow at run time. The Passthrough node allows you to add a label to your message flow or subflow. By combining this label with keyword replacement from your version control system, you can identify which version of a subflow is included in a deployed message flow. You can use this label for your own purposes. If you have included the correct version keywords in the label, you can see the value of the label:
  • Stored in the broker archive (BAR) file, using the mqsireadbar command
  • As last deployed to a particular broker, on the properties of a deployed message flow in the Message Brokers Toolkit
  • In the run time, if you enable user trace for that message flow.
End of change
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.

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 structure
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