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 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.

 

 

 

 

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 such as Twillo must be setup prior to use.  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 information from an event stream.  Information about the statement syntax is available at the Esper Web site (refer to Chapter 5 of Esper Reference Documentation).

 

Example 1:

The simplest example of a Statement is

 

select * from EdcMessageEvent where semanticTopic = "sample/data"

 

where

EdcMessageEvent holds the following properties:

·         account=account used to publish the MQTT message

·         asset=identifier of the asset publishing the MQTT message

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

·         sentOn=timestamp added by the client upon MQTT message transmission

·         semanticTopic=describes the message semantics

·         metrics={a key=value pair set holding the message data}

·         position={holds location-related properties}

 

The property position has, in turn, the following properties:

·         latitude

·         longitude

·         altitude

·         precision (diluition of precision)

·         heading

·         speed

·         timestamp

·         satellites

·         status

 

Generally, the following data types are available for metrics:

·         intMetric

·         longMetric

·         doubleMetric

·         floatMetric

·         boolMetric

·         stringMetric

 

semanticTopic = “sample/data”

·         This structure is the data that will be displayed in your “Data Query by Topic” menu as shown in the following screen capture.  These topics can be renamed to match the context on which you are working (ex: transport/train) in the client Java source code.

 

 

The following examples are based on a company monitoring a CO2 sensor in the Italian area of Friuli-Venezia Giulia, located in the center area of the town Udine.

 

Using the simple example described previously, all the properties ('*') of an EdcMessageEvent whose semanticTopic is fvg/udine/center are selected, and their values (i.e. the query results) could be the following:

·         account=eurotech

·         asset=device_client_id

·         sentOn=Wed Apr 04 08:46:27 CEST 2012

·         receivedOn=Wed Apr 04 08:46:28 CEST 2012

·         semanticTopic=fvg/udine/center

·         metrics={co2=1000.0}

·         position={"longitude":13.234865, "latitude":46.062668, "altitude":296.0, "precision":10.0, "heading":2.0, "speed":60.0, "timestamp":"Wed Apr 04 08:46:27 CEST 2012", "satellites":3, "status":1}

 

One or more rule actions can be associated to a rule.  These rule actions access the values of the selected properties using the $<property name> syntax.

 

Using our example, the template for the body of an email to be sent in response to the event could be

 

On $sentOn, asset $asset, belonging to account $account, located at latitude $position.latitude, longitude $position.longitude, 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 email body.

 

On 1330087578320, 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:

If the CO2 concentration is stored in a metric whose name is "co2" as a double precision floating point number, its value can be selected by

 

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

 

This example illustrates how to select a metric in the Statement.

 

In this case, the email body of the previous example can be written in a slightly different form.

 

On $sentOn, asset $asset, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $doubleMetric("co2") ppm

 

 

Example 3:

To rename the metric, you can write the following Statement.

 

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

 

The email body template for this example can be written as

 

On $sentOn, asset $asset, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $co2 ppm

 

In this example, the metric doubleMetric("co2") will not be present in the query results.

 

 

Example 4:

In the case that you need an alert when the average CO2 concentration in a given time window exceeds a given threshold, you can write

 

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

 

This example illustrates how to include a function in your Statement. 

 

The body of the associated email action could be written as

 

On $sentOn, asset $asset, belonging to account $account, published on topic $semanticTopic a CO2 concentration of $co2 ppm. This resulted in an average concentration of $avgCo2 ppm in the last 10 seconds.

 

 

Example 5:

The following example uses data published to the Everyware Cloud from the EDC Development Kit.  This example rule, as shown in the following screen capture, reports a change in the Quadrature counter from the development kit:

·         Name             ruleReport1

·         Statement      select *, intMetric('qc') as qc from EdcMessageEvent.std:firstunique(intMetric('qc')) where semanticTopic = "us/kansas/stilwell"

 

 

The following screen capture illustrates adding an email rule action to this example:

·         To                    support.us@eurotech.com

·         Subject           Report change to Quadrature counter

·         Body               Timestamp $receivedOn.

Asset ID $asset, Account $account

Counter value = $qc, Published on topic $semanticTopic

Other fields:

sentOn: $sentOn, Position: $position, located at latitude $position.latitude, longitude $position.longitude