Executing an instruction
Invoke-1EInstruction lets you execute any 1E Platform 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 (for example, 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.
You use the invoke-1Einstruction cmdlet to run a 1E Platform instruction. For example:
invoke-1Einstruction "1E-Explorer-TachyonCore-LocalGroupMemberSummary"Fixed parameters
Invoke-1Einstruction 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. The 1E Platform supports more complex target scoping expressions which allow you to precisely define the target devices for an instruction. For more information, refer to Scope and filter expressions. |
|
-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, it causes any instruction parameters which have default values to be prompted for, with the default value automatically filled in. If this flag is not specified, instruction parameters with defaults cause the instruction to be invoked with those defaults automatically. Unless this option is set, only instruction parameters without defaults are prompted for. |
|
-Drilldown |
If specified, it 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 affected devices is returned. 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 the platform, 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. Refer to Instruction management cmdlets. |
Additional parameters
1E Platform instructions can have any number of arbitrary parameters. When invoke-1Einstruction is run, the instruction is examined to determine these parameters, and the PowerShell instruction then adds them as dynamic parameters. You can choose to specify or not specify them on the command line when you run invoke-1EInstruction. If you choose not to specify them, then the following scenarios can occur:
- If -PromptDefaults was not specified, any instruction parameter not passed on the command line is prompted for if it does not have a default value.
- 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.
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.
Invoke-1EInstruction 1E-Explorer-TachyonCore-LocalGroupMemberSummary -Targetscope urth-dev -Account urth\ciso -Drilldown
Unlike auto-generated cmdlets, instruction parameters to invoke-1Einstruction are exposed as dynamic parameters; therefore, there are limitations as to how discoverable they are in PowerShell. If you intend to use an instruction often, it is recommended that you use the cmdlet creation functionality to create a cmdlet with formal parameters. Refer to Creating your own cmdlet from a 1E Platform instruction. This will make it a more natural command from a PowerShell point of view.