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 on the 1E Platform.

Get-1ERespondingDeviceCount -TargetScope <device pattern>

This cmdlet returns the count of devices that match a device pattern, for example, URTH will match all devices whose FQDN contains URTH. This indicates the count of devices which would be associated with an instruction targeted at this device pattern.

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 1E PowerShell Toolkit, 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 platform 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 a device that is not online during the execution of the instruction would still not supply data in that scenario.

Invoke-1EInstruction <instruction>...

This cmdlet invokes the specified instruction, targeting the devices whose FQDN matches the supplied device pattern and returns the result.

Copy

 -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]

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 that is used to invoke the instruction. For more information, refer to Targeted (static) 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 further down. Refer to 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. Refer to Instruction parameters.

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 1E Platform 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 the platform.

The -Raw option specifies that results are to be written as returned JSON directly to the specified file. Refer to Raw mode.

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. Refer to Staged rollouts.

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.

You can use the get-1Einstructionresult 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.

This is used in preference to the -Verbose parameter because -Verbose causes the internal HTTP(S) 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. For more information about result filters, refer to Scope and filter expressions.

Additional command-line parameters correspond to instruction-specific parameters and will be passed to the instruction.

The -Offload parameter allows you to send instruction results to a 1E Platform consumer that has been appropriately configured to pass these on to a service that can accept offloaded results. When you do this, results are not stored in the platform responses database. Refer to Offloading data to an external target.

Instruction parameters

1E Platform instruction parameters generally map exactly to their PowerShell equivalents. For example, a platform instruction parameter of IPAddress would map to the PowerShell parameter -IPAddress. However, the 1E Platform allows embedded spaces in parameter names and PowerShell does not. Accordingly, if a platform instruction exposes a parameter with embedded spaces, these are automatically translated to and from underscores (_). For example, if the platform 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 platform instruction, it is remapped back to "Foo Factor".

Platform 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 instruction.

If a parameter has a defined default value in the platform instruction, you can override this by specifying the -PromptDefaults parameter to invoke-1Einstruction. 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 platform 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-serialize the JSON results returned from the platform, and it can also consume a large amount of memory in doing so.

PowerShell Core, which is fully supported by the 1E PowerShell Toolkit, is considerably faster than legacy PowerShell. Consequently, if you are running platform instructions that return large amounts of data, you may want to consider installing PowerShell Core and running the 1E PowerShell Toolkit under that. Note that this does not affect the PowerShell requirements on platform-managed devices as all the Toolkit code is running on the machine you are working from.

Therefore, in some cases, it may be better to specify raw mode. When this is done, the JSON results from the platform are not deserialized 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-1Eraw 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 serializing 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.

Returning data in raw mode

When an instruction is invoked in raw mode, the return result from invoke-1Einstruction is the instruction statistics information. This is the same information that would be returned by get-1Estatistics, 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-1Einstruction 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 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 that are not active but that 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, and results will be returned at that point.

Using dynamic scoping

However, if you want to emulate the behavior of the 1E Platform 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 standard instruction invocation API without modification in any way. The 1E Platform 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-1Einstruction cmdlet terminates with results. This is because it requests an initial estimate of receiving device count from the platform 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 platform 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 behavior with the 1E PowerShell Toolkit by using the -DynamicScope parameter in conjunction with the -NoWait parameter. You can then subsequently poll the platform for the cumulative instruction results by using the Get-1EInstructionResult cmdlet, passing the instruction Id returned when invoke-1Einstruction is called with -NoWait.

For both static and dynamic scopes, a device that goes offline during instruction execution but before results are collected could also cause the invoke-1Einstruction 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 the 1E Platform itself will always collect as much data as it can from the targeted devices. If you use the get-1Einstructionresult cmdlet to retrieve results, you will always get a result set equivalent to what you would have seen in the platform 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-1Einstructionresult cmdlet to get the result set from history. This emulates the behavior you would see in the platform UI.

ConvertFrom-1ERaw -File <file>

The ConvertFrom-1ERaw 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.

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-1EInstruction [-TargetScope <device pattern>|-TargetFqdns <array of FQDNs>] [-PromptDefaults] [-Drilldown] [-CreateCmdlet]

This cmdlet opens an interactive search where you can type in text which is matched in real time to 1E Platform instructions, similar to the operation of the platform 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.

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 -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.

Restart-1EInstruction -Id <Id> [-Drilldown] [-ResultFilter <filter>]

This cmdlet 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 drill down aggregated results and/or apply a result filter to the results.

You cannot rerun an action, only a question. Attempting to rerun an action will cause an error to be thrown.

Get-1EInstructionStatistics -Id <id>

This cmdlet 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-1ETargetFileInstructionStatus -TargetFile <targetfile>

