Skip to content

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 powershell or cmd.
  • Linux endpoint scripts use bash or sh.
  • Windows Runner scripts use powershell.
  • Linux Runner scripts use bash or sh.

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:

  • string
  • number
  • boolean
  • switch
  • secret

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:

  • string and number are passed as -name value.
  • boolean is passed as -name:$true or -name:$false.
  • switch is passed as -name only when the value is true; it is omitted when the value is false.
  • secret is 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-Json

Bash 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:

  • string and number are passed as --name value.
  • boolean is passed as --name true or --name false.
  • switch is passed as --name only when the value is true; it is omitted when the value is false.
  • secret is 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_directory becomes ORDYN_PARAM_CERTIFICATE_DIRECTORY
  • api-token becomes ORDYN_PARAM_API_TOKEN

Boolean values are exposed as true or false.

Ordyn also provides all passed parameters as JSON:

text
ORDYN_SCRIPT_PARAMETERS_JSON

Switch 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_ID
  • ORDYN_ENDPOINT_NAME
  • ORDYN_ENDPOINT_HOSTNAME
  • ORDYN_ENDPOINT_OS_FAMILY
  • ORDYN_ENDPOINT_OS_VERSION
  • ORDYN_ENDPOINT_OS_ARCH
  • ORDYN_SCRIPT_ID
  • ORDYN_SCRIPT_NAME
  • ORDYN_SCRIPT_INTERPRETER
  • ORDYN_EXECUTION_CONTEXT
  • ORDYN_TASK_PAYLOAD_JSON

Endpoint job script steps also receive:

  • ORDYN_JOB_ARTIFACT_DIRECTORY
  • ORDYN_JOB_LOG_FILE

Use the job artifact directory for files that a later Collect artifacts step should upload.

Runner scripts receive:

  • ORDYN_SCRIPT_ID
  • ORDYN_SCRIPT_NAME
  • ORDYN_SCRIPT_INTERPRETER
  • ORDYN_WORKSPACE

Endpoint-scoped Runner scripts also receive:

  • ORDYN_ENDPOINT_ID
  • ORDYN_ENDPOINT_KIND
  • ORDYN_ENDPOINT_HOSTNAME
  • ORDYN_ENDPOINT_FQDN
  • ORDYN_ENDPOINT_TENANT_ID
  • ORDYN_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.