Skip to main content

1E 8.1 (on-premises)

Instruction management cmdlets

Instruction management cmdlets allow you to perform various tasks associated with Tachyon instructions.

Publish-TachyonInstruction -File <FileName> -InstructionSet <Set Name> [-Force]

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

If the instruction is already uploaded to Tachyon, 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 cancelled. 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 cancelled.

Note

Use the -Force option with caution in a production environment, as it can cancel existing instructions which are executing.

Export-TachyonInstruction [-Names <FileNames>] [-Ids <Ids>] <file>

Export 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)

Note

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 Tachyon API currently.

New-TachyonInstructionSet -InstructionSet <set name> [-Description <description>] [-Icon <path to icon file>]

Creates the instruction set specified and returns its instruction set id. If the set already exists, an error is thrown.

Move-TachyonInstruction -Name <name>|-Id <id> -SetId <set id>

Moves the instruction specified by name or id into the instruction set specified by set id.

Set-TachyonInstructionSetIcon -InstructionSet <set name> -Icon <path to icon file>

Sets the icon associated with the specified instruction set to the icon file specified.

Remove-TachyonInstruction -Id <id>|-Name <name>

Deletes the instruction referred to by the supplied instruction Id or name. If the instruction is active, this cmdlet will throw an exception.

Get-TachyonInstructionId -Instruction <instruction name>

Given an instruction name, return its instruction Id. An error is thrown if the instruction cannot be located.

Get-TachyonInstructionInSet -InstructionSet <set name>

Returns the metadata for each instruction in the supplied set. Metadata content appears as shown below. For more information on each property, see the Tachyon API documentation.

233276800.png
Remove-TachyonInstructionSet -Name <name>| -Id <id> [-deleteInstructions]

Deletes the specified instruction set, either specified 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-TachyonCmdLet -Instruction <instruction name>| file <filename> [-Cmdlet <cmdlet name>] [-OutFile <file>]

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.

Cmdlet creation is discussed in more detail on the parent page to this page.

Note

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

New-TachyonCmdletFromFiles -Folder <folder> -OutFile <outfile> [-Whatif]

Given a folder containing one or more Tachyon instruction XML files, appends these as cmdlets to the specified output file. This allows you to create a single importable module file from a set of Tachyon instructions.

Note

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

Using -whatif with new-cmdletsfromfiles

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.

233276795.png

Note

You can use the get-resultsascsvfile to then process the response and create a CSV which you can directly import into Excel.

Get-TachyonRespondingDevice -TargetScope <scope expression> [-Full] [-Active] [-AsArray]

Returns the devices that match the specified scope expression.

If the optional -Active argument is supplied, only devices which 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 for each device, metadata is returned as follows. For more information on metadata elements, see the Tachyon API documentation.

233276799.png

Note

The osvernum and agentversion values are numerically encoded representations of a four part release number, 1.2.3.4 for example.

To convert these numeric representations to human-readable form, use the cmdlet:

get-tachyonversionasstring <numeric value>

Get-TachyonDevice [-Full] [-Fqdn <fqdn>]

Returns all devices known to the Tachyon server. If the -Full switch is not provided, then a list of FQDNs only is returned, similar to get-respondingdevices. Otherwise, the full set of device properties, similar to get-respondingdevices, is returned.

If the optional -Fqdn property is specified, 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.

Note

To convert the output from get-respondingdevices or get-alldevices into an array suitable for use with the -targetfqdns option in invoke-instruction, take the result from either of these cmdlets and provide as an argument to the Get-TargetFqdns cmdlet. This will return a string array of FQDNs.

Get-TachyonTargetFqdn -TargetFqdns <array>

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-AllDevices or Get-RespondingDevices 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-TachyonInstructionTargetFqdn -Id <id>

Given an instruction Id of an inflight or historical instruction, 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-TachyonInstructionResultFqdn -Id <id>

Returns an array of FQDNs which have returned results for the instruction whose history Id is specified.

If the instruction has expired, no data is returned.

Note

This list corresponds to FQDNs which have responded by providing data to Tachyon, as opposed to the list returned by Get-TachyonInstructionTargetFqdn, which is the original target list of FQDNs to which the instruction will be sent.

Get-TachyonInstruction

Returns metadata about all instructions. For more information about metadata elements, see the Tachyon API documentation.

233276798.png

Note

Use the standard PowerShell cmdlet select-object if you want to return specific instruction properties. For example:

get-instructions | select-object {$_.Name}

will return just the instruction names.

Get-TachyonInstructionSet

Returns information about all instruction sets, as shown below.

233276797.png
Get-TachyonManagementGroup [-Id <id>|-Name <name>|-UsableId <usableId>] [-Devices] [-Source SLA|Tachyon]

With no parameters specified, returns all management groups. If no management groups are defined, no results are returned.

