In this guide you will find an overview of regular expression alerts and guides on how to implement regular expression alerts.
Overview
See the Alerts Guide for an overview of Arrayent Alerts. Regular expressions enable you to define alerts that are triggered when attribute values match certain patterns, not exact values. For example, suppose that your device has been programmed to send error codes to the Arrayent Cloud. Any error code beginning with a 9
indicates a critical error. Suppose there are twenty different critical error codes, every one beginning with a 9
. For any error code beginning with a 9
you want to send a warning email to the customer that they need to get their device serviced. You could go about this by creating a separate alert for each error code (e.g. error == 9001
, error == 9002
, and so on), but that would be tedious and would hurt Arrayent Cloud performance. The proper way to handle this scenario is to create a single alert that uses a regular expression pattern that matches all of the critical error codes. The challenge (and fun) of regular expressions is ensuring that your pattern matches all valid inputs, and filters out all invalid inputs. In this guide we won’t teach you regular expression fundamentals, as there are literally thousands of tutorials and guides on the web covering the topic. However, if you’re new to regular expressions, a good starting point is regexone.com.
Implementing Regular Expression Alerts
Creating Regular Expression Alerts
Use addTrigger
to create regular expression alerts. Below is the generic signature of a request.
https://<SUBDOMAIN>.arrayent.com:8081/zdk/services/zamapi/addTrigger? secToken=<SECURITY TOKEN>&devId=<DEVICE ID>& attrName=<DEVICE ATTRIBUTE NAME>&operation=regex& stringThreshold=<REGULAR EXPRESSION>&address=<ADDRESS>&msg=<MESSAGE>& action={sms|email|htmlemail|mobile_notification|attribute}& autoDisarm={true|false}&autoDisable={true|false}& autoDelete={true|false}&enable={true|false}
See Generic Signature Conventions for an explanation of conventions used above. The key arguments are operation=regex
and stringThreshold=<REGULAR EXPRESSION>
. When the attribute specified inattrName
is updated, the Arrayent Cloud checks if the new value of the attribute matches the pattern specified in stringThreshold
. Below is a brief description of each parameter in the addTrigger
request.
Parameter | Description |
---|---|
secToken |
The security token for this user’s current Arrayent Cloud session. Returned in response to userLogin . |
devId |
The Device ID of the device to be monitored. This alert is only valid for this device. Retrieve Device IDs with getDeviceList . |
action |
The action to take when the alert is triggered. Valid options: sms (SMS text message), email (plaintext email), htmlemail (email with HTML), mobile_notification (iOS or Android push notification), attribute (update the value of another device attribute). |
attrName |
Name of the device attribute to monitor. |
operation |
Setting to regex indicates that the Arrayent Cloud should compare the value of attribute against the regular expression pattern contained in stringThreshold . If there is one or more pattern matches then the alert is triggered. |
stringThreshold |
The regular expression pattern. |
address |
For SMS alerts, the phone number to send the message to. For email alerts, the email to send the message to. For all other alert types, leave this blank. |
msg |
For SMS alerts, the text message to send (max. 140 characters). For email alerts, the body of the email message. For all other alert types, leave blank. |
autoDisarm |
Optional. Default: true . See Optional. Default: false . See Auto-Disable. |
autoDelete |
Optional. Default: false . See Auto-Delete. |
enable |
Enable or disable the alert. Optional. Default: true . |
Regular Expression Pattern Syntax
Your regular expression patterns must conform to the syntax specified in the link below. http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html When implementing regular expression patterns, the website below will be useful. http://www.regexplanet.com/advanced/java/index.html This website enables you to construct a regular expression and test the pattern across multiple inputs. Make sure to test for both false positives and false negatives. Regular expressions tend to have minor implementation or syntax differences in different languages / technology stacks. When testing out regular expressions for use in Arrayent alerts, make sure to test your pattern against the Java regular expression engine.
Inserting Attribute Values into Alert Messages
If you want to know the exact value of an attribute when the regular expression alert is triggered, you can use the Arrayent Cloud’s variable text feature. The syntax is as follows:
{device.<ATTRIBUTE NAME>}
Where <ATTRIBUTE NAME>
is the name of the attribute whose value you want to insert. For example, if you want to insert the value of an attribute called error
then you would use the following:
{device.error}
Continuing with the example, you could send the following message when an alert is triggered:
Error Code: {device.error}
If error
was set to 10
and this value triggers the alert, then the recipient of the alert would receive the following message:
Error Code: 10
If the attribute is not valid, then the Arrayent Cloud will not substitute the template. The text will be interpreted literally. If error
was not a valid attribute in your device data model, the recipient of the alert message would literally receive Error Code:{device.error}
.
Examples
First, we create a Device Attribute for testing regular expression patterns. De-selecting Hardware Attribute enables us to set the value of the attribute, even when the device is offline. See Hardware Attribute to learn more. Next, we create the regular expression alert using addTrigger
:
https://DevKit-api.arrayent.com:8081/zdk/services/zamapi/addTrigger? secToken=11817-106868332&devId=184554197&attrName=message&operation=regex& stringThreshold=H.*&address=kayce.basques@arrayent.com&msg={device.message}& action=email&autoDisarm=true&autoDisable=false&autoDelete=false&enable=true
We’re skipping a few web service requests here. You’ll need to make a few calls before you have enough information to calladdTrigger
(namely userLogin
and getDeviceList
). The Arrayent Cloud returns the following response:
<ns1:addTriggerResponse xmlns:ns1="http://arrayent.com/zamapi/"> <triggerId>16144</triggerId> </ns1:addTriggerResponse>
We could also create the alert using the Utility application. This alert is exactly the same as the addTrigger
request earlier. The regular expression alert is triggered when message
is set to any value that begins with H
. Let’s set the value now. In our email we receive an email containing the text Hello, World!
.
Retrieving, Updating, and Deleting Regular Expression Alerts
The process for retrieving, updating, deleting regular expression alerts is the same as for other type of alerts. See the SMS Alerts Guide for more help on these tasks.
- Retrieving SMS Alerts with getTriggerDetailListByUser
- Modifying SMS Alerts with updTrigger
- Deleting SMS Alerts
How can you tell which alerts are regular expression alerts? Search for the alert definitions that have their operation
fields set toregex
.
Appendix
Generic Signature Conventions
In this guide we document the generic signatures of various web service operations. Below is an example of one such generic signature:
https://<SUBDOMAIN>.arrayent.com:8081/zdk/services/zamapi/addTrigger? secToken=<SECURITY TOKEN>&devId=<DEVICE ID>&action=sms&attrName= <DEVICE ATTRIBUTE NAME>&operation={>|>=|<|<=|==|regex|equals}& threshold=<THRESHOLD>&address=<PHONE NUMBER>&msg=<MESSAGE>& autoDisarm={true|false}&autoDisable={true|false}&autoDelete= {true|false}&enable={true|false}
- Items in angle brackets (e.g.
<SUBDOMAIN>
) are placeholders. - Items in braces (e.g.
{true|false}
) represent a list of valid values. The vertical line character (|
) serves as the delimiter between valid values (e.g. given{true|false}
the valid values aretrue
andfalse
). - All other values are literal.
The free online HTML tidy is the best online tool to clean up the dirty code.