Latest revision as of 19:00, 7 June 2022

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.

Expression Input Data to Event Inputs Mapping

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 are requests that can be sent to external system integrated with Senfi to directly control the sensors in the external system. If the Connector/subsystem agrees to the request, the Asset's Metric value may be updated to reflect the change. E.g. Command sent to backup chiller to turn it on when the main chiller malfunctions.

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 chiller malfunction in a building. There are chiller equipment to help power the air-conditioning in a building. When the status of a chiller shows that it has failed to run, the chiller probably has malfunctioned. You would like to be notified by email of such an occurrence, automatically switch on the backup chiller and issue a work order for maintenance repair.

The Input in this example would be the metric and measurement that readings from chiller equipment is sent to. e.g: iot_chiller_v1.status
Condition is iot_chiller_v1.status = failed to run
Event: Chiller equipment malfunctioned
Event Input: device_id and chiller_status
Notification Action: Email, with body text:

"Chiller device no: ${device_id} has malfunctioned. Chiller status: ${chiller_status}. Please investigate."

Command Action: Send command to backup chiller to turn it on.
Webhook Action: Send webhook to issue work order for chiller maintenance repair.

With the above Expression configured, when iot_chiller_v1.status is equivalent to failed to run, an email will be sent with the body text:

"Chiller device no: 05 has malfunctioned. Chiller status: failed to run. Please investigate."

At the same time, the backup chiller will automatically startup and take over the malfunctioned chiller, and a work order will be issued to request for chiller maintenance repair.

Note: "device_id" comes from the Device ID Tag of the iot_chiller_v1 measurement that identifies a particular chiller. "chiller_status" is mapped to iot_chiller_v1.status metric as specified in the Expression that triggers this Event.

External Events

External Events are specialized Senfi Events that are triggered by external systems. Examples of external events are:

A new Motion Detected alarm raised from Milestone XProtect VMS -> Motion Detected New external event
An acknowledged Motion Detected alarm update from Milestone XProtect VMS -> Motion Detected Acknowledged external event
A closed Motion Detected alarm update from Milestone XProtect VMS -> Motion Detected Closed external event

External events are handled similarly to events raised by Expression created in the CMS. External events can:

Have actions (notification, command, webhook) added to them
Raise alarms

Note: Senfi currently do not allow direct raising of alarms from external systems. All external alarms must be raised by proxy using external events, which then trigger Senfi alarms using Senfi's automation workflow.

Similarities of External Events to general Senfi Events

Similarly to events, External events have the basic general information:

Name
Description
Inputs

Differences between External Events to general Senfi Events

Differences between External Events and Events created in the CMS:

External events are created by Senfi HTTP API only. They cannot be added in the CMS.
External events are updated by Senfi HTTP API only. They cannot be updated in the CMS (except for adding/updating/deleting event Actions).
External events are deleted by Senfi HTTP API only. They cannot be deleted in the CMS.
CMS can only view External events and add/update/delete event Actions
CMS cannot enable/disable External events
Senfi Expression cannot trigger External events

Example of an external event when viewed in Senfi CMS (Editing of name and description is prohibited)

@@ Line 12: / Line 12: @@
 ==== 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 [[V2/CMS_Tutorial/User_Tools/Creating_Content/Automation/Event/Inputs|here]].
+[[File:Concepts_Automation_Expression_Event_Mapping.png|thumb|800px|Expression Input Data to Event Inputs Mapping|center|link=]]
 ==== Example ====
