1E 23.11 (SaaS)

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.

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

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

{ "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" } ] } ] }

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

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.

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

-ResultFilter "Manufacturer=[Microsoft Corporation]"

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

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]

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.

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.

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

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.