End user Rules

 

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:

  1. Device updates temperature to 80.
  2. Device updates temperature to 81.
  3. Device updates temperature to 82.
  4. Device updates temperature to 70.
  5. 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_TIMEATTRIBUTE_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 (updateScheduleAlertdeleteScheduleAlertgetScheduleAlert) 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_TIMEATTRIBUTE_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_TIMEATTRIBUTE_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_TIMEATTRIBUTE_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>