PART 2. ADMINISTRATOR’S GUIDE
Using Cloud Rules

 

Rules

·         Creating a New Rule

Rule Actions

·         Email

·         SMS

·         Twitter

·         MQTT

·         REST

Examples of Rules Statements

 

 

 

Rules

The Rules panel in the Everyware Cloud Console provides real-time business intelligence driven by your data.  To view this panel, you must have “rules:view” permission.

 

With “rules:manage” permission, you can perform the following tasks using the buttons provided in the Rules panel:

·         Create a new rule (New)

·         Edit an existing rule (Edit)

·         Refresh the list of rules (Refresh)

·         Delete a rule (Delete)

 

The following screen capture shows the Rules panel.

 

 

The following table describes the information displayed for each rule in the Rules panel.

 

 

 

 

Creating a New Rule

To create a rule, click New under Rules to open the New Rule window as shown in the following screen capture.

 

In the New Rule window, you can either create a rule from scratch or select one of the pre-defined rule templates, which can then be modified according to your needs.  To select a pre-defined rule template, select the template using the drop-down list.

 

In the Rule Information box, enter the Name, Description, and Statement for your rule and select the Enabled or Disabled checkbox for Status.  Use the tooltips provided in the console when entering the Name and Statement.  See Examples of Rules Statements for an explanation on using the Esper syntax to create the rule statement.

 

 

 

 

 

Rule Actions

Your rule can trigger any number of the following actions:

·         Send an email

·         Send a SMS message (Requires paid service setup prior to use.)

·         Send a real-time message via Twitter (Requires a Twitter account.)

·         Publish an event back to the Everyware Cloud (MQTT)

·         Perform a REST call

 

To add an action for your rule, click the Add button in the Rules Action box as shown in the following screen capture.  Select the action and enter the parameters associated with the selected action.  Use the tooltips provided in the console when entering the parameters for each action.  When complete, click Submit.

 

 

 

Each Rule Action includes a template for the parameters required by that action.  The sections below describe these templates.  For examples of implementing these actions, see Examples of Rules Statements.  Use the tooltips provided in the console when entering the parameters for each action.

 

 

 

Email

The following screen capture shows the parameters required to send an email.

 

 

 

 

 

 

SMS