If the -Id, -Name or -UsableId parameter is specified, the management group (if any) whose -Id, -Name or -UsableId matches the parameter is returned.

If the -Devices parameter is additionally specified, then the devices contained in the specified management group are returned (if any). An error is thrown if -Devices is specified without also supplying an Id, Name or UsableId parameter.

The -Source parameter allows you to specify whether management group information is returned from Tachyon (default) or from SLA.

SLA management groups are discussed in more detail here Working with management groups and the Tachyon PowerShell Toolkit.

To set up management groups in Tachyon, see the tutorial here Tachyon Platform 8.1: Management Groups - tutorial.

Get-TachyonManagementGroupReadPermission

Returns a list of management groups for which the current user has read permission.

Get-TachyonManagementGroupWritePermission

Returns a list of management groups for which the current user has write permission.

Get-TachyonManagementGroupDependency -Id <id>

Returns a list of entities which have dependencies on a management group (such as Guaranteed State policies and rules). These entities may need to be deleted or reassigned to another group before this management group can be deleted.

Get-TachyonSLAManagementGroup [-Id <id>] [-IncludeRules]

Returns all SLA management groups or the group associated with the specified Id. If -IncludeRules is specified, then the management group rules associated with the group(s) are also returned.

This cmdlet is called internally when Get-TachyonManagementGroup is invoked with the -Source SLA parameter specified.

New-TachyonSLAManagementGroup -Name <Name> -Rules <rule expression> [-Description <description>] [-ParentId <id>]

Creates a new SLA management group specified by the name, which must be unique for each group.

If the optional description is not specified, the group's description is set to its name.

The Rule expression is a management group rule expression. For more information on management group rule expressions, please refer to SLA management groups and rule expressions.

The optional -ParentId parameter specifies the Id of a management group which is to be set as the parent to this group.

Note

When assigning a group parent, the parent group must have been synchronised with Tachyon using the Sync-TachyonSLAManagementGroup cmdlet, otherwise a permission error is returned.

Remove-TachyonSLAManagementGroup -Id <id>

Deletes the SLA management group specified by the Id.

Note

If an SLA management group which has been synchronized with Tachyon is deleted, it remains in the list of Tachyon management groups until the Sync-TachyonSLAManagementGroup cmdlet is run against another existing SLA group. When this is done, the deleted group is removed from Tachyon's list of management groups.

You cannot delete an SLA management group which has children specified. To delete such a group, you must first delete all children. You can retrieve group information including parent groups, using the Get-TachyonSLAManagementGroup cmdlet.

You may receive an error indicating that the management group is in use. If this occurs, try running the Sync-TachyonSLAManagementGroup cmdlet, specifying the group you are trying to delete, then retry the delete operation.

Sync-TachyonSLAManagementGroup -Id <Id> -RepositoryId <RepositoryId>

Synchronizes Tachyon's management group list with the SLA management group list. You must specify the Id of a valid SLA management group and the Id of a valid repository. This is normally the Default Inventory repository. To obtain repository Ids, use the Get-TachyonSLARepository cmdlet

When you synchronize, the following occurs:-

  • Any new SLA management groups are added to the Tachyon management group list. However these new groups do not have their members evaluated when they are added . You must explicitly synchronise these groups for that to occur.

  • Any deleted SLA management groups are removed from the Tachyon management group list.

  • The specified management group in the Sync-TachyonSLAManagementGroup cmdlet is updated in Tachyon with a revised set of member devices which are defined by the management group rules.

  • Note that other management groups in SLA that are modified, are not resynchronized unless you explicitly invoke this cmdlet specifying their Ids.

Update-TachyonSLAManagementGroup -Id <id> [-Name <name>] [-Description <description>] [-Rules <rule expression>] [-ParentId <parentId>] [-RemoveParent]

Updates the specified SLA management group. If any optional parameter is not supplied, then the current value for that parameter is left unchanged.

The -RemoveParent parameter allows any existing parent to be removed from the management group. Management groups without a parent are assumed to be children of the built-in 'All Devices' group.

See the notes above on the New-TachyonSLAManagementGroup cmdlet regarding the assignation of group parents.

You must invoke the Sync-TachyonSLAManagementGroup cmdlet after making changes to the SLA management group, in order for the changes to be propagated back to Tachyon from SLA.

Note

If the management group is not rule-based (that is, a direct membership group), then an error is thrown. You update direct membership groups with the Set-TachyonSLADirectManagementGroup cmdlet.

Get-TachyonSLARepository

Returns a list of all SLA repositories. You can use this cmdlet to obtain the appropriate repository Id for use with the Sync-TachyonSLAManagementGroup cmdlet. The repository Id is the 'Id' member of the repository properties returned.

Get-TachyonSLAManagementGroupRuleAttribute

