Rules¶

Overview¶

Rules determine state changes based on an input signal. Each rule has logic to evaluate each new signal value to determine if a state has changed for the rule.

For example, a threshold type rule could evaluate if a value is now above a warning level and when detected create a warning state change event, going from Normal, OK Warning.

---
config:
  theme: neutral
---
graph LR
  Signal@{ shape: das, label: "Signal" }
  d0@{ shape: framed-circle, label: "Data Point" }
  d1@{ shape: framed-circle, label: "Data Point" }
  d2@{ shape: framed-circle, label: "Data Point" }
  d3@{ shape: sm-circ, label: "Data Point" }
  Rule{Rule};
  style Rule stroke-width:3px
  DPC@{ shape: brace-r, label: "New Incoming Signal Values" }
  EVENTC@{ shape: brace-l, label: "State Change Detected: Warning Level" }
  DPC ~~~ d0
  d0 e1@-.- d1 e2@-.- d2 e3@-.- Signal e4@-.- d3 e5@--> Rule
  %%d3 eTS@-.-o ts
  state_change@{ shape: f-circ }
  style state_change fill:#fdd835,stroke:#fdd835
  Rule e6@-.- | State<br>Change | state_change
  state_change ~~~ EVENTC
  e1@{ animate: true }
  e2@{ animate: true }
  e3@{ animate: true }
  e4@{ animate: true }
  e5@{ animate: true }
  e6@{ animate: true }

Configuration¶

Rules are configured as a part of the Asset's signal data pipeline, always attached to a signal. The Asset Configuration allows editing the parameters / constants for the rule. Rules are a part of a templated asset and inherit the parameters from the template. (Note: Optional functionally allows overriding rule constants for assets linked to a template.) Solutions may implement solution level custom rules. (Note: Only the built-in threshold rules allow for displaying thresholds on dashboard panels.)

Signals technically may have multiple rules associated with them to look for different types of conditions (operational state, timeout, etc) and/or use different types of logic. Overall the rule states provide the current status for the specific signal and contribute to the overall status for an asset.

---
config:
  theme: neutral
---
graph LR
  Signal@{ shape: das, label: "Signal" }
  d0@{ shape: f-circ, label: "Data Point" }
  d1@{ shape: f-circ, label: "Data Point" }
  d2@{ shape: f-circ, label: "Data Point" }
  d3@{ shape: f-circ, label: "Data Point" }
  style d0 fill:#DDD,stroke:#999,fill-opacity:0.1,stroke-dasharray:2
  style d1 fill:#DDD,stroke:#999,fill-opacity:0.1,stroke-dasharray:2
  style d2 fill:#DDD,stroke:#999,fill-opacity:0.1,stroke-dasharray:2
  style d3 fill:#DDD,stroke:#999,fill-opacity:0.1,stroke-dasharray:2
  Rule{Threshold Rule};
  RuleTimeout{Timeout Rule};
  DPC@{ shape: brace-r, label: "No new values.<br>Showing expected rate" }
  EVENTC@{ shape: brace-l, label: "State Change Detected: Timeout" }
  DPC ~~~ d0
  d0 ~~~ d1 ~~~ d2 ~~~ Signal -.- d3 -.- Rule
  d3 -.- RuleTimeout
  state_change@{ shape: f-circ }
  style state_change fill:#999,stroke:#999
  RuleTimeout e6@-.- | State<br>Change | state_change
  state_change ~~~ EVENTC
  e6@{ animate: true }

Rule Logic¶

Rules are signal data event driven in that they run on each signal data point as soon as it enters the data pipeline (e.g. Sensor reading -> Device Channel -> Asset Signal -> Rule function). These functions, being event driven, evaluate the new value and return a decision on whether there is a state change based on previous last state of the rule. ExoSense includes several off the shelf rules (documented below) that have logic for common use cases like numeric thresholds, a contains check for string values, a boolean check, an is equal to numeric check, signal timeouts and repeating values. The ExoSense pipeline's rule functionality includes built-in support for sustained values such as over a time period, a count, or a count in a time period.

Checks functionality runs before a Rule function's logic to "check" to see if a signal (the calling signal or any other) meets a criteria or if there is a specific time window to run / not run the rule. For more details: Rule & Transform Checks

Rule Actions¶

When a rule detects a new state, there are a number of outcomes and additional triggered activities.

Rule State Change Activities:

1. Event Log - An event is recorded to the asset event log
2. Status - The rule's status changes (which is used in the UI and API calls)
3. Notifications - Notifications based on user subscriptions are sent out.
4. Conditions - The condition service evaluates whether to create a new Condition based on the policy associated to the rule. (Advanced Feature)
5. Actions - Action functions that have been connected to this rule will be triggered. (Advanced Feature)

---
config:
  theme: neutral
---
graph LR
  Signal@{ shape: das, label: "Signal" }
  d3@{ shape: sm-circ, label: "Data Point" }
  Rule{Rule};
  style Rule stroke-width:3px
  EventLog@{ shape: cyl, label: "Event Log<br>History" }
  Signal e4@-.- d3 e5@--> Rule
  state_change@{ shape: f-circ }
  style state_change fill:#fdd835,stroke:#fdd835,fill-opacity:0.4;
  Rule e6@-.- | State<br>Change | state_change
  state_change e7@--> EventLog ~~~ ELC@{ shape: brace-l, label: "The state change information including level (e.g. Warning), is recorded." }
  Rule --- Status@{ shape: curv-trap, label: "Updated Rule State: <br>OK -> Warning"} ~~~ SC@{ shape: brace-l, label: "Visualizations / API will use this state when evaluating Signal & Asset Statuses." }
  style Status fill:#fdd835,stroke:#fdd835,fill-opacity:0.2
  state_change e9@--> Notify@{ shape: subproc, label: "Notification<br>Subscriptions"}
  state_change e10@--> Conditions@{ shape: subproc, label: "Condition<br>Management"} 
  Conditions ~~~ CC@{ shape: brace-l, label: "If Condition Policies are in use, check to see if new condition exists." }
  state_change e11@--> Actions@{ shape: procs, label: "Action Functions"}
  Actions ~~~ AC@{ shape: brace-l, label: "Triggers any Action functions attached to Rule" }
  Notify--> Email["Email"]
  Notify--> SMS["SMS"]
  e4@{ animate: false }
  e5@{ animate: false }
  e6@{ animate: true }
  e7@{ animate: true }
  %%e8@{ animate: true }
  e9@{ animate: true }
  e10@{ animate: true }
  e11@{ animate: true }

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

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 last known signal status. Dashboard panels that show signals will indicate when a specific signal is timed out.

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 preference and subscriptions 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

Parameters for each Contains Match

Duration Options

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.

Note that this Rule function supports multiple match conditions, each with it's own event level.

Overall Parameters

Parameters for each Contains Match

Duration Options

Boolean (Boolean type)¶

Evaluates a Boolean signal type and allows setting a status for true and for false values.

Parameters

Duration Options

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:

Duration Options

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.

Parameters:

Timeout Rule configuration

A signal with both a timeout rule (shown in timeout state) and a threshold rule.

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:

Duration Options

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.