The following screen capture shows the parameters required to send a text message.  Text messaging is a paid service, and an account at Twillo must be setup prior to use (http://www.twilio.com).  For additional details about setting up text messaging, contact your Eurotech Sales Representative.

 

 

 

 

 

 

Twitter

You must have a Twitter account to add a Twitter message to your Rule.  Using your account, go to https://dev.twitter.com/ and create an application.  Use the information provided by Twitter to complete the Rules Action template shown in the following screen capture.

 

 

 

 

 

 

MQTT

The following screen capture shows the parameters required to perform a MQTT action.  This allows a Rule to publish an event back to the Everyware Cloud when the Rule statement is triggered.

 

 

 

 

Note: You should be very careful to avoid creating a Rule that triggers a publish event, which in turn triggers another Rule event, and so on in an endless loop.

 

 

 

 

REST

The following screen capture shows the parameters required to perform a REST call, which will trigger in response to a Rule event.

 

 

 

 

 

 

Examples of Rules Statements

The Statement is written using the Esper event processing language, which uses SQL-like statements to derive and aggregate data from an event stream.  Information about the statement syntax is available at the Esper Web site (refer to Chapter 5 of Esper Reference Documentation).

 

The next several examples illustrate the Rules syntax in the context of a real-world application, defined as follows: A company located in the center area of the town of Udine, Italy (the area of Friuli-Venezia Giulia) is monitoring a CO2 sensor.  When the average value of the CO2 concentration is greater than a defined limit of parts per million (ppm, on a 10 second rolling average of received CO2 values), an alert e-mail should be sent to a maintenance technician.

 

In order to better illustrate these examples, let’s assume that the properties and values of the EdcMessageEvent are the following:

·         account=eurotech

·         asset=device_client_id

·         sentOn=Tue Sep 03 17:56:38 UTC 2013

·         receivedOn=Tue Sep 03 17:56:39 UTC 2013

·         semanticTopic=fvg/udine/center

·         metrics={co2=1000.0}

·         position={"longitude":13.234865, "latitude":46.062668, "altitude":296.0, "precision":10.0, "heading":0.0, "speed":0.0, "timestamp":"Tue Sep 03 17:56:38 UTC 2013", "satellites":3, "status":1}

 

 

Example 1: Create a simple Rule that sends an e-mail when a message of a specific topic is received.

 

The simplest example of a Statement is

 

select * from EdcMessageEvent where semanticTopic = "fvg/udine/center"

 

The EdcMessageEvent is an event stream that contains a number of properties, including all of the metrics and data published from client devices.  The Esper statement is used to query and filter the data contained in the event stream, in order to trigger the Rule action defined in the Everyware Cloud.

 

In this example, all properties in the EdcMessageEvent are selected with the * wildcard (select * from EdcMessageEvent), only for messages where the semanticTopic exactly matches a specific publish topic (where semanticTopic = "fvg/udine/center").  If the Everyware Cloud receives a message on this account that was published with the indicated topic, it will activate this rule (and all other rules for which the message matches the query statement) and perform all defined rule actions.

 

The properties of EdcMessageEvent are

·         account=account into which the MQTT message was published

·         asset=identifier of the asset publishing the MQTT message (see Communication Data Model for a description of the assetId property of published messages)

·         receivedOn=timestamp added by the server upon MQTT message reception

·         sentOn=timestamp added by the client upon MQTT message transmission (depends on the client application setting the timestamp in the message payload)

·         semanticTopic=topic of the published message, excluding the first two levels of the Topic namespace (accountName/assetId), as described in Communication Data Model

·         metrics=data published by the client device as Metrics (key name, value, and data type – see Communication Data Model)

·         position=contains additional location-related properties

 

Some of the EdcMessageEvent properties are further described in the following paragraphs.

 

semanticTopic – When you query data in the Everyware Cloud console, the Data by Topic and Data by Asset panels include a “Topic” column containing the semanticTopic in the Results table.  Topics published from a client should be defined in a way that allows meaningful organization of the data.  One criterion for choosing the topic is the ability to subscribe to or query appropriate sets of data, such as the queries defined in Rules actions.  The screen capture below shows a set of data published with a semanticTopic of “fvg/udine/center”.  The semanticTopic is case-sensitive.

 

 

 

metrics – When the Rule statement references a specific metric by its data type, the statement must match the type of data actually published by the client in order for the rule to process correctly.  Rules must operate on data contained in Metrics – the data contained in the Body of a message payload may not be used.  The following data types are available for metrics:

·         intMetric

·         longMetric

·         doubleMetric

·         floatMetric

·         boolMetric

·         stringMetric

 

position – The position property of the EdcMessageEvent has the following properties that are optionally set in the message payload by the client application.  If they are set, they may be used in the Rules statement.

·         latitude

·         longitude

·         altitude

·         precision (dilution of precision)

·         heading

·         speed

·         timestamp

·         satellites

·         status

 

One or more rule actions can be associated to a rule.  These rule actions can access the values of the selected properties using the $property_name syntax.  In this example, the template for the body of an email to be sent in response to the event could be

 

On date $sentOn, asset $asset, located at latitude $position.latitude, longitude $position.longitude, belonging to account $account, published on topic $semanticTopic the following data: $metrics

 

When the email is sent, the above $property_name placeholders will be replaced by the query results, resulting in the following e-mail body.  The underlined text below illustrates where the e-mail body has been filled in with the data obtained from a published message.  Note that the $metrics property displays all metrics in the format “{metric1=value1, metric2=value2, etc.}”.

 

On date Tue Sep 03 17:56:38 UTC 2013, asset device_client_id, located at latitude 46.062668, longitude 13.234865, belonging to account eurotech, published on topic fvg/udine/center the following data: {co2=1000.0}

 

Example 2: Select specific metrics to use in Rule actions.

 

If you wish to use a specific metric value in the Rule action, the metrics must be selected specifically in the statement.  One way to do this is to call out the specific metric as a sub-property of the EdcMessageEvent $metrics property.  In this case, the email body of the previous example can be written in a slightly different form.

 

On date $sentOn, asset $asset, located at latitude $position.latitude, longitude $position.longitude, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $metrics.co2 ppm.

 

When the email is sent, the variable $metrics.co2 will be replaced by the actual value of the data obtained from the published message.

 

On date Tue Sep 03 17:56:38 UTC 2013, asset device_client_id, located at latitude 46.062668, longitude 13.234865, belonging to account eurotech, published on topic fvg/udine/center a CO2 concentration of 1000.0 ppm.

 

 

Example 3: Rename metrics.

 

To rename the metrics, you can add specific metric names to the “select” portion of the Statement.  The “doubleMetric("co2")” is necessary to specifically call out the metric and to assign its value to another variable, myCO2.  The data type must match the published metric, and the variable “myCO2” may then be used in the Rule action.  Multiple variables can be called out in the same “select” statement, separated by commas.

 

select *, doubleMetric("co2") as myCO2 from EdcMessageEvent where semanticTopic = "fvg/udine/center"

 

The email body template for this example can be rewritten using the $myCO2 variable as

 

On date $sentOn, asset $asset, located at latitude $position.latitude, longitude $position.longitude, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $myCO2 ppm.

 

 

Example 4: Process messages in a batch over a time period and perform aggregation functions on the data.

 

In this example, we wish to trigger a Rule action based on an average of a metric value over time, not just the value contained in a single published message.  The Esper language defines “views” for the stream of event messages.  We will use the “win:time_batch” view to process all the messages received within 10 seconds.  An aggregation function is used to average the CO2 value across those samples.  Then we can compare this average to a given threshold.

 

In this example, the rule statement is rewritten to add the “win:time_batch” view and the additional “select” statement, where the aggregation function “avg()” takes the average of the CO2 metric values across all messages in the given context.  The “having” clause is used to set conditions on the events to be processed and is often used with a “group-by” clause, although in this case the “group-by” is not needed.

 

select *, doubleMetric("co2") as myCO2, avg(doubleMetric('co2')) as avgCo2 from EdcMessageEvent.win:time_batch(10 sec) where semanticTopic = "fvg/udine/center" having avg(doubleMetric('co2')) > 1000

 

The body of the associated e-mail action is rewritten as

 

On date $sentOn, asset $asset, located at latitude $position.latitude, longitude $position.longitude, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $myCO2 ppm.  This resulted in an average CO2 concentration of $avgCo2 ppm over the last 10 seconds.

 

Note that the e-mail body definition uses the $avgCo2 variable created in the select statement. 

 

This is the end of the Rule examples based on the Udine CO2 monitoring application.

 

 

Example 5: Trigger event based on change of state.

 

In this example, data is published to the Everyware Cloud from the EDC Development Kit.  One of the variables reported by the development kit is a Quadrature counter (metric ‘qc’), which is an integer value that increases or decreases.  We wish to send an e-mail from Everyware Cloud whenever the Quadrature counter changes to a new value, but only when the value is greater than 10.

 

The Rule statement is defined as

 

select *, intMetric('qc') as qc from EdcMessageEvent.win:time(3 minutes).std:firstunique(intMetric('qc')) where semanticTopic.startsWith("eurotech/demo") and intMetric('qc') > 10

 

The “std:firstunique()” view of the EdcMessageEvent triggers when a unique value of ‘qc’ is received, and the “win:time(3 minutes)” view limits this uniqueness to a time window of 3 minutes.

 

The following screen captures illustrate the e-mail rule for this example: