Triggers structure

Describes the Array object of the triggers key within an Event object.

The triggers key within an Event object is an array containing arrays of JSON trigger objects, or in other format, it's an Array[Array[Object]]. The basic structure is as follows:

[
  [
    {triggerObject1},
    ...
    {triggerObjectN}
  ],
  [
    {triggerObject1},
    ...
    {triggerObjectN}
  ],
]

Events support having multiple conditions link together by the AND or the OR operators. Elements in the root array are interpreted as OR, while the JSON trigger objects within the inner arrays are AND. Here's an example:

// Elements in the root array are interpreted as OR conditions
[
  [
    {triggerObject1}, // This is condition 1
  ], 
  // OR
  [
    {triggerObject2}, // This is condition 2
  ],
]
// Trigger objects within an array element in the root array are interpreted as AND conditions
[
  [
    {triggerObject1}, // This is condition 1
    // AND
    {triggerObject2}, // This is condition 2
  ]
]

Continue reading to learn about the trigger object format to setup an event of the different supported types.

Trigger object

Events support a wide variety of trigger types: based on a value, inactivity, position, scheduled and global events, which are based on a device group. This causes the JSON trigger object to be highly nested and have many variants in order to support all the above types.

In its base form, the trigger object follows this structure:

{
  "type": "Type of trigger", // Options: ["last_value", "position", "inactive", "schedule"]
  "entity": {},
  "condition": {}
}

Each key represents:

PropertyTypeDescription
typeStringType of trigger. Valid values are last_value, position, inactive and schedule.
entityObjectObject containing information about the entity that's used to trigger the Event (see below).
conditionObjectObject containing information about the trigger condition (see below).

entity Object - Attribute of triggers Object

The entity key within a trigger object holds an object as well, which has the below structure based on the value of the type key:

// This structure applies when "type" is "last_value", "position" or "inactive" 
{
  "type": "Type of entity", // Options: ["variable", "device_group"],
  "value": [{}], // Array of objects
  "operator": "or", // Options: ["or", "and"]. Defaults to "or",
}
// This structure applies to when "type" is "schedule" 
{
  "type": "Type of entity", // Options: ["variable", "device_group"],
  "value": [{}], // Array of objects. Max lenght = 1. Defaults to [].
  "inputData": {
    "value": "", // Optional
    "timestamp": "", // Optional
    "context": {} // Optional
  }, 
  "hasVariable": Boolean
}

Each key represents the following:

