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 of the MQTT Trigger Node varies slightly 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 valid.

MQTT Integration

When choosing an MQTT integration, the trigger will fire for messages received on any topic configured through the integration. The Trigger configuration will list the topics associated with the integration that will fire the trigger.

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 in Edge Workflows, configuration matches the behavior when using this trigger in an Application Workflow.

Note: As of Gateway Edge Agent v1.29.0, single-level and multi-level wildcard topics–such as custom/+/temperature or custom/#—are valid.

Local Edge Broker

Similar to triggering off Losant’s cloud broker, when triggering workflows with messages to the GEA’s local broker, you must enter a single topic off which to fire the workflow.

Note: Wildcard topics are valid when using the Local Gateway Edge Broker.

Embedded Workflows

Embedded Workflows also take a single MQTT topic on which to fire.

• 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”).
• Wildcard topics are not valid.

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.

Payload

The payloads associated with the MQTT Trigger vary depending on the workflow the trigger is used in and how the trigger is fired.

Application Workflows

The payload for Application Workflows varies depending on whether the MQTT Trigger fires for an MQTT message to the Losant Broker or to an Integration.

Losant Broker

The initial payload for triggering an Application Workflow with a message on the Losant Broker will take on the following shape:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": "<the MQTT message payload as a string>",
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "relayId": "<ID of the resource that published the message>",
  "relayType": "<apiToken|device|flow|user>",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<MQTT topic on which the message was published>",
  "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 the message was published on.
• triggerType is always “mqttTopic” when triggering off of messages to Losant’s cloud broker.

MQTT Integration

The initial payload for triggering an Application Workflow with a message from an MQTT Integration will take on the following shape:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "message": "<the MQTT message payload as a string>",
    "topic": "<the topic the message was published on>"
  },
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "relayId": "<ID of the integration that published the message>",
  "relayType": "integration",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<ID of the integration that published the message>",
  "triggerType": "integration"
}

• 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 topic the message was published on.
• triggerType and relayType are always “integration” when triggering off of an MQTT integration.

Edge Workflows

Like Application Workflows, the payload for Edge Workflows varies depending on which broker you are using; either the Local GEA Broker or the Losant Broker.

Losant Broker

When triggering on messages from Losant’s cloud broker in Edge Workflows, the initial payload matches the initial payload generated when using this trigger in an Application Workflow.

Local Edge Broker

The initial payload for triggering an Edge Workflow with a message on the Local GEA Broker will take on the following shape:

{
  "agentEnvironment": {
    "EXAMPLE": "Environment Variable"
  },
  "agentVersion": "1.31.0",
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "clientId": "<unique identifier of the publishing client>",
    "message": "<the MQTT message payload as a string>",
    "topic": "<the topic the message was published on>"
  },
  "device": {
    "applicationId": "555555555555eeeeeeeeeeee",
    "attributes": {
      "exampleNumber": {
        "attributeTags": {
          "attrTagKey": "tagValue1"
        },
        "dataType": "number",
        "name": "exampleNumber"
      },
      "exampleString": {
        "attributeTags": {
          "attrTagKey": "tagValue2"
        },
        "dataType": "string",
        "name": "exampleString"
      }
    },
    "creationDate": "2018-03-16T18:19:03.376Z",
    "deviceClass": "edgeCompute",
    "deviceId": "222222222222bbbbbbbbbbbb",
    "id": "222222222222bbbbbbbbbbbb",
    "name": "My Great Device",
    "tags": {
      "aTagKey": [
        "exampleTagValue"
      ],
      "tagWithMultipleValues": [
        "tagValue",
        "anotherTagValue"
      ]
    }
  },
  "deviceId": "222222222222bbbbbbbbbbbb",
  "deviceName": "My Great Device",
  "deviceTags": {
    "aTagKey": [
      "exampleTagValue"
    ],
    "tagWithMultipleValues": [
      "tagValue",
      "anotherTagValue"
    ]
  },
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "isConnectedToLosant": true,
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<the topic the message was published on>",
  "triggerType": "mqttTopic"
}

• 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 topic the message was published on. 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

The initial payload for triggering an Embedded Workflow will take on the following shape:

{
  "data": "<the eea_message_received message payload as a string>",
  "deploymentId": "666666666666ffffffffffff",
  "deviceId": "222222222222bbbbbbbbbbbb",
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "isConnectedToLosant": true,
  "time": 1455902760000,
  "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 the message was published on.
• triggerType is always “mqttTopic” when triggering off of messages to eea_message_received.

Related Nodes

• MQTT Node