Rules API¶

Warning

This API is still experimental and might be changed at any time!

The following describes the API calls required to create, modify, activate and deactivate rules. It can also be used to query the current state of an existing rule. As with other API calls, the rule API also requires a valid and an authenticated user session.

A rule is a collection of states and edges. An edge (transition) is defined as a step from a preceding state to the succeeding state when the given conditions are fulfilled and is characterized by the actions to be performed while undergoing the transition. A description of rules, its states, edges and transitions will be called as a rule definition throughout this chapter.

API Call Reference¶

/api/rule¶

POST /api/rule¶

Creates a new rule and returns the rule-id of the newly created rule.

Request body example

{
    "name": "Livingroom lights",
    "time_zone": "Europe/Berlin",
    "initial_state": "lights_off",
    "edges": [{
        "from": "lights_off",
        "to": "lights_on",
        "conditions": [{
            "type": "sensor_data",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
            "value": [1]
        }],
        "actions": [{
            "type": "sensor_action",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
            "value": [1]
        }]
    }, {
        "from": "lights_on",
        "to": "lights_off",
        "conditions": [{
            "type": "sensor_data",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
            "value": [0]
        }],
        "actions": [{
            "type": "sensor_action",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
            "value": [0]
        }]
    }],
    "active": true,
    "state": "lights_on",
    "metadata": {
          "place": "Living Room",
          "properties": {
                "color": "green"
          }
    }
}

JSON Parameters:

name –
^.{1,200}$

mandatory: A user-given name for the rule, does not need to be unique.
time_zone –
^.{2,32}$

optional: The time zone of this rule. If time_zone is not set it will default to UTC.
initial_state –
^.{1,200}$

mandatory: The initial state from which the execution of rule begins, when no further state is specified.
edges – mandatory: A collections of transitions. edges field has to be a json array and can’t be empty.
from –
^.{1,200}$

mandatory: The state from which the specific transition is defined.
to –
^.{1,200}$

mandatory: The state to which the specific transition terminates after performing the action.
conditions – mandatory: A set of conditions necessary to begin a transition, i.e., follow an edge. The conditions field contains an array of conditions. A condition can be described based on the mandatory type field. For example, a condition of type sensor_data is fulfilled when the measurement from the sensor is equal to the one specified in value field.
actions – mandatory: A set of actions to be performed during a transition. The actions field contains an array of actions. An action can be described based on the mandatory type field. For example, a action of type sensor_action is performed by changing the sensor value to the one specified in the value field. In case, no actions are to be performed, actions can be an empty array.
active –
true|false

optional: A JSON boolean value, that specifies if the rule will be activated after the creation or not. The default value is true.
state –
^.{1,200}$

optional: A JSON string value, that specifies the state, from which the rule will start its execution. The rule will start from the initial_state by default. Note that, on setting the active field to false the starting_state field will be ignored. Upon next activation, the rule will start from the initial state when no different state is specified.
metadata – optional: A JSON object with the metadata to be stored with the rule. e.g. { “gui_profile”: “client-id”}. The metadata object can’t be larger than 5 KB. It is in the responsibility of the client to not corrupt any pre-existing metadata, i.e., an overwrite to the metadata must not break its interpretation by other clients or delete any entries added by other clients.

A more detailed description on the types of conditions and actions and how to define them can be found at Conditions in a rule and Actions by a rule.

Response body example

{
    "status": "ok",
    "uuid": "ce19884c-8fed-11e2-93fe-0024e8f90cc0"
}

JSON Parameters:

status –
- wrong-sensor: The user does not have the necessary permissions for one or more of the sensors mentioned in the rule definition.
- wrong-state: The rule definition has a field state that does not exist in the collection of edges.
- deactivated-rule: The rule definition has a field state while active is false.
- too-large: The metadata field is bigger than 5kB.
- access-denied: The edges contain action(s), that the user is not authorized to execute.

GET /api/rule¶

