MQTTPublish node

Use the MQTTPublish node to publish messages from a message flow to a topic on an MQ Telemetry Transport (MQTT) server.

The MQTTPublish node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale
Adapter

For more information, see Operation modes.

This topic contains the following sections:

Purpose

The MQTTPublish node publishes an output message from a message flow to a topic, which you specify, on an MQ Telemetry Transport (MQTT) server.

The MQTTPublish 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 MQTTPublish node to publish messages that are generated within your message flow to a topic that is hosted on an MQTT server. The published messages are then delivered by the MQTT server to all topic subscribers.

For more information about how this node handles client IDs for MQTT connections, 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.

Note: This node was developed as part of the mqtt-client-connector project on GitHub. For more information on the mqtt-client-connector project, see the mqtt-client-connector GitHub repository. This repository includes an example of how an MQTT application or device can be integrated with other technologies by using IBM Integration Bus. For more information, see the MQTT Connector Sample on GitHub.

Local environment variables

When you use the MQTTPublish node in a message flow, you can dynamically override some of its properties with elements in the local environment message tree. You can set the following values under LocalEnvironment.Destination.MQTT.Output.

Table of LocalEnvironment.Destination variables

Table 1. List of elements in the LocalEnvironment.Destination.MQTT.Output subtree
Element Name	Element Data Type	Description
retained	BOOLEAN	Whether the message is a retained message. Set to `TRUE` or `FALSE`. The default is `FALSE`. Set to `TRUE` if the message for a topic must be held by the MQTT server after delivery to all currently connected clients, and then delivered to new clients when they connect to that topic. Each retained message for a topic replaces the previous retained message for that topic. In this way, devices can receive the most recent retained message immediately on connecting to a topic.
TopicName	CHARACTER	The name of the MQTT topic the message will be published to.
qos	INTEGER	Quality of service of the published message. Set to `0` (at most once), `1` (at least once), or `2` (exactly once).
connectionUrl	CHARACTER	The URL that is used to connect to the MQTT server. The URL includes the protocol, the host name, and the port. For example: `tcp://myMQTTserver.com:1883` or, if the connection is encrypted: `ssl://myMQTTserver.com:8883` If set, the value of the connectionUrl property takes precedence over the values of the following MQTT message flow node properties: Host name Port Use SSL

When the MQTTPublish node propagates a message through the Out terminal, it stores information about the message in the local environment subtree called LocalEnvironment.WrittenDestination.MQTT. The following table lists the local environment variables for the MQTTPublish node. The elements contain data about the current record.

Table of LocalEnvironment.WrittenDestination variables

Table 2. List of elements in the LocalEnvironment.WrittenDestination.MQTT subtree
Element Name	Element Data Type	Description
ClientId	CHARACTER	The unique name of the client.
DeliveryToken.isComplete	BOOLEAN	Whether the message was successfully published to the MQTT topic. Set to `TRUE` or `FALSE`.

Terminals and properties

When you add an MQTTPublish 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

Table 3. The terminals of the MQTTPublish node
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 when the message is published to the MQTT topic.
Out	The output terminal to which the message is routed if it was successfully published to the MQTT topic.

Tables of node properties

Table 4. The Description properties of the node
Property	M	Default	Description
Node name	Yes	MQTTPublish	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.

Table 5. The Basic properties of the node
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 MQTTPublish node and the MQTT server attempts to use SSL; see Securing MQTT connections.

Table 6. The Validation properties of the node
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.

Table 7. The Policy properties of the node
Property	M	Default	Description
Policy URL	No		The URL that specifies the name and location of the policy document.

Table 8. The Monitoring properties of the node
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

Table 9. List of node properties that can be configured by using the mqsiapplybaroverride command
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 MQTTPublish policy.

Table of operational properties

Table 10. List of node properties that can be controlled at run time by using an operational policy
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