Some useful scenarios using the instruction XML cmdlets
Walk-through scenarios where you can use the Tachyon PowerShell instruction XML cmdlets to assemble new Tachyon instructions.
Unlike the instructions that you run using the invoke-dynamic cmdlet, these instructions are intended to remain permanently available in Tachyon. Therefore, you need to consider some specific information which you will supply during the process of creating the instruction.
Choosing an instruction name, description and type
The information that we will need to supply when creating the permanent instruction includes:
Should this instruction be a question or an action? | Recall that actions are subject to Tachyon workflow approval and are intended for instructions that alter the state of an device in some way. For convenience, the default is to assume the instruction will be a question. |
What should the instruction readable payload be? | The instruction readable payload is what will be displayed when you search for instructions either in PowerShell or using the Tachyon Explorer. For example, 'show free disk space'. |
What should the instruction name be? | Instruction names are separate from instruction readable payloads. The instruction name should begin with a prefix for which you have a valid code signing certificate, because to upload the instruction to Tachyon, you need to sign it. Instruction prefixes are typically 1E-Exchange, 1E-Core etc for 1E-supplied instructions. For your own instructions, normally the prefix will be allocated for you when you request a code signing certificate. Additionally, your Tachyon server license must specify the prefix(es) which are valid for use in that installation. You cannot upload or run instructions if you do not have a license entry for the appropriate instruction prefix. |
A typical instruction name might be 1E-Exchange-ShowFreeDiskSpace. The instruction itself will be stored in an XML file which is signed and then uploaded to Tachyon. Normally the XML file name matches the instruction name, though this is not required.
Preparing a PowerShell script from a permanent instruction
On the parent page, you saw how to use the invoke-dynamic cmdlet to run a PowerShell script. However, this cmdlet creates a dynamic instruction and then runs it.
For example, suppose we want to create a permanent instruction in Tachyon that runs the 'script.ps1' script that we ran using invoke-dynamic.
We use the new-tachyoninstructionxml cmdlet to do this. The entire command is:
new-tachyoninstructionxml -name 1E-Exchange-RunTestScript -Path 1E-Exchange-RunTestScript.xml -ReadablePayload "Run Test Script" -Content (new-tachyonresource -path script.ps1 -execute)
The result of running this cmdlet is to create a new file, 1E-Exchange-RunTestScript.xml. Let's have a closer look at the other arguments
The -ReadablePayload parameter specifies that the instruction will appear as 'Run Test Script' when we perform a search
The -Content parameter requires a bit more explanation. Our new instruction wants to run a script. To do this the script has to be embedded in the instruction and then some code in the Tachyon agent SCALE language has to be added to download the script and run it.
To make this easier, the new-tachyonresource cmdlet automatically creates all the information that is required and then it bundles that into a standard PowerShell object which specifies the resource. In this case we specify a path to the script we want to embed, and that we want to include code to execute the script (the -execute parameter to new-tachyonresource).
Having a closer look at the resource object
You can see what this resource object contains. As you can see, it has added the SCALE code required to download and run the resource and it has also defined a default schema for the results. You can override this schema if you wish, along with other options, which are discussed on the reference parent page in more detail. For example you can create resource objects which copy the embedded resource to a specified folder on the target devices, rather then execute it. You can specify for a script that the results should be interpreted as JSON rather than text, and so forth.
Signing the new instruction
Our new instruction isn't much use yet. It has neither been signed nor uploaded to Tachyon. To sign the instruction we use the protect-tachyoninstructionxml cmdlet.
Note
Don't forget that to sign instructions you must have a valid code signing certificate in the local machine Personal certificate store.
If you are not running under an elevated PowerShell command prompt you should use the permissions facility in the certificate manager snapin (certlm.msc) to grant your account access to the certificate private key. This will let you sign instructions without running under an elevated PowerShell session.
You should also have the Tachyon instruction signing utility (Tachyon.InstructionSigner.exe) in the current folder.
Our cmdlet invocation looks like this:
protect-tachyoninstructionxml -path 1E-Exchange-RunTestScript.xml
Uploading (publishing) the new instruction
We now need to make the instruction available to Tachyon. To do this we publish, or upload, the instruction, specifying a destination instruction set that we would like it to belong to.
Note
Tachyon allows you to grant permissions to specific instruction sets, which is a convenient way of grouping instructions and delegating rights to them. Tachyon administrators can of course run instructions in any set.
If you would like to create an instruction set at this point for your test instruction, you can do this with the new-tachyoninstructionset cmdlet. The example below assumes that the instruction set has already been created.
publish-tachyoninstruction 1E-Exchange-RunTestScript.xml -instructionset AJM
In this example, the instruction will be uploaded to the instruction set AJM, which must already exist.
Note
You cannot upload an instruction that replaces an existing instruction of the same name, regardless of whether you specify the same instruction set or a different set, unless
(a) The new instruction has a version number greater than the existing one (there is an optional -Version parameter for the new-tachyoninstructionxml cmdlet to handle this; the default is 1.0)
AND
(b) There are no active instructions running based on that instruction.
For convenience, the publish-tachyoninstruction has a -force parameter that allows you to always replace an existing instruction of the same name. It does this by cancelling any active instructions that are based on the instruction being uploaded and then deleting the existing instruction, before replacing it. This is useful during testing
Running our new instruction
We can now run our new instruction. There are several ways to do this
Running the instruction from Tachyon search
We can interactively search and execute it by using the search-tachyoninstruction cmdlet and then entering 'run test script' in the search, then running it
Invoking the instruction directly
We can run our new instruction with the 'invoke-tachyoninstruction' cmdlet:
invoke-tachyoninstruction 1E-Exchange-RunTestScript -targetscope <scope>
where <scope> is the target scope of the devices you want to target with the instruction.
Turning the instruction into a cmdlet
Or we can turn our new instruction into a cmdlet and then run that
new-tachyoncmdlet -instruction 1E-Exchange-RunTestScript -cmdlet Invoke-TestScript
import-module .\invoke-testscript.psm1 invoke-testscript -targetscope <scope>