Difference between revisions of "Creating Rules"

Revision as of 13:55, 27 July 2017

Datonis Documentation Home > Creating Rules

This tutorial assumes that you have set up your Thing and started pushing data to Datonis. The article Building your connected Thing with the Datonis Agent SDK covers this in detail.

It also assumes that you know about Things and Thing Templates. It is also assumed that you have a Thing that is live and pushing data to the Datonis platform.

Introduction to Rules

Rules allow you to analyse your Thing data in near real-time. Rules are defined against a Thing or a set of Things and have conditional logic in it. If the condition evaluates to true, then the Rule gets triggered. For instance, you can write a rule that gets triggered if the temperature metric of a Thing exceeds a threshold. Once a rule is created, you can set Notifications for a role. Notifications are covered in detail at a later point in this document.

Here is a video that demonstrates how to create a simple rule with no scripting required.

Here are some considerations when you are writing rules.

• Tigger intervals are an extremely useful option. This prevents the rule from getting triggered too frequently. Do set it judiciously.
  • Trigger intervals work as follows. Let's say that you keep the trigger interval at 60s. Datonis will ensure that if a rule gets triggered, it will not get triggered again for 60 seconds. The minimum allowed value for rule triggers is 1 second.
• You can specify an individual Thing, specifically select a set of Things, all Things belonging to a Thing Template or select a Group as a target.
  • If your target is a group, please ensure that the group contains Things belonging to a single Thing template or the rule execution can be unpredictable.

The rule engine also allows you to write more advanced rules using a Javascript based syntax. Here's a video that demonstrates how you can achieve that.

Here are some considerations when you are writing advanced script based rules.

• The syntax is Javascript. Datonis will indicate a syntax error if the script has any errors.
• You can use all kinds of conditional logic supported by Javascript to write the rule.
• Metrics are accessible using the syntax $event.data.<metric name>. For instance, $event.data.temperature to access the temperature metric.
• You also have access to special variables. All special variables start with a $_
  • $_return_code: if set to true, indicates that the metric was processed.
  • $_return_value: These are arbitrary key-value pairs that can be set by the rule engine. Return codes are extremely useful to generate additional context when the rule was executed.
  • In the sections below you will see several additional special variables.

In the videos above, you saw how you can create a Point in time rule. Here are all the types of rules that you can create.

• Point in time rules or rules that examine all Incoming Thing data (showcased in the video above).
• Fixed window rules or rules that accumulates data for an interval of time and then the rule is executed.
• Sliding window rules or rules that slides every minute and runs on data accumulated for the specified interval of time.
• Rules against alerts or rules that run against alerts that are sent to the platform.
• Absence of data rules or rules that get triggered if a Thing does not send data or is disconnected from the platform.

Point In Time Rules

A point in time rule is a rule that executes against every metric that is sent to Datonis. This is the simplest form of a rule.

Fixed or Tumbling Time Window Rules

Fixed window or tumbling window rules have a definite beginning and a fixed duration or a window. Once the window expires, all the events are discarded and the window is created once again. In Datonis, you the minimum fixed window size supported is 1 hour. Here is an example of a fixed window duration.

• It is currently 8:45 am. You have created a fixed window rule that begins every hour.
• You are transmitting temperature and humidity readings every minute.
• Datonis will start accumulating events. At 9 am the rule will trigger for the first time. The window is 15 minutes.
• The rule will trigger every subsequent hour: at 10 am, 11am and so on. Every subsequent window is 60 minutes.
• You will have access to min, max, average and sum value for metrics in the rule.
  • For instance, in the first 15 minute window, you will get the average, min, max and sum value for the temperature and humidity metric for that 15 minute period.
  • For every subsequent window, you will get the average, min, max and sum value for the temperature and humidity metric for that 60 minute period.
  • You do not have access to individual metric values. For that, you should use point in time rules.

Here's a video that demonstrates how fixed window rules can be created.

Sliding Time Window Rules

Sliding time window rules consist of a window of time and a slide duration which is 1 minute. Sliding time windows can have a maximum window size of 1 hour. Here is an example of a sliding window.

• It is currently 8.45 am. You have created a sliding window rule with a window duration of 5 minutes.
• You are transmitting temperature and humidity readings every minute.
• The rule will first trigger at 8.50 am. The metrics will me accumulate for 5 minutes and will be available to you.
• It will trigger again at 8:51 am as the slide duration is 1 minute. The window is from 8:46 am to 8:51 am.
• It will trigger again at 8:52 am. The window is from 8:47 am to 8:52 am. This continues as long as the rule is enabled.
• You will have access to min, max, average and sum value for metrics in the rule.
• You will also have access to individual metric values.

Here's a video that demonstrates how sliding time window rules can be created.

Sliding Event Window Rules

Sliding event window rules consist of a window of continuous 'k' events that slides on each new event. Sliding event windows can have a maximum window size of 60 events. Here's a video that demonstrates how sliding event window rules can be created. We have 2 demo Tanks that are being continuously filled with a fluid. Tank-1's level is rising with 5 units at a time, while Tank-2's level is rising with 10 units at a time. The rule showcased demonstrates capability to detect if the level rise rate is greater than 6 units. Thus it will trigger for Tank-2 and not for Tank-1

Absence of Data Rule.

