Skip to main content

1E 23.7 (SaaS)

Key features and concepts of the 1E PowerShell Toolkit

The toolkit allows you to use PowerShell to automate the platform by exposing many features as PowerShell cmdlets. This includes deploying and managing instructions, management of users and roles, creation of management groups, and many other features. The toolkit is implemented in PowerShell itself.

Note

This toolkit is being continuously developed and so the feature list may change at any point; documentation will be updated accordingly. For latest changes, please refer to Release history.

Please refer to Installing the 1E PowerShell Toolkit for detail about installation and the toolkit's files.

Important note about the PowerShell ISE (integrated scripting environment)

When you request PowerShell by typing 'PowerShell' at the Windows start prompt, you are taken into an instance of the PowerShell ISE, not a standard PowerShell session. While the PowerShell Toolkit will work within the ISE, there are two important considerations:

  • The interactive search feature is not available because the PowerShell ISE does not emulate the single character keyboard input functionality that is used

  • Scripts run under the ISE run much slower than they do in a regular PowerShell environment. This is because the ISE is intended primarily for script debugging.

Consequently, in most situations, you should run the PowerShell Toolkit from a regular PowerShell session. You can start a regular session by just typing 'PowerShell' from the Windows command prompt.

Key features

The 1E PowerShell Toolkit provides the following key functionality. Each bullet point has a link to a page which discusses the feature in more detail

PowerShell Core support

PowerShell Core is Microsoft's platform-neutral implementation of PowerShell. It can be installed to run side-by-side with standard PowerShell.

The PowerShell Core interpreter is called 'pwsh.exe' to distinguish it from the legacy 'powershell.exe'.

The toolkit has been tested against PowerShell Core 7.0.3 and is fully functional on the Windows platform.

Note that PowerShell Core is considerably more performant than legacy PowerShell. Consequently, if you are running instructions that return large amounts of data, you may find it worthwhile installing PS Core and running the toolkit under that. In tests, some operations ran up to five times faster in PS Core.

Note that using PS Core with the toolkit has no impact on the software that is running on 1E platform devices. When you run instructions using the toolkit, the software environment under which the instruction executes at each device can be quite different than the environment from which you are controlling the instruction execution. In other words, using PowerShell Core to invoke instructions using the toolkit does not require PowerShell Core on the target devices.

PowerShell Core and non-Windows platform support

The toolkit will run on non-Windows platforms. At present, only Debian 11.5 has been tested, but any Linux platform that supports the .NET Framework and PowerShell Core should function.

Note that only platform-neutral authentication is supported. NTLM authentication is not functional because PowerShell Core does not support it on non-Windows platforms.

Debugging and developing using Visual Studio Code

Visual Studio Code is a more modern and full-featured alternative to the PowerShell ISE. If you want to debug and develop with the PowerShell Toolkit, you may want to consider using VS Code.

The link below discusses how to set up and use Visual Studio Code in conjunction with the PowerShell Toolkit.

Installing and using Visual Studio Code with the Tachyon PowerShell Toolkit

1E Management PowerShell cmdlet reference

The toolkit provides a number of cmdlets which let you directly interact with 1E. Using these, you can invoke instructions, list instructions and instruction sets and perform other management operations directly from PowerShell. The link below provides more information.

1E PowerShell Toolkit management cmdlet reference

How Dynamic Scripting and Querying works

When a script or query is executed dynamically, the following steps occur:

1. A randomized instruction name based on the code signing certificate licensed prefix followed by a GUID is created.

2. A temporary instruction file, _temp.xml is created. This is a valid instruction that can be loaded into the TIMS authoring tool, for example.

3. The Tachyon.InstructionSigner.exe utility is used to sign the _temp.xml file with the code signing certificate.

4. The _temp.xml file is uploaded to 1E. It is placed into an instruction set called 'DynamicScripting' which is created if necessary.

5. The instruction is executed and the results returned.

Note

A new instruction name is created each time. This ensures that executing instructions that are still within their 'time to live' are not disrupted. However, to avoid old instructions 'piling up' in the DynamicScripting instruction set, each time the invoke-dynamic command is run it will automatically attempt to delete all instructions in that set. If the instructions are still active they will be skipped.

Note

The 1E Consumer API is used to perform all interactions with 1E. Therefore, the user cannot perform any action their 1E privileges would not permit.

Dynamic scripting assumes that the schema for the result set is a 64 bit integer value for ExitCode indicating 0 for success, and a string(8000) value for the results. For scripts, the raw script returned data is passed back in the string value.

For queries or SCALE fragments, the returned data is JSON-encoded and returned back in the string value. The JSON represents an array of rows, with each JSON member representing a column and its value.

This approach allows you to run any script, executable, query or SCALE fragment and return the values without needing to change the instruction schema. However, the instruction XML management cmdlets allow you to specify your own schema if you want to build something more complex. For more information, please reefer to Instruction XML management cmdlets.

Script customization

To customize the pstachyonToolkit.psm1 script, simply change the variables at the top of the script to reflect the environment in which you are working. The current set of customizable variables are shown below.

$TACHYONCONSUMER = "Explorer" # Consumer to use when executing instructions
$INSTPREFIX = "1E-Exchange" # Instruction prefix that you have a license for and corresponding code signing certificate in your local machine cert store
$INSTRUCTIONSET = "DynamicScripting" # Instruction set name where dynamic instructions are created in Tachyon
$MAXTARGETDEVICES = 10 # Maximum number of devices allowed to be targeted by scope; this is a safety-catch to prevent you accidentally sending stuff out to a large device count

Note

If you make changes to this script, you should reload the module using the -force option to ensure that the cached module code is correctly replaced in your PowerShell command instance, as follows:

import-module .\pstachyonToolkit.psd1 -force