MQTT Trigger Node

The MQTT Trigger fires a workflow whenever a message is published to a topic of your choosing on the Losant MQTT Broker, the Gateway Edge Agent Broker, or an MQTT Integration.

Node Properties

The configuration options and the shape of the trigger’s payload vary depending on the type of workflow in which the trigger is used.

Application Workflows

In Application Workflows, the MQTT Trigger can fire for messages received on Losant’s MQTT Broker or through an MQTT integration.

Losant Broker

When choosing the Losant Broker, you must also enter a single MQTT topic; messages received on this topic will fire this trigger.

• This must be a valid MQTT topic.
• The topic cannot be an MQTT system topic or a Losant-specific topic (such as “losant/<DEVICE_ID>/state”).
• Single-level and multi-level wildcard topics–such as custom/+/temperature or custom/#—are allowed.

The initial payload takes the following shape:

{
  "time": <time of the message>,
  "data": <the MQTT message payload as a string>,
  "applicationId": <ID of the current application>,
  "applicationName": <name of the current application>,
  "triggerId": <topic on which message was published>,
  "triggerType": "mqttTopic",
  "flowId": <ID of the current workflow>,
  "flowName": <name of the current workflow>,
  "globals": <object of workflow globals>
}

• data is the message payload. Note that this value will always be a string; if the message were published as a JSON object, it is recommended to use a JSON Decode Node to parse the raw text into a JSON object.
• triggerId is the topic on which the message was published.
• triggerType is always “mqttTopic” when triggering off of messages to Losant’s cloud broker.

MQTT Integration

When choosing an MQTT integration, the trigger will fire for messages received on any topic configured through the integration.

The initial payload takes the following shape:

{
  "time": <time of the message>,
  "data": {
    "message": <the MQTT message payload as a string>,
    "topic": <the topic the message was published on>
  },
  "applicationId": <ID of the current application>,
  "applicationName": <name of the current application>,
  "triggerId": <ID of the MQTT integration>,
  "triggerType": "integration",
  "flowId": <ID of the current workflow>,
  "flowName": <name of the current workflow>,
  "globals": <object of workflow globals>
}

• data.message is the message payload. Note that this value will always be a string; if the message were published as a JSON object, it is recommended to use a JSON Decode Node to parse the raw text into a JSON object.
• data.topic is the name of the topic on which the message that triggered the workflow was published.
• triggerType is always “integration” when triggering off of an MQTT integration.

Edge Workflows

For Edge Workflows, you have the option of firing the trigger on messages from Losant’s cloud broker or messages from the Gateway Edge Agent’s local MQTT broker.

Note: The option to fire on messages received by the GEA’s local broker is only available in Gateway Edge Agent v1.17.0 and higher.

Losant Broker

When triggering on messages from Losant’s cloud broker, configuration and the initial payload match the behavior when using this trigger in an application workflow. However, wildcard topics are not valid when using this trigger in Edge Workflows.

Local Edge Broker

Similar to triggering off Losant’s cloud broker, when triggering off messages to the GEA’s local broker, you must enter a single topic off which to fire the workflow. Wildcard topics are not valid.

This initial payload takes the following shape:

{
  "time": <time of the message>,
  "data": {
    "clientId": <unique identifier of the publishing client>,
    "message": <the MQTT message payload as a string>,
    "topic": <the topic the message was published on>
  },
  "applicationId": <ID of the current application>,
  "applicationName": <name of the current application>,
  "isConnectedToLosant": <true|false>,
  "triggerId": <the topic the message was published on>,
  "triggerType": "mqttTopic",
  "flowId": <ID of the current workflow>,
  "flowName": <name of the current workflow>,
  "globals": <object of workflow globals>
}

• data.clientId is the ID of the client that published the message. If the message was published by the local broker itself, this property will be omitted from the original payload.
• data.message is the message payload. Note that this value will always be a string; if the message were published as a JSON object, it is recommended to use a JSON Decode Node to parse the raw text into a JSON object.
• data.topic is the name of the topic on which the message that triggered the workflow was published. It is also available at the path of triggerId.
• triggerType is always “mqttTopic” when triggering off of an the GEA’s local broker.

Embedded Workflows

For Embedded Workflows, configuration takes a single value: a valid MQTT topic on which to fire. Wildcard topics are not valid. Also, the topic cannot be an MQTT system topic or a Losant-specific topic (such as “losant/<DEVICE_ID>/state”)

Note: Since the Embedded Edge Agent requires setting up your own MQTT client, firing the MQTT Trigger requires the following:

1. The agent invokes the eea_message_received method with the encoded topic and payload. Note: Device: Command Triggers and Virtual Button Triggers also work by invoking this method, but only the appropriate trigger will fire based on the topic argument passed to the function.
2. Any MQTT Triggers configured to fire off of messages to the topic matching the topic in the eea_message_received invocation then fire.

The initial payload takes the following shape:

{
  "data": <the eea_message_received message payload as a string>,
  "deploymentId": <ID of the deployment>,
  "deviceId": <ID of the device>,
  "flowId": <ID of the current workflow>,
  "flowName": <name of the current workflow>,
  "globals": <object of workflow globals>,
  "flowVersion": <name of the flow version>,
  "isConnectedToLosant": <true|false>,
  "time": <time of the message>,
  "triggerId": <the eea_message_received topic>,
  "triggerType": "mqttTopic"
}

• data is the message payload. Note that this value will always be a string; if the message were published as a JSON object, it is recommended to use a JSON Decode Node to parse the raw text into a JSON object.
• triggerId is the topic on which the message was published.
• triggerType is always “mqttTopic” when triggering off of messages to eea_message_received.

Related Nodes

• MQTT Node