1E PowerShell Toolkit

The 1E PowerShell Toolkit allows you to use PowerShell to automate the 1E Platform by exposing many features as PowerShell cmdlets. This includes deploying and managing platform instructions, management of users and roles, creation of management groups, and many other features. The Toolkit is implemented in PowerShell itself. For information about installing the Toolkit and the Toolkit's files, refer toInstalling the 1E PowerShell Toolkit.

PowerShell Integrated Scripting Environment (ISE): 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 1E 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 under the ISE run much slower than they do in a regular PowerShell environment. This is because the ISE is primarily intended for script debugging.

Consequently, in most situations, you should run the 1E 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 is being continuously developed and the feature list may change at any point. For the latest changes, refer to 1E PowerShell Toolkit release notes.

The 1E PowerShell Toolkit provides the following key features:

  • Dynamic Scripting:You can run a PowerShell script or executable program on devices via the 1E Platform, without first creating an instruction. Refer toDynamic Scripting and running an executable command.

  • Dynamic SCALE:You can run a SCALE snippet on devices via the 1E Platform without first creating an instruction. Refer toDynamic SCALE.

  • 1E Activity Record queries:You can directly query any persistent 1E Platform table on a device via PowerShell. Refer toQuerying Activity Records.

  • Dynamic file copy: You can send one or more files to devices and have them copied to a specified folder. Refer to Dynamic file copy.

  • Interactive instruction search: You can interactively search for existing instructions from a PowerShell command prompt just as you would when using Endpoint Troubleshooting and then execute the instruction selected. Refer to Interactive instruction search.

  • Interactive search and cmdlet creation: You can interactively search for a platform instruction from the PowerShell command prompt and then create a cmdlet from the instruction for re-use in the PowerShell environment. Refer to Creating cmdlets from interactive search.

  • Dynamic instruction execution: You can invoke any pre-existing platform instruction from PowerShell, supplying parameters as appropriate. Refer to Executing an instruction.

  • Workflow management: You can authenticate action invokers and approve or reject actions. Refer to Workflow management cmdlets.

  • Staged rollouts: You can stage rollouts by targeting a percentage or defined count of devices with a platform 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. Refer to Staged rollouts.

  • OSQuery integration: OSQuery is a powerful open-source solution that supports a wide range of device queries. The OSQuery integration allows you to easily query any OSQuery resource directly from PowerShell. Refer to OSQuery integration.

  • WMI integration: The WMI Integration lets you launch a WMI query directly from a PowerShell cmdlet and target devices as appropriate. Refer to WMI integration.

  • Instruction XML file management: You can dynamically create an instruction XML file and embed resources such as scripts and executable files into it, and then auto-generate SCALE code to run them. Refer to Instruction XML management cmdlets.

  • Secure credential management: You can securely send credentials or secrets to devices for them to be stored in the Windows Credential Store. This allows you to then securely retrieve these credentials from other platform instructions and use them to access secured resources. Refer to Credential management cmdlets.

  • 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, and then programmatically synchronize these with the platform. Refer to SLA management groups and rule expressions.

  • Using the 1E PowerShell Toolkit to manage platform schedules: You can create and manage platform schedules and associate these with conditional evaluation scripts which run server-side when a scheduled instruction is run. Refer to Managing platform schedules.

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 1E PowerShell Toolkit has been tested against PowerShell Core 7.0.3 and is fully functional on the Windows platform.

PowerShell Core, which is fully supported by the 1E PowerShell Toolkit, is considerably faster than legacy PowerShell. Consequently, if you are running platform instructions that return large amounts of data, you may want to consider installing PowerShell Core and running the 1E PowerShell Toolkit under that. In tests, some operations ran up to five times faster in PowerShell Core.

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

PowerShell Core and non-Windows platform support

The 1E PowerShell 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.

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 (VS) Code is a more modern and full-featured alternative to the PowerShell ISE. If you want to debug and develop with the 1E PowerShell Toolkit, you may want to consider using VS Code. To learn how to set up and use VS Code in conjunction with the Toolkit, refer to Installing and using Visual Studio Code.

Platform management PowerShell cmdlet reference

The 1E PowerShell Toolkit provides a number of cmdlets which let you directly interact with the 1E Platform. Using these, you can invoke instructions, list instructions and instruction sets, and perform other platform management operations directly from PowerShell. For more information, refer to1E Platform management cmdlets.

How Dynamic Scripting and Querying works

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

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

  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 PowerShell toolkit signs the _temp.xml file with the user’s code signing certificate.

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

  5. The instruction is executed and the results are returned.

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.

The 1E Platform Consumer API is used to perform all interactions with the platform. Therefore, the user cannot perform any action their platform 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, refer to Instruction XML management cmdlets.

Script customization

Refer to Script customization in Requirements for using the 1E PowerShell Toolkit.