Skip to main content

1E 23.11 (SaaS)

Using scope and filter expressions with the Tachyon PowerShell Toolkit

How to use scope and filter expressions to target specific sets of devices and/or 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 which will define the target devices for an instruction. Powershell cmdlets which 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 which 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 or filter expression together if desired

Note

The dynamic execution cmdlets do not currently support filter expressions, though they do support scope expressions.

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

fqdn like %xyz%

As a result, all devices whose names contain the string 'xyz' are targetted

Note

Reminder: you can use the get-tachyonrespondingdevice cmdlet to find out which devices would be the effective targets of a scope

You can also use the standard Powershell -Whatif switch to return the estimated devices for an instruction targetted by a scope.

Scope and active devices

The Tachyon Explorer and the PowerShell toolkit have different default mechanisms for determining when all devices have returned results for an instruction. You can, however, specify that the PowerShell toolkit should behave in the same way as the Explorer when collating results. There are some important things to consider when dealing with scope, which are discussed below.

How the Tachyon Explorer uses scope

The Tachyon Explorer 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 which 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 Tachyon Explorer will indicate the percentage of responding devices.

How the PowerShell Toolkit uses scope

Unlike users of the Explorer UI, 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 in fact 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 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 targetted instruction to only the responding devices.

This means that devices which are not online when the instruction is launched are not included in the scope. This prevents the invoke-instruction cmdlet from spending a long time trying to retrieve results from devices which are not able to respond. The tradeoff is that devices which are not currently online are not included in the target scope of the instruction.

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

In rare circumstances a device which 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-instruction 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.

You can, however, specify that the PowerShell toolkit should evaluate scope in the same way as the Tachyon Explorer does. You do this by specifying the -DynamicScope parameter when invoking an instruction. For more information on this parameter, see the invoke-tachyoninstruction cmdlet documentation here

Instruction execution management cmdlets

Using a filter expression

Filter expressions work like scope expressions. However a scope expression only allows a fixed set of attributes to be specified, such as fqdn, ostype etc. These are defined in the table 'scope attributes' later on this page.

Filter expressions allow any attribute to be specified. The attribute should correspond to a result value that is returned. For example, the Tachyon instruction 'how is memory configured', 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"

Note

This is an aggregating instruction. If you run it with the -Drilldown parameter, so as to return detailed results, the result set is different and does not contain a DIMM_COUNT member. Consequently if you filter by DIMM_COUNT but then request detailed results, you receive no rows because the filter condition is not met.

You can still filter the detailed rows of course. For example, the detailed rows for the above instruction return a column called Memory_in_MB. You can therefore filter for this column with

-ResultFilter "Memory_in_MB=3968"

and then only detailed results which match this filter are returned.

Scope and filter expressions in depth

The sections below discuss search and filter expressions in more depth.

Scope and filter expression term operators

You can use any of the operators in the table below to compare a scope or filter entity with a value

Operator

LIKE

>

<

>=

<=

!=

=

Note

The LIKE operator is not currently valid with the AgentVer or OSVer scope attributes. This is an API limitation that may be resolved in a future Tachyon release

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

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

This will target all devices whose fqdn begins with abc and which are running either windows or linux but where the os version is not 12.

Note

When using NOT, ensure you surround the expression you wish to negate in brackets (parentheses). Otherwise brackets allow you to group and define precedence for parts of your expression.

If you do not group portions of the expression, then the AND operator has higher precedence than OR. That is

X AND Y OR Z is equivalent to (X AND Y) OR Z

To specify NOT LIKE, you should also use NOT with brackets i.e NOT(LIKE '%XYZ%')

Specifying an attribute or value with embedded spaces

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

-ResultFilter "Manufacturer=[Microsoft Corporation]"

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 'Custom properties' page in the Tachyon Settings app.

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, see Tachyon Explorer 8.1 - Tagging client devices, or Tags page in the SCALE section.

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, suppose you have a custom property called MyProp and it has a value MyVal. You can then specify this tag and value in your scope expression as:

tagtxt=[MyProp=MyVal]

Note

Tag names are not case-sensitive but tag values are. For example, if you specified:

tagtxt=[myprop=MyVal]

you would be querying the same property name and would not receive an error. However, if you specified:

tagtxt=[MyProp=myval]

you would receive an error because the property value is case-sensitive and no value 'myval' has been defined for that tag.

Also note that 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) as in "tagtxt like [myprop=MyVal]" the check will still be the same. This is because the actual operator you specify is required by Tachyon to be removed from the Tachyon scope before being submitted.

Note

Device tags were previously known as coverage tags. Consequently, the cmdlets refer to coverage tags.

A device tag scenario in depth

Using device tags with the Tachyon PowerShell Toolkit explores how you can use device tags with the PowerShell Toolkit in more depth.

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-TachyonManagementgroup cmdlet which is documented here Instruction management cmdlets.

