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
Dynamic Scripting and executable command execution using the Tachyon PowerShell Toolkit - you can run a PowerShell script or executable program on devices using Tachyon, without first creating an instruction.
Dynamic SCALE - you can run a SCALE snippet on devices using Tachyon without first creating an instruction.
Querying Tachyon Activity Records using the Tachyon PowerShell Toolkit - allows user to directly query any persistent table on a device using PowerShell.
Dynamic File Copy- allows user to send one or more files to devices and have them copied to a specified folder.
Interactive instruction search using the Tachyon PowerShell Toolkit - you can interactively search for existing instructions from a PowerShell command prompt just as they would from the Explorer, then execute the instruction selected.
Interactive instruction search using the Tachyon PowerShell Toolkit - you can interactively search for an instruction from the PowerShell command prompt and then create a cmdlet from the instruction for re-use in the PowerShell environment.
Executing an instruction using the 1E PowerShell Toolkit - you can invoke any pre-existing instruction from PowerShell, supplying parameters as appropriate.
Workflow management cmdlets - you can authenticate action invokers, and approve or reject actions.
Staged rollouts using the 1E PowerShell Toolkit - you can stage rollouts by targeting a percentage or defined count of devices with an instruction, and keep track of the progress of the rollout. The user can then re-run the instruction, automatically targeting a fresh set of devices, allowing progressive rollout to the entire estate in a series of tranches.
OSQuery integration - OSQuery is a powerful open-source solution that supports a wide range of device queries. OSQuery integration allows you to easily query any OSQuery resource directly from PowerShell.
WMI Integration - WMI Integration lets you launch a WMI query directly from a PowerShell cmdlet and target devices as appropriate.
Instruction XML management cmdlets - you can dynamically create an instruction XML file, and embed resources such as scripts and executable files into it, then auto-generate SCALE code to run them.
Credential management cmdlets - you can securely send credentials or secrets to devices, to be stored in the Windows Credential Store. This allows you to then securely retrieve these credentials from other instructions and use them to access secured resources.
SLA management groups and rule expressions - you can define management groups and leverage the sophisticated rule management engine in the SLA subsystem to create groups and rules, then programmatically synchronize these with Tachyon.
Using the Tachyon PowerShell Toolkit to manage Tachyon schedules - you can create and manage schedules, and associate these with conditional evaluation scripts, which run server-side when a scheduled instruction is run.
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 Tachyon 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
Tachyon Management PowerShell cmdlet reference
The toolkit provides a number of cmdlets which let you directly interact with Tachyon. 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.
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 Tachyon. 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 Tachyon Consumer API is used to perform all interactions with Tachyon. Therefore, the user cannot perform any action their Tachyon 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