Overview

Control Unit Filters are used generally for searching and filtering of devices and components in the RM system.

They can be used:

• to appoint extensive searches in the system;

• in the scopes of Tasks and Rules to identify the set of devices to be involved in mass executions and automations;

• in the GDM Script Service as method arguments for controlling the filtered set of tweaked devices components via RM Scripting;

• in the GDM Java API as method arguments for programming of java applications and RM plugins.

A filter is a standard logical expression with logical operators, which operands are conditions describing the searched targets – devices, control units, control unit state variables, etc.

Logical Operators

The priority of logical operators described in the table below, starting from the highest to the lowest is: !, &, |. Parenthesis can be used to determine different priorities:

Each filter defines different conditions to act as operands in its logical expression. The conditions defined by all the search filters use comparison operators for defining the matching of a searched attribute against the specified value.

Comparison Operators

The Comparison Operators are described in the following table:

Filter Operands

Attribute Condition

Syntax and semantics. These specify control units by their attribute values. Attribute conditions are matched with the properties provided as metadata for the control units. Script syntax:

[<att_target>] <attribute> <comparison_operator> <search_value>

Example:

where:

• <att_target> – (Optional) Explicitly indicates that what is specified in the <attribute> clause is a name of a control unit state variable, or a device capability, or a device node property. The targets "capability:" and "nodeProps:" are only allowed when the attribute condition is used inside a device condition, i.e. it specifies device-filtering criteria.

• <attribute> – Specifies the name of the searched attribute.

• <comparison_operator> – Contains a standard RM script comparison operator (see the "Comparison Operators" section above).

• <search_value> – Represents the attribute's searched value.

Following is a short description of filtering attribute targets:

• Standard attributes – If one of the keywords ID, TYPE, DEVICE_TYPE or DEVICE_ID is present as <attribute>, the condition is considered to be on respectively the control unit ID, control unit type, device type or device ID of the filtered control unit instance.

• State variable – The condition is on a state variable of the filtered control unit instance.

• Device capability – The condition is on the capabilities of the filtered device.

• Node property – The condition is on the node properties of the filtered device.

Custom attribute condition. Except for generic filtering attributes, script filters can accept custom filtering attributes with individually-defined mapping on the underlying resources. Such custom attributes are handled by condition matcher plugins, and attribute conditions containing custom attributes are forwarded for evaluation to those plugins.

Example:

A device provider may provide filtering on log messages related to particular devices of its controlled type, assuming that log messages are not represented as control units and therefore such filtering is not possible with the generic filtering attributes.

See also "Matching Attribute Conditions" section below.

Parent Control Unit Condition

Defines filtering the control units on conditions concerning their parent control units. Its lexical syntax is:

HAVING PARENT (<control_unit_filter>)

where <control_unit_filter> is a control unit filter.

Sub Control Unit Condition

Defines filtering the control units on conditions concerning their sub control units. Its lexical syntax is:

HAVING CHILD (<control_unit_filter>)

where <control_unit_filter> is a control unit filter.

Device Condition

Defines filtering the control units on conditions concerning the devices to which they belong. Its general syntax is:

ON (<device_filter>)

The <device_filter> differs from the standard control unit filter only by the operands that can take part in it. Operands in device filter could be:

• Device Attribute Conditions – It is a standard attribute condition (see the "Attribute Condition" section above) that have to specify in its <att_target> clause a device capability or a device node property:

  [<device_att_target>] <attribute> <comparison operator> <search value> <device_att_target> ::= (capability:) | (nodeProp:)

• Containment Conditions – This operand defines filtering the devices that contain certain control units. Its lexical syntax is:

  CONTAINING (<control_unit_filter>)

  where the <control_unit_filter> is a standard control unit filter.

Matching Attribute Conditions

In straight examples, an attribute condition may look like one of the following cases:

(propName == "propVal") or

(stateVar: propName == "propVal") or

(nodeProp: propName == "propVal") or

(capability: propName == "propVal")

Matching of the attribute condition proceeds in the following way:

1. If there is an explicitly specified target (i.e. "stateVar:" or "nodeProp:" or "capability:"), the system matches against the respective explicit target .

2. If no explicit target is present (i.e. the case is (propName == "propVal") ), the system checks if propName is one of the keywords ID, TYPE, DEVICE_TYPE or DEVICE_ID, and matches respectively against the control unit ID, control unit type, device type or device ID.

3. Otherwise (no explicit target and not a standard attribute (id, type, etc.)), the system checks if there is a condition matcher plugin registered to match the propName attribute. If yes, forwards the condition to the custom matcher.

4. Otherwise, the system matches the condition as follows:

   • If the control unit has state variable with name propName, the system matches against the state variable value of the filtered control unit.

   • Else, if the device of the filtered control unit has a capability with name propName, the system matches against that capability.

   • Else, if the device of the filtered control unit has a node property with name propName, the system matches against that property.

   • Else, matching ends with FALSE.

Complete Syntax Definition