Rule API

The Rule API is used to manage rules.

Rule

A rule have the following properties.

  • id: The id of the rule. required
  • name: The name of the rule. required
  • description: A longer description of the rule.
  • category: Human readable identifier which ends up searchable along with the event. Must conform to regex /^[0-9a-zA-Z.]*$/
  • enabled: true if the rule should be enabled, false otherwise. required
  • filter: Filter to decide what things this rule should trigger for. required
    • domain: The domain that the thing must belong to. required
    • thingType: The thing type that the thing must have. required
    • thingNames[]: A list of explicit thing names that the thing must be included in.
  • expression[]: A list of expressions to evaluate when an observation is received for a thing that matches the filter. All of the expressions must be matched for the rule to trigger required
    • operator: The operator to use for the comparison in the expression required
      • Value operators: gt | gte | lt | lte | eq | ne
      • Geofence operators: inside | outside | enter| leave | insidePoi | outsidePoi | enterPoi | leavePoi
    • resource: The resource to use in the expression. This can be a resource on a thing in which case this is just the name of the resource or it can be a resource of a nested thing than the name should be the <nestedresource_type>.<resource>. If the nested resource doesn’t have a type, untyped should be used. When using any of the geofence operators inside, outside, insidePoi or outsidePoi the resource must to be latlng. required
    • value: The value to compare the resource value to in the expression required
      • For value operators this should be a simple number, string or expression as string e.g. ${2*thing.state.flow + observation.speed}.
      • For point of interest operators, insidePoi or outsidePoi, this should to be an object like {center: {lat: '<latitude>', lon: '<longitude>'}, radius: <meters>}.
      • For perimeter operators, inside or outside, this should be an array with maximum 25 latlng data point numbers [[17.911, 59.377], [17.888, 59.305], [18.097, 59.307], ...].
  • threshold: Additional conditions to throttle the number of times the rule is triggered. required
    • count: The minimum number of times that the rule must trigger before it actually calls the actions. required
    • interval: The minimum time (in seconds) since the last trigger before it actually calls the actions again. required
  • readonly: A computed property that is true if either the user has explicit Rules.READ privileges or if the rule belongs to a domain higher up in the domain tree towards root than where the user has explicit Rules.READ privileges. A user is always allowed to see rules that can effect domains and Thing Types that the user has access to, but to update the rule it has to belong to the domain (or a sub domain) where the user has the Rules.UPDATE privilege.
  • actions[]: A list of actions to perform when the rule triggers. required
    • type: The type of action to perform. Currently WEBHOOK, EMAIL, SET_RESOURCE, SMS and EVENT are supported. required
    • config: The config for the action. The config is specific to each action type and is as follows:
      • WEBHOOK: See the section called “Configuration for Webhook action” below.
      • SET_RESOURCE: {resource: <resource>, value: <value>}. When trying to use this option, the current resource can only be present in any other rule for this thing type if the threshold interval is 30s or longer. Nested resources can be set by using the type of the nested object. When using the format: <type>.<resource> e.g. pump.speed, all nested objects of the specified type will have the resource set. The types tcxn and untyped are reserved for the platform and cannot be set.
      • EMAIL: {toAddresses: <comma separated addresses>, body: <email message>, subject: <subject>}
      • SMS: {message: <message>, addressList:[array of phone numbers]}. This option requires a valid DCP account for your Managed IoT Cloud. Depending on your DCP account setup there is a limit on the number of SMS messages that can be sent per second. Recommendation is to only use one recipient in the address list. A number should be the MSISDN, i.e. on the E.164 format but without a plus sign (+) prefix, e.g. “46701223344” for a mobile subscriber in Sweden. Messages are truncated at 160 characters.
      • EVENT: {acknowledgmentRequired: <true|false>, classification: <'WARNING'|'INTERNAL'|'ALARM'|'NOTIFICATION'>, message: <message body>}

All fields in the actions configuration are passed through a substitution phase where a payload from the rule engine can be used to replace variables with actual values. So for instance if a field in the config contains the following string Rule triggered for thing: ${thing.thingName} it will result in Rule triggered for thing: thing-001 if the rule triggers for thing-001.

