Write and approve a script

This page adds a script to the library and approves it. When you finish, the script is signed and ready to run on any number of endpoints or on a schedule. For how the library, signing, and parameters work, see Scripting.

Before you begin

• To write and save a script you need script:manage. To approve it you need script:approve. To test the draft on an endpoint you need script:run_unapproved and command:execute.
• To start from a built-in script, duplicate it: select Actions > Duplicate on its row in Scripts > Library. The copy is a new draft you can edit.
• If the script uses batch, zsh, or Python, make sure script_execution.allowed_interpreters allows that interpreter on the endpoints. See Interpreters.

Write the script

1. Go to Scripts > Library and select New script.
2. On the MSP plan, under Who can use this script, choose This client only or Every client.
3. In Name, enter a name. Optionally enter a Description, a Category, and Tags separated by commas. The library search matches the name, description, and tags, not the body.
4. In Interpreter, choose the interpreter.
5. In Runs on, choose Any or the one operating system the script is for.
6. In Runs as, choose SYSTEM or Signed-in user. This is the default for each run, and a run can change it.
7. Set Timeout (seconds), which defaults to 300, and Output limit (bytes), which defaults to 65536.
8. Under Script, write or paste the body.
9. Under Parameters, select Add parameter for each value the script takes. Enter a Key and a Label, choose a Kind, and optionally enter a Default. For Choice, enter the Choices. Select Required when the run must supply a value. Parameters reach the script as arguments in the order you add them.
10. If the script reports a value to keep on the endpoint, under Collector select This script’s output fills in an endpoint field, then choose the Endpoint field and how to Read the output as: Whole output, JSON, or Key and value. See Endpoint custom fields.
11. Select Save. The script is saved as a draft, version 1.

For example, this PowerShell body takes one Number parameter with the key minimum_age_days:

param(
    [int]$MinimumAgeDays = 1
)

Write-Output "Removing files older than $MinimumAgeDays days."

Import a script file

In the script editor, select Import from file, or drag a file onto the import area or script body. The file must be UTF-8 text, without NUL bytes, and no larger than 256 KiB. From the library, Upload script opens a new script ready to import.

Import fills a blank Name from the file name without its extension. It sets Interpreter from the extension:

Extension	Interpreter
.ps1, .psm1	PowerShell
.bat	Batch
.cmd	cmd
.sh, .bash	bash
.zsh	zsh
.py	Python

An unrecognized extension leaves the interpreter unchanged. If the editor already contains script text, select Replace to confirm replacing it. Review the imported body and settings, then select Save. Importing does not approve or run the script.

Test the draft on one endpoint

1. In Scripts > Library, choose the Drafts view. The library opens on Ready to run, which lists approved scripts only.
2. On the script’s row, select Actions > Run.
3. Under Where it runs, choose one endpoint. A draft cannot run on more than one endpoint, a site, or a device group.
4. Enter the parameter values and select Review, then Run script.
5. Open the endpoint and read the result on its Commands tab. A draft run on one endpoint is a single command, so it does not appear under Scripts

   Batches.

If the endpoint runs signed scripts only, the draft cannot run there. Test it on an endpoint where script_execution.require_signed_scripts is off, or approve it first.

Approve the script

1. In Scripts > Library, on the script’s row, select Actions > Approve.
2. The library shows that the script is approved and signed, and its status changes to Approved.

The script can run on many endpoints at once and on schedules.

On endpoints where script_execution.approval_required applies, the approval must come from someone other than the author of this version. If you wrote it, select Ask for approval on the script’s Approval card or in the row’s Actions, and someone else with script:approve approves it. You cannot approve or turn down your own request. If you are the only person who can edit scripts in the workspace, or nobody else can approve in time, see When you are the only script editor and Emergency approval.

Verify

Open the script. The line under its name reads Version 1, approved., with your version number. History lists the version you approved.

If something goes wrong

Symptom	Cause	Fix
Save is unavailable with Built-in scripts are read-only. Duplicate to edit.	The script ships with Outpost.	Select Duplicate and edit the copy.
Approve is unavailable with You do not have permission to approve scripts.	You lack script:approve.	Ask someone who holds it, such as an owner.
An approved script is a draft again	Its body or interpreter was changed, which clears the approval.	Review the change and approve the new version.
The draft run is refused with This endpoint refuses unsigned scripts	The endpoint requires signed scripts.	Approve the script, or test on another endpoint.
This script needs a second person’s approval before it can run on these endpoints.	script_execution.approval_required applies, and the version was approved only by its author, or not at all.	Select Ask for approval and have someone else approve it.
Approve is unavailable with You asked for this approval, so the decision is somebody else’s.	You asked for this approval.	Have someone else with script:approve approve it, or use an emergency approval.
The run is refused because the interpreter is not allowed	script_execution.allowed_interpreters on the endpoint does not include it.	Add the interpreter on a profile that applies.

Next steps

• Run scripts on endpoints
• Endpoint custom fields