MQTT

Use this node to publish incoming message data to an external MQTT broker — for example, forwarding device telemetry to a cloud IoT platform, delivering commands to field devices through a dedicated broker, or bridging ThingsBoard data to a third-party MQTT-based service.

• Topic pattern — required. MQTT topic where messages will be published. Supports templatization.

• Host — required. MQTT broker hostname or IP.
• Port — required. MQTT broker port.
• Connection timeout (sec) — required. Maximum time to wait when establishing the connection.

Optional. Leave empty for auto-generated netty-mqtt/XXXXXXXX. In clustered deployments:

• Singleton mode (default) — one rule node instance per cluster, one connection.
• Disabled singleton + Add Service ID as suffix — one connection per rule engine instance, each with a unique client ID.

• Parse to plain text — when enabled, removes outer JSON string encoding from message data before publishing (useful for string payloads). Regular JSON objects are unaffected.
• QoS — fixed at QoS 1 (at-least-once).
• Retained — when enabled, the broker stores and delivers the message to future subscribers.

MQTT 3.1, MQTT 3.1.1 (default), or MQTT 5.

• Clean session — enabled by default; broker does not store session state between connections.

• Enable SSL — use TLS encryption.
• Credentials — Anonymous, Basic (username/password), or PEM Certificate (CA cert, client cert, private key).

For unacknowledged QoS 1 messages, the client uses exponential backoff with jitter. Configure globally via environment variables:

Controlled by the ACTORS_RULE_EXTERNAL_NODE_FORCE_ACK environment variable. When true, the incoming message is acknowledged immediately and the publish operation runs asynchronously.

1. Establish a persistent connection to the broker on node startup.
2. For each incoming message: resolve the topic pattern; optionally strip JSON string encoding; publish with QoS 1.
3. On success: route via Success. On failure: add error to metadata and route via Failure.
4. On node shutdown (config update or deletion): disconnect gracefully and release resources.

Metadata: { "deviceType": "temperature", "deviceName": "sensor-warehouse-01" } | Data: { "temperature": 22.5, "humidity": 65 }.

{
  "topicPattern": "factory/sensors/${deviceType}/${deviceName}",
  "host": "mqtt.cloud-provider.com",
  "port": 8883,
  "connectTimeoutSec": 10,
  "clientId": "thingsboard-publisher",
  "appendClientIdSuffix": true,
  "retainedMessage": false,
  "cleanSession": true,
  "ssl": true,
  "parseToPlainText": false,
  "protocolVersion": "MQTT_3_1_1",
  "credentials": { "type": "basic", "username": "factory-user", "password": "secure-password" }
}

Result: message published to factory/sensors/temperature/sensor-warehouse-01 over TLS. Routes via Success.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbMqttNodeConfiguration",
  "type": "object",
  "required": ["topicPattern", "host", "port", "connectTimeoutSec", "cleanSession", "ssl", "retainedMessage", "parseToPlainText", "protocolVersion", "credentials"],
  "additionalProperties": false,
  "properties": {
    "topicPattern": { "type": "string" },
    "host": { "type": "string" },
    "port": { "type": "integer" },
    "connectTimeoutSec": { "type": "integer" },
    "clientId": { "type": "string" },
    "appendClientIdSuffix": { "type": "boolean" },
    "retainedMessage": { "type": "boolean" },
    "cleanSession": { "type": "boolean" },
    "ssl": { "type": "boolean" },
    "parseToPlainText": { "type": "boolean" },
    "protocolVersion": { "type": "string", "enum": ["MQTT_3_1", "MQTT_3_1_1", "MQTT_5"] },
    "credentials": { "type": "object" }
  }
}