Configuration for Webhook action

The following configuration belongs to the actions parameter above.

  • type: WEBHOOK
  • config:
    • uri: The request uri. required
    • method: The request method. One of GET, POST, PUT, DELETE or HEAD, defaults to POST. optional
    • includeAllEventData: Set to true if request body should contain all event data. If so, the body parameter will be ignored. optional
    • body: The body of the request. Required if includeAllEventData is false or missing. Only send this if you need to structure the request body yourself. optional
    • authorizationHeader: If set, the request will contain an Authorization header with this value. optional
    • additionalHeaders[]: A list of header keys and values to be included in the request. optional
      • header: The header key required
      • value: The header value required
    • retry: Retry strategy if the first webhook fails. optional *interval: An integer (1-600) representing the number of seconds before the first retry attempt (default 3). required * maxAttempts: An integer (0-5), representing the maximum number of retry attempts (default 3). required * backOffRate: A number (1-4) that is the multiplier by which the retry interval increases on each attempt (default 2). required

Payload for setting a retry strategy of 3, 6 and 12 seconds

{
  ...
  retry: {
    interval: 3,
    maxAttempts: 3,
    backOffRate: 2
  },
}

Payload for setting a retry strategy of 10, 20 and 30 mins

{
  ...
  retry: {
    interval: 600,
    maxAttempts: 3,
    backOffRate: 1
  },
}

LIST

Required role: Read
Required privilege: Rules.READ on the home domain of the calling user
Required privilege: ThingTypes.READ on the Thing Type specified in the filter
Optional privilege: Things.READ on one or more of the domains of the Things specified in the filter

Lists all rules.

API Endpoint: [GET]: /rules

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Response

A list of rules as described above.

CREATE

Required role: ReadWrite
Required privilege: Rules.CREATE on the domain specified in the filter
Required privilege: Domains.READ on the domain specified in the filter
Required privilege: ThingTypes.READ on the Thing Type specified in the filter
Optional privilege: Things.READ on the domain(s) of the Things specified in the filter

Creates a new rule.

API Endpoint: [POST]: /rules

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • id: The id to give the new rule. If no id is provided the system generates a sequential id padded with 0s to be at least 8 characters long. In all environments except production this is also prefixed with the name of the stack. So in in development the first id is dev-00000001.
  • name: See Rule definition above. required
  • description: See Rule definition above.
  • enabled: See Rule definition above. required
  • filter: See Rule definition above. required
    • domain: See Rule definition above. required
    • thingType: See Rule definition above. required
    • thingNames[]: See Rule definition above.
  • expression[]: See Rule definition above. required
    • operator: See Rule definition above. required
    • resource: See Rule definition above. required
    • value: See Rule definition above. required
  • actions[]: See Rule definition above. required
    • config: See Rule definition above. required
    • type: See Rule definition above. required
  • threshold: See Rule definition above. required
    • count: See Rule definition above. required
    • interval: See Rule definition above. required

Example payload

{
  "name": "Thing Overheating",
  "description": "Triggered if the temperature is too high",
  "enabled": true,
  "filter": {
    "domain": "root",
    "thingType": "pump",
    "thingNames": ["thing-001", "thing-002"]
  },
  "expression": [{
    "operator": "gt",
    "resource": "temp",
    "value": "50"
  }],
  "actions": [
    {
      "config": { "..." },
      "type": "WEBHOOK"
    }
  ],
  "threshold": {
    "count": 0,
    "interval": 0
  }
}

Response

The created rule (possibly including a generated id) as described above.

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized to create a rule in the domain.
PROPERTY_REQUIRED name Returned if no name was provided.
PROPERTY_REQUIRED filter Returned if no filter was provided.
PROPERTY_REQUIRED expression Returned if no expression was provided.
PROPERTY_REQUIRED actions Returned if no actions was provided.
PROPERTY_REQUIRED threshold Returned if no threshold was provided.
INVALID_RULE rules Returned when attempting to create a rule with a possible loop
INVALID_RULE_CONFIG Returned if an action config is invalid.
RULE_ID_EXISTS Returned if a rule with provided id already exists

