Regular Expressions Alerts Guide

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.

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 are true and false).
  • All other values are literal.

The free online HTML tidy is the best online tool to clean up the dirty code.