End user Rules
In this guide we use the term rule, alert and trigger interchangeably
addTrigger
Creates a rule (a.k.a. alert)
Usage
addTrigger instructs the Arrayent Cloud to monitor a device for a specific event.
The event is defined in the parameters of addTrigger.
When the event occurs, the Arrayent Cloud executes an automated action, also defined in the parameters of addTrigger.
Maximum message lengths are 140 characters for SMS and 8,000 characters for Push Notifications
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
devId |
int |
The Device ID of the device. |
action |
string |
The action to take when the alert is triggered. Valid options are email, sms,htmlemail, mobile_notification, and attribute |
attrName |
string |
The attribute name. |
operation |
string |
A boolean operator. Valid options are greater-than symbol (>), greater-than-or-equals symbol (>=), less-than symbol (<), less-than-or-equals symbol (<=), and equals symbol (==). Make sure to properly encode each symbol for HTTP (if using GET) or XML (if using POST)! |
threshold |
double |
The value to compare the attribute against. The two values are compared using the boolean operator specified in operation, in the form attrNameoperationthreshold. |
address |
string |
The address to send the alert to. When action is sms, this is the phone number that will receive the message. The format of the phone number is a plus sign character, followed by the country code, followed by the phone number. E.g. +14155001234. Whenaction is email or htmlemail, this is the email address that will receive the email. When action is mobile_notification, this is the mobile device (iOS or Android) that will receive the push notification. Leave address empty if you want to send the alert to all mobile devices registered for this Customer Account. Use a comma-separated list of Phone IDs to selectively specify which mobile devices should receive the alert. See thePush Notification Alerts Guide for more information. |
msg |
string |
The email, SMS, or push notification message that the end user will receive when the alert is triggered. Maximum lengths: SMS, 140 characters; push notification, 200 characters. |
autoDisarm |
boolean |
Optional. Default value: false. See Auto-Disarm. |
autoDelete |
boolean |
Optional. Default value: false. See Auto-Delete. |
autoDisable |
boolean |
Optional. Default value: false. See Auto-Disable. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to1 or true. |
targetDeviceAttributes |
string |
Optional. This attribute is only required when defining attribute alerts. You can omit it when defining email, SMS, or push notification alerts. targetDeviceAttributesspecifies the device, attribute, and attribute value that the Arrayent Cloud should send when the alert is triggered. This attribute should be formatted in the pattern of DeviceID,DeviceAttribute:AttributeValue. For example, if your Device ID is 123Device Attribute is light, and Attribute Value is 1, then targetDeviceAttributesshould contain the value 123,light:1. You can configure a single attribute alert to be sent out to multiple devices by including multiple targetDeviceAttribute in your request. E.g. targetDeviceAttributes=123,light:1 &targetDeviceAttributes=987,siren:1. |
stringThreshold |
string |
Optional. This attribute is only required when the operation is regex or “==”. If using “==” this contains an exact match to the attribute value while if regex then a regular expression is used as seen in the example below |
Response
| Element Name |
Data Type |
Description |
triggerId |
int |
The Trigger ID of the alert. The Arrayent Cloud generates this value upon creation of the alert. A list of all currently defined alerts (including each alert’s Trigger ID) can be retrieved with getTriggerDetailListByUser or getTriggerDetailListByDevice. |
Examples
Create Email Alert
The following web service request creates an email alert that is triggered when the device associated to Device ID “3847” submits a value for its temperature attribute that is greater than “80”.
https://example.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=18vYMt99&devId=3847&attrName=temperature&operation=%3E&
threshold=80&action=email&address=john%40example.com&msg=Caution!&
autoDisarm=1&autoDelete=0&autoDisable=0&enable=1
<ns1:addTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/">
<triggerId>6683</triggerId>
</ns1:addTriggerResponse>
Create Regex Alert
The following request creates an alert that is triggered when the value of the “error-code” attribute begins with the number 7, 8, or 9. The alert definition uses regular expressions to perform this pattern matching. The regular expression syntax follows Java’s usage: http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html. The Arrayent Cloud knows that it is supposed to perform regular expression pattern matching because the “threshold” parameter of the request is set to “regex”.
https://example.arrayent.com/zdk/services/zamapi/addTrigger?
secToken=18vYMt99&devId=3847&attrName=error-code&operation=regex&
stringThreshold=[789].*&action=email&address=john%40example.com&
msg=Caution!&autoDisarm=1&autoDelete=0&autoDisable=0&enable=1
The Arrayent Cloud will return a Trigger ID if the alert is successfully created.
<ns1:addTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/">
<triggerId>6683</triggerId>
</ns1:addTriggerResponse>
getTriggerDetailListByDevice
Retrieves a list of defined alerts for a single device.
Usage
getTriggerDetailListByDevice retrieves the list of all alerts that have been defined for a single device. This operation retrieves the definition of each alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
devId |
int |
The Device ID of the device. |
Response
| Element Name |
Data Type |
Description |
trigList |
Trigger |
Each trigList element contains the definition of one alert. |
The response will contain zero or more of the following Trigger elements:
NameData TypeDescription
triggerId |
int |
The ID for the alert. This value is generated by the Arrayent Cloud upon creation of the alert. |
devId |
int |
The Device ID of the device. |
action |
string |
The action to take when the alert is triggered. Valid options are email, sms,htmlemail, mobile_notification, and attribute |
attrName |
string |
The attribute name. |
operation |
string |
A boolean operator. Valid options are greater-than symbol (>), greater-than-or-equals symbol (>=), less-than symbol (<), less-than-or-equals symbol (<=), and equals symbol (==). Make sure to properly encode each symbol for HTTP (if using GET) or XML (if using POST)! |
threshold |
double |
The value to compare the attribute against. The two values are compared using the boolean operator specified inoperation, in the form attrNameoperationthreshold. |
address |
string |
The address to send the alert to. Whenaction is sms, this is the phone number that will receive the message. The format of the phone number is a plus sign character, followed by the country code, followed by the phone number. E.g.+14155001234. When action is emailor htmlemail, this is the email address that will receive the email. When actionis mobile_notification, this is the mobile device (iOS or Android) that will receive the push notification. Leaveaddress empty if you want to send the alert to all mobile devices registered for this Customer Account. Use a comma-separated list of Phone IDs to selectively specify which mobile devices should receive the alert. See the Push Notification Alerts Guide for more information. |
msg |
string |
The email, SMS, or push notification message that the end user will receive when the alert is triggered. |
autoDisarm |
boolean |
Recall how alerts work. Each time a device submits a new value for an attribute, the Arrayent Cloud checks if any alerts have been defined for that attribute. If an alert has been defined, then the Arrayent Cloud compares the current value against the threshold value that you defined in addTrigger. If the boolean comparison evaluates to true, then the alert is triggered and the Arrayent Cloud executes the action that you also defined in addTrigger. The Arrayent Cloud does the boolean comparison every time that the device submits a new value for the attribute. Suppose that three consecutive attribute updates sent from a device triggers an alert. WhenautoDisarm is set to true, the Arrayent Cloud will execute the action the first time that the alert is triggered, and then ignore the subsequent two triggers. The alert is re-armed once the device submits an attribute update that makes the boolean comparison evaluate to false. WhenautoDisarm is set to false the Arrayent Cloud will execute the action of the alert all three times that the alert is triggered. |
disarmed |
boolean |
The current disarm state of the alert. |
autoDelete |
boolean |
Setting to true instructs the Arrayent Cloud to delete the definition of the alert after the alert is triggered. The Arrayent Cloud deletes the alert from its database of alerts. |
autoDisable |
boolean |
When set to true true, the Arrayent Cloud executes the action of the alert the first time that the alert is triggered, and then disables the alert. See description of parameter enable for more context on enabled/disabled alerts. Your web app will need to manually re-enable the alert usingupddateTriggerEnableState to re-enable the alert. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
targetDeviceAttributes |
string |
Optional. This attribute is only present for attribute alerts.targetDeviceAttributes specifies the device, attribute, and attribute value that the Arrayent Cloud should send when the alert is triggered. This attribute is formatted in the pattern of DeviceID, ,DeviceAttribute : AttributeValue. For example, if your Device ID is 123Device Attribute is light, and Attribute Value is 1. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
getTriggerDetailListByDevice?secToken=123-12345678990&devId=12345
The response of getTriggerDetailListByDevice indicates that there are three alerts defined for the device, two mobile push notifications and an SMS notification.
<ns1:getTriggerDetailListByDeviceResponse xmlns:ns1="http://arrayent.com/zamapi/">
<trigList>
<triggerId>1111</triggerId>
<devId>12345</devId>
<action>mobile_notification</action>
<attrName>online</attrName>
<operation><</operation>
<threshold>1.0</threshold>
<address>123,124</address>
<msg>ALERT</msg>
<autoDisarm>true</autoDisarm>
<disarmed>false</disarmed>
<autoDelete>false</autoDelete>
<autoDisable>false</autoDisable>
<enable>true</enable>
</trigList>
<trigList>
<triggerId>1112</triggerId>
<devId>12345</devId>
<action>mobile_notification</action>
<attrName>online</attrName>
<operation>></operation>
<threshold>0.0</threshold>
<address>123,124</address>
<msg>ALERT</msg>
<autoDisarm>true</autoDisarm>
<disarmed>false</disarmed>
<autoDelete>false</autoDelete>
<autoDisable>false</autoDisable>
<enable>true</enable>
</trigList>
<trigList>
<triggerId>1113</triggerId>
<devId>12345</devId>
<action>sms</action>
<attrName>door</attrName>
<operation>==</operation>
<threshold>1</threshold>
<address>16504381235</address>
<msg>Door is open.</msg>
<autoDisarm>true</autoDisarm>
<disarmed>false</disarmed>
<autoDelete>false</autoDelete>
<autoDisable>false</autoDisable>
<enable>true</enable>
</trigList>
</ns1:getTriggerDetailListByDeviceResponse>
getTriggerDetailListByUser
Retrieves a user’s list of defined alerts. The list includes all alerts for all of the user’s devices.
Usage
getTriggerDetailListByUser retrieves the list of all alerts that have been defined for all of this user’s devices.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
userId |
int |
The User ID of a Customer Account or System Account. |
Response
| Element Name |
Data Type |
Description |
trigList |
Trigger |
Each trigList element contains the definition of one alert. |
The response will contain zero or more of the following Trigger elements:
| Name |
Data Type |
Description |
triggerId |
int |
The ID for the alert. This value is generated by the Arrayent Cloud upon creation of the alert. |
devId |
int |
The Device ID of the device. |
action |
string |
The action to take when the alert is triggered. Valid options are email, sms,htmlemail, mobile_notification, and attribute |
attrName |
string |
The attribute name. |
operation |
string |
A boolean operator. Valid options are greater-than symbol (>), greater-than-or-equals symbol (>=), less-than symbol (<), less-than-or-equals symbol (<=), and equals symbol (==). Make sure to properly encode each symbol for HTTP (if using GET) or XML (if using POST)! |
threshold |
double |
The value to compare the attribute against. The two values are compared using the boolean operator specified inoperation, in the form attrNameoperationthreshold. |
address |
string |
The address to send the alert to. Whenaction is sms, this is the phone number that will receive the message. The format of the phone number is a plus sign character, followed by the country code, followed by the phone number. E.g.+14155001234. When action is emailor htmlemail, this is the email address that will receive the email. When actionis mobile_notification, this is the mobile device (iOS or Android) that will receive the push notification. Leaveaddress empty if you want to send the alert to all mobile devices registered for this Customer Account. Use a comma-separated list of Phone IDs to selectively specify which mobile devices should receive the alert. See the Push Notification Alerts Guide for more information. |
msg |
string |
The email, SMS, or push notification message that the end user will receive when the alert is triggered. |
autoDisarm |
boolean |
Recall how alerts work. Each time a device submits a new value for an attribute, the Arrayent Cloud checks if any alerts have been defined for that attribute. If an alert has been defined, then the Arrayent Cloud compares the current value against the threshold value that you defined in addTrigger. If the boolean comparison evaluates to true, then the alert is triggered and the Arrayent Cloud executes the action that you also defined in addTrigger. The Arrayent Cloud does the boolean comparison every time that the device submits a new value for the attribute. Suppose that three consecutive attribute updates sent from a device triggers an alert. WhenautoDisarm is set to true, the Arrayent Cloud will execute the action the first time that the alert is triggered, and then ignore the subsequent two triggers. The alert is re-armed once the device submits an attribute update that makes the boolean comparison evaluate to false. WhenautoDisarm is set to false the Arrayent Cloud will execute the action of the alert all three times that the alert is triggered. |
disarmed |
boolean |
The current disarm state of the alert. |
autoDelete |
boolean |
Setting to true instructs the Arrayent Cloud to delete the definition of the alert after the alert is triggered. The Arrayent Cloud deletes the alert from its database of alerts. |
autoDisable |
boolean |
When set to true true, the Arrayent Cloud executes the action of the alert the first time that the alert is triggered, and then disables the alert. See description of parameter enable for more context on enabled/disabled alerts. Your web app will need to manually re-enable the alert usingupddateTriggerEnableState to re-enable the alert. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
targetDeviceAttributes |
string |
Optional. This attribute is only present for attribute alerts.targetDeviceAttributes specifies the device, attribute, and attribute value that the Arrayent Cloud should send when the alert is triggered. This attribute is formatted in the pattern of DeviceID ,DeviceAttribute : AttributeValue. For example, if your Device ID is 123Device Attribute is light, and Attribute Value is 1. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
getTriggerDetailListByUser?secToken=912-1693708247&userId=912
<ns1:getTriggerDetailListByUserResponse xmlns:ns1="http://arrayent.com/zamapi/">
<trigList>
<triggerId>4012</triggerId>
<devId>184553180</devId>
<action>htmlemail</action>
<attrName>movement</attrName>
<operation>==</operation>
<threshold>0</threshold>
<address>joe@dirt.com</address>
<msg>He's dead, Jim.</msg>
<autoDisarm>true</autoDisarm>
<disarmed>false</disarmed>
<autoDelete>false</autoDelete>
<autoDisable>false</autoDisable>
<enable>true</enable>
</trigList>
</ns1:getTriggerDetailListByUserResponse>
removeTrigger
Deletes an alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
triggerId |
int |
The Trigger ID of the alert. The Arrayent Cloud generates this value upon creation of the alert. A list of all currently defined alerts (including each alert’s Trigger ID) can be retrieved withgetTriggerDetailListByUser orgetTriggerDetailListByDevice. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/removeTrigger?
secToken=09283489qasdf023fhaore984r&triggerId=42
<ns1:removeTriggerResponse>
<retCode>0</retCode>
</ns1:removeTriggerResponse>
removeTriggersByDevice
Deletes all alerts that have been defined for a single device.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
devId |
int |
The Device ID of the device. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
removeTriggersByDevice?secToken=000-123456789&devId=42
<ns1:removeTriggersByDeviceResponse>
<retCode>0</retCode>
</ns1:removeTriggersByDeviceResponse>
removeTriggersByUser
Deletes all alerts that have been defined for all devices owned by a single user.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
userId |
int |
The User ID of a Customer Account or System Account. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/removeTriggersByUser?
secToken=000-123456789&userId=42
<ns1:removeTriggersByUserResponse>
<retCode>0</retCode>
</ns1:removeTriggersByUserResponse>
resetTrigger
Resets the disarmed field of an alert to false.
Usage
This web service operation is related to the “auto-disarm” feature of alerts. See Auto-Disarm for an overview of this concept. To explain the purpose of resetTrigger we’ll use an example. Suppose you have defined an alert that is triggered when an attribute named temperature is greater than 75. The Auto-Disarm feature of the alert is enabled. Next, suppose the following sequence of events:
- Device updates
temperature to 80.
- Device updates
temperature to 81.
- Device updates
temperature to 82.
- Device updates
temperature to 70.
- Device updates
temperature to 76.
When temperature is set to 80 the alert is triggered. The subsequent updates of 81 and 82 are ignored because the alert is disarmed. When temperature is set back to 70 the Arrayent Cloud re-arms the alert. At temperature=76 the alert is triggered again. If you wanted to bypass the normal behavior of the Auto-Disarm feature and re-arm the alert (such as after the temperature=80event so that the temperature=81 event also triggers the alert), you can call resetTrigger to accomplish that functionality.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
A valid security token. |
triggerId |
integer |
The alert ID. CallgetTriggerDetailListByUser orgetTriggerDetailListByDevice to retrieve alert IDs. |
Response
| Element Name |
Data Type |
Description |
retCode |
integer |
A return code of 0 means that the alert was successfully reset. All other values should be treated as failure. |
Examples
HTTP
https://example.arrayent.com/zdk/services/zamapi/resetTrigger?
secToken=123-456789&triggerId=123456789
<ns1:resetTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/">
<retCode>0</retCode>
</ns1:resetTriggerResponse>
updateTriggerEnableState
Enables or disables a single alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
triggerId |
int |
The Trigger ID of the alert. The Arrayent Cloud generates this value upon creation of the alert. A list of all currently defined alerts (including each alert’s Trigger ID) can be retrieved withgetTriggerDetailListByUser orgetTriggerDetailListByDevice. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
updateTriggerEnableState?secToken=000-123456789&triggerId=42&enable=false
<ns1:updateTriggerEnableStateResponse>
<retCode>0</retCode>
</ns1:updateTriggerEnableStateResponse>
updateTriggersEnableStateByDevice
Enables or disables all of the alerts defined a single device.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
devId |
int |
The Device ID of the device. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
updateTriggersEnableStateByDevice?secToken=000-123456789&devId=42&
enable=false
<ns1:updateTriggersEnableStateByDeviceResponse>
<retCode>0</retCode>
</ns1:updateTriggersEnableStateByDeviceResponse>
updateTriggersEnableStateByUser
Enables or disables all of the alerts defined for all of the devices owned by a single user account.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
userId |
int |
The User ID of a Customer Account or System Account. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
updateTriggersEnableStateByUser?secToken=9834ts98g3qg9432340986gjf&
userId=29348&enable=false
<ns1:updateTriggersEnableStateByUserResponse>
<retCode>0</retCode>
</ns1:updateTriggersEnableStateByUserResponse>
updTrigger
Updates the definition of an existing alert.
Usage
See addTrigger for more information on implementing alerts.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
triggerId |
int |
The Trigger ID of the alert. The Arrayent Cloud generates this value upon creation of the alert. A list of all currently defined alerts (including each alert’s Trigger ID) can be retrieved with getTriggerDetailListByUser or getTriggerDetailListByDevice. |
devId |
int |
The Device ID of the device. |
action |
string |
The action to take when the alert is triggered. Valid options are email, sms, htmlemail,mobile_notification, and attribute |
attrName |
string |
The attribute name. |
operation |
string |
A boolean operator. Valid options are greater-than symbol (>), greater-than-or-equals symbol (>=), less-than symbol (<), less-than-or-equals symbol (<=), and equals symbol (==). Make sure to properly encode each symbol for HTTP (if using GET) or XML (if using POST)! |
threshold |
double |
The value to compare the attribute against. The two values are compared using the boolean operator specified in operation, in the formattrName````operation````threshold. |
stringThreshold |
string |
The value to compare the attribute against. This parameter is only used when comparing an attribute that has been defined as a string. Otherwise the parameter should be omitted completely from the request. |
address |
string |
The address to send the alert to. When action is sms, this is the phone number that will receive the message. The format of the phone number is a plus sign character, followed by the country code, followed by the phone number. E.g. +14155001234. When action isemail or htmlemail, this is the email address that will receive the email. When actionis mobile_notification, this is the mobile device (iOS or Android) that will receive the push notification. Leave address empty if you want to send the alert to all mobile devices registered for this Customer Account. Use a comma-separated list of Phone IDs to selectively specify which mobile devices should receive the alert. See the Push Notification Alerts Guide for more information. |
msg |
string |
The email, SMS, or push notification message that the end user will receive when the alert is triggered. |
autoDisarm |
boolean |
Recall how alerts work. Each time a device submits a new value for an attribute, the Arrayent Cloud checks if any alerts have been defined for that attribute. If an alert has been defined, then the Arrayent Cloud compares the current value against the threshold value that you defined in addTrigger. If the boolean comparison evaluates to true, then the alert is triggered and the Arrayent Cloud executes the action that you also defined inaddTrigger. The Arrayent Cloud does the boolean comparison every time that the device submits a new value for the attribute. Suppose that three consecutive attribute updates sent from a device triggers an alert. When autoDisarm is set to true, the Arrayent Cloud will execute the action the first time that the alert is triggered, and then ignore the subsequent two triggers. The alert is re-armed once the device submits an attribute update that makes the boolean comparison evaluate to false. When autoDisarm is set to falsethe Arrayent Cloud will execute the action of the alert all three times that the alert is triggered. |
autoDelete |
boolean |
Setting to true instructs the Arrayent Cloud to delete the definition of the alert after the alert is triggered. The Arrayent Cloud deletes the alert from its database of alerts. |
autoDisable |
boolean |
When set to true true, the Arrayent Cloud executes the action of the alert the first time that the alert is triggered, and then disables the alert. See description of parameterenable for more context on enabled/disabled alerts. Your web app will need to manually re-enable the alert using upddateTriggerEnableState to re-enable the alert. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1or true. |
targetDeviceAttributes |
string |
Optional. This attribute is only required when defining attribute alerts. You can omit it when defining email, SMS, or push notification alerts. targetDeviceAttributes specifies the device, attribute, and attribute value that the Arrayent Cloud should send when the alert is triggered. This attribute should be formatted in the pattern of DeviceID,,“Device Attribute“:AttributeValue. For example, if your Device ID is 123 Device Attribute islight, and Attribute Value is 1, then targetDeviceAttributes should contain the value 123,light:1. You can configure a single attribute alert to be sent out to multiple devices by including multiple targetDeviceAttribute in your request. E.g.targetDeviceAttributes=123, light:1&targetDeviceAttributes=987,siren:1. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Schedule Alerts
addScheduleAlert
Creates a new scheduled alert. Scheduled alerts are executed at a regular interval by the Arrayent Cloud.
Usage
See Schedule Alerts Guide for an example of implementing a scheduled alert.
Preconditions
- Scheduled alerts have been enabled on your environment. Contact Arrayent Support to enable scheduled alerts.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
devId |
int |
The Device ID of the device. |
frequency |
string |
The interval at which the alert should be executed. Valid values: DAY, WEEK,MONTH, YEAR. |
definition |
string |
A JSON string representing the definition of the alert. See below for more information. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
Definition
| Parameter Name |
Description |
deviceId |
The Device ID. |
triggerAttribute |
A Stored by Server Device Attribute that you have defined in your device data model. |
operation |
When the scheduled alert should be executed. Valid values:BEFORE, AFTER. |
thresholdValue |
A timestamp representing a date in which the scheduled alert is triggered. |
comparisonType |
Valid values: ATTRIBUTE_UPDATE_TIME, ATTRIBUTE_VALUE |
attributeNameToSet |
The name of the Device Attribute which will be updated when the alert is triggered. |
valueToSet |
The value which attributeNameToSet will be updated to when the alert is triggered. |
Response
| Element Name |
Data Type |
Description |
alertId |
string |
A random integer generated by the Arrayent Cloud that serves as an identifier for this alert. For subsequent web service operations (updateScheduleAlert, deleteScheduleAlert, getScheduleAlert) you will need to refer to this alert by this identifier. |
Examples
https://example.arrayent.com/zdk/services/zamapi/addScheduleAlert?secToken=
213-849356371&definition={"deviceId":"1234","triggerAttribute":
"last_regenerationTime","operation":"BEFORE", "thresholdValue":"86400000”,
”attributeNameToSet”:”regeneration_trigger”,”valueToSet”:”1”,"comparisonType":
"last_regenerationTime","operation":"BEFORE", "thresholdValue":"86400000",
"attributeNameToSet":"regeneration_trigger","valueToSet":"1","comparisonType":
"ATTRIBUTE_UPDATE_TIME"}&frequency=MONTH&devId=1234&enable=1
<ns1:addScheduleAlertResponse xmlns:ns1="http://arrayent.com/zamapi/">
<alertId>6683</alertId>
</ns1:addScheduleAlertResponse>
getScheduleAlert
Retrieves information about an existing scheduled alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
alertId |
String |
The alert identifier. The Arrayent Cloud creates this random integer when the alert is created via addScheduleAlert. You can retrieve a list of existing scheduled alerts via getScheduleAlertsByUser. |
Response
| Element Name |
Data Type |
Description |
alert |
ScheduleAlert |
A ScheduleAlert element. See below for more information on the contents of a ScheduleAlert element. |
| Element Name |
Data Type |
Description |
alertId |
string |
A random string identifier for the alert. The Arrayent Cloud generates this ID when the alert is created via addScheduleAlert. |
devId |
int |
The Device ID of the device. |
definition |
string |
A JSON string containing the definition of the alert. See below for more information on the composition of this JSON string. |
frequency |
string |
Valid values: WEEKLY, MONTH |
lastExecution |
string |
A timestamp indicating when the alert was last executed. |
enable |
boolean |
A boolean value indicating whether the alert is currently enabled. |
The definition element is a JSON string consisting of the following key-value pairs:
| Parameter Name |
Data Type |
Required |
Description |
triggerAttribute |
String |
Yes |
operation |
String |
Yes |
Valid values: BEFORE, AFTER |
thresholdDays |
String |
Yes |
comparisonType |
String |
Yes |
Valid values: ATTRIBUTE_UPDATE_TIME, ATTRIBUTE_VALUE |
attributeNameToSet |
String |
Yes |
The name of the Device Attribute which will be updated when the alert is triggered. |
attributeValueToSet |
String |
Yes |
The value which the Device Attribute will be updated to when the alert is triggered. |
Examples
https://DevKit-api.arrayent.com/zdk/services/zamapi/getScheduleAlert?
secToken=213-849356371&alertId=1234
<ns1:getScheduleAlertResponse
xmlns:ns1="http://arrayent.com/zamapi/">
<alert>
<alertId>07e8c451-ad17-408a-8b08-68401152b586</alertId>
<devId>3917</devId>
<definition>
{"deviceId":3917,"triggerAttribute":"LED","operation":"BEFORE","thresholdDays":23,
"attributeNameToSet":"temp","attributeIdToSet":19074,"attributeValueToSet":"33",
"comparisonType":"ATTRIBUTE_UPDATE_TIME"}
</definition>
<frequency>DAY</frequency>
<lastExecution>0</lastExecution>
<enable>false</enable>
</alert>
</ns1:getScheduleAlertResponse>
getScheduleAlertListByUser
Retrieves information about all existing scheduled alerts for a single user.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
userId |
int |
The User ID of a Customer Account or System Account. |
Response
| Element Name |
Data Type |
Description |
alertList |
ScheduleAlert |
Zero or more ScheduleAlert elements. See below for more information on the contents of a ScheduleAlert element. |
Each ScheduleAlert contains the following elements:
| Element Name |
Data Type |
Description |
alertId |
string |
A random string identifier for the alert. The Arrayent Cloud generates this ID when the alert is created via addScheduleAlert. |
devId |
int |
The Device ID of the device. |
definition |
string |
A JSON string containing the definition of the alert. See below for more information on the composition of this JSON string. |
frequency |
string |
Valid values: WEEKLY, MONTH |
lastExecution |
string |
A timestamp indicating when the alert was last executed. |
enable |
boolean |
A boolean value indicating whether the alert is currently enabled. |
The definition element is a JSON string consisting of the following key-value pairs:
| Parameter Name |
Data Type |
Required |
Description |
triggerAttribute |
String |
Yes |
operation |
String |
Yes |
Valid values: BEFORE, AFTER |
thresholdDays |
String |
Yes |
comparisonType |
String |
Yes |
Valid values: ATTRIBUTE_UPDATE_TIME, ATTRIBUTE_VALUE |
attributeNameToSet |
String |
Yes |
The name of the Device Attribute which will be updated when the alert is triggered. |
attributeValueToSet |
String |
Yes |
The value which the Device Attribute will be updated to when the alert is triggered. |
Examples
https://example.arrayent.com/zdk/services/zamapi/
getScheduleAlertListByUser?secToken=213-849356371&userId=1234
<ns1:getScheduleAlertListByUserResponse
xmlns:ns1="http://arrayent.com/zamapi/">
<alertList>
<alertId>07e8c451-ad17-408a-8b08-68401152b586</alertId>
<devId>3917</devId>
<definition>
{"deviceId":3917,"triggerAttribute":"LED","operation":"BEFORE","thresholdDays":23,
"attributeNameToSet":"temp","attributeIdToSet":19074,"attributeValueToSet":"33",
"comparisonType":"ATTRIBUTE_UPDATE_TIME"}
</definition>
<frequency>DAY</frequency>
<lastExecution>0</lastExecution>
<enable>false</enable>
</alertList>
</ns1:getScheduleAlertListByUserResponse>
removeScheduleAlert
Deletes an existing scheduled alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
String |
The security token for this user’s Arrayent Cloud session. |
alertId |
String |
The alert identifier. The Arrayent Cloud creates this random integer when the alert is created via addScheduleAlert. You can retrieve a list of existing scheduled alerts via getScheduleAlertsByUser. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://DevKit-api.arrayent.com/zdk/services/zamapi/removeScheduleAlert?
secToken=213-849356371&alertId=1234
<ns1:removeScheduleAlertResponse xmlns:ns1="http://arrayent.com/zamapi/">
<retCode>0</retCode>
</ns1:removeScheduleAlertResponse>
updateScheduleAlert
Updates an existing scheduled alert.
Parameters
| Parameter Name |
Data Type |
Description |
secToken |
string |
The security token for this user’s Arrayent Cloud session. |
alertId |
string |
The ID of the existing alert. |
frequency |
string |
The interval at which the alert should be executed. Valid values: WEEKLY, MONTH. |
definition |
string |
A JSON string representing the definition of the alert. See below for more information. |
enable |
boolean |
The enable state. To disable, set this value to 0 or false. To enable, set this value to 1 or true. |
Each definition consists of the following key-value pairs.
| Parameter Name |
Data Type |
Description |
deviceId |
string |
Device ID |
triggerAttribute |
string |
Attribute to use for storing time if |
operation |
string |
Valid values: BEFORE, AFTER |
thresholdDays |
string |
Scheduled days for alert. |
comparisonType |
string |
Valid values: ATTRIBUTE_UPDATE_TIME, ATTRIBUTE_VALUE |
attributeNameToSet |
string |
The name of the Device Attribute which will be updated when the alert is triggered. |
attributeValueToSet |
string |
The value which the Device Attribute will be updated to when the alert is triggered. |
Response
| Element Name |
Data Type |
Description |
retCode |
int |
A return code indicating the status of the operation. A value of 0 indicates that the operation was successful. All other values should be treated as failure. |
Examples
https://example.arrayent.com/zdk/services/zamapi/updateScheduleAlert?
secToken=213-849356371&alertId=07e234-ad15-8484-56834599&definition={"deviceId":"1234","triggerAttribute":
"last_regenerationTime","operation":"BEFORE","thresholdDays":"30",
"attributeNameToSet":"regeneration_trigger","attributeValueToSet":"1",
"comparisonType":"ATTRIBUTE_UPDATE_TIME"}&frequency=MONTH&enable=1
<ns1:updateScheduleAlertResponse xmlns:ns1="http://arrayent.com/zamapi/">
<retCode>0</retCode>
</ns1:updateScheduleAlertResponse>
