Using Triggers

Getting Started with Triggers

In this tutorial you'll be creating a trigger associated with one of your M2X devices. A trigger examines stream(s) of data in real time. Conditions are defined in the trigger and applied against the trigger's associated streams. When the trigger condition(s) are met, a notification is delivered to the trigger's callback URL.

There are a few prerequisites to creating a trigger: First, you'll need to create a new device (or use an existing one from your account if you prefer). Next, make sure the device has at least one stream. For the Creating a Trigger example below you'll need to add two streams to your device, make sure to set each of their Stream IDs to "temperature" and "humidity".

Triggers in M2X send POST requests to user-defined callback URLs when the trigger condition(s) evaluate to true. To keep things simple, we will use the RequestBin service to receive these notifications.

Go to http://requestb.in/ and create a new RequestBin. Copy the Bin URL as we will need it as the callback URL when creating the trigger.

If you are interested in integrating trigger functionality into your app, you can also reference the official Node.js trigger sample app on GitHub. This application demonstrates how to set up a Heroku cloud server to receive and handle the trigger notifications sent by M2X.

Example Create Trigger Command


Use the following command to create a new trigger. In this example the trigger's associated stream id's are temperature and humidity. Make sure to replace [DEVICE-ID] and [M2X-API-KEY] with a valid Device ID and API Key from your M2X account.

$ curl -i -X POST http://api-m2x.att.com/v2/devices/[DEVICE-ID]/triggers -d "{ \"name\": \"Hot and Humid\", \"conditions\": { \"temperature\": { \"gt\": 30, \"reset\": 28 }, \"humidity\": { \"gt\": 20, \"reset\": 18 } }, \"frequency\": \"single\", \"timeframe\": 300, \"callback_url\": \"http://requestb.in/11yu9ux1\" }" -H "Content-Type: application/json" -H "X-M2X-KEY: [M2X-API-KEY]"

Required Parameters


The following parameters are required to be passed along with a Create Trigger request:

  • name the name of the new trigger .
  • conditions the condition(s) that must be met in order for the trigger to fire. For each stream listed in conditions an optional reset threshold can be defined. After a trigger is initially fired it will not be turned off again until at least one stream listed listed in conditions logs a value equal to or surpassing its respective reset threshold and thereafter logs a value meeting the respective condition. If a reset threshold is not specified, the condition's threshold value is used by default.
  • callback_url the trigger payload is delivered to this callback URL through an HTTP POST request
  • frequency either "single", "periodic" or "continuous". See frequency definitions below.
  • interval (conditionally required ) the interval (in seconds) during which trigger notifications will be delivered, if and only if the trigger conditions continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger. This parameter is required if frequency is periodic. Should be an integer value between 1 and 86,400 (24 hours).

Currently, the following operators are supported for conditions:

  • gt stream must log a value greater than the one specified.
  • gte stream must log a value equal to or greater than the one specified.
  • lt stream must log a value lesser than the one specified.
  • lte stream must log a value equal to or lesser than the one specified.
  • eq stream must log a value equal to the one specified.

The reset parameter supplied with each condition is optional. After a trigger is initially fired it will not be turned off again until at least one stream listed listed in conditions logs a value equal to or surpassing its respective reset threshold and thereafter logs a value meeting the respective condition.

The frequency with which a trigger's payload will be delivered to the callback_url must be specified using the frequency parameter. There are three frequency options available:

  • single triggers with single notification frequency only deliver the trigger payload to the callback_url once, when the first datapoint matching the trigger conditions is received. The trigger payload will not be delivered again until at least one datapoint is received which falls outside any of the trigger's defined conditions. The payload for triggers with a single notification frequency is guaranteed to be delivered at least once, though there are instances in which the payload is delivered more than once.
  • periodic triggers with a periodic notification frequency deliver the trigger payload to the callback_url once the trigger conditions have been met, and at most once per interval if the condition(s) continue to be met. Any datapoint received that falls outside of the trigger conditions will reset the trigger.
  • continuous triggers with continuous notification frequency deliver the trigger payload to the callback_url each time a new datapoint matching the trigger conditions is received.

Make sure to use the URL of your own RequestBin in the callback_url field of your request.

Optional Parameters


The following parameters can be optionally included in a Create Trigger request:

  • timeframe the number of seconds representing the largest interval that will be considered when evaluating values and conditions from different streams. The largest possible timeframe that can be set is 86,400 (24 hours).
  • status either "enabled" or "disabled. If omitted, defaults to "enabled".
  • send_location either "true" or "false", indicating if the last known location of the device should be included in the payload. If omitted, defaults to "true".
  • notify_on_reset either "true" or "false", indicating if the trigger should send a notification to the callback_url whenever the trigger gets reset. If omitted, defaults to "false".
  • custom_data a static string of up to 5,000 characters that will be included in the notification payload sent to the callback_url.

