Run a script

A script from the register (see "Manage scripts") is launched from its page: display the version you want, then Execute. These screens are restricted to Administrators.

Launch an execution

The Execute screen first asks for the Parameters declared by the version (an asterisk marks the mandatory ones), then the Target:

Single agent: one machine equipped with an active Outpost agent;
Machine group: every agent of a machine group at once. Above the script's confirmation threshold (25 machines by default, see "Manage scripts"), tick I confirm triggering this on multiple machines at once., otherwise the launch is refused;
Local, marked Sensitive: the script runs on the Portail ZAPP server itself. This choice is not offered on a SaaS-hosted instance.

When the Outpost agents module is not enabled, remote targets are greyed out and only local execution remains possible.

Execute launches the script and opens the execution tracking page (or the batch page, for a machine group).

What can block a launch

An error message is shown above the form when:

a parameter value breaks the version's rules (required, format, minimum, maximum, list of values);
the script's Target scope excludes the chosen target (for example a Local only script launched on an agent);
you are not covered by a Target authorization rule for that agent (remote execution);
an execution of the same script is already running on the same target. For a single agent, the new request is queued and starts as soon as the previous one ends; for a machine group or locally, it is refused;
you launched more than 20 executions in the last minute;
the script references a secret that cannot be found, or the Secrets module is not enabled;
an administrator has switched off all executions (see below).

The message is in your language and states the cause (parameter at fault, number of machines and confirmation threshold…). The executions API (POST /api/v1/script-executions/local, /remote, /remote-group, /{id}/cancel) then answers 400 with the stable code (error, the one of the troubleshooting table below), an English sentence (message), the translation key (messageKey) and its values (parameters); the technical message stays in the server log.

Follow an execution

The Execution screen shows the Status (Queued, Running, Succeeded, Failed, Canceled, Timed out), the Target, the Machine, the Exit code, the Timestamp and the person who launched it (Requested by), then the script's Output. Output that is too long is cut and flagged with "Output truncated.". When an execution fails without writing anything, the Failure reason (reported by the agent) is displayed. A warning also flags the case where the agent could not limit the script's CPU and memory.

While the execution is not finished:

Refresh asks the agent for the latest state;
Cancel asks for the execution to stop, after confirmation.

An execution that exceeds the script's timeout becomes Timed out.

Batches and history

A launch on a machine group opens the Execution on a machine group screen: one row per machine with its status and exit code; Details opens that machine's execution.
A machine disabled (revoked, quarantined or archived) during a launch on a group does not stop the batch: its row is failed, with "The Outpost agent was revoked, quarantined or archived when the script was sent: it was not sent to it.", and the other machines of the group run the script.
A machine cancelled within a batch stays in the batch (status Canceled). Once every machine of the batch has finished and at least one failed, was cancelled or timed out, the script's failure notification recipients receive a single notification for the batch — even when the launch was interrupted by a server shutdown: the batch is then picked up again at restart or within the following quarter of an hour.
History (from the script page or an execution) lists all of the script's executions, most recent first, with the version, target, machine, status and who launched it.

When the Data grids module is installed, these lists are shown as a grid (sorting, filters).

Switch off all executions in an emergency

Setting ScriptRunner:KillSwitchEnabled to true in the Configuration screen immediately refuses any new script launch, whatever the target. Executions already running are not stopped: cancel them one by one if needed. Set the value back to false to allow launches again.

Troubleshooting scheduled executions

A scheduled execution (created through the ScriptRunner API) is a Scheduler job (Administration › Instance and operations › Scheduler). When the launch fails, the job's Execution history shows the cause in your language; the API and exports receive the stable code followed by an English sentence. The technical message stays in the server log.

Code	Cause	What to do
`ScriptNotFound`	The script has been deleted	Delete or update the schedule
`VersionNotFound`	The scheduled version no longer exists	Delete or update the schedule
`InvalidParameterDefinition`	A parameter (its name is shown) is missing or invalid	Fix the schedule parameters
`SecretResolutionUnavailable`	The script uses a secret, but the secrets vault is not installed	Enable the Secrets module
`SecretResolutionFailed`	The secret used (its name is shown) cannot be found or read	Check the secret in the vault
`MalformedSecretReference`	The script contains a malformed secret reference	Fix the script (new version)
`VersionNotExecutable`	The script's Target scope excludes this kind of execution	Change the target scope or the schedule
`DraftExecutionRequiresAuthor`	A draft version only runs locally for its author	Approve the version or schedule it as its author
`DraftExecutionRequiresTestGroup`	A draft version only runs on an agent of the "test" group	Approve the version or target the "test" group
`LocalExecutionDisabledInSaas`	Local execution is closed in SaaS	Target an Outpost agent
`ExecutionAlreadyInProgress`	An execution of the script is already running on the target	Nothing: the next run will launch the script again
`RemoteExecutionChannelUnavailable`	The Outpost agents module is not installed	Enable the Outpost module
`AgentNotFound`	The target agent no longer exists	Update the schedule
`NotAuthorizedForTarget`	The schedule's author is not covered by any authorization rule for this agent	Add a Target authorization rule
`GroupConfirmationRequired`	The group is above the script's confirmation threshold (count and threshold shown)	Raise the script threshold or reduce the group
`RateLimitExceeded`	Too many recent launches for the schedule's author	Space out the schedules
`ExecutionsGloballyDisabled`	An administrator has switched off all executions	Set `ScriptRunner:KillSwitchEnabled` back to `false`

A code missing from this table is shown as "Trigger failed: code"; an unforeseen error is shown as "Unexpected error" with its type, the detail being in the server log.