Rules¶
Rules determine condition states based on an input signal. Conditional rule state changes trigger an event status which is recorded to the event log, notifications are sent out, and the signal and asset statuses are updated in the application.
Rules offer the ability to run logic against a signal to determine a current condition of a signal. Signals may have multiple rules associated with them to look for different types of conditions and overall, the rule states provide the current conditions for an asset.
When a rule detects a new state, a state change event is recorded to the asset log, the rule state changes, and any associated notification subscriptions are triggered.
The Using Rules Guide provides a step by step walk through of using rules in ExoSense.
Rule Condition States¶
Rules generate status events which are logged in the Asset Log and affect the connected Signals status and the overall Asset Status. In the application, Critical status (shown as red) takes preference over Warning status (yellow), which takes preference over OK status (green).
| Event Status (Severity) | System Color | General Description |
|---|---|---|
Ok | Condition state associated as being normal or good. | |
Warning | Condition State used by some rules for noting that a condition is not normal or close too bad. This should be monitored appropriately or preemptive action taken. | |
Critical | Condition State used by some rules for noting that a condition is bad and action should be taken immediately. | |
Error | There is an issue with the signal or rule that prevents the rule from actually determining the current state. Action is recommended. | |
Informational | Condition State used by some rules to provide information but is not associated as good or bad. |
Timeout States¶
Timeout states for signals are handled separately. Any signal that has a timeout rule associated to it, will roll up to the overall Asset. If the signal is timed out, the asset will show a timeout icon throughout the application. Timeout states do not change the condition state, which stays as the last known condition. Dashboard panels that show signals will indicate when a specific signal is timed out.
| Event Status | General Description |
|---|---|
Timeout | The rule for the signal has detected that no value has been received past a given timeout period and therefore is in a timeout state. |
Not In Timeout | The rule for the signal has detected that the last value has been received within a given period and therefore is not in a timeout state. |
Notifications Messages¶
Rule status events are recorded to an Asset's event log. In addition, notifications are sent out based on a user's notification preferences set up in their profile.
Rules may support additional custom messages that can be included in notifications. Each rule function supports this individually. The text entered in these fields is included in the notification messages sent out to users.
Notifications and Message Formats
Standard Rules¶
Threshold (Numeric type)¶
Allows user to configure the following thresholds for an input signal. If the value of the signal goes above / below these thresholds, the status changes \(critical take preference over warning\) and an event is created in the Asset log.
Overall Parameters
| Parameter | Description |
|---|---|
| Name | The rule name used in the asset modify view. |
| Extra details for when value does not match | Prefix text that is applied to Event messages \(Log, Notifications\) when there are no threshold parameters that are true. |
Parameters for each Contains Match
| Parameter | Required? | Description |
|---|---|---|
| Operation | Required | The logical operator used in the threshold calculation |
| A value to compare to | Required | The numeric threshold for the operation to compare to |
| Duration Type | Required | See below for Duration options. Default is 'Sustained Duration'. |
| Extra details for when value does match | Optional | Prefix text that is applied to Event messages \(Log, Notifications\) when this specific value has a match. |
Duration Options
| Duration Option | Description |
|---|---|
| Once | When selected the function will only evaluate the last signal value with the operator and threshold value. |
| Sustained Duration | [Default] When selected the function will evaluate based on a time Duration and Duration Units. The signal value threshold operation comparison must stay true for this time duration for a state change. |
| Repeated | When selected the threshold operator function will evaluate based on the number of continuous \(**Count**\) times the threshold operator is true in a row. If this count condition is met, it will cause a state change. |
| Repeated Over Time | When selected, both a Count \(number of times\) and Duration \(time period\) are used. The function will look for the specified matching threshold operator count within the given duration for a state change. |
Contains (String type)¶
A String signal type rule that will perform a substring search for the specified string value inside of the actual signal's last value.
For normalization of the strings, this rule uses the NFC (Canonical Decomposition, followed by Canonical Composition) as described https://www.unicode.org/reports/tr15/#Norm_Forms.
Note that this Rule function supports multiple match conditions, each with it's own event level.
Overall Parameters
| Parameter | Description |
|---|---|
| Name | The rule name used in the asset modify view. |
| Extra Notification Message text when no value matches | Prefix text that is applied to Event messages \(Log, Notifications\) when there are no matches for the contains values. |
Parameters for each Contains Match
| Parameter | Required? | Description |
|---|---|---|
| The substring value to look for | Required | |
| Alert level for a matching value | Required | |
| Duration Type | Required | See below for Duration options. Default is 'Once'. |
| Prefix Notification Message text when a match is found | Optional | Prefix text that is applied to Event messages \(Log, Notifications\) when this specific value has a match. |
Duration Options
| Duration Option | Description |
|---|---|
| Once | Default Duration option. When selected the function will only evaluate the last signal value for a matching comparison. |
| Sustained Duration | When selected the function will evaluate based on a time Duration. The signal value matching comparison must stay the same for this long for a state change. |
| Repeated | When selected the function will evaluate based on the number of continuous \(**Count**\) times a matching comparison has been made. If this count condition is met, it will cause a state change. |
| Repeated Over Time | When selected, both a Count \(number of times\) and Duration \(time period\) are used. The function will look for the specified matching comparisons count within the given duration for a state change. |
Boolean (Boolean type)¶
Evaluates a Boolean signal type and allows setting a status for true and for false values.
Parameters
| Parameter | Required? | Description |
|---|---|---|
| The Alert Level for True | Required | The severity level of the event status state change created when the signal value is true. |
| The Alert Level for False | Required | The severity level of the event status state change created when the signal value is false. |
| Duration Type | Required | See below for Duration options. Default is 'Once'. |
| Prefix Notification Message text when equal | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when the value is true. |
| Prefix Notification Message text when not equal | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when the value is false. |
Duration Options
| Duration Option | Description |
|---|---|
| Once | Default Duration Option. When selected the function will only evaluate the last signal value for a comparison. |
| Sustained Duration | When selected the function will evaluate based on a time Duration. The signal value must stay the same for this long for a state change to occur. |
| Repeated | When selected the function will evaluate based on the number of continuous \(**Count**\) times the same value has been sent. If this count condition is met, it will cause a state change. |
| Repeated Over Time | When selected, both a Count \(number of times\) and Duration \(time period\) are used. The function will look for the specified count of the same value within the given duration for a state change. |
Is Equal To (Numeric type)¶
Allows a user to set a value to compare a numeric value against. If any match it will set the status to whichever status value was set for that comparison.
Parameters:
| Parameter | Required? | Description |
|---|---|---|
| Value to compare to | Required | The value the rule will compare to the current signal value. |
| The number of decimal places to check | Required | The function will compare the signal value to this many decimal places. Default is 1. |
| The alert when equal | Required | The severity level of the event status state change created when there is an equal comparison. |
| Duration Type | Required | See below for Duration options. Default is 'Once'. |
| Prefix Notification Message text when equal | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when the comparison is true. |
| Prefix Notification Message text when not equal | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when the comparison is false. |
Duration Options
| Duration Option | Description |
|---|---|
| Once | Default Duration Option. When selected the function will only evaluate the last signal value for a comparison. |
| Sustained Duration | When selected the function will evaluate based on a time Duration. The signal value must stay the same for this long for a state change. |
| Repeated | When selected the function will evaluate based on the number of continuous \(**Count**\) times the same value has been sent. If this count condition is met, it will cause a state change. |
| Repeated Over Time | When selected, both a Count \(number of times\) and Duration \(time period\) are used. The function will look for the specified count within the given duration for a state change. |
Timeout¶
The Timeout rule allows a user to set a maximum time period without a new value being received before it is considered to be in a timeout state. Once in the timeout state, the receipt of any new value would trigger an exit out of the timeout state. Both the entering and exiting of the timeout state generate an event in the asset log and can be subscribed-to for notifications.
Enabling the Timeout Features
The timeout Rule and visualization of timeout status in ExoSense are controlled a Feature Flag switch found on the Configuration page's Features tab. Note: Dashboard Panels can visualize a timeout using only the signal's timeout property. Timeout rules are not required for showing individual signal timeouts on dashboard panels.
Asset Timeout Rule - Makes the Timeout Rule available in the asset configuration
Asset Timeout Visualization and Alerts
An asset will be shown in asset lists, group view, and maps with a timeout indicator if any signal that has a timeout rule is in the timeout state. Only one signal needs a timeout rule for this to occur. For application use cases where all signals our sourced from a single device, only 1 rule is typically necessary to get timeout states and alerts.
Parameters:
| Parameter | Required? | Description |
|---|---|---|
| Timeout Interval | Required | The maximum time period without a new value received for the signal before entering the timeout state. The value is in minutes or hours. The minimum time is 1 minute. |
| Extra details when timed out | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when **entering** the timeout state. |
| Extra details for when timed in | Optional | Pre-fix text that is applied to Event messages (Log, Notifications) when **exiting** the timeout state. |
Timeout Rule configuration 
A signal with both a timeout rule (shown in timeout state) and a threshold rule. 
Timeout Rule vs Signal Timeout Property
The dashboard panels will use a Timeout Rule for showing a signal's timeout status. If none is found, it will use the Signal's Timeout property if it exists to show a timeout state. A signal timeout property is only visual, it does not generate a timeout event / notification.
Repeating Value¶
The Repeating Value rule allows users to look for a situation where the sensor or controls or device firmware may be 'stuck' in which it continues to just send the same value over and over.
Parameters:
| Parameter | Required ? | Description |
|---|---|---|
| The number of decimal places to check | Required | The function will compare the signal value to this many decimal places. Default is 1. |
| The alert level when too many | Required | The severity level of the event status state change created when there is an equal comparison. |
| Duration Type | Required | See below for Duration options. Default is repeated count of '5' times. |
Duration Options
| Duration Option | Description |
|---|---|
| Once | Not Recommended. |
| Sustained Duration | When selected the function will evaluate based on a time Duration. The signal value must stay the same for this long to trigger. |
| Repeated | When selected the function will evaluate based on the number of continuous (Count) times the same value has been sent. If this count condition is met, it will trigger and cause a state change. |
| Repeated Over Time | When selected, both a Count (number of times) and Duration (time period) are used. The function will look for the specified count within the given duration for a state change. |
Other Rules¶
ExoSense instances may have other rules added by administrators, built specifically for the instance or added from the IoT Marketplace. These rules will have their own descriptions, input and outputs, and constants.