Create Trigger Response


After successfully sending the Create Trigger command to M2X, the following response will be received:


        HTTP/1.1 201 Created
        Content-Type: application/json
        Location: http://api-m2x.att.com/v2/devices/[DEVICE-ID]
        /triggers/AU7Hls0d9QWS89vuj58x
        Status: 201 Created
        Content-Length: 458

        {
          "id": "AU7Hls0d9QWS89vuj58x",
          "name": "hot and humid",
          "conditions": { "temperature": { "gt": 30, "reset": 28},
                          "humidity": { "gt": 20, "reset": 18 } 
                        },
          "frequency": "single",
          "timeframe":300,
          "callback_url":"http://requestb.in/v0qyguv0",
          "url": "http://api-m2x.att.com/v2/devices/[DEVICE-ID]/triggers/AU7Hls0d9QWS89vuj58x",
          "status": "enabled",
          "activated": false,
          "send_location": true,
          "notify_on_reset": false,
          "custom_data": "{ \"foo\": \"bar\" }",
          "payload_version": 2,
          "created": "2015-07-25T23:40:25.754Z",
          "updated": "2015-07-25T23:40:25.754Z" }
        

The id of the newly created trigger is included in the response. The trigger id is required when making requests to view, update, test, or delete this trigger.

Trigger Payload


The trigger we've just created will send a POST request containing the trigger payload to the http://requestb.in/11yu9ux1 callback URL whenever the temperature stream receives a value > 30 and the humidity stream receives a value > 20. These values must be received by M2X within 300 seconds in order for the trigger notification to be delivered, as prescribed by the timeframe parameter. Since the frequency was set to single the notification will only be delivered once, per the single frequency notification definition from above.

Payload example:


        {
          "device": { "id": "e534850ff4fc3c8bab86ac14b41d26f7", 
                      "name": "Test Device", 
                      "serial": "ABC123" },
          "trigger": "hot and humid",
          "conditions": { "temperature": { "gt": 30, "reset": 28 },
                          "humidity": { "gt": 20, "reset": 18 } 
                        },
          "values": { "temperature": { "value": 31.0, "timestamp": "2015-07-26T00:51:02.550Z", "unit": "°C" },
                      "humidity": { "value": 23.0, "timestamp": "2015-07-26T00:51:02.550Z", "unit": "%"} 
                    },
          "timeframe": 300,
          "timestamp": "2015-07-26T00:51:02.550Z" }
        

The payload will include the device id, the trigger name, a description of the condition(s) that caused the trigger to be fired, the actual value(s) that caused this trigger to be fired, the timestamp at which the trigger condition(s) were met, and if provided the timeframe limit that was imposed on the trigger.


View the full API Documentation for more details

To view the details of any existing trigger, use the following command. Note that [DEVICE-ID] and [TRIGGER-ID] in the request URL will need to be updated with the device id and trigger id from your account:

$ curl -i http://api-m2x.att.com/v2/devices/[DEVICE-ID]/triggers/[TRIGGER-ID] -H "X-M2X-KEY: [M2X-API-KEY]"

Alternatively, you can list all triggers for a specific device, instead of retrieving just one specific trigger. Note that [DEVICE-ID] in the request URL will need to be updated with the device id from your account:

$ curl -i http://api-m2x.att.com/v2/devices/[DEVICE-ID]/triggers -H "X-M2X-KEY: [M2X-API-KEY]"

At this point we can confirm the trigger is configured, enabled and ready to start sending notifications whenever its condition(s) evaluate to true.

The simplest way of testing if the trigger is working as expected is to edit the trigger's stream(s) in the M2X developer portal and enter value(s) that would make this trigger fire (e.g. 35 for temperature, and 25 for humidity in our example).

Another way would be to POST values to the stream using the Device API. Note that [DEVICE-ID] in the request URL will need to be updated with the device id from your account:

$ curl -i -X POST http://api-m2x.att.com/v2/devices/[DEVICE-ID]/values -d "{ \"values\": { \"temperature\" : 35, \"humidity\": 25 } }" -H "Content-Type: application/json" -H "X-M2X-KEY: [M2X-API-KEY]"

Choose your preferred method or try both. Then, open your RequestBin's URL in the browser to see the notifications that have been delivered by M2X.

At any time, you can test a trigger programatically without POSTing any values to the stream. This is useful for debugging purposes when the app that will receive the notifications is being written. Note that [DEVICE-ID] and [TRIGGER-ID] in the request URL will need to be updated with the device id and trigger id from your account:

$ curl -i -X POST http://api-m2x.att.com/v2/devices/[DEVICE-ID]/triggers/[TRIGGER-ID]/test -H "X-M2X-KEY: [M2X-API-KEY]"

The command above will fire the trigger using the current server time and a fake value that would have caused the condition to be true .