24. Operational Mode Datum Filter¶
The Operational Mode Datum Filter provides a way to evaluate expressions to toggle
operational modes. When an expression evaluates to true the associated operational mode
is activated. When an expression evaluates to false the associated operational mode is
deactivated.
This filter is provided by the Standard Datum Filters plugin.
24.1 Settings¶
Each filter configuration contains the following overall settings:
| Setting | Description |
|---|---|
| Service Name | A unique ID for the filter, to be referenced by other components. |
| Service Group | An optional service group name to assign. |
| Source ID | A case-insensitive pattern to match the input source ID(s) to filter. If omitted then datum for all source ID values will be filtered, otherwise only datum with matching source ID values will be filtered. |
| Required Mode | If configured, an operational mode that must be active for this filter to be applied. |
| Required Tag | Only apply the filter on datum with the given tag. A tag may be prefixed with ! to invert the logic so that the filter only applies to datum without the given tag. Multiple tags can be defined using a , delimiter, in which case at least one of the configured tags must match to apply the filter. |
| Expressions | A list of expression configurations that are evaluated to toggle operational modes. |
Use the + and - buttons to add/remove expression configurations.
24.2 Expression settings¶
Each expression configuration contains the following settings:
| Setting | Description |
|---|---|
| Mode | The operational mode to toggle. |
| Expire Seconds | If configured and greater than 0, the number of seconds after activating the operational mode to automatically deactivate it. If not configured or 0 then the operational mode will be deactivated when the expression evaluates to false. See below for more information. |
| Property | If configured, the datum property to store the expression result in. See below for more information. |
| Property Type | The datum property type to use if Property is configured. See below for more information. |
| Expression | The expression to evaluate. See below for more info. |
| Expression Language | The expression language to write Expression in. |
24.2.1 Expire setting¶
When configured the expression will never deactivate the operational mode directly. When
evaluating the given expression, if it evaluates to true the mode will be activated and configured
to deactivate after this many seconds. If the operation mode was already active, the expiration will
be extended by this many seconds.
This configuration can be thought of like a time out as used on motion-detecting lights: each time motion is detected the light is turned on (if not already on) and a timer set to turn the light off after so many seconds of no motion being detected.
Note that the operational modes service might actually deactivate the given mode a short time after the configured expiration.
24.2.2 Property setting¶
A property does not have to be populated. If you provide a Property name to populate, the value of the datum property depends on property type configured:
| Type | Description |
|---|---|
| Instantaneous | The property value will be 1 or 0 based on true and false expression results. |
| Status | The property will be the expression result, so true or false. |
| Tag | A tag named as the configured property will be added if the expression is true, or removed if false. |
24.3 Expressions¶
See the Expressions section for general expressions reference. The expression
must evaluate to a boolean (true or false) result. When it evaluates to true the
configured operational mode will be activated. When it evaluates to false the operational mode
will be deactivated (unless an expire setting has been configured).
The root object is a datum samples expression object that lets you treat all datum properties, and filter parameters, as expression variables directly, along with the following properties:
| Property | Type | Description |
|---|---|---|
datum |
GeneralNodeDatum |
A GeneralNodeDatum object, populated with data from all property and virtual meter configurations. |
props |
Map<String,Object> |
Simple Map based access to the properties in datum, and transform parameters, to simplify expressions. |
The following methods are available:
| Function | Arguments | Result | Description |
|---|---|---|---|
has(name) |
String |
boolean |
Returns true if a property named name is defined. |
24.3.1 Expression examples¶
Assuming a datum sample with properties like the following:
| Property | Value |
|---|---|
current |
7.6 |
voltage |
240.1 |
status |
Error |
Then here are some example expressions and the results they would produce:
| Expression | Result | Comment |
|---|---|---|
voltage * current > 1800 |
true |
Since voltage * current is 1824.76, the expression is true. |
status != 'Error' |
false |
Since status is Error the expression is false. |