Skip to content

Triggers

Triggers monitor data sources and evaluate device and service data to see if a predefined trigger condition is true.

Triggers can be defined for a variety of source data:

Trigger Source Description
Device database value Polled Monitor device and service data on a schedule
Streamed device data Streamed Monitor all device data sent to the cloud and trigger specific values
Device metric values Polled Monitor device metrics on a schedule
HTTP Endpoints Direct Respond to REST (HTTP) API requests
User UI actions. Direct Respond to user UI actions

Triggers can define parameters for actions. For example: a trigger can supply an Email action with an Email subject, severity level and email message.

Trigger Sources

The Builder supports three varieties of data sources:

  • Streamed
  • Polled
  • Direct

Streamed Trigger sources monitor data as it is received by, or sent to the device cloud.

Polled sources query the target data on a fixed schedule. Direct sources respond to incoming requests.

Trigger Expressions

The trigger expression is a JavaScript like expression that is evaluated to yield a true or false result. If true, the Trigger action is invoked.

The trigger expression is provided with a context of variables that can be accessed by the expression. The fields for a database item are provided as named variables. For metric data sources, the metric result is provided as a "value" variable.For example:

1
value > 0

The query language supports the operators:

1
+ - * / ( ) ^ ! % == != < <= > >= ^= ^!= $= $!= << >> && || <> ><

These extension operators have the following meaning:

  • a ^= b means a starts with the string b
  • a ^!= b means a does not start with the string b
  • a $= b means a ends with the string b
  • a $!= b means a does not end with the string b
  • a >< b means a contains the string b
  • a <> b means a does not contain the string b

Sub-expressions can be grouped with parenthesis and the boolean operators && and || can group conditional operands.

Regular expressions (delimited by slashes) may be used with the "==" and "!=" operators. The regular expression can be on either side of the operator.

The expression language understands the types: Numbers, Boolean, String literals, Regular Expressions and null.

The expression is run-time limited to evaluate up to 100 terms. This is to protect your cloud against denial of service attacks.

Database Value

Database values can be queried according to a polling schedule. To specify the database item to query, you must specify the:

  • Item model (entity) as defined in the Device Data schema
  • Item keys
  • Item filter properties

The Builder and Device Cloud provides data modeling and storage of application entities (models). Data items can be retrieved by specifying the appropriate item key. Other properties can be provided to further filter the data to be queried.

Polled Metric Value

Metric values can also be queried according to a polling schedule. To specify the metric item to query, you must specify the:

  • Metric namespace
  • Metric name
  • Metric dimensions
  • Metric statistic
  • Metric period

Metrics are grouped into namespaces and have a unique metric name. Metrics can also have dimensions where a set of resources may have unique metric values for each resource.

The metric statistics supported are: min, max, avg, sum, count and current. Sum is the sum of values over the request period. Count is the number of values sampled over the period. Current is the most recent updated value.

The metric period should be set to the last 5 minutes, hour, day, week, month or year.

The Builder console provides pulldown lists for each of these fields based on the available metrics on your system.

For more information on metrics, please see Metrics.

Streamed Device Data

As device data is sent to the device cloud, data can be used to activate an automation trigger.

The Device Schema can define triggers for specific device data models (entities). This efficiently invokes triggers for the required subset of data synchronized with the cloud.

UI Actions and HTTP Request

The UI Actions and HTTP request triggers have the same underlying capture mechanism. They list on the following endpoint for POST requests:

1
https://DEVICE_CLOUD/tok/trigger/invoke

The POST request accepts a JSON body with the following parameters:

  • name
  • ...parms

You can add any other parameters that will be made available to the Trigger expression as variables.

See Authentication for how to authenticate HTTP requests.