Fetches rules in the system that belong to the user.

Parameters:

from –
timestamp

optional: start time in seconds-since-epoch (must have from <= to)
to –
timestamp

optional: end time in seconds-since-epoch (must have from <= to)
start –
uuid

optional: The UUID of the first rule to be returned. The rule with an exact match UUID is not returned. If present, it overrides the from parameter
count –
1...500

optional: limits the number of returned rules. The default value is 20.

Response body example

{
    "status": "ok",
    "rule": {
        "ce19884c-8fed-11e2-93fe-0024e8f90cc0" : {
            "name": "Livingroom lights",
            "active": true,
            "state": "lights_on",
            "metadata":  {}
        },
        "ce19884c-8fed-11e2-93fe-0024e8f90cc7" : {
            "name": "Bedroom lights",
            "active": false,
            "state": "lights_off",
            "metadata":  {}
        }
    }
}

JSON Parameters:

name – The name of the rule as specified in the rule definition.
active – The execution state of the rule, if it is active or not.
state – The current state at which the rule is waiting for the set of conditions to be satisfied. If the rule is inactive, the last saved state before the deactivation is returned.
metadata – A JSON object containing the latest version of metadata.

DELETE /api/rule/(rule-id)¶

Deletes an existing rule definition with the given rule-id. The rule will be deactivated automatically before it is deleted.

Response body example

{
    "status": "ok"
}

JSON Parameters:
	status – wrong-rule: The rule with `rule-id` does not exist or does not belong to the user.

GET /api/rule/(rule-id)¶

Returns all information about the rule with the given rule-id.

Response body example

{
    "status":"ok",
    "rule":{
        "active":true,
        "state":"lights_on",
        "time_zone": "Europe/Berlin",
        "metadata": {},
        "name":"Livingroom lights",
        "initial_state":"lights_off",
        "edges": [{
            "from": "lights_off",
            "to": "lights_on",
            "conditions": [{
                "type": "sensor_data",
                "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
                "value": [1]
            }],
            "actions": [{
                "type": "sensor_action",
                "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
                "value": [1]
            }]
        }, {
            "from": "lights_on",
            "to": "lights_off",
            "conditions": [{
                "type": "sensor_data",
                "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
                "value": [0]
            }],
            "actions": [{
                "type": "sensor_action",
                "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
                "value": [0]
            }]
        }]
    }
}

JSON Parameters:
	status – wrong-rule: The rule with `rule-id` does not exist or does not belong to the user.

POST /api/rule/(rule-id)¶

Updates the rule with the given rule-id.

Request body example

{
    "name": "Livingroom lights",
    "time_zone": "Europe/Berlin",
    "metadata": {},
    "state": "lights_on",
    "active": true,
    "initial_state": "lights_off",
    "edges": [{
        "from": "lights_off",
        "to": "lights_on",
        "conditions": [{
            "type": "sensor_data",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
            "value": [1]
        }],
        "actions": [{
            "type": "sensor_action",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
            "value": [1]
        }]
    }, {
        "from": "lights_on",
        "to": "lights_off",
        "conditions": [{
            "type": "sensor_data",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
            "value": [0]
        }],
        "actions": [{
            "type": "sensor_action",
            "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
            "value": [0]
        }]
    }]
}

JSON Parameters:

name –
^.{0,200}$

optional: New name of the rule.
time_zone –
^.{2,32}$

optional: The new time zone of this rule. If the rule is active and the active field is not false, the rule will be restarted with the updated definition. However, if the rule is inactive and the active field is true, the rule will activated and the state will be set in accordance with state field.
metadata – optional: A JSON object with the metadata to be stored with the rule. The metadata object can not be larger than 5 KB. For more information, check POST /api/rule
state –
^.{0,200}$

optional: The state to which the rule will jump without following intermittent edges, before continuing the execution. In other words, no actions will be executed during this change since none of the edges were followed. More importantly, the state can only be changed, when the rule is active and the state exists. As a consequence, setting the active field to false and changing the state field has no effect.
active –
true|false

