Executing an instruction using the 1E PowerShell Toolkit
Invoke-1EInstruction lets you execute any instruction directly from the PowerShell command window, and return the results.
You can return results either as an array of native PowerShell objects which you can then process further e.g by using the PowerShell pipeline, or you can return results as JSON to a text file, which is faster and uses less memory for large result sets.
Getting started with Invoke-TachyonInstruction
You use the 'invoke-tachyoninstruction' cmdlet to run a Tachyon instruction. For example:
invoke-tachyoninstruction "1E-Explorer-TachyonCore-LocalGroupMemberSummary"
invoke-tachyoninstruction takes the following fixed parameters.
Parameter | Description |
|---|---|
<Instruction name> | This is assumed to be the first parameter on the command line. |
-TargetScope <pattern> | Specifies the target scope (by default, a simple FQDN pattern match) for the device target scope. If not specified, you are prompted to supply it when the instruction is run. Tachyon supports sophisticated scope expressions, which allow you to precisely define the target devices for an instruction. For more information on scope expressions, see Using scope and filter expressions with the Tachyon PowerShell Toolkit. |
-TargetFqdns <array> | Specifies a string array of FQDNs which will be the targets of the instruction. This argument is mutually exclusive with the -TargetScope argument. |
-PromptDefaults | If specified, causes any instruction parameters which have default values to be prompted for, with the default auto-filled in. Normally, if this flag is not specified, instruction parameters with defaults cause the instruction to be invoked with those defaults automatically. Only instruction parameters without defaults are prompted for, unless this option is set. |
-Drilldown | If specified, causes any aggregating instruction to be displayed at detail level instead of at aggregated level. |
-WhatIf | As per PowerShell conventions, the -WhatIf command line option allows the user to determine the impact of a command. If specified, then instead of executing the instruction against the target scope of devices, the full list of devices affected is returned instead. You can use this to confirm the expected scope of the instruction if required. |
-InstTTL <mins> | Allows you to override the default Instruction Time to Live for the instruction, in minutes. |
-ResultsTTL <mins> | Allows you to override the default results Time to Live for the instruction, in minutes |
-Raw <file> | Specifies that the results are not to be deserialized from the JSON returned by Tachyon, but stored directly to a file. This is faster and consumes less memory, especially for large results sets. You can convert the file JSON to a serialized format by using the convertfrom-raw cmdlet, which is discussed in more detail on this page Instruction management cmdlets |
Additional parameters
Tachyon instructions can have any number of arbitrary parameters. When invoke-instruction is run, the Tachyon instruction is examined to determine these parameters and the PowerShell instruction then adds them as 'dynamic parameters'. This means that you can either specify them on the command line when you run Invoke-TachyonInstruction, or, if you do not do this, then:
If -PromptDefaults was not specified, any instruction parameter not passed on the command line that does not have a default value specified in the instruction is prompted for.
If -PromptDefaults was specified, any instruction parameter not passed on the command line is prompted for, regardless of whether or not it has a default value.
Note
If you specify -PromptDefaults and then supply an optional parameter on the command line whose value is the same as the default value specified in the instruction, you will still be prompted to supply a value. This is due to current command argument processing limitations in PowerShell
In the example below we invoke the local group instruction, specifying the parameters on the command line for the target scope and account, and specifying that we want to see the detailed, and not aggregated, results.
 |
Note
Unlike auto-generated cmdlets, instruction parameters to invoke-instruction are exposed as dynamic parameters and so there are limitations as to how 'discoverable' they are in PowerShell. If you intend to use an instruction often, I recommend that you use the cmdlet creation functionality discussed on this page: Creating your own cmdlet from a Tachyon instruction to create a cmdlet with formal parameters. This will make it a more 'natural' command from a PowerShell point of view.