Scope and filter expressions

This article explains how to use scope and filter expressions to target specific sets of devices and how to filter results to only include selected rows of data.

About scope and filter expressions

Scope expressions allow you to define a set of attributes that will define the target devices for an instruction. PowerShell cmdlets that work with device results take a -TargetScope parameter, which allows you to define the devices.

Filter expressions allow you to define a set of attributes by which the result set will be filtered. PowerShell cmdlets that work with device results take a -ResultFilter parameter, which allows you to define a filter expression by which results will be filtered before they are returned to you.

You can use both a scope and a filter expression together.

Using a pattern as a default target scope

The simplest target scope you can specify is simply to use a string such as XYZ. When you do this, the scope is translated to the following:

fqdn like %xyz%

As a result, all devices whose names contain the string xyz are targeted.

Scope and active devices

The 1E Platform and the 1E PowerShell Toolkit have different default mechanisms for determining when all devices have returned results for an instruction. However, you can specify that the Toolkit should behave in the same way as the platform when collating results. There are some important things to consider when dealing with scope. These are discussed below.

Scope in the 1E Platform

The 1E Platform deals with instruction results by accumulating results as they arrive from target devices. Results continue to be accumulated over the instruction time to live, which is typically 60 minutes.

This means that scope as defined for an instruction will always include any candidate devices that match the scope expression, whether or not those devices are online at the point of time where the instruction is invoked. This is designed to ensure that during the instruction lifetime, any devices that come online and fall within scope will automatically receive and execute the instruction and add their results to the collected results from all candidate devices. At the end of the instruction collection lifetime, the percentage of responding devices will be indicated.

Scope in the 1E PowerShell Toolkit

PowerShell consumers typically want to view instructions and their results as batch operations. It would not be desirable to wait for 60 minutes before the results are returned if all online devices had responded already.

In other words, when invoking instructions via PowerShell, the user wants to consider the instruction execution as a synchronous process, with the cmdlet returning to the user when all devices have responded. Consequently, when an instruction is invoked via the 1E PowerShell Toolkit with a specified target scope, this scope is amended to include only active devices (by appending a term and status=1), and then the responding device set is used to send a targeted instruction to only the responding devices. This means that devices that are not online when the instruction is launched are not included in the scope. This prevents the invoke-1Einstruction cmdlet from spending a long time trying to retrieve results from devices that are not able to respond. The tradeoff is that devices that are not currently online are not included in the target scope of the instruction.

If you re-run the instruction, the scope is re-evaluated each time. If you are using the targeted rollout feature (refer to Staged rollouts), then devices that come online at any time in the staged rollout will be included.

In rare circumstances, a device that was online when the scope was evaluated may go offline after the instruction was invoked but before its results could be collected. In this scenario, the invoke-1Einstruction cmdlet will loop, waiting for the device to respond until the instruction time to live is reached. You can interrupt execution at any time by pressing ctrl+C, and choose to just retrieve results from instruction history in this rare scenario. However, you can specify that the Toolkit should evaluate scope in the same way as the 1E Platform does. You do this by specifying the -DynamicScope parameter when invoking an instruction. For more information on this parameter, refer to Instruction execution management cmdlets.

Filter expressions

Filter expressions work like scope expressions; however, a scope expression only allows a fixed set of attributes to be specified, such as fqdn, ostype, and so on. These are defined in a table further below. Refer to Scope attributes.

Filter expressions allow any attribute to be specified. The attribute should correspond to a result value that is returned. For example, the 1E Platform instruction How much memory is installed?, whose name is 1E-Explorer-TachyonCore-GetCurrentInstalledMemoryDetails, returns a column called DIMM_COUNT, which represents the number of installed DIMM memory modules. To filter the results from this instruction so that only devices with a single installed DIMM module are returned, you can specify -ResultFilter "DIMM_COUNT=1".

More complex scope and filter expressions

You can specify a more complex expression to the -TargetScope or -ResultFilter parameters. When doing so, remember to place it in quotes if you are passing it on the command line as otherwise, the PowerShell command line processor will change it.

For example, the following will target all devices whose fqdn begins with abc or def:

-TargetScope "fqdn like abc% or fqdn like def%"

Scope expressions can refer to other scope attributes. Refer to Scope attributes. You compare scope attributes to values using one of the operators listed below.

Scope and filter expression term operators

You can use any of the following operators to compare a scope or filter entity with a value:

• LIKE
• >
• <
• >=
• <=
• !=
• =