@@ Line 28: / Line 30: @@
 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 value or tag of an '''Input''' metric in the content of an '''Action'''. You can also embed the Rule's [[#Name_and_Description|Name, Description]] and [[#Severity|Severity]] in the content of an '''Action'''.
+To further aid you in describing the event, you can [[V2/CMS_Tutorial/User_Tools/Creating_Content/Automation/Event/Inputs|embed]] the Event '''Input''' in the subject and message of a notification.
-To embed:
-* metric's value, use <tt>${<measurement_code>.<metric_code>}</tt>. e.g: <tt>${iot_temperature_sensor_v1.temperature}</tt>
-* metric's tag, use <tt>${<measurement_code>.<tag>}</tt>. e.g: <tt>${iot_temperature_sensor_v1.site_id}</tt>
-* Rule's name, use <tt>${NAME}</tt>.
-* Rule's description, use <tt>${DESCRIPTION}</tt>.
-* Rule's severity, use <tt>${SEVERITY}</tt>.
-<div class="important">Note: embedding Rule's name, description and severity is case sensitive. You must use all capital letters.</div>
 Take a look at [[#Detailed_Example | 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.
+Commands are requests that can be sent to external system integrated with Senfi to directly control the sensors in the external system. If the Connector/subsystem agrees to the request, the Asset's Metric value may be updated to reflect the change. E.g. Command sent to backup chiller to turn it on when the main chiller malfunctions.
 ==== 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.
-== Rule execution options ==
-By setting '''Evaluate Type''' to '''Immediate''' or '''Polling''', you can choose to execute a Rule when new values are received for any Input Measurements, or periodically, regardless of whether any Input Measurements have changed.
-If Rule is set to run periodically ('''Polling'''), you must specify how often a Rule is executed by setting '''Intervals''' in seconds.
 == Detailed Example ==
-The event that you would like to be notified about is potential fire in a building.
+The event that you would like to be notified about is chiller malfunction 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.
+There are chiller equipment to help power the air-conditioning in a building. When the status of a chiller shows that it has failed to run, the chiller probably has malfunctioned.
-You would like to be notified by email of such an occurrence.
+You would like to be notified by email of such an occurrence, automatically switch on the backup chiller and issue a work order for maintenance repair.
-* The '''Input''' in this example would be the metric and measurement that readings from temperature sensor is sent to. e.g: <tt>iot_temperature_sensor_v1.temperature</tt>
-* '''Condition''' is <tt>iot_temperature_sensor_v1.temperature > 60</tt>
-* '''Action''' is email, with body text:
-:<tt>"Potential fire detected in room: ${iot_temperature_sensor_v1.room}. Temperature in the room is ${iot_temperature_sensor_v1.temperature}°C"</tt>
-With the above '''Rule''' configured, when <tt>iot_temperature_sensor.temperature</tt> 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 <tt>iot_temperature_sensor_v1</tt> measurement that indicates which room the sensor is in.
-== Constructing Condition ==
-This section will guide you to construct a condition using the Rule Editor when adding/editing a Rule in the CMS. The objective here is to tell Senfi how to detect the event or situation that you wish to be notified of.
-[[File:rule_editor.png|thumb|Rule Editor|link=]]
-The Rule Editor is a graph based "Drag and Drop" editor. Each node in the Editor represents either an '''Input''', Data Transformation, Logic, or an '''Action'''. Arrows are used to link the nodes and control the flow of data between nodes.
-[[File:rule_editor_input_output_arrows.png|thumb|Input & Output of a node|link=]]
-'''Arrows coming into the left of a node indicates the node's input, <br>and arrows going out the right of a node indicates the node's output'''.
-The graph must always start from '''Input''' nodes and ends in the '''Result''' or '''Action''' nodes (Data originates from '''Input''' nodes, is transformed by Data Transformation, Logic nodes, and is consumed by '''Result''' & '''Action''' nodes).
-;'''Input''' nodes
-:'''Metric''' - outputs the value/s of a metric. can be set to output the last known value, or a range of historical values
-;Logic Nodes
-:'''Compare''' - comparison operators. e.g. <, >=, ==, !=
-:'''Logic''' - perform "AND" or "OR" between 2 or more boolean values
-;Data Transformation nodes
-:'''Filter''' - used to filter a range of values and output a subset number of values. Can only be used after a Metric node in "Range of Value" mode and before an Aggregate
-:'''Aggregate''' - used to aggregates a range of values into a single value. E.g. sum, average, median. Can only be used after a Metric node in "Range of Value" mode
-:'''Function''' - value-wise transformation. Transform each value, e.g ABS, Floor, Round etc. Can be used after a Metric node and before a Compare node. Outputs the same number of values as its input.
-;Result node
-:'''Result''' - '''Result''' node. Must have 1 and only 1 node. Specifies the '''Result''' of a '''Rule'''
-;Action nodes
-:'''Action''' - '''Action''' node. Input must always be from the "Result" node. Can have 0 or more "Action" nodes. Instructs Senfi to do something when '''Result''' changes.
-=== Basic Steps ===
-# Drag a node above working area into the working area to create a node.
-# Create "Metric" nodes, one for each '''Input''' metric.
-# Select the correct measurement and metric for each "Metric" node. Read: [[#Configuring_Nodes|how to configure a node]]
-# (Optional) If you need to compare metric value against a constant value, use the "Constant" node.
-# Create "Operator" and "Logic" nodes to construct necessary logic
-#* logic graph should output a single boolean (true or false) value
-#* output from "Metric" node must go to input of a "Operator" node.
-#* "Operator" and "Logic" nodes can be nested.
-#* You can attach more than 2 inputs to a "Logic" node
-# Create a "Result" node and attach output of logic graph as its input
-# Create "Action" nodes, one for each desired '''Action''' and attach output of "Result" node as its input
-# Save when done
-=== Example ===
-[[File:rule_editor_example.png|center|Example 1|thumb|700px|link=]]
-Example 1: A simple Rule detecting when a Lift has tripped (safetyTrip == 1).
-[[File:rule_editor_example2.png|center|Example 2|thumb|700px|link=]]
-Example 2: Detects when a Lift tripped (safetyTrip == 1), AND passengers are trapped in the Lift (load > 0)
-=== Working with historical values ===
+* The '''Input''' in this example would be the metric and measurement that readings from chiller equipment is sent to. e.g: <tt>iot_chiller_v1.status</tt>
-When historical values is required to detect an event, the "Range", "Filter" and "Aggregate" nodes are needed.
+* '''Condition''' is <tt>iot_chiller_v1.status = failed to run</tt>
+* '''Event''': Chiller equipment malfunctioned
+* '''Event Input''': <tt>device_id</tt> and <tt>chiller_status</tt>
+* '''Notification Action''': Email, with body text:
+:<tt>"Chiller device no: ${device_id} has malfunctioned. Chiller status: ${chiller_status}. Please investigate."</tt>
+* '''Command Action''': Send command to backup chiller to turn it on.
+* '''Webhook Action''': Send webhook to issue work order for chiller maintenance repair.
-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.
+With the above '''Expression''' configured, when <tt>iot_chiller_v1.status</tt> is equivalent to '''failed to run''', an email will be sent with the body text:
+:"Chiller device no: 05 has malfunctioned. Chiller status: failed to run. Please investigate."
+At the same time, the backup chiller will automatically startup and take over the malfunctioned chiller, and a work order will be issued to request for chiller maintenance repair.
-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.
+Note: "device_id" comes from the Device ID Tag of the <tt>iot_chiller_v1</tt> measurement that identifies a particular chiller. "chiller_status" is mapped to <tt>iot_chiller_v1.status</tt> metric as specified in the Expression that triggers this Event.
-After obtaining the list of historical values, you can:
+== External Events ==
-* Filter the list using the "Filter" node.
+External Events are specialized Senfi Events that are triggered by external systems. Examples of external events are:
-* Transform each value in the list using the "Function" node.
+* A new Motion Detected alarm raised from Milestone XProtect VMS -> Motion Detected New external event
-The "Filter" and "Function" nodes can be nested.
+* An acknowledged Motion Detected alarm update from Milestone XProtect VMS -> Motion Detected Acknowledged external event
+* A closed Motion Detected alarm update from Milestone XProtect VMS -> Motion Detected Closed external event
-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.
+External events are handled similarly to events raised by Expression created in the CMS. External events can:
+* Have actions (notification, command, webhook) added to them
+* Raise alarms
-=== Example using historical values ===
+Note: Senfi currently do not allow direct raising of alarms from external systems. All external alarms must be raised by proxy using external events, which then trigger Senfi alarms using Senfi's automation workflow.
-[[File:rule_editor_example_historical.png|center|Historical Example 1|thumb|700px|link=]]
-The example above detects when a Lift is stopped at Level 2 for over a minute.
-=== Configuring Nodes ===
+=== Similarities of External Events to general Senfi Events ===
-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.
+Similarly to events, External events have the basic general information:
+* Name
+* Description
+* Inputs
-==== Aggregate node ====
+=== Differences between External Events to general Senfi Events ===
-This section explains what each of the options for "Aggregate" node does.
+Differences between External Events and Events created in the CMS:
-;sum
+* External events are created by Senfi HTTP API only. They cannot be added in the CMS.
-:the sum of all input values
+* External events are updated by Senfi HTTP API only. They cannot be updated in the CMS (except for adding/updating/deleting event Actions).
-;count
+* External events are deleted by Senfi HTTP API only. They cannot be deleted in the CMS.
-:the number of input values
+* CMS can only view External events and add/update/delete event Actions
-;average
+* CMS cannot enable/disable External events
-:the average of input values
+* Senfi Expression cannot trigger External events
-;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
-:[https://en.wikipedia.org/wiki/Standard_deviation standard deviation]
-;percentile
-:[https://en.wikipedia.org/wiki/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 ====
+[[File:External_Events_in_CMS.png|thumb|800px|Example of an external event when viewed in Senfi CMS (Editing of name and description is prohibited)|center|link=]]
-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
-<span class="right">[[Computed_measurement|Next: Computed Measurement]]</span>
+==== What's Next ====
+-----
+* [[V2/Concepts/Preparing for Event Creation|What is needed to create an Event]]
+* Start [[V2/CMS_Tutorial/User_Tools/Creating_Content/Automation/Event|creating your own Event]]
+* Learn about [[V2/Concepts/Alarm|Alarm]]

Difference between revisions of "V2/Concepts/Event"