Note

The API returns both an Id and a UseableId. It is the UseableId you must use in the example below, not the Id:

Example: You have a management group named 'MG1' and the get-TachyonManagementGroup cmdlet has returned an UseableId of 2 for that management group. You can now specify:

managementgroup=2

in your scope expression to refer to this management group.

A management group scenario in depth

Working with management groups and the Tachyon PowerShell Toolkit explores management groups and the Powershell Toolkit in more depth.

Specifying location in scope expressions

The location attribute of a device is an arbitrary special tag which is set by running an instruction that defines a value for a set of devices.

For more information on setting this tag see Tachyon Explorer 8.1 - 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 Tachyon 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 Tachyon 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 Tachyon scope or filter expression from a scope or filter expression

When the Tachyon 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-Tachyonscope cmdlet allows you to retrieve the Tachyon 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.

Example

get-Tachyonscope -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-Tachyonfilter cmdlet allows you to return the tachyon filter expression from a filter expression, for example:

get-Tachyonfilter -ResultFilter "DIMM_COUNT=1"

Note

Both these cmdlets do exactly the same thing. They are provided for your convenience since you will be used to the appropriate parameter names for scope and filter expressions, but they process their input arguments in exactly the same way.

These cmdlets do not validate their input, e.g, get-tachyonscope does not mandate that the attributes entered correspond to valid scope attributes.

For more about Tachyon scope and filter expressions, please refer to Using scope and filter expressions.

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

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

This will target all devices whose fqdn begins with abc or def.

Note

If you do not specify TargetScope on the command line and PowerShell prompts you for it, you do not need the quotes - and in fact, you should omit them or you will currently receive an error.

Scope expressions can refer to other scope attributes, as listed in the table below. You compare scope attributes to values using one of the operators shown in the table below

Scope and filter expression term operators

You can use any of the operators in the table below to compare a scope or filter entity with a value

Operator

LIKE

>

<

>=

<=

!=

=

Note

The LIKE operator is not currently valid with the AgentVer or OSVer scope attributes. This is an API limitation that may be resolved in a future Tachyon release

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

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

This will target all devices whose fqdn begins with abc and which are running either windows or linux but where the os version is not 12.

Note

When using NOT, ensure you surround the expression you wish to negate in brackets (parentheses). Otherwise brackets allow you to group and define precedence for parts of your expression.

If you do not group portions of the expression, then the AND operator has higher precedence than OR. That is

X AND Y OR Z is equivalent to (X AND Y) OR Z

To specify NOT LIKE, you should also use NOT with brackets i.e NOT(LIKE '%XYZ%')

Specifying an attribute or value with embedded spaces

To specify an attribute or value which 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.

Attribute name

Description

ostype

The operating system type. Can be Linux, MacOS or Windows

osver

The OS version e.g. 10.0.18363.1016

name

The NETBIOS name of the device

rammb

The amount of RAM in megabytes e.g. 4095

osvertxt

String description of the OS e.g. "Windows 10 Enterprise 1909"

agentver

The agent version e.g. 5.0.0.574

vrplatform

Name of virtualisation platform (if any) e.g. Hyper-V

model

The device model name as reported by the BIOS. On a virtualised platform this is "Virtual Machine"

chassistype

The device chassis type. DMTF defines the standard, the latest list was defined in 2017 - https://docs.microsoft.com/en-gb/archive/blogs/brandonlinton/updated-win32_systemenclosure-chassis-types.

Note - the chassistype value of 3 is defined as 'desktop' but also includes virtual machines.

fqdn

The device FQDN e.g. mydomain.mydevice.local etc

devtype

"Server", "Desktop", "Laptop" or "Mobile". Some devices may report "Unknown"

timezone

The device's current timezone offset from UTC in minutes (positive or negative).

lastboot

The last boot time expressed as a standard ISO8601 datetime string

tagtxt

Specifies a specific tag and its associated value. See the notes below on tags

managementgroup

The specified management group. Note that you do not refer to management groups by name, but by Id

See the note below on management groups

criticality

The criticality value (as a number) of the device. For more information on device criticality see Tachyon Explorer 8.1 - Using Device Criticality.

domain

The domain name (NETBIOS) of the device, if it is domain-joined

location

The location which the device has been tagged with. See the discussion on location below

status

Device status. A value of 1 indicates that the device is online, 0 = offline

Note

Status is not a valid scope attribute when submitting an instruction.

It is, however, accepted when querying affected devices through get-tachyonrespondingdevice.

This appears to be a current inconsistency in the Tachyon API set and may be resolved in a future Tachyon release.

You can, however, still use status in the -targetscope parameter to the PowerShell cmdlets because internally the Toolkit will use the 'affected devices' API to create a target list and then submit the instruction to that target list of FQDNs. Therefore scope attributes are not used by the Toolkit when invoking instructions via the actual instruction invocation APIs.

