Dynamic Scripting and executable command execution using the Tachyon PowerShell Toolkit
The standard Tachyon environment assumes that a user wishing to deploy a script or executable command via Tachyon will package up this script or command via the TIMS authoring tool. It may, however, be more convenient in some cases to do this using PowerShell directly.
Dynamic Scripting allows you to create a PowerShell script and then deploy it dynamically. The script will automatically be packaged into an instruction XML file, signed and then uploaded to the Tachyon server and assigned to a specially created instruction set reserved for dynamic instructions. It is then executed, and the results returned directly to the caller.
As an alternative to a script, you can also specify an executable command to be run.
Note
To use this feature, you must enable code signing. Please refer to Requirements for using the Tachyon PowerShell Toolkit: Code Signing Certificate.
Getting Started with Dynamic Scripting
For example, suppose the use has a simple PowerShell script, 'script.ps1' which contains the following commands:
|
To deploy this script, the user types the following from a PowerShell window.
invoke-tachyondynamic -script script.ps1 -targetscope XYZ
where XYZ is an example scope that would send the instruction to all devices whose FQDN contains "XYZ"
Note
The -targetscope parameter accepts more complex scope expressions. These give you great flexibility in choosing the target endpoints to which the instruction will be deployed. See Using scope and filter expressions with the Tachyon PowerShell Toolkit for more information on scope expressions
The screenshot below shows an example of running the script in a test lab with five devices.
Running an executable command instead of a script
Simply specify -Executable and the path to an executable file, instead of the -script parameter.
Parameters
Use the -Parameters option to supply one or more parameters to a script or executable file. A single parameter is just specified as a string. Specify an array to pass multiple parameters i.e @("param1value", "param2value",...)
Result format
By default, the results are returned as a dictionary keyed by device FQDN. Each dictionary value for a successful invocation is an object with two members
Exitcode - an integer as returned by the Tachyon instruction API. 0 indicates success. 2 indicates failure.
Output - a string value in Tachyon (now a string in PowerShell), that contains the output from the script as a simple string.
Overriding the standard result format
You can specify an alternative schema for the results to be returned from a script. Use the -Schema option to provide an alternative schema.
The script you invoke is assumed to return results in JSON that match the schema you provide. When you invoke a script like this, the results are returned in a PowerShell object whose properties match those of the schema you define.
The PowerShell script can return an array in JSON. If it does, then the results will be returned in an array of objects instead of a single instance.
 |
Error results
One endpoint in the lab has PowerShell execution disabled. This results in the Tachyon instruction failing. When an instruction fails, an alternate data set consisting of an object with two members is returned as the dictionary entry, still keyed by FQDN
Status - An integer code indicating the failure reason.
ErrorData - Any additional data associated with the failure
Note
The same convention for error handling is used elsewhere in the package. Wherever instruction results are returned to PowerShell, if the instruction fails on an endpoint, then the result row for that endpoint will contain the error results as defined above. Otherwise, it will contain an arbitrary set of object properties which map to the output schema of the instruction itself.