GET

Required role: Read
Required privilege: Rules.READ on the domain specified in the filter of the rule
Required privilege: ThingTypes.READ on the Thing Type specified in the filter
Optional privilege: Things.READ on one or more of the domains of the Things specified in the filter

Gets information about a rule.

API Endpoint: [GET]: /rules/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • id: The id of the rule to get, set in query path. required

Response

The matching rule as described above.

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user tries to get a rule that is assigned to a domain that the user is not authorized to see.
PROPERTY_REQUIRED id Returned if no id was provided.
RULE_NOT_FOUND id Returned if the rule cannot be found.

REMOVE

Required role: ReadWrite
Required privilege: Rules.DELETE on the domain specified in the filter of the rule
Required privilege: ThingTypes.READ on the Thing Type specified in the filter
Optional privilege: Things.READ on the domain(s) of the Things specified in the filter

Removes a rule.

API Endpoint: [DELETE]: /rules/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • id: The id of the rule to remove, set in query path. required

Response

No output

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user tries to remove a rule that is assigned to a domain that the user is not authorized to see.
PROPERTY_REQUIRED id Returned if no id was provided.
RULE_NOT_FOUND id Returned if the rule cannot be found.

UPDATE

Required role: ReadWrite
Required privilege: ThingTypes.READ on the Thing Type specified in the filter
Optional privilege: Things.READ on the domain(s) of the Things specified in the filter
Optional privilege: Rules.UPDATE on the domain specified in the filter, if you are updating a rule in a same domain as before
Optional privilege: Rules.DELETE on the old domain, if you are moving the rule from one domain to another one
Optional privilege: Rules.CREATE on the new domain , if you are moving the rule from one domain to another one

Updates a rule.

API Endpoint: [PUT]: /rules/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query parameters

  • id: See Rule definition above, set in query path. required

Body

  • name: See Rule definition above. required
  • description: See Rule definition above.
  • enabled: See Rule definition above. required
  • filter: See Rule definition above. required
    • domain: See Rule definition above. required
    • thingType: See Rule definition above. required
    • thingNames[]: See Rule definition above.
  • expression: See Rule definition above. required
    • operator: See Rule definition above. required
    • resource: See Rule definition above. required
    • value: See Rule definition above. required
  • actions[]: See Rule definition above. required
    • config: See Rule definition above. required
    • type: See Rule definition above. required
  • threshold: See Rule definition above. required
    • count: See Rule definition above. required
    • interval: See Rule definition above. required

Response

The updated rule as described above.

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized to update the rule or move the rule to another domain.
PROPERTY_REQUIRED id Returned if no id was provided.
PROPERTY_REQUIRED name Returned if no name was provided.
PROPERTY_REQUIRED filter Returned if no filter was provided.
PROPERTY_REQUIRED expression Returned if no expression was provided.
PROPERTY_REQUIRED actions Returned if no actions was provided.
PROPERTY_REQUIRED threshold Returned if no threshold was provided.
RULE_NOT_FOUND id Returned if the rule cannot be found.
INVALID_RULE rules Returned when attempting to create a rule with a possible loop

BULK UPDATE

Required privilege: Rules.UPDATE on the domain specified in the filter of each rule

Enables or disables multiple rules in a single call

API Endpoint: [PATCH]: /rules

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • rules: An array of rules to be updated
    • id: The id of the rule to be updated required
    • enabled: true to enable the rule, false to disable the rule required

Example payload

{
  "rules": [
    {
      "id": "-f74f2186-4a88-402d-8341-ca60cdacb4bd",
      "enabled": false
    },
    {
      "id": "-1f5d7f85-a536-41e7-ac56-508a6b9fc78a",
      "enabled": true
    }
  ]
}

Response

  • updated: An array of the updated rules
  • errors: An array of the rules which could not be updated
    • id: The id of the rule
    • message: The reason that the rule did not get updated