Instruction XML management cmdlets
Reference for the Instruction XML management cmdlets. These cmdlets allow you to create or modify instruction XML files, which can then be uploaded to Tachyon.
About instruction XML files
Tachyon instruction XML files are the standard encoding for Tachyon instructions. Within an XML file, an instruction contains content, which is written using the SCALE language, and optionally one or more resources which correspond to embedded files. Resources in an instruction XML file are copied to the Tachyon background channel server when the instruction is uploaded to Tachyon. Subsequently, they can be retrieved during instruction execution and then used in the instruction. Typically, an embedded resource is a PowerShell script or an executable file, but embedded resources can specify any file that is appropriate.
When embedded resources are downloaded, the Nomad file distribution subsystem ensures they are transmitted to devices efficiently and quickly without consuming unnecessary network bandwidth.
Managing XML instructions
The XML management cmdlets provide two key areas of functionality
Dynamic instruction Execution
The Tachyon dynamic instruction invocation functionality creates XML instructions which are uniquely named, and then uploads and executes them. As discussed on the individual pages on dynamic functionality, you can use dynamic instruction invocation to
Run a PowerShell script on devices
Run an executable program on devices
Query any of the Tachyon Activity Record tables on devices
Run a piece of SCALE code on devices
Copy one or more files to a specified location on devices
These functions are carried out via the invoke-dynamic cmdlet, whose syntax is discussed below
Permanent instruction management
You can also use create permanent instruction files using the XML management cmdlets. These can contain arbitrary SCALE payloads. As a convenience feature you can also wrap any inbuilt SCALE function in a permanent instruction. This makes it easy to leverage the powerful Tachyon agent capabilities directly.
Creating instructions dynamically
As discussed above, the 'invoke-dynamic' cmdlet is the core cmdlet used when creating dynamic instructions. Using this cmdlet you can execute a script, run an executable program, embed a SCALE snippet or query any Tachyon Activity Record table quickly. You can also use it to create an instruction which will copy one or more files to a specified path on the target devices.
Invoke-TachyonDynamic -Script|-Query|-Scale|-Executable|-Files <path|query> [-Path <path>] -TargetScope|-TargetFqdns <scope|fqdns> [-Force] [-Parameters <parameters>] [-Schema <schema>] [-DataSource <datasource>] [-RowSourceType <rowsourcetype>]
The -script argument must be followed with the name or path to a PowerShell script
The -query argument must be followed by an appropriate query to a Tachyon Activity Record table
The -scale argument must be followed with the name or path to a file containing the SCALE code to be run
The -executable argument must be followed with the name or path to an executable file
The -Files argument must be followed with the name of one or more files. To specify multiple files, use a PowerShell array
The -Path argument is ignored unless the -Files argument is specified. If -Path is specified, it defines the absolute path to which the files specified will be copied on the target devices
The -Force argument is ignored unless the -Script argument is supplied. If specified, it causes the generated SCALE to override the PowerShell execution policy on the target device(s) so that the script will execute regardless of local execution policy.
The -Parameters argument optionally specifies one or more parameters as a string or a string array e.g "param1" or @("param1","param2",...)
If specified, these parameters are passed to the invoked script or executable. The parameters argument is currently ignored for the -query and -scale options.
The -Schema argument optionally provides an alternative schema for the results to be returned by the script, query or scale snippet. By default, the schema for these results is defined as an int64 ExitCode value and a String(8000) Output value.
The -DataSource argument specifies the data source for a server-side instruction. If supplied, this infers that the instruction is to run server-side. It is only effective if the -Scale argument has been provided to supply an instruction payload, otherwise, it is ignored
The -RowSourceType argument specifies the type of row set that should be returned for a server-side instruction. If not specified, a default of Generic will be used.
If you override the schema then the script, query or scale snippet is assumed to return results that match the schema you provide. For a script, it should provide the results back in JSON format so they can be serialised correctly.
This argument is ignored for the -Files option
Protect-TachyonInstructionxml -Path <filepath>
Invokes the Tachyon instruction signing tool. The instruction file will be signed with the user's instruction code signing certificate, which must be in the local machine certificate store under the Personal store location.
An XML file must be signed before it can be uploaded. To upload a signed XML file, use the publish-instruction cmdlet, which is documented on the Tachyon Instruction Management cmdlets page.
Note
You may need to configure the Tachyon Instruction signing tool, which is used by the PowerShell toolkit, before signing instructions. To configure the signing tool, locate the configuration file, which is called Tachyon.InstructionSigner.exe.config and located in your PowerShell toolkit installation folder.
The shipped copy of the configuration file is shown below.
You may want to change the following settings (note that the SigningExecutable value is not used in the context of the PowerShell toolkit and will not require configuration)
The Signing.StoreLocation setting can be either "CurrentUser" to look for the certificate in the current user's certificate store, or "LocalMachine" to look for the certificate in the local machine certificate store
The Signing.StoreName setting specifies which named store entry is to be searched for a certificate. The default setting, "My", specifies that the Personal certificate store entry is searched
The Signing.Subject setting specifies the allowable subject name for a code signing certificate. If set to "*", any subject is accepted. Otherwise the subject must match the value specified. As shipped, this is set to any subject.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<appSettings>
<add key="SigningExecutable" value="C:\Program Files (x86)\Windows Kits\10\bin\x64\signtool.exe"/>
<add key="SigningParameters" value=""/>
<!-- Signing certificate store, e.g., My (Personal), TrustedPublisher (Trusted Publishers) etc. -->
<add key="Signing.StoreName" value="My"/>
<!-- Signing certificate location. Valid values LocalMachine and CurrentUser. -->
<!-- If you are signing the resources then this has to be CurrentUser -->
<add key="Signing.StoreLocation" value="LocalMachine"/>
<!-- To find certificate from cert store using subject name. This value can be set to "*" to mean "use the first active certificate in the StoreLocation that contains a private key" -->
<add key="Signing.Subject" value="*"/>
</appSettings>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6"/>
</startup>
</configuration>
Set-TachyonDynamicinstructionset -Name <set name>
Sets the name of the instruction set to be used when publishing and running dynamic instructions. By default this is 'DynamicScripting' but you can use this cmdlet to override it. The instruction set is created automatically when an instruction is first published to it.
Get-TachyonDynamicinstructionset
Returns the current dynamic instruction set name
Set-TachyonInstructionPrefix
Sets the instruction prefix to be used when creating dynamic instructions. The default will be the value of the $INSTPREFIX variable in the tachyondynamic.psm1 module file.
Get-TachyonInstructionPrefix
Gets the instruction prefix to be used when creating dynamic instructions.
Creating permanent instruction XML files
You may also wish to create instructions which are intended for long-term use. Unlike the dynamically created instructions associated with the invoke-dynamic cmdlet, these instructions are intended to be uploaded to Tachyon and then used repeatedly.
The dynamic instruction invoke-dynamic cmdlet is convenient when you want to create ephemeral instructions to perform simple tasks. For more complex instruction management tasks, you can use the cmdlets below to create permanent instructions in Tachyon. These cmdlets simplify the process of creating instruction XML files which can then be uploaded to Tachyon, or loaded into the TIMS authoring tool for further modification.
Some useful scenarios using the instruction XML management cmdlets
The material below is a reference guide to the cmdlets. For some practical scenarios using these cmdlets, please refer to Some useful scenarios using the instruction XML cmdlets.
New-TachyonInstructionxml -Name <name> -Path <path> -ReadablePayload <payload> -Content <content> [-Description <description>] [-Schema <schema>] [-Resources <resources>] [InstructionType <type>] [-Version <version>] [-Parameters <params>
-Name. Specifies the name of the instruction. If not fully specified e.g with the appropriate instruction prefix e.g 1E-Explorer, then the prefix will automatically be added. For example a name of MyInstruction will become 1E-Explorer-MyInstruction if the code signing certificate and instruction prefix are set for 1E-Explorer.
-Path. Specifies the name and path of the XML file to be created
-ReadablePayload. Specifies the readable payload which the instruction will define. For example 'return all local disk drives'
-Content. Specifies the SCALE code that will be contained in the instruction. Optionally you can specify a resource object, which is returned from the New-Resource cmdlet discussed below. This will add both SCALE content and a resource to the XML instruction.
-Description. Specifies a description for the instruction. If not specified, the ReadablePayload property is used.
-Resources. Specifies one or more resource files to be embedded in the instruction. To specify multiple resources, pass them as an array e.g @("ResourceFile1.ps1","ResourceFile2.exe")....
Note
You do not need to specify resource files in the -resources property if you use the new-resource cmdlet to manage them. This is because the object returned by new-tachyonresource is automatically understood by new-tachyoninstructionxml to be a resource specification. The purpose of having the -resources property is to allow you to embed additional resources that you will manage in SCALE code yourself.
If you just want a single resource in an instruction to execute, you will probably find it easier to use new-resource, as discussed below, to automatically manage this process.
-InstructionType. Either 'Question' or 'Action'. The default is 'Question'
-Schema. Specifies a schema for the instruction. If not specified, the default schema is used. The default schema is 'ExitCode int64, Output string(8000)'.
Note
Instruction schemas are discussed in more detail in the section 'schemas' below
-Version. The version for the instruction. If not specified, a version of '1.0' is used.
-Parameters. A set of parameters for the instruction. See the section on 'instruction parameters' below
Instruction Parameters
Instructions may define one or more input parameters. Input parameters form part of the instruction's readable payload and are then substituted into the instruction body. For example, an instruction might define a parameter 'UsbOnly' which might be provided to an instruction that was intended to report all device drivers found. Then if this parameter was set, it would cause the instruction to report only USB devices. The mechanism for doing this would be defined in the instruction's SCALE code.
Simple instruction parameters
You can define an instruction parameter list as a simple set of named parameters e.g
MyParam1, MyParam2, ....
In this case the parameters are assumed to be simple unconstrained string parameters,
For example, suppose we create a simple instruction that simply returns the parameters that were passed in.
new-tachyoninstructionxml -name paramdemo -path paramdemo.xml -readablepayload ParamDemo -Content 'select "%Param1%" result1, "%Param2%" result2;' -Parameters "Param1, Param2" -schema "result1 string(256), result2 string(256)"
For clarity, this has been split out over several lines
This defines a simple instruction with a single line of SCALE in the payload. The SCALE payload simply selects the passed-in parameters, which are always referred to with % characters around them, and aliases them to two return columns, result1 and result2.
The -schema argument then defines these two result columns as string(256).
When we create this instruction, and then sign and upload it to Tachyon, then when we invoke it, we see this
 |
 |
You can see that the instruction now has two parameters which are mandatory. The values you supply are then in this case simply returned as the result of the command.
The instruction's readable payload includes the parameters. This information is used by the Tachyon Explorer UI to show the instruction and its parameters when it is invoked from the Explorer.
Complex parameters
Parameters can be defined to have a specific data type, which is one of the following
String
Int
Float
Date
Time
They can also be specified to have a default value. The default value is used if it is not specifically overridden when the instruction is invoked
To specify complex parameters to an instruction, you need to create an array of objects, which define the parameters and their data type and default values (if any).
To understand how to create this object array, see the section below on SCALE method parameters. The cmdlet which retrieves SCALE method parameters creates an array of objects in the required format.
This is because normally when you use this feature, you will be creating instructions that invoke SCALE methods. However you can manually create the required object array if you wish.
Creating an instruction which Invokes a SCALE method
SCALE provides a large number of inbuilt methods that the device agent can execute. These provide sophisticated cross-platform capabilities. You might want to invoke one of these methods directly in an instruction.
For a full list of available methods see the link here Tachyon Agent Methods
You can also use the get-tachyoninfo cmdlet to get information on all methods, or detailed information for any individual method. This is discussed in more detail below
A detailed example can be found here Some useful scenarios using the instruction XML cmdlets
You can also explore a scenario where we author an instruction using the Tachyon Instruction Management Studio (TIMS) tool and then create a similar instruction directly from PowerShell that calls an agent method here Creating your own cmdlet from a Tachyon instruction
For example, the Patch.List method returns the status of Microsoft patches on a target device. You can easily create an instruction which invokes any SCALE method, providing the required parameters, and with the output schema automatically created for you.
You do this using the new-instructionxmlformethod cmdlet, which is discussed in more detail below
When you use this cmdlet, code to run the specified method is translated into a Tachyon instruction XML file, ready to be signed (using the protect-instruction cmdlet) and uploaded (using the publish-instruction cmdlet) to Tachyon.
Any parameters associated with the method are automatically created as instruction parameters and will be passed to the method when the instruction is executed.
Once you have uploaded the instruction, you can run it from PowerShell using the invoke-instruction cmdlet, or turn it into a PowerShell cmdlet using the new-cmdlet cmdlet.
New-TachyonInstructionXmlForMethod -MethodName <method> [-IncludeOptionalParams] [-OptionalParams <params>]
-MethodName is the name of the scale module and method. For example Patch.List
-IncludeOptionalParams. If specified, optional parameters for the method are also included as parameters to the instruction. For example, Patch.List has five optional parameters and no mandatory parameters. If the -IncludeOptionalParams switch is not specified, then no parameters are specified for the instruction. If -IncludeOptionalParams is specified, then all three optional parameters are specified as instruction parameters.
-OptionalParams. This parameter allows you to specify that optional method parameters will be included as instruction parameters. If not specified, optional method parameters are not included as instruction parameters.
This is because optional method parameters do not necessarily have default values, and may change the behaviour of the method if specified, so you don't normally want to include them unless you are going to provide values for them.
When the OptionalParams parameter is specified, it allows you to supply a list of parameters separated by commas that, if they correspond to method parameters, will be included in the instruction input parameters. For example, the Patch.List method has the optional parameters, Source, PatchSpec, CheckOnline, CabFilePath and TimeoutSecs. You can specify that any or all of these optional parameters will be included in the input parameters for the generated instruction by specifying them in the -OptionalParams argument. For example, to include the Source and PatchSpec arguments, specify -OptionalParams "Source, PatchSpec"
Now when you run the generated instruction it will support the optional parameters -Source and -PatchSpec
Note
This cmdlet uses a file packaged with the PowerShell toolkit, methods.json. This file contains metadata about all available SCALE methods and their parameters.
You can examine this information with the Get-TachyonMethodInfo cmdlet, discussed below.
This file is correct as of Tachyon 5.2. You can automatically create this file using the Tachyon Instruction Management Studio (TIMS) tool. Versions of TIMS shipped with Tachyon 5.2 and subsequent resources support the ability to export all SCALE methods to a metadata file, which you can then use to replace methods.json.
To export the data, run the TIMS tool with the /debugging command line option and then select the Tools/Download SCALE metadata option from the menu. Replace the methods.json file in the toolkit with this newly-created file and you will have an up-to-date list of methods that the toolkit can use when creating instructions and cmdlets.
 |
Get-TachyonMethodInfo [-MethodName <method name>]
Retrieves information about all SCALE methods or a selected method.
 |
Examining SCALE method parameters and schemas
Each SCALE method takes zero or more parameters, and returns a result set which is defined by a schema.
To examine the parameters and schema, use the get-methodparameters and get-methodschema cmdlets
Get-TachyonMethodParameter -MethodName <method name> [-NoTranslate]
Returns the parameters associated with a method. The -NoTranslate option causes the parameters to be returned with their data types and default values as defined directly for the method.
However these data types and default values do not always map directly to the available input parameters for instructions. Therefore by default they are translated. For example, a parameter of type 'boolean' with a default value of 'true' is translated to be of type 'int' with a default value of 1, because instruction parameters do not support boolean types.
The example below shows the available method parameters for the 'Agent.Echo' method
 |
Get-TachyonMethodSchema -MethodName <method name> [-AsText]
Returns the schema for a method. If the -AsText option is specified, the schema is returned in text form. In this format, it can be directly supplied as the -schema argument to new-instructionxml if you wish.
Note that when you use the New-InstructionXmlForMethod cmdlet, this cmdlet is used internally to ensure that the generated instruction has the appropriate schema.
 |
New-TachyonResource -Path <path> [-ResourceVar <varname>] -CopyTo <destpath> [-Execute] [-InterpretAsJson] [-Force] [-Parameters <parameters>] [-Schema <schema>]
Returns a resource object which can be used directly as an argument to the -Content property of the New-TachyonInstructionXml cmdlet. Resource objects are discussed in more detail below
-Path. Specifies the path to the file to be used as the resource object
-ResourceVar. If specified, defines the SCALE variable name to be used when retrieving the resource. If this is not specified, a default name 'Resource' is used, as you can see in the examples below.
-CopyTo. If specified, causes the resource object SCALE code to include code to copy the embedded resource to the specified destination path
-Execute. If specified, causes the resource object SCALE code to include code to execute the embedded resource. This option is mutually exclusive with -CopyTo.
-InterpretAsJson. If the -Execute option is set, specifies that the resource object SCALE code to execute the resource should require that the results from executing the resource be interpreted as Json
The -Force argument is ignored unless the -Execute argument is supplied and the resource object is a PowerShell script. If specified, it causes the generated SCALE to override the PowerShell execution policy on the target device(s) so that the script will execute regardless of local execution policy.
-Parameters. Specifies one or more parameters to be passed to the executed resource. Multiple parameters are defined as an array.
-Schema. If specified, overrides the default schema which is "ExitCode Int64, Output string(8000)"
Using New-TachyonResource in conjunction with New-TachyonInstructionXml
The New-TachyonResource cmdlet is intended to simplify the creation of instructions that use embedded resources. In many cases the resources are intended to be executed, which requires some SCALE code to be created. New-TachyonResource automates this process.
The simplest usage of New-TachyonResource is to specify just a source file. In this case the -Path parameter is assumed by PowerShell.
The output from New-TachyonResource is a resource object. It contains the resource type, the SCALE content which will load the resource inside an instruction, a full path to the resource file, and a schema, which is currently fixed to define an exitcode and output result.
 |
If the optional -Execute parameter is passed to New-Resource then the SCALE code includes the necessary code to download and execute the resource instead of just downloading it.
In this case two SCALE variables are used. The second variable will be named xxxResult where xxx is the value assigned to the -ResourceVar property. By default, since we did not specify it, it is set to 'Resource' so the second variable is named ResourceResult.
You can pass the object returned by New-Resource to the new-Tachyoninstructionxml -Content parameter
For example
new-Tachyoninstructionxml -name MyInstruction -path MyInstruction.XML -ReadablePayload "My New Instruction" -Content (new-resource script.ps1 -execute)
When you do this, new-Tachyoninstructionxml automatically adds the resource to the instruction and adds the code to execute it. This means that the resulting instruction will immediately be useable to execute the resource specified. You need only sign it with protect-instruction, then upload with publish-instruction and then run it.
Note
The instruction name in this example was given as 'MyInstruction'. When the instruction XML file is created, this will automatically contain the full prefixed instruction name. The full prefixed name depends on the name prefix that you have defined using the Set-InstructionPrefix cmdlet. For example, if the instruction prefix is 1E-Explorer then the full instruction name will be 1E-Explorer-MyInstruction.
In order to sign and subsequently upload the instruction for execution, you need to possess a code signing certificate and you need a Tachyon license for the instruction prefix that you are using.
Running executables instead of scripts
New-TachyonResource also handles executable resources. Additionally, you can pass parameters both to scripts and executables. For example, suppose we wanted to run the devcon.exe utility and pass it a parameter 'classes'
As you can see, the SCALE code to download the resource, then append the parameters and execute it is automatically generated.
 |
You can use the -InterpretAsJson parameter to New-TachyonResource to specify that the results from the resource should be interpreted as JSON. Note that in this case you will probably want to override the default schema for the instruction, which is suitable for simple scripts and executables, and define the results you want to return as a set of columns.
Get-TachyonResourceInfo -Path <path>
Returns information about all embedded resources in the instruction XML file referenced by <path>
 |
Export-TachyonResource -Path <path> -Name <name> [-Outfile <outfile>]
Exports the resource whose name is specified. If -Outfile is not specified, an output file whose name corresponds to the resource name is written to the current directory. Otherwise it is written to a file specified by -OutFile
Instruction Schemas
An instruction must define the schema of the result set that it returns. A default schema which is adequate to run embedded resources that do not return JSON is automatically used unless you override it. The default schema specifies two columns, an integer ExitCode and a string(8000) Output.
Tachyon supports the following data types:
int32
int64
string
clob
guid
datetime
double
bool
You define your schema by simply listing the column names and types, for example:
column1 string(200), column2 int32, column3 double
If you do not specify a string length, a value of 256 is used by default.
Note
Column names are case-sensitive. You must specify a column name to exactly match the case of the returned data in your instruction.
The Get-TachyonMethodSchema cmdlet returns a schema directly useable as an instruction schema when the -AsText option is specified.