Scope and filter expression booleans

A scope or filter expression can use AND, OR, and NOT, as well as brackets (parentheses) to specify complex expressions.

For example, the following will target all devices whose fqdn begins with abc and that are running either Windows or Linux, but where the OS version is not 12:

-TargetScope "fqdn like abc% and (ostype=windows or ostype=linux) and not(osver=12)"

Specifying an attribute or value with embedded spaces

To specify an attribute or value that contains embedded spaces, surround it with square brackets. For example:

-ResultFilter "Manufacturer=[Microsoft Corporation]"

Scope attributes

The table below lists all the scope attributes that are available for use in a scope expression.

Specifying device tags and values in scope expressions

Device tags are special entities that have a name and one or more values associated with them. You define tags using the Settings > Custom properties page in the 1E Platform. You can then associate these tags and values with one or more devices so that later on, you can specify the tags and values in a scope expression to target specific devices. To understand more about this process, refer to Tagging client devices and Tags in the SCALE User Guide.

You can define a tag and its associated value as part of a scope expression. To do this, you specify the expression term as follows:

tagtxt=[tagname=tagvalue]

For example, if you have a custom property called MyProp and it has the value MyVal, you can specify this tag and value in your scope expression the following way:

tagtxt=[MyProp=MyVal]

Note the following:

• Tag names are not case-sensitive, but tag values are. For example, you would receive an error if you specified the following because the property value is case-sensitive and no value called myval has been defined for this tag:

  Copy

  tagtxt=[MyProp=myval]

• Spaces are not allowed around the = in the [tagname=tagvalue] portion of the expression term. This is because the API will not accept them if they are provided.

• You can only check tag values for equality. Even if you specify a different operator (such as like), for example, tagtxt like [myprop=MyVal], the check will still be the same. This is because the actual operator you specify is required by the 1E Platform to be removed from the platform scope before being submitted.

To learn more, refer to Device tags.

Specifying management groups in scope expressions

The managementgroup scope attribute requires you to use the management group Id you want to test against, not the management group name. To retrieve the appropriate Id, use the Get-1EManagementgroup cmdlet. Refer to Management Group cmdlets.

For example, you have a management group named MG1 and the get-1EManagementGroup cmdlet has returned a UseableId of 2 for that management group. You can now specify the following in your scope expression to refer to this management group:

managementgroup=2

To learn more, refer to Working with management groups.

Specifying location in scope expressions

The location attribute of a device is an arbitrary special tag that is set by running an instruction that defines a value for a set of devices. Refer to Using Location. You can then specify location in a scope expression based on the arbitrary tag values that have been set, for example:

location=Ealing

Scope or filter expression errors

A scope expression that specifies an unsupported attribute will cause an error to be thrown by the called platform API. This will generally indicate that the scope is invalid.

A filter expression can reference any attribute, but if the result set doesn't contain a column that matches the attribute, no results are returned.

A scope or filter expression that is invalid because the brackets don't match will throw an exception indicating a bracket (parenthesis) mismatch before the platform APIs are even called.

Other malformed scope or filter expressions may currently cause an error to be thrown inside the expression parser. If this occurs, verify that the scope or filter expression you have specified is valid.

Retrieving the internal platform scope or filter expression from a scope or filter expression

When the platform APIs are called, they accept a scope or filter member as a piece of JSON. The format of this JSON is intended to be able to be processed efficiently, so it is not as human-readable as a scope expression that you supply to the -TargetScope or -ResultFilter parameter.

Although intended primarily for test purposes, the get-1Escope cmdlet allows you to retrieve the platform scope JSON from a scope expression. This could be useful if you intended to call the APIs directly and wanted to construct a scope expression to use with them. For example:

get-1Escope -Targetscope "(ostype=windows or ostype=linux) and not(fqdn like abc%)"

{ "Operator":"AND", "Operands":[ { "Operator":"NOT", "Operands":[ { "Attribute":"fqdn", "Operator":"like", "Value":"abc%" } ] } ,{ "Operator":"OR", "Operands":[ { "Attribute":"ostype", "Operator":"==", "Value":"linux" } ,{ "Attribute":"ostype", "Operator":"==", "Value":"windows" } ] } ] }

The get-1Efilter cmdlet allows you to return the internal platform filter expression from a filter expression. For example:

get-1Efilter -ResultFilter "DIMM_COUNT=1"

To learn more about platform scope and filter expressions, refer to Using scope and filter expressions.