optional: A boolean JSON value, that specifies if the rule shall be activated or deactivated. The rule will be activated if the active field is true and the rule is currently inactive.
initial_state –
^.{1,200}$

optional: The initial state from which the execution of rule shall begin after the next start/restart. Note, that the state has to exist.
edges – optional: A set of transitions. If the rule is active and the active field is not false, the rule will be restarted with the updated definition. However, if the rule is inactive and the active field is true, the rule will activated and the state will be set in accordance with state field.

At least, one of the fields must be present in the request body.

Response body example

{
    "status": "ok"
}

JSON Parameters:

status –
- wrong-rule: The rule with rule-id does not exist or does not belong to the user.
- deactivated-rule: The state could not be changed because the rule is inactive.
- wrong-state: The rule definition has a field state that does not exist in the edges.
- too-large: The metadata is larger than 5kB.
- access-denied: The edges contain action(s), that the user is not authorized to execute.

If any one of the fields in the API request is invalid or causes an error, then none of the specified changes will be executed.

Conditions in a rule¶

Conditions are checks that are performed before stepping from one state to another via an edge. This section describes all currently supported types of conditions.

Conditions are usually transformed to triggers, and a state check and transition is only performed when triggered.

Sensor Data¶

This condition checks one or more measured data points of a sensor for equality and whether the value is inside a given range.

Equality is evaluated by checking for all the capabilities provided in the value property.

Ranges can be checked by a combination of min and max. Note that, all the entries in the min property require a corresponding entry in the max property, that is greater than the min property. In order to specify a condition outside of the range specified by min and max, use the boolean not operator as specified in Boolean conditions. Also, min and max mean more or equal and less or equal respectively. Null values will be skipped in all checks. This also applies to multi sensor values, which will be defined as value-arrays.

Examples¶

If capability with index 0 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc1 equals 1:

{
    "type": "sensor_data",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "value": [1]
}

If capability with index 0 and 1 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc1 equals 1 and 0 respectively:

{
    "type": "sensor_data",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "value": [1, 0]
}

If capability with index 1 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc2 is at least 5.3:

{
    "type": "sensor_data",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
    "min": [null, 5.3]
}

If capability with index 0 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc2 is less than or equal to 5.3:

{
    "type": "sensor_data",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
    "max": [5.3]
}

If capability with index 0 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc3 is in the range of 10 and 234, with 10 and 234 included:

{
    "type": "sensor_data",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc3",
    "min": [10],
    "max": [234]
}

Trigger¶

This condition creates a trigger that is fired every time a new sensor data is received. It does not necessarily mean that the data has changed. The trigger can also fire when the condition was already satisfied by the last seen value of the sensor, which will be checked when the condition is enabled. In case this behavior is not wanted, have a look at the sensor_event condition type.

Sensor Event¶

The sensor_event condition skips the initial check with the last value, otherwise works in the same way as sensor_data conditions. This condition supports all of the operators as supported by the sensor_data conditions. The creation of triggers is slightly different, as it will only react to sensor events that enter the cloud when the condition is enabled.

Examples¶

If capability with index 0 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc1 equals 1:

{
    "type": "sensor_event",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "value": [1]
}

Trigger¶

This condition creates a trigger that is fired every time a new sensor data is entering the cloud. It does not necessarily mean that the data has changed.

Time¶

The time condition checks if it is a certain point in time or whether the time is in a certain range. Time must be represented in the format hh:mm:ss with hh ranging from 0 to 23, and mm and ss ranging from 0 to 60.

Examples¶

When it is 4:30 pm:

{
    "type": "time",
    "value": "16:30:00"
}

When the event occurs between 10 pm and 5 am:

{
    "type": "time",
    "min": "22:00:00",
    "max": "05:00:00"
}

Trigger¶

