SLA management groups and rule expressions

SLA management groups and rule expressions are the same as the rule-based and direct-based management groups seen in the platform UI. They are referred to as SLA because management groups depend upon the inventory features provided by SLA components of the 1E Platform. 

For information on the 1E PowerShell Toolkit cmdlets available for the management of SLA management groups, refer to Instruction management cmdlets.

Rule expressions were significantly enhanced in version 8 of the 1E Platform to support operator precedence so that you can, effectively, group terms by using brackets to prioritize how they are evaluated. In earlier releases, this was not possible.

Management group internals changed in version 8. For more information on the changes, refer to Management group changes in version 8 of the 1E Platform.

The new elastic SaaS environment has changed the names for some rule expression attributes and others are not available in initial releases of the platform.

About rule expressions

Within Settings of the 1E Platform, you can define new management group rules graphically. However, when you are creating rules programmatically, you will naturally want to express your rules as simple text expressions that you can pass to the appropriate cmdlets on the command line.

You build management group rule expressions in a very similar way to building scope or filter expressions.

  • Scope expressions allow you to define a target set of devices for an instruction, which meet the criteria associated with the scope expression.
  • Filter expressions allow you to define how results from an instruction will be filtered before being returned to the caller.
  • Management group rule expressions allow you to define a set of criteria that will control the devices that are associated with the specified management group.

Expressions use a set of attributes. For information about scope and filter expressions, refer to Scope and filter expressions.

Rule expression attributes

A rule expression consists of a set of attributes that can be compared with values. To get a full set of attributes that are allowed, you can use the Get-1ESLAManagementGroupRuleAttribute cmdlet.

Copy
Get-1ESLAManagementGroupRuleAttribute

Attributes and data sources

While you can always specify any attribute in a rule expression, be aware that some data sources do not populate these attributes. For example, Active Directory attributes, such as Organizational Unit, are only captured from data sources, such as Microsoft SCCM, that collect them.

For information on which attributes are available from the different data sources, refer to Management groups rules.

Extending attributes using device tags

The 1E Platform supports a mechanism for assigning custom tags and values to a device population. Device tags have a name and one or more values. Refer to Device tags.

When a device tag is created in the platform, it automatically becomes available as a rule expression attribute. You can then refer to the device tag in a rule expression and compare it to a value or values to determine management group membership.

For example, you can create a device tag named DomainRole with an initial value DatabaseServer.

Copy
add-1Edevicetag -name DomainRole -Value DatabaseServer

If you now use the Get-1ESLAManagementGroupRuleAttribute cmdlet to list all available attributes, you see a new attribute listed for the new coverage tag, called ReportDeviceTag.DomainRole. You can now refer to this tag in a rule expression.

Rule expression operators

Rule expressions support a set of operators defined in the table below. The UI operators column shows you the terminology that is used for these operators in the management group maintenance user interface.

However, internally rules are encoded and stored using the operators defined below.

Operator

Supported data types

Description

UI operators

LIKE

String

Matches a string pattern using the normal syntax. For example, LIKE %abc% matches any string that contains abc.

The UI operator Contains is equivalent to LIKE %string%.
The UI operator Begins With is equivalent to LIKE string%.
The UI operator Ends With is equivalent to LIKE %string.

Contains
Begins With
Ends With

NOT LIKE

String

Matches any string pattern that does NOT match the LIKE pattern. For example, NOT LIKE %abc% will match any string that does not contain abc.

The UI operator Not Contains is equivalent to NOT LIKE %string%.

Not Contains

IN

Coverage/Device Tag

Matches a value list that is contained within brackets (parentheses). For example, IN (abc,def) matches any string that equals abc or def.

Is One Of

NOT IN

Coverage/Device Tag

Matches any string that is outside the specified value list. For example, NOT IN (abc,def) matches any string that is not either abc or def.

Is Not One Of

>

Number, Date

Matches any string or integer value that collates to be greater than the entity being tested.

Greater than (number)

After (date)

<

Number, Date

Matches any string or integer value that collates to be less than the entity being tested.

Less than (number)

Before (date)

>=

Number

Matches any string or integer value that collates to be greater than or equal to the entity being tested.

Greater than or equal to

<=

Number

Matches any string or integer value that collates to be less than or equal to the entity being tested.

Less than or equal to

==

String, Date, Number, Yes/No

Matches any string or integer value that collates to be equal to the entity being tested.

Equal To

=

String, Date, Number, Yes/No

This is a convenience synonym for the == operator.

Equal To

!=

String, Date, Number

Matches any string or integer value that collates to be not equal to the entity being tested.

Not Equal To

IS NULL

String, Date, Number, Tag

Matches any entity that evaluates to NULL. Note that no comparison value is provided for this operator.

Is Null

IS NOT NULL

String, Date, Number, Tag

Matches any entity that evaluates to NOT NULL. Note that no comparison value is provided for this operator.

Is Not Null

Example rule expressions

Some simple examples are shown below. Note that expressions may use the AND and OR boolean operators to combine terms, and use brackets, or nested brackets, to determine operator precedence. You can combine multiple attributes in a rule expression, not just one, as in the simple examples.

Note that you cannot compare one attribute with another. All comparisons are to constant values, not other attributes.

Copy
ReportDevice.Fqdn = abc
 
ReportDevice.Fqdn is not null
        
ReportDevice.Fqdn like %abc% or ReportDevice.Fqdn like %def%
        
ReportDevice.Fqdn like %abc% or (ReportDevice.Fqdn like %def% and ReportDevice.Fqdn not like %pqr%)
        
ReportDevice.Fqdn in (abc,def,ghi)

Retrieving the JSON model for direct use with the Management Group APIs

The Management Group APIs do not directly accept rule expressions in human-readable format. They accept the rule expression as a JSON model, which is a representation of the expression. To obtain a JSON model for a particular expression, you can use the Get-1ESLAManagementGroupRule cmdlet as shown below.

Copy
Get-1ESLAManagementGroupRule -expression "ReportDevice.Fqdn like %abc% or (ReportDevice.Fqdn like %def% and ReportDevice.Fqdn in (abc,ghi))"

Currently, the expression parser is unified between scope and filter expressions and management group expressions. However, unlike the former two cases, management group expressions allow multiple operands to be associated with an operator at the top level, and the UI relies on this to show rule grouping. This means that an expression with more than two terms will create an expression tree that causes a rule to be created as two sub-groups. For example:

Copy
ReportDevice.Fqdn like %abc% or ReportDevice.Fqdn like %def% or ReportDevice.Fqdn like %ghi

To mitigate against this, currently, you can directly supply the JSON rule expression as a string when creating or updating management groups. This issue will be addressed in a future release of the 1E PowerShell Toolkit.

Notes on syntax differences between rule expressions and scope and filter expressions

The 1E PowerShell Toolkit expression parser is unified to accept either a rule expression, a scope expression, or a filter expression, and to produce an internal JSON model for consumption by the appropriate APIs. There are some small syntax differences between the API sets which you should be aware of. 
If you submit an expression containing one of these operators, the underlying API may reject it, depending on whether you are using the expression for scoping or filtering, or for defining a management group rule.

  • The scope and filter APIs do not accept IN, NOT IN, or NOT LIKE. However, for these APIs, you can express NOT LIKE %abc% as NOT(LIKE %abc%).
  • The Management Group APIs do not accept the NOT operator as a standalone operator, so that you cannot negate a term using NOT().