user

Valid for Tachyon v5 onward. The primary user associated with the device (if any). The devices page in the Tachyon Explorer will show this user. e.g. urth\administrator

oslocale

Valid for Tachyon v5.2 onward. The locale associated with the OS installation (e.g. 'en_gb')

osinstallutc

Valid for Tachyon v5.2 onward. The UTC datetime on which the OS was installed. This is an ISO8601 datetime e.g 2020-02-05T21:35:44.000.

To match just the date portion you could use a scope expression such as 'osinstallutc>=2020-02-05 and osinstallutc<2020-02-06' which will match any install datetime whose date portion is 5th Feb 2020

priconntype

Valid for Tachyon v8 onward. The primary connection type associated with the device. Valid values are

  • "Ethernet"

  • "Wireless LAN"

  • "Tunnel"

  • "VPN"

  • "IEEE 1394 Firewire"

  • "Token Ring"

defaultgw

Valid for Tachyon v8 onward. The default gateway IP address associated with the primary network adaptor on the device. For example, 10.10.10.250

pridnsserv

Valid for Tachyon v8 onward. The IP address of the DNS server associated with the primary network adaptor. For example 10.10.10.100

dhcpserver

Valid for Tachyon v8 onward. The IP address of the DHCP server associated with the primary network adaptor. Devices that are allocated static IP addresses will not have a value for this attribute

leaseexpiry

Valid for Tachyon v8 onward. The expiry date for the current DHCP lease associated with the primary network adaptor as an ISO8601 datetime. If there is no expiry date, then a value of 1970-01-01T00:00:00.000 is stored for that device.

ipaddr

Valid for Tachyon v8 onward. The IP address of the primary network adaptor

macaddr

Valid for Tachyon v8 onward. The MAC address of the primary network adaptor e.g. "00-15-5d-0b-b5-0b"

Note

Attributes that are noted as having a Tachyon version prerequisite will only be returned for devices on which the 1E Client version is equal to or greater than the prerequisite version. Older client releases will not return these attributes.

A device which is upgraded to a newer version of the 1E Client will populate any missing attributes when it is upgraded.

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 'Custom properties' page in the Tachyon Settings app.

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, see Tachyon Explorer 8.1 - Tagging client devices, or Tags page in the SCALE section.

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, suppose you have a custom property called MyProp and it has a value MyVal. You can then specify this tag and value in your scope expression as:

tagtxt=[MyProp=MyVal]

Note

Tag names are not case-sensitive but tag values are. For example, if you specified:

tagtxt=[myprop=MyVal]

you would be querying the same property name and would not receive an error. However, if you specified:

tagtxt=[MyProp=myval]

you would receive an error because the property value is case-sensitive and no value 'myval' has been defined for that tag.

Also note that 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) as in "tagtxt like [myprop=MyVal]" the check will still be the same. This is because the actual operator you specify is required by Tachyon to be removed from the Tachyon scope before being submitted.

Note

Device tags were previously known as coverage tags. Consequently, the cmdlets refer to coverage tags.

A device tag scenario in depth

Using device tags with the Tachyon PowerShell Toolkit explores how you can use device tags with the PowerShell Toolkit in more depth.

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-TachyonManagementgroup cmdlet which is documented here Instruction management cmdlets.

Note

The API returns both an Id and a UseableId. It is the UseableId you must use in the example below, not the Id:

Example: You have a management group named 'MG1' and the get-TachyonManagementGroup cmdlet has returned an UseableId of 2 for that management group. You can now specify:

managementgroup=2

in your scope expression to refer to this management group.

A management group scenario in depth

Working with management groups and the Tachyon PowerShell Toolkit explores management groups and the Powershell Toolkit in more depth.

Specifying location in scope expressions

The location attribute of a device is an arbitrary special tag which is set by running an instruction that defines a value for a set of devices.

For more information on setting this tag see Tachyon Explorer 8.1 - 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 Tachyon 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 Tachyon 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 Tachyon scope or filter expression from a scope or filter expression

When the Tachyon 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-Tachyonscope cmdlet allows you to retrieve the Tachyon 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.

Example

get-Tachyonscope -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-Tachyonfilter cmdlet allows you to return the tachyon filter expression from a filter expression, for example:

get-Tachyonfilter -ResultFilter "DIMM_COUNT=1"

Note

Both these cmdlets do exactly the same thing. They are provided for your convenience since you will be used to the appropriate parameter names for scope and filter expressions, but they process their input arguments in exactly the same way.

These cmdlets do not validate their input, e.g, get-tachyonscope does not mandate that the attributes entered correspond to valid scope attributes.

For more about Tachyon scope and filter expressions, please refer to Using scope and filter expressions.