Instruction execution management cmdlets
The instruction execution management cmdlets allow you to invoke instructions, retrieve the estimated target count for an instruction and perform other tasks associated with the execution of instructions in Tachyon.
Get-TachyonRespondingDeviceCount -TargetScope <device pattern>
Returns the count of devices that match a device pattern, e.g URTH will match all devices whose FQDN contains URTH. This indicates the count of devices which would be associated with an instruction targetted at this device pattern
Note
Devices may come online or drop offline during the staging and execution of an instruction. Therefore this count is not necessarily exact. When an instruction is executed using the Tachyon PowerShell package, an initial count is retrieved. When the count of responding devices matches this initial count, the instruction is deemed to have completed execution and the results are returned.
However the instruction will currently remain active until its time to live expires. During that time, any devices which come online and match the pattern may receive and execute the instruction. Results from that device will not be returned to the PowerShell caller because the cmdlet has already terminated. However they are visible on the Tachyon Explorer UI.
To specify a fixed snapshot of target devices when invoking an instruction (see below), you should use the -TargetFqdns option instead. This requires a specific list of devices, so the target set is fixed at the time the instruction commences execution. Note that an device which is not online during the execution of the instruction would still not supply data in that scenario.
Invoke-TachyonInstruction <instruction>...
-TargetScope <device pattern>|-TargetFqdns <array of FQDNs>
[-PromptDefaults]
[-Drilldown]
[-Whatif]
[-InstTTL <mins>]
[-ResultsTTL <mins>]
[-Raw <file>] | -Csv <file>
[TargetCount <count>]|[TargetPercent <percent>]
[-TargetFile <file>] [instruction-specific parameters]
[-NoWait]
[-InformationAction <continue|silentlycontinue>]
[-ResultFilter <filterexpression>]
[-DynamicScope]
[-Offload]
Invokes the specified instruction, targetting the devices whose FQDN matches the supplied device pattern and returns the result
The -TargetScope option, if specified, determines the devices to which the selected instruction will be sent.
The -DynamicScope option affects how the -TargetScope parameter is used. It is not valid if the -TargetFqdns parameter is specified. When you set this option, you change the way that target devices are calculated and the associated instruction invocation API which is used to invoke the instruction. For more information see the section below on 'Targeted and Dynamic Scope'
As a mutually exclusive argument option, you can specify an array of device FQDNS using the -TargetFqdns parameter instead. This will target the devices associated with the fqdns
The use of -TargetScope and -TargetFqdns is discussed in more detail in the section below "Scope patterns and target FQDN lists"
The -PromptDefaults option, if specified, causes any instruction parameters with defaults to be prompted for, unless a non-default value has been entered for the parameter on the command line. See the discussion on Instruction Parameters below for more detail
The -Drilldown option, if specified, causes detail rows to be returned for an aggregating instruction. For non-aggregating instructions this option is ignored
The -Whatif option, if specified, causes the specific devices which would be the targets for the instruction to be returned. The instruction is not executed.
The -InstTTL and -ResultsTTL parameters allow you to override the instruction default time to live and results time to live values. Note that the default minimum values for these are 10 minutes and attempting to specify smaller values will cause an error to be thrown. It is possible to reconfigure the Tachyon server to allow smaller values but this requires a change to global settings and also a per-instruction database update. If these overrides are not applied, then the values for these TTL parameters are as specified when the instruction was uploaded to Tachyon.
The -Raw option specifies that results are to be written as returned JSON directly to the specified file. Raw option is discussed in more detail below
The -Csv file option specifies that results are to be written to a CSV file. The first row of the file will contain the headers. The -Raw and -Csv options are mutually exclusive
The -TargetCount, -TargetPercent and -TargetFile options are intended for use with staged rollouts. Staged rollouts are described in more detail in Staged rollouts using the Tachyon PowerShell Toolkit.
If -NoWait is specified , then if the instruction is an action, once it has been queued for approval, the cmdlet returns with the instruction Id rather than waiting until the results are available. If the instruction is a question then once it has been submitted the cmdlet returns immediately with the instruction Id.
Note
You can use the get-tachyoninstructionresult cmdlet to retrieve instruction results from history subsequently, using the returned Id in this scenario.
The -InformationAction parameter is a standard PowerShell option. If the 'continue' value is set, then the cmdlet will display informational messages about the progress of an instruction during the execution of the instruction.
Note
This is used in preference to the -Verbose parameter because -Verbose causes the internal HTTP requests to also report information and the resulting clutter is hard to decipher.
The -ResultFilter parameter allows you to specify an optional results filter. Only results that match the filter will be returned. You can find out more about result filters here Using scope and filter expressions with the Tachyon PowerShell Toolkit.
Additional command-line parameters correspond to instruction-specific parameters and will be passed to the instruction.
The -Offload parameter allows you to send instruction resul ts to a Tachyon consumer which has been appropriately configured to pass these on to a service which can accept offloaded results. When you do this, results are not stored in the Tachyon responses database.
For more information on the use of this option, please refer to Offloading data to an external target.
Instruction Parameters
Tachyon instruction parameters generally map exactly to their PowerShell equivalents. For example, a Tachyon instruction parameter of 'IPAddress' would map to the PowerShell parameter -IPAddress. However, Tachyon allows embedded spaces in parameter names and PowerShell does not. Accordingly, if a Tachyon instruction exposes a parameter with embedded spaces, these are automatically translated to and from underscores (_). For example, if the Tachyon instruction exposes a parameter called 'Foo Factor' then you would supply it via PowerShell as -Foo_Factor. When the parameter is passed down to the Tachyon instruction, it is remapped back to "Foo Factor".
Tachyon instruction parameters are defined as PowerShell dynamic parameters. This means that if you fail to provide a parameter, you are prompted for it automatically, unless it has a default value defined for the Tachyon instruction.
If a parameter has a defined default value in the Tachyon instruction, you can override this by specifying the -PromptDefaults parameter to invoke-instruction. Then you will receive a prompt both for non-default and default parameters.
Raw mode
Normally when an instruction is invoked, the results are returned as a PowerShell hash table (or dictionary).
For normal non-aggregating instructions each set of results are created as an array of objects associated with a dictionary entry keyed by the device FQDN. Therefore, a result set from 10 FQDNs comprises a dictionary of 10 entries,
Each dictionary entry then contains an array of results, stored as objects. The properties of each object correspond to the schema of the Tachyon instruction. For example, if an instruction returned a string and two integers, the object array instances associated with the dictionary entry will each have three properties corresponding to these schema members.
However for large result sets PowerShell can take a long time to re-serialise the JSON results returned from Tachyon and it can also consume a large amount of memory in so doing.
Note
Note that PowerShell Core, which is fully supported by the PowerShell Integration Toolkit, is considerably faster than legacy PowerShell. If you are routinely retrieving large amounts of data via Tachyon, you should consider using PowerShell Core instead of legacy PowerShell. Note that this does not affect the PowerShell requirements on Tachyon devices as all the integration toolkit code is running on the machine you are working from.
In some cases therefore it may be better to specify raw mode. When this is done, the JSON results from Tachyon are not deserialised but instead written directly to the specified output file during processing.
This can be much quicker and consume much less memory. You can convert the contents of the resulting file back to a dictionary by using the convertfrom-raw cmdlet, discussed below
Because the text file is stored as plain JSON, you can also use PowerShell to search for strings and values without going to the expense of serialising the JSON back to PowerShell objects. If you are looking for specific information in a large result set this could be far quicker and easier than trying to locate the information via PowerShell's object selection pipeline.
Return data in raw mode
When an instruction is invoked in raw mode, the return result from invoke-instruction is the instruction statistics information. This is the same information that would be returned by get-statistics, as applicable when the instruction results have all been processed. You can use the results from statistics to quickly see which devices processed the instruction and which failed due to an error.
Targeted (static) and Dynamic Scope
Normally the invoke-tachyoninstruction uses static scoping to target devices. This functions as follows:-
The -TargetScope expression is surrounded by parentheses and then an extra term "status=1" is added to the scope expression. This ensures only currently online devices are regarded as in scope.
The devices which would then be valid for that scope are computed by calling the appropriate API
The instruction is then sent to that device list using the Tachyon targeted instruction invocation API
This behaviour is normally what a user would expect. If a new device appears during instruction execution, it is not considered to be part of the initially computed target scope and will not receive the instruction. However, in the case of duplicate FQDNs, this behaviour ensures that devices which are not active but which share an FQDN with an active device are not considered to be potential instruction targets. If they were, the cmdlet might take a long time to return results because the instruction statistics estimate of target devices will always exceed the number of responding devices. Eventually the cmdlet will time out or the instruction time to live will be reached, of course, and results will be returned at that point.
Using Dynamic Scoping
If, however, you want to emulate the behaviour of the Tachyon Explorer UI when you invoke an instruction, you can specify the optional -DynamicScope parameter
If you do this, then the instruction targets are computed as follows
The -TargetScope expression is directly fed to the Tachyon standard instruction invocation API without modification in any way. Tachyon will now handle the evaluation of the device target list during instruction execution.
This means that any devices which become active during the instruction execution lifetime will be included as targets. However results from these devices will *not* necessarily be returned when the invoke-tachyoninstruction cmdlet terminates with results. This is because it requests an initial estimate of receiving device count from the Tachyon statistics API and this will not include devices that are not currently online. The cmdlet will return results when the responding device count equals the estimated sent count. Obviously a device which responds after this point will not have its results immediately included. Conversely, a device which comes into scope early enough might cause results from another device to be excluded, as either way the sent count will equal the received count at some point, and the cmdlet will then return the results.
With dynamic scoping there is no concept of 'all devices responded' since we have no way of knowing which devices might connect during instruction execution.
The Tachyon Explorer UI updates results continuously to its UI, so a new device responding five minutes after all other devices have responded will update the results. You can emulate this behaviour with the PowerShell toolkit by using the -DynamicScope parameter in conjunction with the -NoWait parameter. You can then subsequently poll Tachyon for the cumulative instruction results by using the Get-TachyonInstructionResult cmdlet, passing the instruction Id returned when invoke-tachyoninstruction is called with -NoWait.
Note
For both static and dynamic scopes, a device which goes offline during instruction execution but before results are collected could also cause the invoke-tachyoninstruction cmdlet to take a long time to return results. This is because the original estimated device count will always exceed the received device count in that scenario.
However note that Tachyon itself will always collect as much data as it can from the targeted devices. If you use the get-tachyoninstructionresult cmdlet to retrieve results, you will always get a result set equivalent to what you would have seen in the Tachyon Explorer at that point in time.
You could, therefore, issue an instruction with dynamic scoping enabled and the -Nowait parameter. Control will return to your script immediately. You can then choose to wait until the instruction time to live (ttl) has expired and then use the get-tachyoninstructionresult cmdlet to get the result set from history.
This emulates the behaviour you would see in the Tachyon Explorer UI.
ConvertFrom-TachyonRaw -File <file>
The ConvertFrom-Raw cmdlet takes the output of an instruction that was stored in raw mode and serialises it to create a dictionary, similar to the results that would have been obtained had the command been run in normal mode.
Note
This process can take some time and consume significant amounts of memory for large output files. A future enhancement to this cmdlet will allow pattern matching on the raw JSON string so that only a subset of data is converted.
Search-TachyonInstruction [-TargetScope <device pattern>|-TargetFqdns <array of FQDNs>] [-PromptDefaults] [-Drilldown] [-CreateCmdlet]
Opens an interactive search where you can type in text which is matched in realtime to Tachyon instructions, similar to the operation of the Tachyon Explorer UI.
The -TargetScope option, if specified, determines the devices to which the selected instruction will be sent.
As a mutually exclusive argument option, you can specify an array of device FQDNS using the -TargetFqdns parameter instead. This will target the devices associated with the fqdns
Note
If neither TargetScope nor TargetFqdns are specified when this cmdlet is run, then you will be prompted for a target scope when you select the instruction to execute.
You cannot run this cmdlet from the PowerShell ISE (as opposed to a standard PowerShell session) because it uses single character keyboard input functionality not provided by the ISE
The -PromptDefaults option, if specified, causes any instruction parameters with defaults to be prompted for, unless a non-default value has been entered for the parameter on the command line. If not specified, then any instruction parameters with defaults will have these defaults used automatically.
The -Drilldown option, if specified, causes detail rows to be returned for an aggregating instruction. For non-aggregating instructions this option is ignored
The -CreateCmdlet option, if specified, creates a cmdlet from the selected instruction rather than executing it. If this option is specified, then the -TargetScope, -TargetFqdns, -PromptDefaults and -Drilldown options are ignored
For more information on cmdlet creation see the new-cmdlet cmdlet, which is discussed below
Restart-TachyonInstruction -Id <Id> [-Drilldown] [-ResultFilter <filter>]
Reruns the specified instruction and returns the results. The original instruction target scope or fqdn list is used to determine the devices to which the instruction is sent. You can optionally specify whether to drilldown aggregated results and/or apply a result filter to the results.
Note
You cannot rerun an action, only a question. Attempting to rerun an action will cause an error to be thrown
Get-TachyonInstructionStatistics -Id <id>
Returns execution statistics for an instruction. Execution statistics include the number of devices to which the instruction was sent, the count of devices from which responses were received, and counts of devices which reported error or 'not implemented' return codes. This is a useful cmdlet when chaining instructions, as you can use it to determine that an instruction has been successful across the target estate.
Get-TachyonTargetFileInstructionStatus -TargetFile <targetfile>
Returns the status for each instruction that is contained in the specified target file. Target files are created when staged rollouts use the -TargetFile option when invoking instructions with Invoke-Instruction. For more information on staged rollouts, see Staged rollouts using the Tachyon PowerShell Toolkit.
Get-TachyonLastInstructionState [-Full]
If an instruction has already been executed in this PowerShell session, returns the state of that instruction. The -Full option returns the entire results from the instruction statistics API. If omitted, a summary is returned as shown below
 |
