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:

Property	Type	Description
type	String	Type of trigger. Valid values are `last_value`, `position`, `inactive` and `schedule`.
entity	Object	Object containing information about the entity that's used to trigger the Event (see below).
condition	Object	Object 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:

Property	Type	Description
type	String	Type of entity, can be `variable` or `device_group`.
value	Array	Contains an array of objects with keys varying based on `type`. `type="variable"`: `id` of a Variable triggering the event. `type="device_groups":` id`of the device group,`label`of the variable in the group,`deviceGroup_name`(optional) and`isMultipleGlobalEvent`. When type="schedule" max length = 1.
operator	String	Type of condition, valid values are `or` and `and`.
inputData	Object	[Only for `type="schedule"`] Optional object with keys: `value`: string or integer `timestamp`: string or integer. Timestamp in milliseconds `context`: Object
hasVariable	Boolean	[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 Connected Sensors.

// 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:

Property	Type	Description
type	String	Type of condition, can be `value` or `threshold`.
value	String or Integer	Threshold number used for condition for `type="last_value"` and `type="inactive"`. In case of `type="position"`, `"value"` is a polygon drawn in a map
operator	String	Operator 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)
delay	String or Integer	Time to wait until condition execution
unit	String	Type 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.
days	String	[Only for `type="schedule"`] Can be `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` or `sunday`
time	String	[Only for `type="schedule"`] Validate military hour
timezone	String	[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"
}