Scenarios using the instruction XML cmdlets

This article describes walk-through scenarios where you can use the 1E PowerShell Toolkit instruction XML cmdlets to assemble new 1E Platform instructions.

Unlike the instructions that you run using the invoke-1Edynamic cmdlet, these instructions are intended to remain permanently available on the platform. Therefore, you need to consider some specific information that you will supply during the process of creating the instruction.

Choosing an instruction name, description, and type

The information that you will need to supply when creating the permanent instruction includes the following:

  • Should this instruction be a question or an action?

    Recall that actions are subject to platform workflow approval and are intended for instructions that alter the state of a 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 in the 1E Platform. 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 the 1E Platform, you need to sign it. For 1E-supplied instructions, instruction prefixes are typically 1E-Exchange, 1E-Core, and so on. For your own instructions, the prefix will normally be allocated for you when you request a code signing certificate. Additionally, your platform license must specify the prefix or prefixes that 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 that is signed and then uploaded to the platform. Normally the XML file name matches the instruction name, though this is not required.

Preparing a PowerShell script from a permanent instruction

When you use the invoke-1Edynamic cmdlet to run a PowerShell script, it creates a dynamic instruction and then runs it.

For example, if we want to create a permanent instruction that runs the script.ps1 script that we ran using invoke-1Edynamic, we can use the new-1Einstructionxml cmdlet. The entire command is the following:

Copy 
new-1Einstructionxml -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 1E Client SCALE language has to be added to download the script and run it.

To make this easier, the new-1Eresource cmdlet automatically creates all the information that is required and then it bundles that into a standard PowerShell object that specifies the resource. In this example, 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-1Eresource).

Having a closer look at the resource object

This resource object 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. (Refer to Instruction XML management cmdlets.) For example, you can create resource objects that copy the embedded resource to a specified folder on the target devices, rather than execute it. You can specify for a script that the results should be interpreted as JSON rather than text, and so forth.

Copy 
New-1EResource -path script.ps1 -execute | format-list *

Signing the new instruction

Our new instruction isn't of much use yet. It has neither been signed nor uploaded to the 1E Platform. To sign the instruction, we use the protect-1Einstructionxml cmdlet.

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 platform instruction signing utility (Tachyon.InstructionSigner.exe) in the current folder.

Our cmdlet invocation looks like this:

Copy 
protect-1Einstructionxml -path 1E-Exchange-RunTestScript.xml

Uploading (publishing) the new instruction

We now need to make the instruction available to the platform. To do this we publish, or upload, the instruction, specifying a destination instruction set that we would like it to belong to.

The 1E Platform allows you to grant permissions to specific instruction sets, which is a convenient way of grouping instructions and delegating rights to them. Platform 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-1Einstructionset cmdlet. The example below assumes that the instruction set has already been created.

Copy 
publish-1Einstruction 1E-Exchange-RunTestScript.xml -instructionset AJM

In this example, the instruction will be uploaded to the instruction set AJM, which must already exist.

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 the following is true:

  1. The new instruction has a version number greater than the existing one. (There is an optional -Version parameter for the new-1Einstructionxml cmdlet to handle this; the default is 1.0.)

    AND

  2. There are no active instructions running based on that instruction.

For convenience, the publish-1Einstruction cmdlet has a -force parameter that allows you to always replace an existing instruction of the same name. It does this by canceling 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 the new instruction

We can now run our new instruction. There are several ways to do this.

Running the instruction from the Toolkit search cmdlet

We can interactively search and execute it by using the search-1Einstruction cmdlet, then entering run test script in the search, and then running it.

Invoking the instruction directly

We can run our new instruction with the invoke-1Einstruction cmdlet where <scope> is the target scope of the devices you want to target with the instruction.

Copy 
invoke-1Einstruction 1E-Exchange-RunTestScript -targetscope <scope>

Although the -targetscope parameter accepts arbitrarily complex scope expressions, entering a simple string is always regarded as shorthand for fqdn like %<string>% because this is such a common mechanism for defining the scope of the endpoints you wish to target.

Turning the instruction into a cmdlet

We can also turn our new instruction into a cmdlet and then run that.

Copy 
new-1Ecmdlet -instruction 1E-Exchange-RunTestScript -cmdlet Invoke-TestScript
import-module .\invoke-testscript.psm1

invoke-testscript -targetscope <scope>

Using the resource management cmdlets to upload a resource to the background channel

Instructions that use large resources may wish to dynamically download those resources. Otherwise, if Content Distribution is not enabled on the platform, large resource files (for example, 150M) would have to be downloaded each time to the target endpoints. This could result in significant network traffic.

One way to get a dynamic, changing resource file up to the background channel would be to use the TIMS authoring tool and create an instruction, then select Import Resource and then upload the instruction to the platform. This will put the resource into the background channel. If the resource file changes, you would have to repeat this process, loading the instruction into TIMS, updating the resource from a fresh copy of the file, and then re-uploading the changed instruction.

You can also script this sequence of operations with the 1E PowerShell Toolkit. In the example below, a large ZIP file is automatically inserted as a resource into a newly-created instruction, then the instruction is signed, and then uploaded, overwriting any existing copy. This will put the resource into the platform Background Channel.

Copy 
new-1Einstructionxml -name 1E-Demo-AIEngineResource -path 1E-Demo-AIEngineResource.XML -ReadablePayload "AIEngine Resource Instruction" -Content (new-1eresource g:\downloads\1e-aisentimentengine.zip)
protect-1einstructionxml 1e-demo-aiengineresource.xml
publish-1einstruction 1e-demo-aiengineresource.xml -instructionset ajm -force