Dynamic Scripting and running an executable command

The standard 1E Platform environment assumes that a user wishing to deploy a script or executable command via the platform will package up this script or command via the Tachyon Instruction Management Studio (TIMS) authoring tool. However, it may 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, uploaded to the 1E Platform server, and assigned to a specially created instruction set reserved for dynamic instructions. It is then executed and the results are returned directly to the caller.

As an alternative to a script, you can also specify an executable command to be run.

To use this feature, you must enable code signing. Refer to Code signing certificate.

Getting started

A user may have a simple PowerShell script (script.ps1) containing the following commands:

Copy 
$hostname = $env:COMPUTERNAME write-host "This script was run on " $hostname

To deploy this script, the user types the following from a PowerShell window, where XYZ is an example scope that would send the instruction to all devices whose FQDN contains XYZ:

Copy 
invoke-1Edynamic -script script.ps1 -targetscope XYZ

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. For more information on scope expressions, refer to Scope and filter 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, that is, @("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 platform instruction API. 0 indicates success. 2 indicates failure.
  • Output: A string value in the 1E Platform (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 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.

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, 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.