########### Trigger API ########### A REST API to lookup/create/update/delete triggers All trigger API requests require an API bearer token to prove that the client is authorized to make the request. If the token has OWNER permissions then only triggers owned by the account associated with the token are accessible. If the token has GROUP or ADMIN privilege then the client can access any trigger owned by any account provided that a valid key is provided that is associated with the requested object. This would normally be an account key or a gateway key for which the trigger is assigned to. Lookup trigger ============== .. http:get:: /api/trigger Get trigger attributes for the specified trigger as a JSON object. :query string key: The owner account key. This can be an account key or a gateway key. :query string trigger: The trigger uuid :query int indent: optional - pretty print the json output using the indent value. Default is no indent. :reqheader Authorization: Bearer :reqheader Content-Type: application/json :statuscode 200: Request succeeded :statuscode 400: Parameters are invalid :statuscode 403: Unauthorized - invalid key or API token :statuscode 404: Invalid trigger id (trigger not found) .. http:get:: /api/trigger Get trigger attributes for the all the triggers owned by the specified gateway. :query string key: The owner account key. This can be an account key or a gateway key. :query string gateway: The mac address of the gateway that owns the trigger. :query int indent: optional - pretty print the json output using the indent value. Default is no indent. :reqheader Authorization: Bearer :reqheader Content-Type: application/json :statuscode 200: Request succeeded :statuscode 400: Parameters are invalid :statuscode 403: Unauthorized - invalid key or API token :statuscode 404: Invalid trigger id (trigger not found) Example ------- Get a list of triggers for `gateway 4016fa0500cd `_. .. http:example:: curl GET /api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd HTTP/1.1 Host: api.ekmpush.com Accept: application/json Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk HTTP/1.1 200 OK Content-Type: application/json { "triggers": [ { "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c", "trigger_name": "test", "conditions": [ { "type": "data", "field": "kWh_Tot", "source": "meter", "duration": "0", "source_id": "000350000900", "continuous": false, "hysteresis": "60", "threshold_test": "rise_eq", "threshold_value": "10" } ], "actions": [ { "params": { "relay": "relay_1", "status": "close", "duration": 1 }, "target": "meter", "command": "setRelay", "target_id": "000350000900" } ], "enabled": true, "created_at": "2021-07-28T17:20:31.824621+00:00", "updated_at": "2021-07-28T17:20:31.824621+00:00" } ] } Create Trigger ============== .. http:post:: /api/trigger Create a new trigger :query string key: The owner account key. This can be any key associated with the account. :query string gateway: The mac address of the gateway that owns the trigger. :reqjson jsonobj trigger: The trigger attributes :reqheader Authorization: Bearer :reqheader Content-Type: application/json :statuscode 201: Request succeeded, trigger created :statuscode 400: Parameters are invalid :statuscode 403: Unauthorized - invalid key or API token :statuscode 500: Internal error (ie unable to create trigger) The trigger JSON will be returned as JSON in the response body if successful (status 201). In case of an error (response code 400) the response JSON will contain an *error* attribute with a string value describing the error. Trigger JSON Attributes ----------------------- :trigger_name: *(string)* The name of the trigger :enabled: *(boolean)* Enable trigger if true (default) :conditions: *(jsonobj)* List of conditions :actions: *(jsonobj)* List of actions Read-only attributes: :trigger_uuid: *(string)* A unique identifier :created_at: *(string)* The date/time of creation (ISO format) :updated_at: *(string)* The date/time of last update/modify (ISO format) Conditions .......... There are two types of conditions: Data and RRULE (recurrence rule). Data conditions are for testing field data values and RRULE conditions are for triggering actions at a specified time or recurrence. :type: *(string)* Condition type (ie "data", or "rrule") Data Condition ++++++++++++++ :source: *(string)* The data source device type (ie "meter", "iostack") :source_id: *(string)* The source id (ie meter address). :field: *(string)* The name of the field to monitor. :threshold_value: *(float)* The threshold value to compare with. :threshold_test: *(string)* The threshold value test. *"=="*: Data field value equals threshold value *"!="*: Data field value not equals threshold value *">="*: Data field value greater than or equals threshold value *"<="*: Data field value less than or equals threshold value *">"*: Data field value greater than threshold value *"<"*: Data field value less than threshold value :duration: *(float)* Optional - Minimum duration in seconds of the test condition (default 0). :hysteresis: *(float)* Optional - Minimum time in seconds before the next test (default 60). :continuous: *(boolean)* Optional - Keep firing as long as condition is satisfied (default false). :tolerance: *(float)* Optional - Floating point comparison tolerance/epsilon (default 1e-6). Example: Trigger when meter 0000300001317 field kWh_Tot rises above 1000 .. code:: "conditions": [ { "type": "data", "source": "meter", "source_id": "0000300001317", "field": "kWh_Tot", "threshold_value": "1000", "threshold_test": "rise_gt", } ] RRULE Condition +++++++++++++++ :rrule: *(string)* Recurrence rule (see: `iCalendar RFC-5545 `_) Note: All date-times are UTC (no offset). Example RRULE condition: Starting on 7/2/2021 17:32 UTC, trigger every day at 00:35:00 UTC .. code:: "conditions": [ { "type": "rrule", "rrule": "DTSTART:20210702T173200\nRRULE:FREQ=DAILY;BYHOUR=0;BYMINUTE=35;BYSECOND=0" } ] There are some decent open source RRULE generator demos you can use to build the RRULE strings: - `rrule.js `_ - `React RRULE `_ Actions ....... Actions can be a meter setting command or an email notification. See `EKM Meter Commands `_. Email notifications have some limitations to limit potential abuse: - They can only be specified for Data conditions. - The email "to" address will always be the verified email address of the account holder. - The subject and body will be auto-generated based on the condition that was satisfied. Example action: Send email notification .. code:: "actions": [ { "target": "gateway", "command": "sendEmail" } ] Example action: Close relay one on meter 000350000900 .. code:: "actions": [ { "target": "meter", "target_id": "000350000900" "command": "setRelay", "params": { "relay": "relay_1", "status": "close", "duration": 1 }, } ] Example ------- .. http:example:: curl POST /api/trigger?key=MTAxMDoyMDIw&gateway=4016fa0500cd HTTP/1.1 Host: api.ekmpush.com Accept: application/json Content-Type: application/json Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk { "trigger": { "trigger_name": "Some trigger", "enabled": true, "conditions": [ { "type": "data", "field": "kWh_Tot", "source": "meter", "duration": "0", "source_id": "000350000900", "continuous": false, "hysteresis": "60", "threshold_test": "rise_eq", "threshold_value": "10" } ], "actions": [ { "target": "meter", "target_id": "000350000900", "command": "setRelay", "params": { "relay": "relay_1", "status": "close", "duration": 1 } } ] } } HTTP/1.1 201 OK Content-Type: application/json { "trigger": { "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c", "trigger_name": "test", "enabled": true, "created_at": "2021-07-28T17:20:31.824621+00:00", "updated_at": "2021-07-28T17:20:31.824621+00:00", "conditions": [ { "type": "data", "field": "kWh_Tot", "source": "meter", "duration": "0", "source_id": "000350000900", "continuous": false, "hysteresis": "60", "threshold_test": "rise_eq", "threshold_value": "10" } ], "actions": [ { "target": "meter", "target_id": "000350000900", "command": "setRelay", "params": { "relay": "relay_1", "status": "close", "duration": 1 } } ] } } Modify trigger ============== .. http:put:: /api/trigger Modify an existing trigger :query string key: The owner account key. This can be any key associated with the account. :reqjson jsonobj trigger: The trigger attributes :reqheader Authorization: Bearer :reqheader Content-Type: application/json :statuscode 200: Request succeeded, trigger modified :statuscode 400: Parameters are invalid :statuscode 403: Unauthorized - invalid key or API token :statuscode 404: Invalid trigger id (trigger not found) :statuscode 500: Internal error (ie unable to modify trigger) The trigger JSON will be returned as JSON in the response body if successful (status 201). In case of an error (response code 400) the response JSON will contain an *error* attribute with a string value describing the error. Example ------- .. http:example:: curl PUT /api/trigger?key=MTAxMDoyMDIw HTTP/1.1 Host: api.ekmpush.com Accept: application/json Content-Type: application/json Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk { "trigger": { "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c", "trigger_name": "New trigger name" } } HTTP/1.1 201 OK Content-Type: application/json { "trigger": { "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c", "trigger_name": "New trigger name", "enabled": true, "created_at": "2021-07-28T17:20:31.824621+00:00", "updated_at": "2021-07-28T17:20:31.824621+00:00", "conditions": [ { "type": "data", "field": "kWh_Tot", "source": "meter", "duration": "0", "source_id": "000350000900", "continuous": false, "hysteresis": "60", "threshold_test": "rise_eq", "threshold_value": "10" } ], "actions": [ { "target": "meter", "target_id": "000350000900" "command": "setRelay", "params": { "relay": "relay_1", "status": "close", "duration": 1 }, } ] } } Delete trigger ============== .. http:delete:: /api/trigger Delete an existing trigger :query string key: The owner account key. This can be any key associated with the account. :reqjson jsonobj trigger_uuid: The trigger id :reqheader Authorization: Bearer :reqheader Content-Type: application/json :statuscode 200: Request succeeded, trigger modified :statuscode 400: Parameters are invalid :statuscode 403: Unauthorized - invalid key or API token :statuscode 404: Invalid trigger id (trigger not found) :statuscode 500: Internal error (ie unable to modify trigger) Example ------- .. http:example:: curl DELETE /api/trigger?key=MTAxMDoyMDIw HTTP/1.1 Host: api.ekmpush.com Accept: application/json Content-Type: application/json Authorization: Bearer BZTdu8_5iw62WQuDg4OHIMhG7mcEqJu8VrzHSywCkPk { "trigger_uuid": "1c27d0dcefc811eb90b27de8d650408c" } HTTP/1.1 201 OK Content-Type: application/json {}