Interactive instruction search

The 1E Platform contains an interactive search dialogue for finding and executing 1E instructions. The interactive instruction search feature provides you with similar capabilities but directly from the PowerShell command window. It allows you to do the following:

• Interactively find and execute an instruction.
• Interactively find an instruction and automatically create a PowerShell cmdlet from it. The cmdlet can then be run at any time, just like any regular PowerShell cmdlet.
• Interactively find an instruction and then export it to an XML instruction file.

Getting started

To initiate an interactive search, enter the following PowerShell command:

search-1Einstruction

The following screen will be displayed:

Start typing your search just as you would in the 1E Platform. Instructions that match your search are shown as you type.

As you continue typing, the list of available instructions will shrink. When it reaches 10 or less, the top bar turns green and the instructions are displayed with a number next to each one. Questions are shown in green. Actions are shown in amber.

Select an instruction by entering the number associated with it. You will now see a screen displayed confirming your choice.

Enter the parameters required. These will vary depending on the instruction invoked. You will always be prompted to supply a target scope. In this example, we have requested all devices whose FQDN contains URTH.

Note that the instruction invoked was an aggregating instruction. By default, the results are shown aggregated. You can override this by specifying a command line parameter that specifies that aggregating instructions should instead have the results displayed as details instead. Refer to -Drilldown.

Selecting a single instruction

If the search list is reduced to a single instruction, then the search bar turns green but no digit is displayed next to the instruction. To select this instruction, simply press RETURN.

Exiting the search without selecting an instruction

To exit the search without selecting an instruction, either press ctrl+C or, with the search line blank, simply press RETURN.

Interactive search command line arguments

You can specify the following optional arguments to the 1E-searchinstruction command.

Creating cmdlets from interactive search

You can use the interactive search instruction to locate a 1E instruction and then package that as a cmdlet for re-use within the PowerShell environment. To do this, invoke the search-1Einstruction cmdlet with the -CreateCmdlet parameter.

The search process is identical to the normal instruction search. However, once you have selected an instruction, you will be prompted for the cmdlet name you want to associate it with, as shown below.

A cmdlet file called get-localaccounts.psm1 is created in the current folder. To use the cmdlet, import it into your PowerShell session using the following:

import-module .\get-localaccounts.psm1 -force

You can then invoke the cmdlet as shown in the screenshot below. Note that the cmdlet was invoked twice. As an aggregating command, you can use the -Drilldown parameter to show details instead of the aggregated results.

Exporting instructions

You can specify the -Export flag instead of -CreateCmdlet. When you do this and select an instruction, you are prompted for the name of a ZIP file. The instruction will be exported and saved to the specified file.

Creating cmdlets directly from an instruction

If you know the name of the instruction on the 1E Platform, you can create a cmdlet directly from it without invoking the search. To do this as in the above example, enter the following:

new-1Ecmdlet -Instruction 1E-Explorer-TachyonCore-LocalGroupMemberSummary -cmdlet Get-LocalAccounts

Auto-generated cmdlets and parameters

An auto-generated cmdlet has parameters generated based on the instruction invoked. Additionally to these parameters, the following five fixed parameters are always added to an auto-generated cmdlet.

Sample auto-generated cmdlet

Here is what the auto-generated cmdlet discussed above looks like. It is a thin wrapper over a cmdlet called invoke-1Einstruction which supports the dynamic execution of any existing 1E instruction. The invoke-1Einstruction cmdlet is discussed in more detail below.

The cmdlet builder adds parameters as discussed above: the five fixed parameters and then a set of additional parameters which are dependent on the instruction being wrapped.

In this example, the instruction has a single parameter, accountName, which does not have a specified default. Consequently, the parameter is created as a mandatory parameter and must be supplied when the cmdlet is executed.

If the instruction has parameters with defaults, then the cmdlet parameters for these will be marked Mandatory=false, and the default value for each parameter will be as specified in the instruction.

This means that when you invoke the cmdlet, you can then override any default parameter if you wish, or leave it unchanged and do not supply an override.

Note that the four fixed parameters are simply passed down to the invoke-instruction command along with the instruction-specific parameters.

function get-localaccounts
{
[CmdletBinding(SupportsShouldProcess=$true, DefaultParameterSetName='devices')]
 
Param(
    [Parameter(Mandatory=$true, ParameterSetName='TargetScope')] [string]$TargetScope,
    [Parameter(Mandatory=$true, ParameterSetName='TargetFqdns')] [string[]]$TargetFqdns,
    [Parameter(Mandatory=$false)] [switch]$PromptDefaults = $false
,[Parameter(Mandatory=$false)] [switch]$Drilldown = $false,
[Parameter(Mandatory=$true)] [string] $accountName
)
$instruction = "1E-Explorer-TachyonCore-LocalGroupMemberSummary"
$arguments = @{}
if ($promptdefaults)
    {
    $arguments.Add("PromptDefaults",$true)
    }
if ($drilldown)
    {
    $arguments.Add("Drilldown",$true)
    }
if ($TargetScope -ne "")
    {
    $arguments.Add("TargetScope",$targetScope)
    ]
if ($TargetFqdns -ne $null)
    {
    $arguments.Add("TargetFqdns", $TargetFqdns)
    }
if (-not $pscmdlet.ShouldProcess($instruction))
    {
    $arguments.Add("Whatif",$true)
    }
return Invoke-1EInstruction $instruction @arguments -accountName $accountName
}
Export-ModuleMember -Function get-localaccounts

Cmdlet instruction parameter type mapping

The auto-generated cmdlet will map the underlying property type in the instruction as follows. The left side is the type of the parameter as defined in the instruction and the right side is the PowerShell data type to which it maps.

Constrained type values

Instruction properties whose type is set to value picker will have a constraint added to the cmdlet using the PowerShell ValidateSet option. This will constrain the parameter in PowerShell to the list of valid values which the instruction has defined for the value picker.