Appearance
Scripts
Scripts are reusable automation blocks that can run from jobs, package workflows, OS image workflows, collectors, alert rules, and configuration profiles.
Use saved scripts when the same logic should be maintained once and reused in multiple places. Use inline scripts when the logic only belongs to one workflow step.
Script Types
Each saved script has a platform, execution target, interpreter, content, optional parameters, optional output settings, and optional exit-code mappings.
Supported combinations:
- Windows endpoint scripts use
powershellorcmd. - Linux endpoint scripts use
bashorsh. - Windows Runner scripts use
powershell. - Linux Runner scripts use
bashorsh.
Windows endpoint scripts can also use a Windows execution context. See Windows Execution Contexts for the available identities and their tradeoffs.
Runner scripts execute through a pool managed under Administration > Services. They use the Runner service identity and do not use endpoint Windows execution contexts.
Infrastructure jobs can also use inline Bash, POSIX shell, or PowerShell without creating a saved script. See Infrastructure Jobs.
Linux scripts resolve the selected bash or sh executable from the process PATH. The selected shell must be installed and available to the Ordyn Agent or Runner account. Ordyn does not substitute a different shell when the selected executable is unavailable.
Execution Mode
Windows endpoint scripts using PowerShell or CMD support two execution modes:
- Blocking waits for the interpreter to finish. Ordyn captures output and the exit code, applies the timeout, and supports cancellation, output bindings, exit-code mappings, and infrastructure maintenance.
- Non-blocking completes the script step when the interpreter starts. The process continues independently, and Ordyn does not track its later output, exit code, failures, or completion. Cancelling the job does not stop the detached process.
Choose the Windows desktop independently from the execution mode:
- Background / non-interactive desktop starts the interpreter in the selected execution context without attaching it to the active desktop.
- Existing active desktop lets GUI applications started by the hidden interpreter appear in the active, signed-in, unlocked console session. Console applications do not automatically receive a visible console window; launch them through a mechanism that creates a new console when their window must be visible. This mode cannot use
LocalSystem.
In Blocking mode on the existing active desktop, Ordyn waits for completion but does not make the interpreter or a child console window visible. Make the script wait for any asynchronously launched GUI process when the job must wait too, for example with PowerShell's Start-Process -Wait.
Non-blocking scripts use text output with no output schema or exit-code mappings. Linux endpoint scripts, Bash and POSIX shell scripts, and Runner scripts use Blocking execution.
Timeout
Set a saved Runner script's timeout in seconds when it needs to run for several days. For example, 172800 allows 48 hours. A job step's explicit timeout takes precedence over the saved script timeout; if neither is set, Runner scripts use 300 seconds. An empty timeout uses this default behavior, and zero is not an unlimited timeout.
Endpoint scripts have a maximum saved timeout of 24 hours. Set the job's overall timeout to allow enough execution time for the script and the other steps.
Parameters
Saved scripts can define parameters. Jobs and workflow steps that use the script show fields for those parameters. Alert rules using a Runner script also accept parameter values.
Supported parameter types:
stringnumberbooleanswitchsecret
Required parameters must be provided unless the script defines a default value. Secret parameters accept a value or template, or a reference to a secret variable. Ordyn resolves variables and templates when the script runs.
String parameter defaults and values can use normal Ordyn templates, for example:
text
{{ endpoint.hostname }}Use {{ env.NAME }} to read an environment variable from the script's effective runtime identity. Use bracket syntax when the variable name is not a simple identifier:
text
{{ env.TEMP }}
{{ env["ProgramFiles(x86)"] }}Each environment reference is resolved once immediately before the script starts, after the runtime environment and job environment overrides are assembled. Windows names are case-insensitive; Linux names are case-sensitive. A missing environment variable fails the step with the variable name in the error.
How Parameters Reach The Script
Ordyn passes saved-script parameters in two ways:
- command-line arguments
- environment variables
This lets scripts use whichever style is most natural for the interpreter. The command-line argument, ORDYN_PARAM_* value, and ORDYN_SCRIPT_PARAMETERS_JSON entry all receive the same resolved parameter value.
Inline scripts do not have saved-script parameter definitions. They can still use templates in the script content and can read the task payload environment variables described below.
PowerShell Parameters
PowerShell parameters are passed with PowerShell-style names.
For a script parameter named certificate_directory, Ordyn passes:
powershell
-certificate_directory "C:\ProgramData\Vendor"A PowerShell script can receive it with a normal param block:
powershell
param(
[string]$certificate_directory,
[bool]$force,
[switch]$restart_service
)
Write-Output "Certificate directory: $certificate_directory"Parameter type behavior:
stringandnumberare passed as-name value.booleanis passed as-name:$trueor-name:$false.switchis passed as-nameonly when the value istrue; it is omitted when the value isfalse.secretis resolved to the secret value and passed like a string parameter.
PowerShell scripts can also read parameters from environment variables:
powershell
$certificateDirectory = $env:ORDYN_PARAM_CERTIFICATE_DIRECTORY
$allParameters = $env:ORDYN_SCRIPT_PARAMETERS_JSON | ConvertFrom-JsonBash And POSIX Shell Parameters
Bash and POSIX shell parameters are passed with long option names. Underscores in parameter keys become dashes in command-line arguments.
For a script parameter named certificate_directory, Ordyn passes:
bash
--certificate-directory "/etc/vendor"A Bash script can parse those arguments normally:
bash
#!/usr/bin/env bash
set -euo pipefail
certificate_directory=""
force="false"
restart_service="false"
while [[ $# -gt 0 ]]; do
case "$1" in
--certificate-directory)
certificate_directory="$2"
shift 2
;;
--force)
force="$2"
shift 2
;;
--restart-service)
restart_service="true"
shift
;;
*)
echo "Unknown argument: $1" >&2
exit 2
;;
esac
done
echo "Certificate directory: $certificate_directory"Parameter type behavior:
stringandnumberare passed as--name value.booleanis passed as--name trueor--name false.switchis passed as--nameonly when the value istrue; it is omitted when the value isfalse.secretis resolved to the secret value and passed like a string parameter.
Bash and POSIX shell scripts can also read parameters from environment variables:
bash
certificate_directory="${ORDYN_PARAM_CERTIFICATE_DIRECTORY:-}"
all_parameters_json="${ORDYN_SCRIPT_PARAMETERS_JSON:-{}}"Parameter Environment Variables
For every parameter that is actually passed to the script, Ordyn also creates an environment variable:
text
ORDYN_PARAM_<PARAMETER_KEY>The parameter key is uppercased and non-alphanumeric characters are converted to underscores.
Examples:
certificate_directorybecomesORDYN_PARAM_CERTIFICATE_DIRECTORYapi-tokenbecomesORDYN_PARAM_API_TOKEN
Boolean values are exposed as true or false.
Ordyn also provides all passed parameters as JSON:
text
ORDYN_SCRIPT_PARAMETERS_JSONSwitch parameters with value false are omitted from command-line arguments and from ORDYN_SCRIPT_PARAMETERS_JSON.
Runtime Environment
Endpoint scripts receive runtime context through environment variables.
Common endpoint variables:
ORDYN_ENDPOINT_IDORDYN_ENDPOINT_NAMEORDYN_ENDPOINT_HOSTNAMEORDYN_ENDPOINT_OS_FAMILYORDYN_ENDPOINT_OS_VERSIONORDYN_ENDPOINT_OS_ARCHORDYN_SCRIPT_IDORDYN_SCRIPT_NAMEORDYN_SCRIPT_INTERPRETERORDYN_EXECUTION_CONTEXTORDYN_TASK_PAYLOAD_JSON
Endpoint job script steps also receive:
ORDYN_JOB_ARTIFACT_DIRECTORYORDYN_JOB_LOG_FILE
Use the job artifact directory for files that a later Collect artifacts step should upload.
Runner scripts receive:
ORDYN_SCRIPT_IDORDYN_SCRIPT_NAMEORDYN_SCRIPT_INTERPRETERORDYN_WORKSPACE
Endpoint-scoped Runner scripts also receive:
ORDYN_ENDPOINT_IDORDYN_ENDPOINT_KINDORDYN_ENDPOINT_HOSTNAMEORDYN_ENDPOINT_FQDNORDYN_ENDPOINT_TENANT_IDORDYN_ENDPOINT_PRIMARY_IP_ADDRESS
ORDYN_ENDPOINT_PRIMARY_IP_ADDRESS uses the endpoint's primary network interface. Optional endpoint values are empty strings when unavailable.
Infrastructure-scoped Runner scripts receive script, workspace, and parameter variables without endpoint values.
Runner scripts execute as the configured Runner service identity, which defaults to LocalSystem on Windows and root on Linux. Treat them as trusted privileged code.
Cancellation
Cancelling a blocking script requests that it and its managed child processes stop. A disconnected endpoint may need to reconnect before cancellation finishes. Work already accepted by another system can continue, and non-blocking scripts are independent of job cancellation.
See Agent Runtime Limits for operational limits.
Output
Blocking scripts return stdout, stderr, and an exit code. Non-blocking scripts report that the interpreter started without completion output.
The endpoint agent retains a bounded prefix of each blocking script's stdout and stderr and reports whether either stream was truncated. See Agent Runtime Limits for the default limit, result metadata, and cancellation behavior.
In infrastructure jobs, runner scripts stream stdout and stderr to the run log. Save additional diagnostics to explicit paths in the workspace and collect them as artifacts. Runner script output is bounded and reports truncation metadata. Runner workspace and execution-time limits are enforced for each command.
By default, Ordyn treats script output as text. A script can also be configured for JSON output. JSON-output scripts must print valid JSON to stdout. Write progress messages to stderr.
For PowerShell JSON output, use Write-Output with the result of ConvertTo-Json and keep unrelated messages out of stdout.
Example:
json
{
"installed": true,
"version": "1.2.3",
"restart_required": false
}When a script has JSON output, jobs can bind fields from that JSON document into job variables and use them in later If branch steps.
Output bindings can be marked as secret. Secret-bound values are stored as secret runtime values and are redacted from the normalized script output shown later.
Exit Codes
Exit-code mappings let a script classify specific exit codes as success, success with reboot required, or failure, with an optional message.
Unmapped non-zero exit codes are treated as failures. Exit code 0 is the normal success case unless you map it differently.
Use exit-code mappings when a tool has known non-zero success codes or when a specific code should show a clearer message in the job history.
Secrets
The script receives resolved secret parameters so it can use them. Known secret values are redacted from captured output, but transformed values and files can still disclose them.
Do not print secrets or pass them to tools that log their command lines. Prefer standard input or protected credential files when the tool supports them. See Variables for secret configuration.
Import And Export
Scripts can be represented as JSON documents with:
json
{
"schema_version": 1,
"kind": "script",
"name": "Example script",
"platform": "windows",
"execution_target": "endpoint",
"interpreter": "powershell",
"execution_mode": "blocking",
"windows_desktop_mode": "default_session",
"content": "Write-Output 'hello'",
"parameters": []
}Use script JSON documents when you want to move scripts between Ordyn systems or keep scripts in source control.
The document stores the script definition: content, platform, interpreter, parameters, output schema, exit-code mappings, timeout, and execution settings. Values that reference local Ordyn objects, such as folders or secret variable definitions, must exist or be selected when importing.