Returns the valid SLA management group attributes that can be used in rule expressions, along with their data type and SLA record ID.

Note that SLA record Ids are site-specific.

For more information on the use of management group rule attributes in rule expressions, please refer to SLA management groups and rule expressions.

Get-TachyonSLAManagementGroupDevice -Id <id> -RepositoryId <RepositoryId>

Returns a list of devices that are contained within the specified management group, within the specified repository.

When a management group is sync'd with Tachyon, you should see the same device set reported when you use the Get-TachyonRespondingDevice cmdlet and specify a scope "managementgroup=nn" where nn is the Tachyon Id for the management group.

Note

An exception is currently thrown if the underlying group contains no devices. This is caused by the current API behavior and may change in a future release of the platform.

Set-TachyonSLADirectManagementGroup -Name <Name> [-Description <description>] -FqdnList <fqdn list>

Creates or updates an SLA direct membership management group. The list of Fqdns which is to constitute the group membership is passed as an array.

233276787.png

Note

A Tachyon synchronization operation is triggered automatically when this cmdlet is run, unlike for rule-based management groups. During the synchronization, any other management group changes (new or deleted groups) will be propagated across as well.

It is not possible to assign a parent to a direct membership management group.

Optimize-TachyonMemory

Invokes the garbage collector to reclaim memory. This can be useful if your PowerShell command window is consuming excessive memory.

Note

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

Returns a list of all instructions which are currently in process (that is, the instruction time to live has not yet expired). Instructions which have completed processing or where the results have additionally been deleted are not included.

Note

The Tachyon API which is called when this cmdlet is invoked does not appear to include instructions which are in a workflow state, such as 'pending approval'. Consequently, these instructions are not reported when this cmdlet is invoked.

Stop-TachyonInstruction -Id <Id> [-DeleteResults]

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-TachyonInstructionStatus -Id <id> [-Full]

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

If 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:

        0. New
        1. RiskAssessment
        2. PendingApproval
        3. Processing
        4. InProgress
        5. Completing
        6. Cancelling
        7. Rejecting
        8. Closed
        9. Failed
        10.Suspended
        11.Authenticating

Note

Instruction history is currently preserved indefinitely in Tachyon, so any instruction that has ever been processed will have its status preserved and can be queried.

Get-TachyonInstructionHistory [-ItemCount <itemcount>]

Gets the full instruction history, which includes all instructions ever executed by Tachyon. 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.

Note

The instruction status and workflow state members of each history entry are returned as their raw numeric Tachyon values for efficiency, since instruction history could return potentially thousands of results.

To decode these into the description that Get-InstructionStatus returns, you can use the get-workflowstatedesc and get-instructionstatusdesc cmdlets documented below.

Get-TachyonWorkflowStateDesc -Value <value>

Decodes the numeric workflow state returned for instruction history entries to a description, consistent with that returned for the Get-InstructionStatus cmdlet.

Get-TachyonInstructionStatusDesc -Value <value>

Decodes the numeric instruction status returned for instruction history entries to a description, consistent with that returned for the Get-InstructionStatus cmdlet.

Get-TachyonInstructionMetadata -Name <name>|-Id <id> [-Schema]

Given either an instruction name or its Id, return 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 int32

Note

This is the same format that is accepted for the -schema option in the new-instructionxml cmdlet, contained in the Tachyon Dynamic instruction module. See Instruction XML management cmdlets for more details.

Get-TachyonInstructionXml -File <file>

Return structured information from an XML instruction file, as shown below.

233276796.png
Get-TachyonInstructionResult -Id <id> [-DrillDown] [-ResultFilter <result filter>] [-Raw <file>] [-ReceivedOnly]

Given an ID of an instruction, return 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 Tachyon. This is more efficient because raw results are not kept, but 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, please refer to Using scope and filter expressions with the Tachyon PowerShell Toolkit.

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.

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 (e.g, cancelled, rejected, expired etc) then an error is thrown. Results are not available in these scenarios.

Note

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 Tachyon Explorer, provided you have permission to do so.

Get-TachyonTargetFromFile -File <filename>

Returns an array of FQDNs extracted from a target file. Target files are specified when you are using the invoke-instruction cmdlet to manage a staged rollout of an instruction. For more information about Staged rollouts, please refer to Staged rollouts using the Tachyon PowerShell Toolkit.

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-TachyonResultAsCsvFile -InputObject <object>|-Id <id> -Path <path> [-Drilldown] [-ResultFilter <resultfilter>] [-ResultColumns <resultcolumns>] [-Raw <file>] [-ReceivedOnly]

Creates a CSV file specified by -Path from either 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 -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.

The -ResultColumns option allows you to specify one or more columns that you want to be included 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.

Note

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.

Note

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 honoured. This is because -ResultFilter is supplied to the Tachyon 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.

233276790.png