MQTTSubscribe node

Use the MQTTSubscribe node to subscribe to published data from your message flow.

Purpose

Use the MQTTSubscribe node to receive messages that are published to a topic, on an MQTT server, to which you are subscribed. The message is sent only once.

For more information about MQTT, see MQTT.

The MQTTSubscribe node is contained within the MQTT drawer of the message flow palette, and is represented in the IBM Integration Toolkit by the following image:

MQTTSubscribe node

Using the MQTTSubscribe node in a message flow

Before you can use MQTT, you must complete the postinstallation step to set up MQTT, see Completing the postinstallation steps for IBM Integration Bus Manufacturing Pack.

Configuring the MQTTSubscribe node

Configure the MQTTSubscribe node by modifying the properties.

Multiple execution group scaling with the same BAR file is not supported. Additional instances of a message flow in a single execution group is supported.

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

Terminals and properties

The MQTTSubscribe node terminals are described in the following table.
Terminal Description
Failure The output terminal to which a message is routed if an error occurs during processing.
Out The output terminal to which a message is routed if the record is written successfully. The message is unchanged except for status information in the Local Environment.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node. Exceptions are caught only if this terminal is attached.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (a mandatory property is 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 broker archive (BAR) file to deploy it).

The Description properties for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Node name Yes No The node type, MQTTSubscribe. 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 for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Client ID Yes Yes   The unique ID of the MQTT client. Provide a unique name of a 1 - 23 byte string for the MQTT client connection. For more information, see MQTT Protocol Specification.
Topic name Yes Yes   The name of the MQTT topic that the node subscribes to. Levels in the hierarchy are delimited by the forward slash (/) character; for example, Hypertension/Alert. For more information, see MQTT Protocol Specification.
Host name Yes Yes   The host name for the MQTT server; for example, localhost.
Port Yes Yes 1883 The port number to use to connect to the MQTT server; for example 1883.
The Input Message Parsing properties for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Message domain No Yes   The name of the domain that is used to parse the incoming message.
To enable this property, select a value from the drop-down list or specify a user-defined parser.
  • If you are parsing an XML message, select the XMLNSC parser.
  • For binary or text messages with a Data Format Description Language (DFDL) schema model, select the DFDL parser.
  • To access the byte data without parsing, select the BLOB parser.
  • If you do not specify a parser, the BLOB parser is used, and the binary data can be accessed directly within the flow.

The data can be reparsed with a different parser at any point in the flow by using the ResetContentDescriptor node, or by using a parse clause in a Compute node.
Message model No Yes   The name of the schema file, or the name or identifier of the message set, in which the incoming message is modeled.

To enable this property, set the Message domain property to DFDL or XMLNSC and select a schema file, or set the Message domain property to MRM or IDOC and select a message set.

Only message models that are contained in your Integration project, or are contained in a referenced application or library, are available for selection.

Qualify this property by specifying a library name if the name of your schema file, or the qualified message name that you selected in the Message property, is not unique within the referenced resources.
Message No Yes   The namespace qualified name of the incoming message.

To enable this property, set the Message domain property to DFDL or MRM and select a message model. Only message names from the selected message model are available for selection.
Physical format No Yes   The physical format name of the incoming message, as specified in the message set.

To enable this property, set the Message domain property to MRM or IDOC.
The Parser Options properties for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Parse timing No Yes On Demand The timing of when the input message is parsed. The following values are available:
  • On Demand: Parses an input message bit stream only as far as is necessary to satisfy the current reference (partial parsing).
  • Immediate: Parses the entire message, including any message headers.
  • Complete: Parses the entire message, including any message headers.

The difference in behavior between the Immediate and Complete values occurs when MRM validation is enabled.
XMLNSC Parser Options No Yes   You can customize the XML parser by selecting any of the following options:
  • Build tree using XML schema data types: Select this property to create syntax elements in the message tree with data types taken from the XML schema. To enable this property, set the Validate property on the Validation tab to Content or Content and Value.
  • Use XMLNSC compact parser for XMLNS domain: Select this property to use the XMLNSC Compact Parser for messages in the XMLNS Domain. If you set this property, the response message data is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or the Input Message Parsing property Message domain is XMLNS.
  • Retain mixed content: Select this property to create elements in the message tree when the parser finds mixed text in an input message. If you clear the check box, mixed text is ignored and no elements are created.
  • Retain comments: Select this property to create elements in the message tree when the parser finds comments in an input message. If you clear the check box, comments are ignored and no elements are created.
  • Retain processing instructions: Select this property to create elements in the message tree when the parser finds processing instructions in an input message. If you clear the check box, processing instructions are ignored and no elements are created.
Opaque elements No Yes   The elements that you want to parse opaquely. These elements are not referenced by the message flow. You can add, edit, and delete these elements.
Note: If validation is enabled in the Validation tab, no opaque parsing is performed. Any entries in the Opaque elements table are ignored.
The Validation properties for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Validate No Yes None The type of validation that you want to use. The following values are available:
  • None: Does not validate the message.
  • Content and Value: Validates the message content and value checks, such as whether the value conforms to data type, length, range, and enumeration.
  • Content: Validates the content and message composition.
Note: If validation is enabled, no opaque parsing is performed. Any entries in the Opaque elements table are ignored
Failure action No Yes Exception The action to take if the message flow is invalid. The default value is Exception unless the value of Validate is either Content or Content and Value, in which case the following values are available:
  • User Trace: Logs all validation failures to user trace, even if user tracing of the message flow is not requested. Use this setting if you want processing of the message to continue regardless of validation failures.
  • Local Error Log: Logs all validation failures to the system log. Use this setting if you want processing of the message to continue regardless of validation failures.
  • Exception: Throws an exception on the first validation failure. If you asked for user tracing of the message flow, the failure is also logged in the user trace and validation stops. Use this setting if you want processing of the message to halt as soon as a failure happens.
  • Exception List: Throws an exception if validation failures happen, but only when the current parsing or writing operation completes. If you asked for user tracing of the message flow, each failure is also logged in the user trace and validation stops. Use this setting if you want processing of the message to halt if a validation failure occurs, but you want to see the full list of failures.
    Note: This property is affected by the Parse timing property; when partial parsing is selected, the current parsing operation parses only a portion of an input message, so only the validation failures in that portion of the message are reported.
The Monitoring properties for the MQTTSubscribe node are described in the following table.
Property M C Default Description
Events Yes Yes   Events that you define for the node are displayed in 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. For more information, see Configuring monitoring event sources by using monitoring properties in the IBM Integration Bus documentation.

You can enable and disable events that are shown here by selecting or clearing the Enabled check box.
Related reference:
MQTTPublish node
Notices | Trademarks | Downloads | Library | Support

Copyright IBM Corporation 2016 Copyright IBM Corporation 2016.
Last updated Last updated : 2016-07-30 06:30:50


Reference topicReference topic | Version 1.0.0.2 | ma00440