Run Script job
- Synopsis
- Full Details
In briefA Run Script job runs a script you type into the job — PowerShell, Bash, Python or
Shell — on a Universal Agent machine. The agent writes the script to a temporary file, runs it with
the matching interpreter, and then removes the file. Success is decided by the same rules as Run
Command: exit code 0 by default, or your own exit criteria and output parsing.
WhereIn Design › Workflows, open a workflow and open the job in the Job Editor (open its context menu on the canvas › Edit Job). On the Job Definition tab, choose Run Script as the job type, set the fields under Job Parameters, and pick a Universal Agent under Agent Assignment.
WhenUse a Run Script job when:
- the logic is more than one command line;
- the script belongs to this one job, rather than being shared by many;
- the script's exit codes or output need their own success rule.
For a single command, use Run Command. To share one script across jobs on legacy Windows or UNIX machines, store it in the script library.
How
- Choose Run Script as the job type and choose the Script Type.
- Enter the Script Content, and any Script Arguments, Working Directory or Environment Variables.
- Add Exit Criteria or Output Parsing rules if the default rule does not fit.
- Assign the job to a Universal Agent and save.
For the full steps, see Run a script.
- The interpreter must already be installed on the agent machine. PowerShell on Linux or macOS
needs
pwsh. - PowerShell runs with
-NoProfile, so the script cannot rely on a profile. - An exit criterion that matches means the job failed. With criteria set, Fail on Error is ignored.
- A script can set its own exit code. That is often simpler than parsing its output.
- A new job starts with Script Type
shell. Choose the type that matches the script before you save, or the script runs with the shell interpreter. - A script longer than 65,536 characters is refused.
- Every Run Script job stops after one hour, and no setting changes that. Kill does not stop the script on a Universal Agent.
- Only the first and last 512 KB of each output stream are searched by output parsing.
Task walkthrough: Run a script. This page is the full configuration and troubleshooting reference.
The Run Script job runs an embedded script — PowerShell, Bash, Python, or Shell — on the
agent machine. It's a built-in job type (builtin:script), so no setup or connection is
required. Use it instead of Run Command when the logic is more than a single command line.
| Property | Value |
|---|---|
| Job type | Run Script (run-script) |
| Runs on | Universal Agent only |
| Operating systems | Windows, Linux, macOS |
| Connections required | None |
| Category | Script |
- How It Works
- Configuration Reference
- Deciding Success
- Outcomes
- Troubleshooting
How It Works
The script content is written to a temporary file on the agent, run with the matching interpreter, and the temporary file is removed afterward. The interpreter must be installed on the agent — OpCon Continuum does not provide it.
| Script type | Interpreter used | Notes |
|---|---|---|
powershell | powershell.exe on Windows, pwsh on Linux/macOS | Run with -NoProfile -NonInteractive -ExecutionPolicy Bypass. pwsh (PowerShell 7+) must be installed on non-Windows agents. |
bash | /bin/bash | Bash must be present. |
python | python on Windows, python3 on Linux/macOS | Python must be installed and on PATH. |
shell | cmd.exe on Windows, /bin/sh on Linux/macOS | Default. Always present on the matching OS. |
Standard output and standard error are captured; standard error is appended under a
--- STDERR --- marker. The agent sets OPCON_WORK_ITEM_ID and OPCON_CORRELATION_ID for the
script, and filters sensitive environment variables exactly as Run Command does.
Configuration Reference
| Parameter | Required | Default | Limits | Notes |
|---|---|---|---|---|
| Script Type | Yes | shell | One of powershell, bash, python, shell | Selects the interpreter. |
| Script Content | Yes | — | 1–65,536 characters | The script content. A longer script is refused as an invalid parameter. |
| Script Arguments | No | none | Up to 100 arguments, each up to 8192 characters | Add as many as you need, one per entry. Passed to the script. |
| Working Directory | No | agent working directory | Up to 4096 characters | Directory to run in. |
| Environment Variables | No | none | Each value up to 32768 characters | Extra environment variables, each a name and a value. |
| Fail on Error | No | On | — | A switch. On fails the job on a non-zero exit code; off never fails it on its exit code. Ignored when Exit Criteria are set. |
| Exit Criteria | No | none | Up to 5 conditions | Exit codes that mean failure. See Deciding success. |
| Output Parsing | No | none | Up to 5 rules | Search the job output for text and set an exit code. See Deciding success. |
On a new job the editor stores the default Script Type, shell, so a job saved without
choosing one runs as a Shell script. A job that holds no script type at all is refused at save with
Required parameter 'scriptType' is missing.
The platform sends every Universal Agent job with a 3,600-second limit, and no setting on the job changes it. At the hour the agent stops the script (graceful stop, then a forced stop after 5 seconds) and the job fails with Script exceeded its timeout of 3600s and was terminated. Kill does not reach a Universal Agent, so it does not stop the script sooner — see How a Universal Agent takes and runs work.
Deciding Success
Deciding success: exit criteria and output parsing
By default the job succeeds on exit code 0 and fails on anything else. Exit criteria and
output parsing replace that rule when the script's own convention is different — an exit 3 that
means "nothing to do", or a script that exits 0 and prints an error.
Run Script and Run Command share one evaluator, so the rules below are identical on both job types. In short:
- Output parsing searches the job output and may rewrite the exit code. It never decides the outcome by itself.
- Exit criteria judge the resulting code — the effective exit code — and decide failure.
Exit criteria
Each condition is an operator and a whole number, and a condition that matches means the job
failed. Equal To 5 means fail when the script exits 5, not succeed when it does.
| Field | Values |
|---|---|
| Operator | Equal To, Not Equal To, Less Than, Greater Than, Less Than or Equal To, Greater Than or Equal To |
| Value | A whole number from −2,147,483,648 to 2,147,483,647 |
- Conditions are OR-ed: the first one that matches fails the job. If none matches, the job finished OK — including on a non-zero code.
- Up to five conditions. Leave the list empty to keep the default rule.
- With conditions set, Fail on Error is ignored — the criteria are the rule.
Output parsing
Each rule searches the job output for text and, when it matches, sets an exit code that the exit criteria then judge.
| Field | Values |
|---|---|
| Search Operation | Contains or Does Not Contain |
| String To Find | 1–255 characters |
| Exit Code To Set | A whole number in the same range as above |
- Rules are evaluated in order, and the first match wins — later rules aren't consulted.
- Both standard output and standard error are searched.
- Matching is case sensitive and supports
*(any run of characters) and?(exactly one character). It is not a regular expression, so.,\and(are literal text. - A wildcard never spans a line break, so a search string containing a newline can never match.
- Up to five rules.
The agent keeps the first 512 KB and the last 512 KB of standard output, and the same of standard error. A script that produces more than 1 MB on a stream has its middle dropped, and a match that appears only there is missed. When that could have changed the outcome, the job output opens with a note saying so — so treat output parsing as unreliable on a script that logs heavily, and have the script print less instead.
Unlike a command, a script can choose its own exit code — exit 8 costs one line. Exit criteria and
output parsing earn their place when the script is one you can't change, or when the interesting
signal is only in its output.
Outcomes
The effective exit code below is the script's own code, or the code an output-parsing rule set.
| Result | Exit code | When |
|---|---|---|
| Success | 0 | Script exited 0, with nothing configured to say otherwise. |
| Success despite a non-zero exit | the effective code | Exit criteria are set and none matched, or Fail on Error is off. |
| Failed — exit criteria matched | the effective code | A condition matched the effective code. |
| Failed — script error | the effective code | The effective exit code is non-zero, no exit criteria are set, and Fail on Error is on. |
| Failed — invalid parameters | 1 | A parameter fails validation: an empty Script Content, an unknown Script Type, a value over its limit, more than five conditions or rules, an unrecognised operator, or a value outside the whole-number range. |
| Failed — interpreter missing | 1 | The interpreter for the chosen script type is not installed on the agent. |
| Failed — output parsing could not finish | the script's own code | A rule's search could not complete within the agent's matching budget. |
| Stopped — timeout or cancel | 128 | The agent terminated the process. Criteria and rules are not applied — a job the platform stopped always fails. |
- A process ended by a signal reports exit code 128, and that cannot be told apart from a process
that genuinely exited
128. - A job that fails with exit code 0 shows its return code as — rather than
0, so a failed job never displays a code that reads like success.
The job's Termination text names what decided the outcome — the rule that fired, the criterion that matched, or the script's own code — followed by whatever the script wrote to standard error.
Troubleshooting
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job fails immediately with "Invalid task definition" | Script Content empty, Script Type not one of the four values, or a value over its limit | Correct the parameters (Builder). |
| Job fails to start a PowerShell script on Linux/macOS | pwsh (PowerShell 7+) is not installed on the agent | Install pwsh on the agent, or use a different script type (Administrator / Builder). |
| Python script won't start | python/python3 not installed or not on PATH on the agent | Install Python on the agent and confirm it's on PATH (Administrator). |
| PowerShell script behaves differently than in an interactive console | The script runs with -NoProfile and -ExecutionPolicy Bypass | Don't rely on profile setup or local execution policy; make the script self-contained (Builder). |
| Script can't see an environment variable (often a password/secret) | Filtered by design (same rule as Run Command) | Pass it as a job Environment Variable, or use a connection-based connector for credentials (Builder / Administrator). |
| Job fails on a non-zero exit you consider acceptable | Fail on Error is on and no exit criteria are set | Set exit criteria that exclude that code, or turn Fail on Error off (Builder). |
| Job finishes OK on an exit code that should have failed it | Exit criteria are set and none of them matches that code — the criteria replace Fail on Error entirely | Add a condition that matches the code, remembering a match means failure (Builder). |
| An output-parsing rule never fires even though the text is in the output | The search is case sensitive, */? are the only wildcards, a wildcard can't cross a line break, or the text sits in the dropped middle of more than 1 MB of output | Match the case exactly, replace regular-expression syntax with */?, and have the script print less (Builder). |
| Job fails with "could not be evaluated within the allowed matching budget" | A long search string containing ? against output with a long repeating run | Replace the ? with *, which makes the search efficient (Builder). |
| Job ends after one hour with exit code 128 | The script ran past the fixed one-hour timeout and was stopped | The limit can't be raised. Split the work, or make the script finish within the hour (Builder). |
| Job fails with "Invalid task definition" on a long script | The script is over 65,536 characters | Shorten the script, or split it across jobs (Builder). |
| Job assigned but never runs | Target agent is not a Universal Agent | Reassign to a Universal Agent. |
Contact support when
- A script fails to start even though its interpreter is installed and runs the same script manually on the agent.
- Output or exit codes don't match what the script actually produces.
Include the job output, the Script Type, the agent OS, and confirmation that the interpreter is installed on the agent.