3.2. Alerts¶
An alert is set up by an user for notification purpose. Multiple conditions can be attached to an alert. Each condition is associated with a sensor field. An alert fires and sends a message to the owner’s inbox and email (if email functionality is enabled) when all of its attached conditions are satisfied. Currently, each user is limited to have a maximum of 20 alerts.
An alert has the following attributes:
Name | Value Description |
---|---|
id | the numeric id of the alert. It is automatically assigned when alert is created. |
name ** | the name of the alert. |
longName | longer display name of the alert. |
description ** | a description of the alert. |
owner | the user that creates the alert. The value of this field is automatically assigned as a user creates an alert. |
disabled |
|
inProgress |
|
template ** | The message template that is sent to the inbox when alert is fired. |
sendEmail ** | A boolean to enable/disable send email functionaity. |
conditions | the list of alert conditions |
** Required when creating a new alert.
An alert condition is composed of a sensor field, an operator for evaluation, and a value. It has the following attributes:
Name | Value Description |
---|---|
sensorId | the ID of the sensor associated with the condition |
field | the field name to be compared of the chosen sensor |
operator |
|
value | value that the operator compares with |
3.2.1. Listing Alerts of an User¶
To view a list of “alerts” created by an user:
URL | http://wotkit.sensetecnic.com/api/v2/alerts |
Privacy | Private |
Format | JSON |
Method | GET |
Returns | 200 OK if successful. A JSON object in the response body containing a list of alerts. |
example
curl --user {id}:{password} "http://wotkit.sensetecnic.com/api/v2/alerts"
Sample Output:
[{
"id": 6,
"owner": "crysng",
"name": "temperature-alert",
"longName": "Temperature Alert",
"description": "This alert notifies user when Hydrogen Sulfide content and Wind speed is too high at Burnaby Burmount. ",
"disabled": false,
"inProgress": false,
"template": "Hydrogen Sulfide and wind speed is high!",
"sendEmail": true,
"email": "rottencherries@hotmail.com",
"conditions": [
{
"sensorId": 241,
"field": "h2s",
"operator": "GT",
"value": 10
},
{
"sensorId": 241,
"field": "wspd",
"operator": "GE",
"value": 50
}
]
},
{
"id": 5,
"owner": "crysng",
"name": "test",
"longName": "Moisture Sensor Alert",
"description": "This alert fires when moisture level is too low. ",
"disabled": false,
"inProgress": false,
"template": "Moisture level is too low, water the plant now!",
"sendEmail": true,
"email": "someone@email.com",
"conditions": [
{
"sensorId": 504,
"field": "value",
"operator": "LT",
"value": 3
}
]
}]
3.2.2. Viewing an Alert¶
To view an alert, query the alert by its id as followed:
URL | http://wotkit.sensetecnic.com/api/v2/alerts/{alert id} |
Privacy | Private |
Format | json |
Method | GET |
Returns | 200 OK if successful. A JSON object in the response body describing an alert. |
example
curl --user {id}:{password} "http://wotkit.sensetecnic.com/api/v2/alerts/5"
Output:
{
"id": 5,
"owner": "crysng",
"name": "test",
"longName": "Moisture Sensor Alert",
"description": "This alert fires when moisture level is too low. ",
"disabled": false,
"inProgress": false,
"template": "Moisture level is too low, water the plant now!",
"sendEmail": true,
"email": "someone@email.com",
"conditions": [
{
"sensorId": 504,
"field": "value",
"operator": "LT",
"value": 3
}
]
}
3.2.3. Creating Alerts¶
To create an alert, you POST an alert resource to the url /v2/alerts.
- The alert resource is a JSON object.
- The “name”, “description”, “template”, and “sendEmail” fields are required when creating an alert.
- The alert name must be at least 4 characters long, contain only lowercase letters, numbers, dashes and underscores, and can start with a lowercase letter or an underscore only.
To create an alert:
URL | http://wotkit.sensetecnic.com/api/v2/alerts |
Privacy | Private |
Format | json |
Method | POST |
Returns | 201 Created if successful; 400 Bad Request if sensor is invalid; 409 Conflict if alert with the same name already exists. |
example1
curl --user {id}:{password} --request POST --header "Content-Type: application/json" --data-binary @test-alert.txt 'http://wotkit.sensetecnic.com/api/v2/alerts'
For this example, the file test-alert.txt contains the following. This is the minimal information needed to create an alert.
{
"name":"test alert",
"description":"A test alert.",
"template":"Template for test alert",
"sendEmail":false
}
example2
Now, let’s create an alert with additional information and conditions. The file test-alert.txt contains the following.
{
"name": "test alert 2",
"longName": "Test Alert 2",
"description": "This is test 2. ",
"disabled": false,
"template": "The alert test 2 has fired!! ",
"sendEmail": true,
"email": "someone@email.com",
"conditions": [
{
"sensorId": 504,
"field": "value",
"operator": "LT",
"value": 3
},
{
"sensorId": 24,
"field": "data",
"operator": "NOTNULL"
}
]
}
3.2.4. Updating Alerts¶
Updating an alert is the same as creating a new alert other than PUT is used and the alert id is included in the URL.
Note that all top level fields supplied will be updated.
- You may update any fields except “id”, and “owner”.
- Only fields that are present in the JSON object will be updated.
To update an alert owned by the current user:
URL | http://wotkit.sensetecnic.com/api/v2/v2/alerts/{alert id} |
Privacy | Private |
Format | json |
Method | PUT |
Returns | 204 No Content if successful. |
For instance, to update an alert:
example
curl --user {id}:{password} --request PUT --header "Content-Type: application/json" --data-binary @update-alert.txt 'http://wotkit.sensetecnic.com/api/v2/alerts/{alert id}'
The file update-alert.txt would contain the following:
{
"longName": "New Alert Name",
"description":"Updated Description"
}
3.2.5. Deleting Alerts¶
Deleting an alert is done by deleting the alert resource.
To delete an alert owned by the current user:
URL | http://wotkit.sensetecnic.com/api/v2/alerts/{alert id} |
Privacy | Private |
Format | not applicable |
Method | DELETE |
Returns | 204 No Response if successful. |
example
curl --user {id}:{password} --request DELETE 'http://wotkit.sensetecnic.com/api/v2/alerts/{alert id}'