Skip to content

Manage Rules

Jump to bottom
Ivan Emilov edited this page Apr 6, 2018 · 12 revisions

Table of contents

Rules

The rules engine is running as continuous WEBJOB within the WEBAPI application.

Note: all examples contains comments about the required KEYS in the JSON body in case of POST, PUT or PATCH requests!

Create rules

Currently the following conditions are possible with this application:

  • activate/deactivate the rule
  • set threshold values
  • set range between values
  • store only delta sensor data
  • monitor device connection status

Note: give meaningful names to the rules. Currently it is possible to create only one condition and 2 actions (store alarm and send email) within one rule!

Threshold rule

Threshold rules supports currently operators: '>', '<' and '=='

Example curl for threshold rule:

POST /api/rules HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "rulename": "temperaturethreshold",  //required
  "description": "notify me if temperature reaches 24 degree",
  "tag": "aircondition", //required
  "objects": [  //required
    {
      "object": "aircondition01",  //required
      "deviceid": "device01"  //required
    }
  ],
  "condition": {             //required
    "name": "threshold",     //required
    "sensor": "temperature",
    "value": 24,
    "operator": ">"
  },
  "actions": {  //required
    "alarm": true,
    "notifyMail": true
  },
  "mailReceiver": [
    {
      "mail": "john.doe@gmail.com"
    }
  ],
  "enable": true  //required
}

Note: if you set threshold condition, the name of the condition should be written exactly as the example above("name":"threshold"). The sensor type, the threshold value and the operator can be set based on the user needs!

Range rule

Example curl for the range rule:

POST /api/rules HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "rulename": "TemperatureRange",
  "description": "notify me if the temperature get outside a given range",
  "tag": "airCondition",
  "objects": [
    {
      "object": "airCondition01",
      "deviceid": "myPi"
    }
  ],
  "condition": {
    "name": "range",
    "sensor": "temperature",
    "from": 22,
    "to": 23.4
  },
  "actions": {
    "alarm": true,
    "notifyMail": true
  },
  "mailReceiver": [
    {
      "mail": "chris@mail.com"
    },
    {
      "mail": "liam@mail.com"
    }
  ],
  "enable": true,
}

Note: if you set range condition, the name of the condition should be written exactly as the example above("name":"range"). The sensor type, the range values( FROM TO ) can be set based on the user needs!

Telemetry rule

Example curl for telemetry rule:

POST /api/rules HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "rulename": "storeTelemetryTemperature",
  "description": "store temperature values of picked objects/devices",
  "tag": "airCondition",
  "objects": [
    {
      "object": "airCondition01",
      "deviceid": "myPi"
    }
  ],
    "condition": {
      "name": "telemetry",
      "sensor": "temperature",
      "delta": 5
    },
    "actions": {
      "storeMessage": true
    },
    "enable": true
}

Note: if you set store telemetry condition, the name of the condition should be written exactly as the example above("name":"telemetry"). The sensor type and the delta value can be set based on the user needs. The delta value 5 (from the example) would mean that every current temperature value will be compared with the previous one and if the difference is more than 5% the rule will be triggered an the message will be stored!

Connection status rule

Example curl for connection status rule:

POST /api/rules HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
    "rulename": "MonitorConnectionStatus",
    "description": "notify me if device get disconnected",
    "tag": "airCondition",
    "objects": [
      {
        "object": "airCondition01",
        "deviceid": "myPi"
      }
    ],
    "condition": {
      "name": "connectionstatus",
      "status": "Disconnected"
    },
    "actions": {
      "alarm": true,
      "notifyMail": true
    },
    "mailReceiver": [
      {
        "mail": "is.emilov@gmail.com"
      },
      {
        "mail": "ihsamardzhieva@gmail.com"
      }
    ],
    "enable": true
  }

Note: if you set connectionstatus condition, the name and the status of the condition should be written exactly as the example above("name":"connectionstatus" and "status": "Disconnected")!

Add object and device to the rule

Once created a particular rule can be populated with different objects/devices which generated sensor data you want to apply the rule to. Keep in mind that every object should be always added with the associated device.

Example curl:

PATCH /api/rules/YOURRULE/addObject HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "object": "elevator02", //required
  "deviceid": "device02"  // required
}

Remove object and device from the rule

If you want to exclude one particular object/device relation from the ruleset you can remove it.

Example curl:

PATCH /api/rules/YOURRULE/removeObject HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "object": "elevator02", //required
  "deviceid": "device02"  // required
}

Add mail receiver to the rule

You can also add several mail receivers to get notifications if a particular rule is triggered.

Example curl:

PATCH /api/rules/YOURRULE/addMAIL HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "mail": "john.doe@gmail.com"  //required
}

Remove mail receiver from the rule

You can also remove a particular mail receiver from the rule.

Example curl:

PATCH /api/rules/YOURRULE/removeMAIL HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "mail": "john.doe@gmail.com"  //required
}

View rules

Get all rules within the current rulesset.

Example curl:

GET /api/rules HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>

Example response body:

[
  {rule 1},
  {rule 2},
  {rule N}
]

View rule

Get all data from particular rule.

Example curl:

GET /api/rules/YOURRULE HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>

Example response body:

  {rule N},

Delete rule

Delete request removes the rule document completely from the data base.

Example curl:

DELETE /api/rules/YOURRULE HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>

Change rule

Every rule parameter (enable state, description and etc.) except the name, can be changed.

Example curl:

PUT /api/rules/YOURRULE HTTP/1.1
Host: NAMEOFYOURAPP.azurewebsites.net
Content-Type: application/json
Authorization: Bearer <token>
{
  "ruleKey":"deltaValue"
}
Clone this wiki locally