PropertyTypeDescription
typeStringType of entity, can be variable or device_group.
valueArrayContains an array of objects with keys varying based on type.
- type="variable": id of a Variable triggering the event.
- type="device_groups": idof the device group,labelof the variable in the group,deviceGroup_name(optional) andisMultipleGlobalEvent`.

When type="schedule" max length = 1.
operatorStringType of condition, valid values are or and and.
inputDataObject[Only for type="schedule"] Optional object with keys:
- value: string or integer
- timestamp: string or integer. Timestamp in milliseconds
- context: Object
hasVariableBoolean[Only for type="schedule"] If there is a value in the variable.

Here are examples of the entity object with its different possible variants:

// type="variable" variant
{
  "type": "variable",
  "value": [{
    "id": "5df2b8d32e8472535a7437b8"
  }],
  "operator": "or", // Options: ["or", "and"]. Defaults to "or",
}
// type="device_group" variant
{
  "type": "device_group",
  "value": [{
    "id": "5df2b8d32e8472535a9238c9",
    "label": "temperature",
    "deviceGroup_name": "My Device Group",
    "isMultipleGlobalEvent": false
  }],
  "operator": "or", // Options: ["or", "and"]. Defaults to "or",
}
{
  "type": "variable",
  "value": [],
  "inputDict": {
    "value": 1, 
    "timestamp": 1693265562000,
    "context": {}
  }, 
  "hasVariable": false
}

condition Object - Attribute of triggers Object

The condition key within a trigger object holds an object as well, which has the below structure based on the value of the type key. Look at this article about basic features of Events in Ubidots.

// This structure applies to when "type" is "last_value"
{
  "type": "value", // Options: ["value", "threshold"]. Defaults to "value"
  "value": "", // String or Integer
  "operator": "", // Options: ["==", "!=", ">", "<", ">=", "<="]
  "delay": "0" // Minimum value is 0. Defaults to 0
}
// This structure applies to when "type" is "position"
{
  "type": "value", // Options: ["value", "threshold"]. Defaults to "value"
  "value": "", // String, Polygon in a map
  "operator": "in", // Options: ["in", "out"]
  "delay": "0" // Minimum value is 0. Defaults to 0
}
// This structure applies to when "type" is "inactive"
{
  "unit": "T", // Options: ["T", "H", "D"]. Defaults to "T". Max_value_by_unit = {"T": 43200, "H": 168, "D": 90}
  "value": 1, // Minimum value is 1. Defaults to 1
}
// This structure applies to when "type" is "schedule" 
{
  "days": "", // Options: ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
  "time": "", // String. Validate military hour
  "timezone": "UTC", // Choice in all time zones. Defaults to "UTC"
}

Each key represents the following:

PropertyTypeDescription
typeStringType of condition, can be value or threshold.
valueString or IntegerThreshold number used for condition for type="last_value" and type="inactive". In case of type="position", "value" is a polygon drawn in a map
operatorStringOperator of the condition, valid values are: == (equal to), != (not equal to), > (greater than), < (less than), >= (greater than or equal to), and < (less than or equal to)
delayString or IntegerTime to wait until condition execution
unitStringType of unit, can be T (minutes), H (hours) or D (days). It has a maximum value by unit as the following {"T": 43200, "H": 168, "D": 90}. Available data ranges are: "nT": every n minutes, "nH": every n hours, "nD": every n days, "W": every end of the week, "M": every end of the month. Look at this developer guide.
daysString[Only for type="schedule"] Can be monday, tuesday, wednesday, thursday, friday, saturday or sunday
timeString[Only for type="schedule"] Validate military hour
timezoneString[Only for type="schedule"] Select from all time zone list.

Here are examples of the condition object with its different possible variants:

{
  "type": "value",
  "value": "100",
  "operator": ">=",
  "delay": 0.0
}
{
  "type": "value",
  "value": "GEOMETRYCOLLECTION(POLYGON((-75.54887263947114 6.326935,-75.54901848612035 6.328406786674764,-75.54945042126302 6.329822013413004,-75.55015184587384 6.331126293844838,-75.55109580459839 6.332269505204719,-75.55224602163229 6.333207714521209,-75.55355829477993 6.333904866936427,-75.5549821941202 6.334334171274024,-75.556463 6.334479129609064,-75.55794380587979 6.334334171274024,-75.55936770522005 6.333904866936427,-75.5606799783677 6.333207714521209,-75.5618301954016 6.332269505204719,-75.56277415412615 6.331126293844838,-75.56347557873697 6.329822013413004,-75.56390751387964 6.328406786674764,-75.56405336052885 6.326935,-75.56390751387964 6.325463213325236,-75.56347557873697 6.324047986586995,-75.56277415412615 6.322743706155162,-75.5618301954016 6.32160049479528,-75.5606799783677 6.32066228547879,-75.55936770522005 6.319965133063572,-75.55794380587979 6.319535828725975,-75.556463 6.319390870390936,-75.5549821941202 6.319535828725975,-75.55355829477993 6.319965133063572,-75.55224602163229 6.32066228547879,-75.55109580459839 6.32160049479528,-75.55015184587384 6.322743706155162,-75.54945042126302 6.324047986586995,-75.54901848612035 6.325463213325236,-75.54887263947114 6.326935)))",
  "operator": "out",
  "delay": 5.0
}
{
  "unit": "D",
  "value": 10.0
}
{
  "days": [
    "monday",
    "tuesday",
    "wednesday",
  ],
  "time": "08:00",
  "timezone": "America/Bogota"
}