The 'Successful' property is derived as follows.
If the EstimatedCount - SentCount = 0 and the ErrorCount is 0, then successful is true. Otherwise it is false, because either one or more devices did not respond or one or more devices reported some type of error.
If no instruction has been executed in this session, then this cmdlet will throw an exception
Get-TachyonLastInstructionId
Returns the Id of the most recently executed instruction (if any). If no instruction has executed yet in this session, returns 0.
Get-TachyonDeviceList -TargetFqdns <fqdn list> [-Inactive]
Given a list of FQDNs as an array, returns a fresh array which includes only the devices in the list which are currently online. If the -Inactive flag is specified, returns an array which includes only the devices on the list which are currently offline.
If any FQDN does not correspond to a valid device recognised by Tachyon, an error is thrown.
This cmdlet is useful if you want to use the -TargetFqdns parameter when invoking an instruction, because by default, all devices in the list you provide are targeted, even if they are not currently online. This may cause instruction execution to take a long time, as the cmdlet will wait for the offline device(s) to come online and respond
See the section 'Scope patterns and target FQDN lists' below.
To use this cmdlet with the invoke-tachyoninstruction cmdlet or other cmdlets that accept the -TargetFqdns property, either assign the result of running this cmdlet to a variable and then pass the variable to the -TargetFqdns parameter for the cmdlet you wish to use subsequently, or directly embed the cmdlet results like this
invoke-tachyoninstruction <instruction> -TargetFqdns (Get-TachyonDeviceList -TargetFqdns <list of devices>)
This will filter down the list you provide and return only a list of currently online devices to the invoke-tachyoninstruction cmdlet
Scope patterns and target FQDN lists
Anywhere where the -TargetScope parameter is accepted, a mutually exclusive -TargetFqdns parameter can be specified instead. This parameter takes an array of FQDNs and these become the target(s) of the instruction.
For example, specifying -TargetFqdns @("urth-dev.urth.local","urth-sql.urth.local") will target two devices as specified.
Regardless of whether you specify the -TargetFqdns parameter or the -TargetScope parameter, internally a set of FQDNs is always used to target devices by default.
These are sent to a special 'targeted' variant of the Tachyon APIs. The set of responding devices is fixed by the FQDNs specified, so that, had -TargetScope been specified, any device that comes online during instruction execution and would match the specified scope, will be excluded because it was not in the original static computed list.
Note
This behaviour is to avoid scenarios where inactive devices with duplicate FQDNs are returned as potential matches to a specified -TargetScope argument. As discussed below, the computed target FQDN list is pruned to remove any devices known to be inactive before being submitted to the Tachyon instruction APIs. If this were not done, then duplicate inactive devices would be considered as potential targets and the result would be that the instruction would never appear to return data from all devices, causing ultimately a timeout.
You can override this default behaviour by specifying dynamic scoping if you wish. This is discussed in the section above 'Targeted (static) and dynamic scope'. Dynamic scoping emulates the behaviour of the Tachyon Explorer UI, but the tradeoff is that you may wait a long while before an instruction returns results if you have duplicate FQDNs in your scope.
The target fqdn list has been tested up to approximately 140,000 entries. This is well within Tachyon's capabilities to handle. However just above this point PowerShell will stop marshalling the array down to the cmdlets, so this is a practical upper limit on the maximum number of devices you can target via an FQDN list.
Note that scope pattern targetting does not have this limitation because of course only the scope pattern is passed to the cmdlets. The internally computed FQDN list from a specified target scope can be much larger than 140,000 entries.
If you are debugging in the PowerShell ISE, it may take a long timé to process large arrays of FQDNs (e.g 10K or more entries). This is because the debugger imposes a significant performance overhead. You will not see this issue outside the debugger.
Target scope, target FQDN lists and active devices
Devices which are not online (active) are automatically excluded from the target list when the -TargetScope parameter is specified.
However, the -TargetFqdns parameter is assumed to explicitly define the exact devices which are to be targeted. If any of these devices are offline, then instructions targeting those devices may run until either the device responds, or the instruction time to live expires. At that point, all responses are returned.
If you want to use -TargetFqdns but ensure that only online devices from the list you supply are targeted, you can use the Get-TachyonDeviceList cmdlet to return only the active devices. For more information, see the Get-TachyonDeviceList cmdlet details above.
Scope expressions
The -TargetScope parameter also accepts scope expressions. A scope expression allows you to specify one or more attributes that will determine which devices receive an instruction.
When you specify a simple scope pattern, it is automatically translated into the scope expression "fqdn like <pattern>". For more complex scope expressions, please refer to Using scope and filter expressions with the Tachyon PowerShell Toolkit.
Synchronous instructions
Tachyon 5.2 supports a new type of instruction invocation mechanism. Any instruction can be invoked as a synchronous instruction. When an instruction is invoked synchronously, there are some differences in how the instruction is targeted and processed. Specifically:-
A synchronous instruction targets a single device.
A synchronous instruction's results are returned directly to the instruction invoker. They are not stored on the Tachyon responses database and cannot therefore be retrieved from history subsequently.
If the instruction is an aggregating instruction, detailed results are always returned.
A synchronous instruction's results are cached. If the same instruction is sent by the same user to the same device within the default cache lifetime (normally, 180 seconds) then by default the previously cached results are returned. It is possible to override this behaviour to force fresh results to be returned instead.
Invoking instructions synchronously with the Tachyon PowerShell Toolkit
You invoke instructions synchronously using the invoke-TachyonSyncInstruction cmdlet, discussed below.
Invoke-TachyonSyncInstruction -instruction <instruction name> [-targetscope <scope>|-targetfqdns <fqdns>] -PromptDefaults -WhatIf -Refresh
The -TargetScope option, if specified, determines the devices to which the selected instruction will be sent.
As a mutually exclusive argument option, you can specify an array of device FQDNS using the -TargetFqdns parameter instead. This will target the devices associated with the fqdns.
The use of -TargetScope and -TargetFqdns is discussed in more detail in the section "Scope patterns and target FQDN lists" on this page.
The -PromptDefaults option, if specified, causes any instruction parameters with defaults to be prompted for, unless a non-default value has been entered for the parameter on the command line. See the discussion on Instruction Parameters elsewhere on this page
The -Whatif option, if specified, causes the specific devices which would be the targets for the instruction to be returned. The instruction is not executed.
The -Refresh option forces the results to be freshly computed rather than being returned from cache. If there is no cached value or the cache lifetime has been exceeded (180 seconds by default) then fresh results will be computed and re-cached.
Note
Synchronous instructions target individual devices. For convenience, the standard targetscope and targetfqdns parameters are supported. However if either of these resolve to more than 10 devices, the cmdlet will throw an error.
Each device will result in an entry in the Tachyon instruction history, so if five devices are targeted, there will be five history rows after the invoke-tachyonsyncinstruction cmdlet completes.
You cannot retrieve instruction results from history for a synchronous instruction. This is because the results are never stored on the Tachyon database. To determine if an instruction in history was run synchronously, use the get-tachyoninstructionstatus cmdlet, specifying the -Full option. The SynchronousOffLoadUrl property will be non-empty if the instruction was executed synchronously. Note that Tachyon versions prior to 5.2 will not report this property since it was added in that release.
Aggregating queries always return detailed results.
Synchronous instruction invocation does not support targeted rollouts, raw results, result filtering or several other options available for normal invocation, through the invoke-tachyoninstruction cmdlet.
The results from Invoke-TachyonSyncInstruction are in the same format as those for Invoke-TachyonInstruction i.e a dictionary of results keyed by device FQDN.
Attempting to run this cmdlet on versions of Tachyon prior to 5.2 will result in an error being thrown.
The default timeout for synchronous instructions is only 30 seconds. If they fail to respond within this timeframe, a timeout error is returned. While you can, theoretically, invoke an action rather than a question via a synchronous instruction, you would only have a brief time window to authenticate and approve the instruction before it timed out.