The MQTT Action operation publishes one MQTT message per run when gate and input validation allow it. It is a terminal action node with no outputs. Topic is treated as a full topic; the runtime publishes exactly to the configured or resolved topic.
Inputs
Port
Type
Required
Description
> (Gate)
Any
No
When connected, a false or Nil value stops the path. See Gate Inputs.
Topic
String
No
Overrides the item Topic property when connected.
Payload
String, Binary, Map or Array
Yes
Message payload. String and Binary are sent as raw bytes; a Map or an Array is sent as JSON — the failure record on an error output wires straight in. Any other type fails the Node.
MessageExpiry(s)
Integer
No
Message lifetime in seconds (0..4294967295).
ResponseTopic
String
No
MQTT 5 response topic.
CorrelationData
Binary
No
MQTT 5 correlation data.
UserProperties
Map
No
MQTT 5 user properties (key/value map).
ContentType
String
No
MQTT 5 content type.
Outputs
This operation has no outputs. It is a terminal action node.
Properties
Name
Type
Default
Description
Topic
TextLine
""
Full topic to publish to. Must start with <slot>/. Hint: Add full topic as <slot>/…
Retain
Boolean
false
Whether the published message should be retained by the broker.
On Error
Combo
Stop this branch
Per-op On Error verb. MQTT Action is a sink, so the Editor offers it the two verbs a sink can honour: Stop this branch / Continue with the last value. See the Error Handling guide.
State on Reload
This operation does not persist any state across restarts. Each execution is independent.
Gate check — If a Gate Input is connected, evaluate it. A false or Nil value stops the execution path; no message is published.
Topic resolution — If the Topic input is connected and is a String, it overrides the item Topic. If Nil, the item Topic is used. Any other type fails the Node with MqttAction: Topic input is not a String, addressed to the Topic Input.
Topic validation — The resolved topic must be non-empty, must not start with /, and must start with <slot>/. Otherwise the Node fails with MqttAction: invalid topic '{}' — the topic it read — addressed to the Topic Input.
Payload resolution — The Payload input is read. String and Binary are sent as raw bytes; a Map or an Array is sent as JSON — the failure record on an error output wires straight in. An unconnected Payload or any other type fails the Node with MqttAction: payload type not publishable, addressed to the Payload Input (the port mask already forbids the wrong type; this is the defensive runtime guard).
Publish options — Retain is initialized from the item property and optionally overridden by the Retain input. Optional metadata inputs (MessageExpiry, ResponseTopic, CorrelationData, UserProperties, ContentType) are applied only if connected and valid.
Publish — The message is published to the resolved topic with the configured options. A message the broker will not take fails the Node with MqttAction: publish failed, addressed to the Node.
When the Node fails, the engine applies the On Error verb the Node carries; see Error Handling below.
Topic validation requires the <slot>/... format in both constructor/validate and at runtime. When the Topic Input is connected, the runtime value is used and the static Topic property is not checked.
MQTT 5 metadata fields (MessageExpiry, ResponseTopic, CorrelationData, UserProperties, ContentType) have no item defaults — they are controlled exclusively by connected inputs.
If publish is skipped due to invalid input, the Node records its own status (Topic input is not a String / invalid topic / payload type not publishable) and fails; the engine then applies the On Error verb.
To avoid publishing an empty message when an upstream Node has not yet produced a Payload, set Input Validation on the Payload Input to Written ever.
MQTT Action can fail for these reasons: an unconnected Mandatory Payload, a Payload that is not a String, Binary, Map or Array (a Map or an Array is sent as JSON), a non-String Topic value, an invalid topic (empty, leading /, or missing the <slot>/ prefix), or a message the broker will not take.
Each records its own status and answers a failure; the engine then applies the On Error verb you picked. See the Error Handling guide for the common verb model; MQTT Action’s verbs are:
Verb
What it does
Stop this branch (default)
This Node and its dependents stop. Nodes that do not depend on this one still run.
Continue with the last value
Path continues.
MQTT Action is a sink: it has no Output, so there is nothing for Continue with the fallback to write. Its schema states the two verbs above, and the Editor offers only those.
Gate closure is not an error — a closed Gate stops the Path without consulting the On Error verb.
One host setting bounds MQTT Action. It is read at start-up from the host’s
configuration file; see the
MQTT Broker configuration reference.
Key
Type
Default
Effect
mqttbroker.maxActionPerTask
Integer
-1
How many MQTT Action nodes one Task may contain. Negative means unlimited.
The cap travels to the editor in the operation’s schema, so the editor refuses
to add an Action beyond it rather than letting you build a Task the server will
reject.
The broker-wide settings a published message runs under — the granted QoS
level, whether the retain flag is honoured, the packet-size ceiling, and the
per-device publish rate — are on the same page.
