Instruction management cmdlets
Instruction management cmdlets allow you to perform various tasks associated with 1E Platform instructions.
Publish-1EInstruction -File <FileName> -InstructionSet <Set Name> [-Force]
This cmdlet takes the XML file specified and uploads it to the specified instruction set. The XML instruction file must be validly signed or the upload will be rejected by the platform.
If the instruction is already uploaded to the platform, then it will only be replaced if the XML file version has been incremented.
If there are active instructions already executing based on the existing instruction, then an error indicating this will be raised.
If the -Force option is specified, then any active instruction matching the uploaded instruction name is canceled. Then the existing instruction is deleted. Finally, the XML file is uploaded. This is a convenient option in labs because you can re-upload an instruction XML file without changing its version and also ensure any existing invocations are canceled.
Use the -Force option with caution in a production environment as it can cancel existing instructions that are executing.
Export-1EInstruction [-Names <FileNames>] [-Ids <Ids>] <file>
This cmdlet exports one or more instructions by name or Id to a file. The file is created as a ZIP file, so the .zip extension is recommended.
You can specify a single string or Id value or you can specify multiple string/Id values. To specify multiple values, declare them as an array, for example:
-Ids @(23,56,78)If you specify the same name or Id multiple times, you will receive an error message that the Id or name does not exist. This is a quirk of the platform API currently.
New-1EInstructionSet -InstructionSet <set name> [-Description <description>] [-Icon <path to icon file>]
This cmdlet creates the instruction set specified and returns its instruction set id. If the set already exists, an error is thrown.
Move-1EInstruction -Name <name>|-Id <id> -SetId <set id>
This cmdlet moves the instruction specified by name or id into the instruction set specified by set id. An instruction with a given name can only be associated with a single instruction set at any time.
Set-1EInstructionSetIcon -InstructionSet <set name> -Icon <path to icon file>
This cmdlet sets the icon associated with the specified instruction set to the icon file specified.
Remove-1EInstruction -Id <id>|-Name <name>
This cmdlet deletes the instruction referred to by the supplied instruction Id or name. If the instruction is active, this cmdlet will throw an exception.
Get-1EInstructionId -Instruction <instruction name>
Given an instruction name, this cmdlet returns its instruction Id. An error is thrown if the instruction cannot be located.
Get-1EInstructionInSet -InstructionSet <set name>
This cmdlet returns the metadata for each instruction in the supplied set. Metadata content appears as shown below. For more information on each property, refer to the 1E Platform API documentation.
Remove-1EInstructionSet -Name <name>| -Id <id> [-deleteInstructions]
This cmdlet deletes the specified instruction set, specified either by name or by id. If the optional -deleteInstructions parameter is supplied, all instructions that belong to the set are deleted. If it is not specified, all instructions that belong to the set are re-assigned back to the unassigned set.
New-1ECmdLet -Instruction <instruction name>| file <filename> [-Cmdlet <cmdlet name>] [-OutFile <file>]
This creates a cmdlet (.psm1 file) from the specified instruction or instruction XML file. You can then import this using the import-module cmdlet and run it as a standard PowerShell cmdlet.
If the -instruction option is specified, then you must specify a cmdlet name. If the -file option is specified, then the cmdlet name is determined by reading the comments field in the instruction. If this contains a cmdlet=xxxx string, then the cmdlet name specified is used by default.
You can still override the cmdlet name by additionally specifying the -cmdlet option if you wish.
If -OutFile is specified, then instead of automatically creating a .psm1 file based on the cmdlet name, the cmdlet text is appended to the specified file. This allows you to conveniently package multiple cmdlets into a single .psm1 file. When you want to use them, you can simply use import-module to bring all the cmdlets into your current PowerShell session.
For information on cmdlet creation, refer to Creating your own cmdlet from a 1E Platform instruction.
If you use the -file option to create a cmdlet from an XML instruction file, then you cannot run the cmdlet until you have uploaded the instruction to the 1E Platform.
New-1ECmdletFromFiles -Folder <folder> -OutFile <outfile> [-Whatif]
Given a folder containing one or more instruction XML files, this cmdlet appends these as cmdlets to the specified output file. This allows you to create a single importable module file from a set of platform instructions.
Each instruction file must have an appropriately marked-up comments field with a [cmdlet=xxxx] member so that the name of the cmdlet can be automatically determined. Any file that cannot be processed is skipped, and a warning is output during the conversion.
Note that you cannot actually run the generated cmdlets until the associated instructions themselves have been uploaded to the 1E Platform.
Using -whatif with new-1Ecmdletsfromfiles
If -Whatif is specified, instead of creating the cmdlets, a set of metadata is output for each XML instruction file, showing its type, name, description, payload, and the associated cmdlet name for it.
This provides a useful self-documenting help mechanism for instruction files.
You can use the get-1Eresultsascsvfile to then process the response and create a CSV file that you can directly import into Excel. You can import the results as a Confluence table by copying the sheet and then pasting in Confluence.
Get-1ERespondingDevice -TargetScope <scope expression> [-Full] [-Active] [-AsArray]
This cmdlet returns the devices that match the specified scope expression.
If the optional -Active argument is supplied, only devices that are currently online and match the scope expression are returned.
If the optional -Full argument is omitted, only the device FQDNs are returned as an object collection, with each object containing just an FQDN property.
If -AsArray is specified, then just the device FQDNs are returned as a collection of simple strings.
If -Full is specified, then metadata is returned for each device as follows. For more information on metadata elements, refer to the 1E Platform API documentation.
The OsVerNum and AgentVersion values are numerically encoded representations of a four part release number, that is, 1.2.3.4.
To convert these numeric representations to human-readable form, use the following cmdlet:
get-1Eversionasstring <numeric value>Get-1EVersionAsString <numeric value>
This cmdlet translates an OS or agent version value into a human-readable numeric value.
Get-1EDevice [-Full] [-Fqdn <fqdn>]
This cmdlet returns all devices known to the platform server. If the -Full switch is not provided, then a list of FQDNs only is returned, similar to get-1Erespondingdevices. Otherwise, the full set of device properties, similar to get-1Erespondingdevices, is returned.
If the optional -Fqdn property is specified, this cmdlet returns information only for the specified device. The -Full parameter is ignored if an FQDN is specified, and the full data for that device is always returned.
To convert the output from get-1Erespondingdevices or get-1Ealldevices into an array suitable for use with the -targetfqdns option in invoke-1Einstruction, take the result from either of these cmdlets and provide it as an argument to the Get-1ETargetFqdns cmdlet. This will return a string array of FQDNs.
Get-1ETargetFqdn -TargetFqdns <array>
This cmdlet returns a simple string array from the passed-in -TargetFqdns argument. If the input is a string array, it is returned unchanged. Otherwise, it is tested to see if it is an array of objects, each of which contains (at least) an FQDN property. If so, then the FQDN property for each object in the array is returned as part of a string array.
This allows the results from Get-1EAllDevices or Get-1ERespondingDevices to be directly used as an input to cmdlets that accept a list of target fqdns in their -TargetFqdns parameter.
If the input array is empty or null, an exception is thrown.
Get-1EInstructionTargetFqdn -Id <id>
Given an instruction Id of an inflight or historical instruction, this cmdlet returns the target list of FQDNs for the instruction.
An exception is thrown if the instruction Id is not valid or if the instruction was invoked with a scope expression rather than a target FQDN list.
Get-1EInstructionResultFqdn -Id <id>
This cmdlet returns an array of FQDNs that have returned results for the instruction whose history Id is specified.
If the instruction has expired, no data is returned.
This list corresponds to FQDNs that have responded by providing data to the platform, as opposed to the list returned by Get-1EInstructionTargetFqdn, which is the original target list of FQDNs to which the instruction will be sent.
Get-1EInstruction
This cmdlet returns metadata about all instructions. For more information on metadata elements, refer to the 1E Platform API documentation.
Use the standard PowerShell cmdlet select-object if you want to return specific instruction properties. For example, the following will return just the instruction names:
get-1Einstruction | select-object {$_.Name}Get-1EInstructionSet
This cmdlet returns information about all instruction sets, as shown below.
Optimize-1EMemory
This cmdlet invokes the garbage collector to reclaim memory. This can be useful if your PowerShell command window is consuming excessive memory.
Assigning large result sets to variables can consume significant memory. To free this memory, assign $null to the variable(s) and then invoke the optimize-memory cmdlet.
Get-1EActiveInstruction
This cmdlet returns a list of all instructions that are currently in process (that is, the instruction time to live has not yet expired). Instructions that have completed processing or where the results have additionally been deleted are not included.
The platform API, which is called when this cmdlet is invoked, does not appear to include instructions that are in a workflow state such as pending approval. Consequently, these instructions are not reported when this cmdlet is invoked.
Stop-1EInstruction -Id <Id> [-DeleteResults]
This cmdlet cancels the active instruction whose Id is specified. If the Id is not valid or the instruction is not currently processing, an error is thrown. If -DeleteResults is specified, any collected results are discarded. Otherwise, they are preserved.
Get-1EInstructionStatus -Id <id> [-Full]
This cmdlet returns the instruction status of the instruction whose Id is specified. If the Id is not valid, an exception is thrown. Otherwise, if -Full is not specified, a string is returned with the following status values:
0. Created
1. InApproval
2. Rejected
3. Approved
4. Sent
5. InProgress
6. Complete
7. Expired
8. Cancelling
9. Cancelled
10.Failed
11.Suspended
12.AuthenticatingIf the -Full switch is provided, then the full instruction data set is returned rather than just the status.
For convenience, the workflow status member is also decoded. Valid values for this member are the following:
0. New
1. RiskAssessment
2. PendingApproval
3. Processing
4. InProgress
5. Completing
6. Cancelling
7. Rejecting
8. Closed
9. Failed
10.Suspended
11.AuthenticatingInstruction history is currently preserved indefinitely in the platform, so any instruction that has ever been processed will have its status preserved and can be queried.
Get-1EInstructionHistory [-ItemCount <itemcount>]
This cmdlet gets the full instruction history, which includes all instructions ever executed by the 1E Platform. Results are returned in descending datetime order, so the first result in the returned array is the most recent instruction.
If Itemcount is specified, then only the specified count of items are retrieved. For example, to get the most recent instruction in history, specify -ItemCount 1.
The instruction status and workflow state members of each history entry are returned as their raw numeric platform values for efficiency since instruction history could return potentially thousands of results.
To decode these into the description that Get-1EInstructionStatus returns, you can use the get-1Eworkflowstatedesc and get-1Einstructionstatusdesc cmdlets documented below.
Get-1EWorkflowStateDesc -Value <value>
This cmdlet decodes the numeric workflow state returned for instruction history entries to a description, consistent with that returned for the Get-1EInstructionStatus cmdlet.
Get-1EInstructionStatusDesc -Value <value>
This cmdlet decodes the numeric instruction status returned for instruction history entries to a description, consistent with that returned for the Get-1EInstructionStatus cmdlet.
Get-1EInstructionMetadata -Name <name>|-Id <id> [-Schema]
Given either an instruction name or its Id, this cmdlet returns the instruction metadata, which includes whether it is a question or an action and information about parameters, etc.
If the -Schema option is specified, then only the instruction schema is returned as a string in human-readable format, for example:
Col1 string(20), Col2 int64, Col3 int32This is the same format that is accepted for the -schema option in the new-1Einstructionxml cmdlet. Refer to Instruction XML management cmdlets.
Get-1EInstructionXml -File <file>
This cmdlet returns structured information from an XML instruction file, as shown below.
Get-1EInstructionResult -Id <id> [-DrillDown] [-ResultFilter <result filter>] [-Raw <file>] [-ReceivedOnly]
Given an ID of an instruction, this cmdlet returns the instruction results. If -Drilldown is specified and the instruction is an aggregating instruction, then if the instruction had been originally invoked with the -drilldown parameter, then detailed results are returned.
If -Drilldown is specified and the instruction is an aggregating instruction but was not invoked originally with the -drilldown option, then an error is thrown because in that situation the KeepRaw option was set to false when the instruction was sent to the platform. This is more efficient because raw results are not kept, but it means that it is not possible to subsequently drill down and retrieve them.
Otherwise, aggregated results are returned for aggregating instructions.
If -ResultFilter is specified, results are filtered by the supplied filter expression. For more information on filter expressions, refer to Scope and filter expressions.
If -Raw is specified, results are written to the appropriate file as raw JSON instead. In this case, the instruction statistics are returned as the result of the cmdlet itself.
For very large result sets, it can be quicker to output the results to a raw file because PowerShell doesn't have to convert them into internal PowerShell objects. Also, this option consumes much less memory because the results don't have to be loaded into memory.
You can use a raw JSON file as input to the Get-1EResultAsCsvFile cmdlet discussed below. This will allow you to subsequently create a CSV file from the raw JSON file. Starting with version 1.2.8 of the 1E PowerShell Toolkit, converting from a raw file directly to a CSV file is done using a filestream and consumes very little memory. If the source file is very large (>100M or so), then this is the preferred mechanism for converting data in order to conserve memory and resources.
If -ReceivedOnly is specified, only the results available at the time the cmdlet is invoked are returned. Otherwise, the cmdlet will wait until the sent count and received count match before returning results, or until the instruction transitions to Complete. At this point, the received count is taken to be the final count since no further devices can contribute results. Therefore, if you specify -ReceivedOnly against an instruction that is complete, it has no effect because all available results are immediately returned.
If the instruction is not in an appropriate state (for example, canceled, rejected, expired, and so on), then an error is thrown. Results are not available in these scenarios.
You can retrieve instruction results for any active instruction, not just ones that you invoked via the PowerShell cmdlets. For example, you can retrieve instruction results for instructions launched via the platform, provided you have appropriate Role-Based Access Control (RBAC) permissions.
Get-1ETargetFromFile -File <filename>
This cmdlet returns an array of FQDNs extracted from a target file. Target files are specified when you are using the invoke-1Einstruction cmdlet to manage a staged rollout of an instruction. Refer to Staged rollouts.
You can use the result of this cmdlet directly as the array argument to the invoke-instruction parameter -targetfqdns. This is handy if you want to send an instruction to a set of devices that are part of a targeted rollout, perhaps to monitor the success of the rollout.
Get-1EResultAsCsvFile -InputObject <object>|-Id <id> -Path <path> [-Drilldown] [-ResultFilter <resultfilter>] [-ResultColumns <resultcolumns>] [-Raw <file>] [-ReceivedOnly]
This cmdlet creates a CSV file specified by -Path either from the results of an instruction that have been stored in a variable (by specifying the -InputObject option) or from an instruction result in history, specified by the result Id or from a raw result file.
For instructions from history, you can optionally specify -Drilldown if the historical result was aggregated (and contains details, that is, keepraw = true) and also a result filter to specify which results you wish to match.
if -Raw is specified, then instead of specifying an instruction Id or an input object (using the -Id and -InputObject parameters) as the source of the instruction data, you specify a raw JSON file created using the Get-1EInstructionResult cmdlet discussed earlier.
Starting with release 1.2.8 of the 1E PowerShell Toolkit, converting from a raw file directly to a CSV file is done using a file stream and consumes very little memory. Other conversion options require that the data be buffered in memory. For very large result sets, this can consume large amounts of memory. Hence converting from a raw file directly to a CSV file is the preferred mechanism for converting very large result sets.
If -ReceivedOnly is specified, and you are retrieving data by specifying an instruction Id, only the results available at the time the cmdlet is invoked are returned. Otherwise, the cmdlet will wait until the sent count and received count match before returning results, or until the instruction transitions to Complete. At this point, the received count is taken to be the final count since no further devices can contribute results. Therefore, if you specify -ReceivedOnly against an instruction that is complete, it has no effect because all available results are immediately returned.
The -ResultColumns option allows you to specify one or more columns that you want to include in the CSV. By default, all columns are included. For example, in the results shown below, we could have included only the DeviceLocator and Tag columns by specifying -ResultColumns "DeviceLocator,Tag".
For non-aggregating instructions, the CSV file contains the FQDN associated with the row in a field named Fqdn. For aggregating instructions, this field will contain the string Aggregated for each row.
For performance reasons the FQDN property is added to the input object (if not already present) and thus alters the object. This should not normally cause issues if you want to re-use the object variable; however, you should be aware that this occurs.
You should enclose the column list in quotes when specifying this option on the command line to prevent the PowerShell parser from processing it.
When retrieving CSV results from an instruction in history, you can specify both the -ResultFilter and -ResultColumns options.
When retrieving CSV results from an input object or a raw result file, the -ResultFilter option is not valid and only the -ResultColumns option is honored. This is because -ResultFilter is supplied to the platform API, which is not called in this case.
For example, we can request the results from history Id 27, which was an instruction to return memory details per device, and then filter to return only the rows where the memory_in_mb column is 3968. This then returns us a CSV containing only the matching rows.
Get-1EResultAsCsvFile -id 27 -resultfilter "memory_in_mb=3968" -drilldown -path foo.csv