This condition will create triggers based on the type of the condition (value vs. range):

A time-condition with value will be triggered only at the specified time.
A time-range-condition with min and max will be triggered at the the specified time in the min property.

Time conditions can often be combined with additional conditions specifying repetitions and recurrences, as we specify below.

Weekday¶

The weekday condition checks if it is a certain day of the week. The value field is an array containing all the days, in abbreviated form, on which the condition will be true.

{
    "type": "weekday",
    "value": [ "MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN" ]
}

Trigger¶

This condition will create triggers at the start (00:00:00) of the specified day(s):

Date¶

The user can also specify exact dates optionally. The date condition may contain the specific date or a range of two dates in “DD.MM” format.

When it is 22nd of March (00:00:00),

{
    "type": "date",
    "value": "22.03"
}

or a range from 22nd of March (00:00:00) to 27th of April (23:59:59)

{
    "type": "date",
    "min": "22.03",
    "max": "27.04"
}

Trigger¶

This condition will create triggers based on the type of the condition (value vs. range):

A date-condition with value will be triggered only at the start (00:00:00) of the specified date.
In case, one has specified the 29th of February as a date-condition, the condition will only be triggered in a leap year.
A date-range-condition with min and max will be triggered at the beginning of the specified date in the min property.
In case, one has specified the 29th of February as a bound of a date-range-condition, it will be interpreted as the 28th of February if the current year is not a leap year.

Timeout¶

The timeout condition checks how long is the rule waiting at the current state. The timeout is reset, if on following an edge the rule comes back to the same state from which the edge starts.

The duration of the timeout is determined by the value field which must be given in seconds.

Examples¶

After 5 minutes:

{
    "type": "timeout",
    "value": 300
}

Trigger¶

This condition will be triggered when the timeout expires.

Boolean conditions¶

The and, or and not conditions can be used to create boolean combinations of other conditions. A not operator on a timeout-condition and daytime-condition alone is invalid.

Examples¶

If both conditions are required to be satisfied before following an edge:

{
    "type": "and",
    "conditions": [{
        "type": "sensor_data",
        "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
        "value": [1, 0]
    }, {
        "type": "date",
        "value": "22.03"
    }]
}

If one of the conditions is to be satisfied:

{
    "type": "or",
    "conditions": [{
        "type": "sensor_data",
        "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
        "value": [1, 0]
    }, {
        "type": "sensor_data",
        "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
        "min": [null, 5.3]
    }]
}

If the negation of a condition is to be satisfied:

{
    "type": "not",
    "condition": {
        "type": "sensor_data",
        "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc3",
        "min": [10],
        "max": [234]
    }
}

Trigger¶

The triggers are created for the conditions connected by the boolean conjuncts.

Actions by a rule¶

Actions are performed when stepping from one state to another via an edge. This sections describes all currently supported types of actions.

Sensor Action¶

This action sets one or more values on a sensor device. Each sensor action holds information about the sensor identifier (uuid) and the values to be set. A particular value for a specified capability can also be an array (example below).

Examples¶

Set capability with index 1 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc1 to 1:

{
    "type": "sensor_action",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "value": [null, 1]
}

Set capability with index 0 and 1 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc1 to 0 and 1 resp.:

{
    "type": "sensor_action",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "value": [0, 1]
}

Set capability with index 0 of sensor ce19884c-8fed-11e2-93fe-0024e8f90cc2 to green (0 red, 255 green, 0 blue):

{
    "type": "sensor_action",
    "sensor": "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
    "value": [[0, 255, 0]]
}

Notification E-Mail¶

This action will send an email to one or more recipients.

Examples¶

Send an email to user@domain.com and user_2@domain.com with the specified subject and text:

{
    "type": "email",
    "recipients": ["user@domain.com", "user_2@domain.com"],
    "subject": "Movement at ${NAME} detected",
    "text": "You might want to check this ${METADATA.properties.color} ${METADATA.place} ...!"
}

