1E 23.7 (SaaS)

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.

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)

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

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

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

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

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

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.

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.

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.

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.

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.

Note

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

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.

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.

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.

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.

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.

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

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

Returns information about all instruction sets, as shown below.

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.

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

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

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.

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.

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.

Deletes the SLA management group specified by the Id.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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

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

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

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.

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.

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.

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.