V2/Concepts/Event
Event
Whenever Result changes (from true to false and vice versa), Events may be triggered. Events includes Actions such as sending of notifications, commands to systems or request to a webhook.
General Information
Name and Description
An Event has a Name and Description. The Name and Description allows you to describe the event or situation that the Expression detects, such that recipients of the Event's notification or Alarms knows exactly what happened and is able to react to it accordingly.
- The Event's Name and Description is displayed in the Alarm Description on the Digital Twin.
Description can also be the default content of an Action. You can describe the event or situation once in the Description, and reuse the information in all the Actions of the Event.
Inputs
You can define Inputs tags in the Event. These Inputs tags are linked to values or tag of input data coming from the related Expression. By doing so, you can embed the Inputs in the Description. You can learn more on how to embed the Input in the Description as described here.
Example
Using our Smart Weighing Scale measurement from earlier, the general information for one simple Event can be as follows:
- Name: Battery level low
- Inputs: weighing_scale_id, current_battery_level
- Description: Weighing scale $(weighing_scale_id) battery level is running low. Current battery level: $(current_battery_level)
Action
There are 3 types of content options available for Action, namely:
- Notification
- Command
- Webhook
Notification
Notifications such as Email, SMS and Telegram can be sent to personnel listed upon Event execution. You will be able to describe the event or situation that has happened to the recipient of the notification in the subject and message of a notification.
To further aid you in describing the event, you can embed the Event Input in the subject and message of a notification.
Take a look at this more detailed example.
Command
Commands can be sent to external system integrated with Senfi to directly control the sensors in the external system. E.g. Command sent to lift system to automatically make a lift call for a VIP upon arrival.
Webhook
Webhook request can be sent to external systems such as work order system via Webhook address. You can pass the required parameters in the message body of a Webhook.
Detailed Example
The event that you would like to be notified about is potential fire in a building. There are temperature sensors throughout the building. When a reading from any temperature sensor exceeds 60°C, a fire has probably broken out near the sensor. You would like to be notified by email of such an occurrence.
- The Input in this example would be the metric and measurement that readings from temperature sensor is sent to. e.g: iot_temperature_sensor_v1.temperature
- Condition is iot_temperature_sensor_v1.temperature > 60
- Action is email, with body text:
- "Potential fire detected in room: ${iot_temperature_sensor_v1.room}. Temperature in the room is ${iot_temperature_sensor_v1.temperature}°C"
With the above Rule configured, when iot_temperature_sensor.temperature goes from 59 to 61, an email will be sent with the body text:
- "Potential fire detected in room: #03-00. Temperature in the room is 61°C"
Note: "room" is a Tag of the iot_temperature_sensor_v1 measurement that indicates which room the sensor is in.
Example
Example 1: A simple Rule detecting when a Lift has tripped (safetyTrip == 1).
Example 2: Detects when a Lift tripped (safetyTrip == 1), AND passengers are trapped in the Lift (load > 0)
Working with historical values
When historical values is required to detect an event, the "Range", "Filter" and "Aggregate" nodes are needed.
By default, a "Metric" node will output the Last Known value of the metric. To obtain historical values of a metric, attach the output of "Metric" node to the input of a "Range" node. The output of the "Range" node will be historical values from the metric.
The configuration options of the "Range" node allows you to change the range of historical values to output. E.g: You can configure it to output metric values from 1 hour ago till now, or the last 10 received metric values.
After obtaining the list of historical values, you can:
- Filter the list using the "Filter" node.
- Transform each value in the list using the "Function" node.
The "Filter" and "Function" nodes can be nested.
Finally, the list of historical values must be aggregated using the "Aggregate" node before its output can be used by a "Logic" or "Operator" node.
Example using historical values
The example above detects when a Lift is stopped at Level 2 for over a minute.
Configuring Nodes
Each node contains attributes & options which you can modify. To modify the attributes of a node, move your mouse over the node and click on the "Gear" button that appears near the top right corner of the node (Beside the "X" button). A window will popup to allow you to configure the node.
Aggregate node
This section explains what each of the options for "Aggregate" node does.
- sum
- the sum of all input values
- count
- the number of input values
- average
- the average of input values
- median
- the median value of input values
- max
- the largest value
- min
- the smallest value
- mode
- the value that appears most often
- range
- the difference between the largest and smallest value (max - min)
- stddev
- standard deviation
- percentile
- percentile. This option accepts an additional "Percentile Value" parameter.
- every
- outputs true if every value fulfills the condition. This option accepts an additional "Condition" parameter.
- any
- outputs true if at least 1 value fulfills the condition. This option accepts an additional "Condition" parameter.
Function node
This section explains what each of the options in "Function" node does.
- abs
- absolute value
- round
- round to nearest integer
- ceil
- round up
- floor
- round down
- map
- This option accepts an additional "function" parameter. Using the custom "function" parameter, transforms each input value