This cmdlet 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, refer to Staged rollouts.

Get-1ELastInstructionState [-Full]

If an instruction has already been executed in this PowerShell session, this cmdlet 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-1ELastInstructionId

This cmdlet returns the Id of the most recently executed instruction (if any). If no instruction has executed yet in this session, it returns 0.

Get-1EDeviceList -TargetFqdns <fqdn list> [-Inactive]

Given a list of FQDNs as an array, this cmdlet returns a fresh array that includes only the devices in the list that are currently online. If the -Inactive flag is specified, it returns an array that includes only the devices on the list that are currently offline.

If any FQDN does not correspond to a valid device recognized by the 1E Platform, 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. Refer to Scope patterns and target FQDN lists.

To use this cmdlet with the invoke-1Einstruction 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:

Copy

invoke-1Einstruction <instruction> -TargetFqdns (Get-1EDeviceList -TargetFqdns <list of devices>)

This will filter down the list you provide and return only a list of currently online devices to the invoke-1Einstruction 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, a set of FQDNs is always used internally 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.

This behavior 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 1E Platform 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, ultimately causing a timeout.

You can override this default behavior by specifying dynamic scoping if you wish. Refer to Targeted (static) and dynamic scope. Dynamic scoping emulates the behavior of the platform 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.

Size limitations on the target fqdn list

The target fqdn list has been tested up to approximately 140,000 entries. This is well within the platform's capabilities to handle. However just above this point, PowerShell will stop marshaling 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 targeting does not have this limitation because 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 time to process large arrays of FQDNs (for example, 10,000 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 that 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-1EDeviceList cmdlet to return only the active devices. Refer to Get-1EDeviceList -TargetFqdns <fqdn list> [-Inactive].

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, refer to Scope and filter expressions.

Synchronous instructions

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.

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 platform 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 behavior to force fresh results to be returned instead.

Invoking instructions synchronously with the 1E PowerShell Toolkit

You invoke instructions synchronously using the invoke-1ESyncInstruction cmdlet as discussed below.

Invoke-1ESyncInstruction -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. For more information about the use of -TargetScope and -TargetFqdns, refer to Scope patterns and target FQDN lists.

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.

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 platform instruction history, so if five devices are targeted, there will be five history rows after the invoke-1Esyncinstruction cmdlet completes.

You cannot retrieve instruction results from history for a synchronous instruction. This is because the results are never stored on the platform database. To determine if an instruction in history was run synchronously, use the get-1Einstructionstatus cmdlet, specifying the -Full option. The SynchronousOffLoadUrl property will be non-empty if the instruction was executed synchronously.

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-1Einstruction cmdlet.

The results from Invoke-1ESyncInstruction are in the same format as those for Invoke-1EInstruction, that is, a dictionary of results keyed by device FQDN.

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 times out.

Data export

1E Platform supports data export from the platform UI. When data is exported, the user specifies the path to a local share on the platform to which the data is copied.

If data export is requested at the time an instruction is invoked, the data will become available when the instruction time to live followed by the results time to live have both expired. Thus, if the instruction time to live is 60 minutes and the data time to live is 120 minutes, then the export is triggered after 180 minutes have elapsed from the initial instruction invocation time.

A user can also request that data be exported earlier by stopping (canceling) the instruction, selecting to preserve (keep) the results and then selecting Export All Data. When they do this, the data available is immediately exported.

Exported data takes the form of a tab-separated file (.tsv) file. The cmdlets discussed below allow you to enumerate available export result sets, retrieve exported data from a result set, and delete export result sets.

Export data sets are automatically deleted after seven days by default.

Get-1EExportedResultSet [-InstructionId <id>]

This cmdlet enumerates the available export result sets. Each result set will be associated with a unique Id.

If -InstructionId is specified, only the exported results from that particular instruction will be listed. If omitted, then all the exported results from all instructions accessible to the user will be returned.

Do not mistake the Instruction Id for the Exported Result Set Id. One instruction can be exported multiple times, so the Ids of the instruction and the exported result sets will not match.

Get-1EExportedResult -Id <id> [ -Path <path> ]

This cmdlet retrieves data from the specified export result set whose Id was retrieved using the Get-1EExportedResultSet cmdlet.

If -Path is specified, it denotes the full path and file name of a file to receive the data. If this file already exists, an error is thrown.

Otherwise, the data is returned directly as the output from the cmdlet. If data is returned directly then the maximum result set that can be returned is approximately 2G of data. If data is written to a file, there is no limitation on the maximum size of data that can be retrieved. Data is retrieved from the platform in chunks of 100K.

Remove-1EExportedResultSet -Id <id>

This cmdlet deletes the result set whose Id is specified.