Device: State Trigger

The Device: State Trigger fires a workflow whenever one or more devices report state.

Node Properties

There are a number of properties to set when configuring a Device: State Trigger.

Devices

The Device: State Trigger can be configured with one or more specific devices, a selection of tags, or both. When a device that matches anything in the selection reports state, the workflow will trigger. See the device query documentation for more info about how ID and tag matching works.

In the above example, the workflow will trigger whenever any device with the type=Smoke Detector tag reports state.

Batch Behavior

Optionally, you may configure how the Device State: Trigger deals with batch reporting. By default, a trigger will fire for single reports and also fire once per item in a batch report.

Trigger On

• Both individual and batch reports: The trigger will fire for state reported both as individual items and for batches. This is the default.
• Only individual reports: The trigger will fire only for individual state reports. Batch reports will be ignored.
• Only batch reports: The trigger will fire only for batch state reports. Individual state reports will be ignored.

Batch Report Behavior

If the trigger is configured to fire on batch reports, there are two additional different behavior options.

• Trigger per item in a batch report: When a batch report is received, the trigger will fire for each individual item in the batch report.
• Trigger once for a batch report: When a batch report is received, the trigger will only fire once, with the entire batch report placed on the data payload property as an array. Note: The Filter By Attributes and Filter By Age options do not apply in this case.

Filter By Attributes

Optionally, you may only fire the Device State: Trigger if certain attributes are included (or are not included) in the state report. You can filter by:

• Any …: All attributes fire this trigger.
• Only the following …: The payload must contain one of the selected attributes to fire this trigger.
• Any but the following …: The payload must contain at least one attribute not selected to fire this trigger.

In the example at the top of the page, the workflow triggers only when the tempF attribute is included in the state report. This is because the workflow is recording the same temperature in Celsius at the same timestamp (using a Device: State Node), and we do not want this workflow to run again from the recording of the converted value.

Filter By Age

Optionally, you may also filter device state changes by the device’s state payload age (time field value relative to now). Thus, if the device state was reported with a time older than this value, it will not fire the trigger. Set the maximum age of the payload by seconds, minutes, hours, or days.

For example, consider the following cases:

• If a device is batch reporting its state data, this action will trigger a workflow for each state within the batch. If you only care about the most current update, you can use this option to ignore all updates but the most recent.
• With the use of timestamps, you can overwrite previous states. However, you may want to not trigger the workflow for such overwrites, in which case this setting can filter out those payloads.

Invalid Payloads

You may also optionally fire the trigger for state reports where the payload is not a valid JSON object. In these cases, the data field on the payload will be null, and the field original will contain the message published by the device.

Payload

The trigger’s initial payload includes information about the device that caused the workflow to fire. Additionally, it includes a data object, the shape of which depends on the state report that triggered the workflow.

Individual Reports

For individual state reports …

• data is an object whose keys correspond to the accepted attribute values in the report.
• If any meta value was provided in the state report, that will be available on the root of the initial payload.
• The time property on the initial payload corresponds not to the time the workflow executed, but to the timestamp included with the state report.

For example, consider the following scenario …

• A device has attributes number1, number2, number3, and number4, all of which are of the “number” type.
• The device reported state just for attributes number1, number2, and number3.
• However, the value for number3 was sent as “foo”, which cannot be parsed as a number. Therefore, that value was not accepted.
• The trigger is configured with an attribute filter to fire only if the state report contains a value for the number1 attribute.

In this case, the data property would contain keys and values for number1 and number2.

• number1 was included in the state report, and its value was accepted, and the trigger is configured to fire if the report includes a value for number1.
• number2 was included in the state report, and its value was accepted. The trigger fired because of the presence of number1 in the report due to the applied attribute filter; if only number2 were reported, the trigger would not have fired.
• number3 was reported, but with an invalid value, therefore it was not accepted and thus is not in the trigger’s payload.
• number4 was not included in the state report, therefore there is no value to place on the payload.

In the general case, a Device: State workflow payload for an individual report looks like the following:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "aNumberAttribute": 10,
    "aStringAttribute": "Hello, world",
    "aBooleanAttribute": true,
    "aGpsAttribute": "39.15, -84.51"
  },
  "device": {
    "_etag": "\"567-SY26IHrVRzUBMUwxnY59Fn6vOvo\"",
    "applicationId": "555555555555eeeeeeeeeeee",
    "attributes": {
      "exampleNumber": {
        "attributeTags": {
          "attrTagKey": "tagValue1"
        },
        "dataType": "number",
        "description": "",
        "name": "exampleNumber"
      },
      "exampleString": {
        "attributeTags": {
          "attrTagKey": "tagValue2"
        },
        "dataType": "string",
        "description": "",
        "name": "exampleString"
      }
    },
    "creationDate": "2018-03-16T18:19:03.376Z",
    "description": "",
    "deviceClass": "standalone",
    "deviceId": "222222222222bbbbbbbbbbbb",
    "id": "222222222222bbbbbbbbbbbb",
    "lastUpdated": "2020-08-26T13:09:11.814Z",
    "name": "My Great Device",
    "tags": {
      "aTagKey": [
        "exampleTagValue"
      ],
      "tagWithMultipleValues": [
        "tagValue",
        "anotherTagValue"
      ]
    }
  },
  "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"
  },
  "meta": "Arbitrary data included alongside the state report",
  "relayId": "<ID of the entity that reported state for the device>",
  "relayType": "apiToken|device|flow|user",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<ID of the reporting device>",
  "triggerType": "deviceId"
}

Batch Reports

For a trigger configured to fire once for an entire batch report …

• The payload’s data property will instead be an array of state report objects.
• The time property corresponds to the time at which the batch report was received instead of the timestamp of any individual state report.
• There will be no meta property on the root of the payload, regardless of whether any or all of the state object in the batch include such a property.

In the general case, a Device: State workflow payload for a batch report looks like the following:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": [
    {
      "data": {
        "aNumberAttribute": 10,
        "aStringAttribute": "Hello, world"
      },
      "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST)
    },
    {
      "data": {
        "aNumberAttribute": 12,
        "aStringAttribute": "Goodbye, world",
        "aBooleanAttribute": false
      },
      "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
      "meta": {
        "lastReport": true
      }
    }
  ],
  "device": {
    "_etag": "\"567-SY26IHrVRzUBMUwxnY59Fn6vOvo\"",
    "applicationId": "555555555555eeeeeeeeeeee",
    "attributes": {
      "exampleNumber": {
        "attributeTags": {
          "attrTagKey": "tagValue1"
        },
        "dataType": "number",
        "description": "",
        "name": "exampleNumber"
      },
      "exampleString": {
        "attributeTags": {
          "attrTagKey": "tagValue2"
        },
        "dataType": "string",
        "description": "",
        "name": "exampleString"
      }
    },
    "creationDate": "2018-03-16T18:19:03.376Z",
    "description": "",
    "deviceClass": "standalone",
    "deviceId": "222222222222bbbbbbbbbbbb",
    "id": "222222222222bbbbbbbbbbbb",
    "lastUpdated": "2020-08-26T13:09:11.814Z",
    "name": "My Great Device",
    "tags": {
      "aTagKey": [
        "exampleTagValue"
      ],
      "tagWithMultipleValues": [
        "tagValue",
        "anotherTagValue"
      ]
    }
  },
  "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"
  },
  "relayId": "<ID of the entity that reported state for the device>",
  "relayType": "apiToken|device|flow|user",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<ID of the reporting device>",
  "triggerType": "deviceId"
}

Related Nodes

• Device: State Node