ApplicationEdge 1.0.0Embedded 1.0.0

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, or the Gateway Edge Agent Local Broker, as well as any of the pre-defined topics of a configured external broker, or an MQTT Integration.

MQTT Trigger

Node Properties

The configuration of the MQTT Trigger Node varies 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.

MQTT Trigger From Integration

Edge Workflows

For Edge Workflows, you have the option of firing the trigger on messages from the Losant MQTT Broker, messages from the Gateway Edge Agent Local MQTT Broker, or messages from configured external brokers.

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, and the option to fire on messages received from external brokers is only available in Gateway Edge Agent v1.42.0 and higher.

Losant Broker

When triggering on messages from Losant’s cloud broker in Edge Workflows, the 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 broker.

External Brokers

When triggering workflows with messages from external brokers, you must enter the name of the MQTT client configuration that you have defined in the GEA’s configuration file. The trigger will then fire whenever a message is received on any of the topics that you have defined to subscribe to in the MQTT client configuration.

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 a message to the Losant MQTT Broker or to an Integration.

Losant Broker

The initial payload for triggering an Application Workflow with a message on Losant’s cloud 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 was 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 was 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: the Losant MQTT Broker, the Gateway Edge Agent Local MQTT Broker, or an external 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 GEA’s local 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 the GEA’s local broker.

External Broker

The initial payload for triggering an Edge Workflow with a message from an external broker will take on the following shape:

{
  "agentEnvironment": {
    "EXAMPLE": "Environment Variable"
  },
  "agentVersion": "1.31.0",
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "brokerUrl": "<the URL of the broker this message arrived from>",
    "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 name of the MQTT client configuration>",
  "triggerType": "mqttTopic"
}
  • data.brokerUrl is the URL of the broker this message arrived from.
  • data.message is the message payload. Note that this value will always be a string; if the message was 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.
  • triggerId is the name of the MQTT client configuration that this trigger is configured to listen to.
  • triggerType is always “mqttTopic” when triggering off of an external 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.

Was this page helpful?

Still looking for help? You can also search the Losant Forums or submit your question there.