How to use rules¶
Rules used to set up conditions according to which the system logs the events and sends notifications to user.
When a server receives a new portion of data from the device, it checks whether the conditions set are true or false for this data. If they are true, the server generates an event in history, logs it and immediately sends SMS, push message or email and saves event in history.
Create¶
To start work the rule must be created. Let's create a rule with conditions according to which the platform will generate events and schedule intervals when this rule should work using the rule/create. The user must have access to rule update.
Necessary parameters for this call. Availability of some parameters depends on used rule type:
name
- A string containing a name of created rule.description
- A string containing rule's description.zone_ids
- An int array. A list of zones to bind where the rule will work. Leave it empty if rule should work everywhere. Parameterzone_ids
is not allowed for ruleoffline
and required forroute
andinoutzone
rule types.trackers
- An int array. A list of tracker IDs belong to user for which the rule will work.type
- A string containing one of pre-defined types of rules. See rule types.primary_text
- A string with primary text of rule notification when condition istrue
.secondary_text
- An optional string with secondary text of rule notification when condition isfalse
. The availability of this parameter depends on rule type. Not every rule has thesecondary_text
.param
- An optional integer. A common parameter that responsible for integer conditions. The availability of this parameter depends on rule type. See rule types.alerts
- An object with destinations for notifications. Answers the question - who and how will receive notifications. Described in rule object.suspended
- A boolean which starts and stops the rule.true
if the rule suspended.schedule
- An optional object which configures the time - when the rule works. Described in rule object.extended_params
- An optional object. Specified for concrete rule type. See rule types.
API request:
curl -X POST 'https://api.navixy.com/v2/tracker/rule/create' \
-H 'Content-Type: application/json' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "rule": {"description": "", "type": "work_status_change", "primary_text": "status changed", "alerts": {"push_enabled": true, "emails": ["example@gmail.com"], "emergency": false, "sms_phones": ["745494878945"], "phones": []}, "suspended": false, "name": "Status changing", "trackers": [123456], "extended_params": {"emergency": false, "zone_limit_inverted": false, "status_ids": [319281,319282,319283]}, "schedule": [{"from": {"weekday": 1, "time": "00:00:00"}, "to": {"weekday": 7,"time": "23:59:59"}, "type": "weekly"}], "zone_ids": []}}'
You will get ID of created rule in response.
{
"success": true,
"id": 123
}
Bind/Unbind¶
When a rule created, bind devices to it. For example, a newly registered device must have the same rule. Unnecessary to create another rule. Bind this device to an already existing rule. Unbinding works similarly. When a rule is not necessary for some devices, unbind them without deleting rules.
Necessary parameters for both calls the same.
rule_id
- An ID of a rule. You can get IDs using the rule/list call.trackers
- An int array. List trackers' IDs. Trackers which do not exist, owned by other user or deleted ignored without errors.
API requests:
curl -X POST 'https://api.navixy.com/v2/tracker/rule/bind' \
-H 'Content-Type: application/json' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "rule_id": 123, "trackers": [265489]}'
curl -X POST 'https://api.navixy.com/v2/tracker/rule/unbind' \
-H 'Content-Type: application/json' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "rule_id": 123, "trackers": [265489]}'
Update¶
If the rule must be updated, for example, one more phone number must be added for SMS notifications, you can use the rule/update call. It is much better than deleting an existing rule and creating a new one.
List of necessary parameters is the same as in rule/create call plus id
parameter.
id
- An integer with ID of the updating rule. You can get IDs using the rule/list call.
API request:
curl -X POST 'https://api.navixy.com/v2/tracker/rule/update' \
-H 'Content-Type: application/json' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "rule": {"id": 123, "description": "", "type": "work_status_change", "primary_text": "status changed", "alerts": {"push_enabled": true, "emails": ["example@gmail.com"], "emergency": false, "sms_phones": ["745494878945"], "phones": []}, "suspended": false, "name": "Status changing", "trackers": [123456], "extended_params": {"emergency": false, "zone_limit_inverted": false, "status_ids": [319281,319282,319283]}, "schedule": [{"from": {"weekday": 1, "time": "00:00:00"}, "to": {"weekday": 7, "time": "23:59:59"}, "type": "weekly"}], "zone_ids": []}}'
Suspend¶
To suspend the rule use the rule/update call and change only one parameter suspended
to true
. All other parameters should present in the call without changes.
API request:
curl -X POST 'https://api.navixy.com/v2/tracker/rule/update' \
-H 'Content-Type: application/json' \
-d '{"hash": "a6aa75587e5c59c32d347da438505fc3", "rule": {"id": 123, "description": "", "type": "work_status_change", "primary_text": "status changed", "alerts": {"push_enabled": true, "emails": ["example@gmail.com"], "emergency": false, "sms_phones": ["745494878945"], "phones": []}, "suspended": true, "name": "Status changing", "trackers": [123456], "extended_params": {"emergency": false, "zone_limit_inverted": false, "status_ids": [319281,319282,319283]}, "schedule": [{"from": {"weekday": 1, "time": "00:00:00"}, "to": {"weekday": 7, "time": "23:59:59"}, "type": "weekly"}], "zone_ids": []}}'