Both recipients will be added to the to-field in the email header. The ${NAME} template will be replaced by the rule name. The ${METADATA.place} template will be replace by the metadata field place. The ${METADATA.properties.color} template will be replace by the metadata field properties.color.

Predefined templates:

${NAME} rule name

${STATE} rule state

${ISO_DATE} trigger date in ISO format

${ISO_DATE_TIME} trigger date & time in ISO format

${ISO_TIME} trigger time in ISO format

Set credit counter of usergroup¶

This action will set the credit counter of the specified usergroup to the specified credit value. This action can only be used by authorized users!

Examples¶

Sets the credit of usergroup: cc17884c-8fed-11e2-93fe-0024e8f90cc3 to a value of 100:

{
    "type": "set_credit",
    "usergroup": "cc17884c-8fed-11e2-93fe-0024e8f90cc3",
    "credit": 100
}

The credit field has to be a positive integer. In case the user loses the authorization to execute the action during the runtime of the corresponding rule, it will be deactivated once the action will be executed for the next time, but it will nevertheless follow the edge to the followup state.

Push-Notification Android and iOS¶

This action will send push notification messages to all registered devices of the rule creator.

Examples¶

{
    "type": "push_notification",
    "content": "Movement at home detected"
}

The content field can be an arbitrary JSON value. The corresponding payload the receiving devices can expect looks like the following:

{
    "message": "rule_engine_notification",
    "rule": "af729cc0-3251-11e2-81c1-0800200c9a66",
    "content": "Movement at ${NAME} detected"
}

The message field identifies the received notification as payload produced by the rule engine. The rule field tells the receiving application, which rule has executed the push_notification action and the content field is carrying the specified content in the action definition. The overall size of resulting push notification messages is limited to 2048 Byte. As the message and rule fields are static, the content field has to be chosen properly to not exceed this limit. The content field can contain the same templates like the email notification.

Call-Notification¶

This action will call the one or more given numbers.

Examples¶

{
    "type": "call",

    "from": "+492216698701",
    "from_name": "John Doe",
    "clip": "+492216698702",
    "recipients": ["+492216698706", "+492216698707"],
    "commands": [
        { "silence":500 },
        { "announcement": "550625e0-fb34-11e5-aabf-2fe9eca72bbf" }
    ]
}

JSON Parameters

from – ^\+[0-9]{3,20}$

sets the user phone number.
from_name – ^\+[0-9]{3,20}$

optional; sets the from name for this call setup.
clip – ^\+[0-9]{3,20}$

optional; sets the clip number for this call setup.
recipients – JSON array

contains all targets(^\+[0-9]{3,20}$).
commands – JSON array

contains the commands for playback.

In the example above the object which contains silence will generate 500 ms of silence in the call. The announcement container holds the UUID of the object for playback.

Rule events¶

Event rule_new¶

This event is sent to all session of the current user when a new rule is created. It also contains the metadata corresponding to the rule if added by the rule creator.

{
    "rule" : "ce19884c-8fed-11e2-93fe-0024e8f90cc0",
    "name": "Livingroom lights",
    "initial_state": "lights_off",
    "active": false,
    "metadata" : {}
}

Event rule_delete¶

This event is sent to all session of the current user when a rule is deleted.

{
    "rule" : "ce19884c-8fed-11e2-93fe-0024e8f90cc0"
}

Event rule_update¶

This event is sent to all sessions of the current user when any property of the rule is updated or modified.

{
    "rule" : "ce19884c-8fed-11e2-93fe-0024e8f90cc0",
    "name": "Livingroom lights",
    "initial_state": "lights_off",
    "edges_updated": true,
    "time_zone": "Europe/Berlin",
    "active" : true,
    "state" : "init_state",
    "metadata": {}
}

The event will only carry the properties that have changed. In case, the edges and the time_zone was updated, so the edges_updated and time_zone field is set to true.