MQTTSubscribe node
Use the MQTTSubscribe node to receive messages from an application or device that publishes messages by using the MQ Telemetry Transport (MQTT) messaging protocol. IBM® Integration Bus can then propagate these messages in a message flow.
- Developer
- Application Integration Suite
- Standard
- Advanced
- Express
- Scale
- Adapter
This topic contains the following sections:
Purpose
The MQTTSubscribe node subscribes to one or more topics, which you specify, on an MQTT server, and propagates the received messages in a message flow.
The MQTTSubscribe node is contained in the MQTT drawer of the palette, and is represented in the IBM Integration Toolkit by the following icon:
Using this node in a message flow
Use the MQTTSubscribe node to receive messages that are published by applications and devices to topics that are hosted on an MQTT server. The received messages can then be processed within a message flow.
For more information about how this node handles client IDs for MQTT connections, and scalability, see Using MQTT with IBM Integration Bus. For more information about how this node handles messages that are delivered with different quality of service (QoS) levels, see Quality of service and connection management.
Local environment variables
When the MQTTSubscribe node propagates a message, it stores information about it in the local environment subtree called LocalEnvironment.MQTT.Input. The following table lists the local environment variables for the MQTTSubscribe node. The elements contain data about the current record.
Table of local environment variables
| Element Name | Element Data Type | Description |
|---|---|---|
| Duplicate | BOOLEAN | Whether the message is a duplicate of a previous message. Set to TRUE or FALSE. |
| Retained | BOOLEAN | Whether the message is a retained message. Set to TRUE or FALSE. Retained is set to TRUE if the message was kept by the server and is now being sent when the client first connects to the server. |
| Topic | CHARACTER | The name of the MQTT topic the received message was published to. |
| QualityOfService | INTEGER | Quality of service of the received message. Set to 0 (at most once), 1 (at least once), or 2 (exactly once). |
Terminals and properties
When you add an MQTTSubscribe node to a message flow, you can use the Properties view in the Message Flow editor to configure it. To display field help, click within a field, and then click the information icon that is displayed at the beginning of the field. All mandatory properties that do not have a default value defined are marked with an asterisk. For general configuration information, see Configuring a message flow node.
You can create and attach operational policies to control particular connection properties for this type of node at run time. For more information about policy, see Operational policy properties.
The following tables describe the node terminals and the node properties that you can set on a specified tab in the Properties view in the Message Flow editor. 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).
Table of node terminals
| Terminal | Description |
|---|---|
| Failure | The output terminal to which the message is routed if an error occurs before the message is propagated to the Out terminal. Even if the Validation property is set, messages that are propagated to this terminal are not validated. |
| Out | If no errors occur within the input node, a message that is received from an external resource is always sent to the Out terminal first. |
| 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. |
Tables of node properties
| Property | M | Default | Description |
|---|---|---|---|
| Node name | Yes | MQTTSubscribe | The name of the node. |
| Short description | No | A brief description of the node. | |
| Long description | No | Text that describes the purpose of the node in the message flow. |
| Property | M | Default | Description |
|---|---|---|---|
| Client ID | Yes | * | The unique name of the client. |
| Topic name | Yes | * | The name of the MQTT topic. |
| Host name | Yes | * | The host name for the MQTT server. |
| Port | Yes | 1883 | The port number for connecting to the MQTT server. |
| Quality of service | No | 0 - At most once | The quality of service level for the delivery of MQTT messages. Valid values are 0 - At most once, 1 - At least once, and 2 - Exactly once. |
| Security identity | No | None | The name of the security identity object that
is created and configured by the mqsisetdbparms command, which
contains the user ID and password to be used by the integration node
to authenticate the connection to the MQTT server. Use the mqsisetdbparms command to set
the security identity user ID and password to be accessed by the integration
node. The default value for this property is None, which signifies that a user ID and password are not passed to the MQTT server. For more information about security identity support, see mqsisetdbparms command. |
| Use SSL | No | Unselected | If selected, the connection between the MQTTSubscribe node and the MQTT server attempts to use SSL; see Securing MQTT connections. |
| Property | M | Default | Description |
|---|---|---|---|
| Message domain | No | BLOB | The domain that is used to parse the message. If the field is blank, then the default is BLOB. |
| Message model | No | Cleared | The name or location of the message model schema
file in which the message is defined. When you click Browse, you see a list of available message model schema files for the selected Message domain. |
| Message | No | Cleared | The name or location of the message root within your message model schema file. This list is populated with all available messages that are defined in the Message model that you selected. |
| Physical format | No | Cleared | The name of the physical format of the message. If you are using the MRM or IDOC parser, select the physical format of the incoming message from the list. This list includes all the physical formats that you have defined for the selected message model. If you set the Message domain property to DataObject, you can set this property to XML or SAP ALE IDoc. Set this property to SAP ALE IDoc when you have to parse a bit stream from an external source and generate a message tree. |
| Property | M | Default | Description |
|---|---|---|---|
| Parse timing | No | On Demand | This property controls when an input 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 | 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. For more information about XMLNSC, see Manipulating messages in the XMLNSC domain. |
| Use XMLNSC compact parser for XMLNS domain | 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 is displayed under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Input Message Parsing properties Message domain is XMLNS. |
| Retain mixed content | No | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in an input 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 | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an input 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 | Cleared | This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in an input 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 | Blank | This property is used to specify a list of elements in the input 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. |
| Property | M | Default | Description |
|---|---|---|---|
| Validate | No | Inherit | This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit. |
| Failure action | 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. |
For a full description of these properties, see Validation properties.
| Property | M | Default | Description |
|---|---|---|---|
| Policy URL | No | The URL that specifies the name and location of the policy document. |
| Property | M | Default | Description |
|---|---|---|---|
| Events | No | 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. |
Configurable properties
The following table describes the node properties that are configurable (you can change the property value when you add the message flow to the BAR file for deployment by using the mqsiapplybaroverride command). The table maps the message flow node properties to the corresponding properties of the mqsiapplybaroverride command.
For more information about configurable properties, see Configurable properties in a BAR file.
Table of configurable properties
| Property | mqsiapplybaroverride command property |
|---|---|
| Client ID | clientId |
| Topic name | topicName |
| Host name | hostName |
| Port | port |
| Quality of service | qos |
| Validate | validateMaster |
| Policy URL | policyUrl |
| Security identity | securityIdentity |
| Use SSL | useSSL |
| Connection URL | connectionUrl |
Operational policy properties
You can create and attach operational policies to MQTT nodes to control the behavior of the node at run time. The following table maps the operational properties of the message flow node to the corresponding properties of the node policy document. Operational properties are properties that you can control the value of at run time by using an operational policy.
For more information about operational policy and how to use a policy in a message flow, see Operational policy and MQTTSubscribe policy.
Table of operational properties
| Property | Policy document property |
|---|---|
| Short description | shortDesc |
| Long description | longDesc |
| Client ID | clientId |
| Topic name | topicName |
| Host name | hostName |
| Port | port |
| Quality of service | qos |