Sometimes you need to know if a critical Thing which is supposed to send data to Datonis is not doing so. You can do this by creating Absence of Data rules. These rules can be of two types.

• A Thing is not sending data: A Thing was supposed to send data but did not do so.
• A Thing is disconnected: A Thing also sends heartbeats (you can see the last heartbeat in the Things list view). Usually heartbeats are sent if a Thing does not send data frequently but sends periodic heartbeats to indicate that it is alive and connected to the platform.

Here is a video that demonstrates how absence of data rules are created.

Some additional information about these rules:

• You can also use Javascript to write script based expressions for absence of data rules.
• You have access to the following special variables.
  • $currentTimestamp which is the current time in milliseconds since epoch.
  • $lastDataTimestamp which is the time when Datonis last received data from a Thing.
  • $lastActivityTimestamp which is the time when Datonis last received a heartbeat from a Thing.

Rules for Alerts.

Datonis provides support for rules against alert data. Here is a video that demonstrates this feature.

Additional Features of the Rule Engine

The rule engine has a few  additional features that makes it more flexible.

Setting return codes and return parameters

As demonstrated in the advanced script based rule section, rules can set context objects as a part of execution and set return codes that indicates weather it processed an event or not. Here is a code snippet that demonstrates that.

my_params = {};
if ($event.data.temperature < 20)
{
    my_params["jacket"] = "wool";
    $_return_status.push(my_params);
    $_return_code = true;
}
else
{
    $_return_code = false;
}

In this case, you will see two additional variables being introduced.

• $_return_code: This indicates that the rule has evaluated for that event or not. For instance, in the example above, the rule only looked at temperature values that were below 20 and discarded every other event. If the value of $_return_code is true then the rule has evaluated. Otherwise that event has been ignored by the rule.
• $_return_status: This is a status map that can be populated by the script and returned back. The status map can be viewed in the Datonis UI by viewing the rule results and looking at the return status section. In this case, the rule triggers if the temperature is < 20. And we have populated a parameter called "jacket" with the value "wool". You can populate multiple params with values. You can also have a nested hierarchical map as well.

Accessing and setting User Defined Properties

User Defined Properties (UDPs) are also accessible to the rule engine. For instance, in the example above, you might not wish to hard-code the low temperature value as 20. You might want to read it from a variable instead. To do this.

• You can add a UDP called low_temp in the Thing LivingRoom. Give it the threshold value which is 20.
• Modify the rule as given below.

my_params = {};
if ($event.data.temperature < $thing.user_defined_properties.low_temp)
{
    my_params["jacket"] = "wool";
    $_return_status.push(my_params);
    $_return_code = true;
}
else
{
    $_return_code = false;
}

Defining geofencing Rules on your Things

Rules can also be defined on waypoints sent by your things. These rules can be used to check whether your Thing at any given instance lies inside or outside a circle or a n-sided polygon. We have provided Javascript functions that you can customize with values of the polygon or circle you want to geofence your thing against. The waypoints sent by your Thing are available to you in the event data as [longitude, latitude]. The different types of rules that can be defined for geofencing are as follows:

• IsPointInsidePolygon: Checks whether a Thing lies inside a custom defined polygon and triggers if the result is true. For instance, given a 4-sided polygon the function prototype will be:

IsPointInsidePolygon({latitude: $event.waypoint[1],longitude:$event.waypoint[0]},[{<latitude-1>,<longitude-1>},{<latitude-2>,<longitude-2>},{<latitude-3>,<longitude-3>},{<latitude-4>,<longitude-4>}]);
//where {<latitude-1>,<longitude-1>} can be {latitude: 18.522377, longitude: 73.889580}

• IsPointOutsidePolygon: Checks whether a Thing lies outside a custom defined polygon and triggers if the result is true. For instance, given a 4-sided polygon the function prototype will be:

isPointOutsidePolygon({latitude: $event.waypoint[1], longitude: $event.waypoint[0]},[{<latitude-1>,<longitude-1>},{<latitude-2>,<longitude-2>},{<latitude-3>,<longitude-3>},{<latitude-4>,<longitude-4>}]);
//where {<latitude-1>,<longitude-1>} can be {latitude: 18.522377, longitude: 73.889580}

• IsPointInsideCircle: Checks whether a Thing lies inside a custom defined circle and triggers if the result is true. For instance, given a circle with radius r(in meters) the function prototype will be:

IsPointInsideCircle({latitude: $event.waypoint[1], longitude: $event.waypoint[0]}, {<latitude-of-the-radius>,<longitude-of-the-radius>}, r);
//where {<latitude-of-the-radius>,<longitude-of-the-radius>} can be {latitude: 18.519284, longitude: 73.919106} and r can be 3000

• IsPointOutsideCircle: Checks whether a Thing lies outside a custom defined circle and triggers if the result is true. For instance, given a circle with radius r(in meters) the function prototype will be:

isPointOutsideCircle({latitude: $event.waypoint[1], longitude: $event.waypoint[0]}, {<latitude-of-the-radius>,<longitude-of-the-radius>}, r);
//where {<latitude-of-the-radius>,<longitude-of-the-radius>} can be {latitude: 18.519284, longitude: 73.919106} and r can be 3000

Now that you have created Rules, you can set up notifications that get invoked when a rule is triggered. The Setting Up Notifications tutorial covers this in detail.