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.

Parameters

Saved scripts can define parameters. A job or workflow step that uses the script shows fields for those parameters.

Supported parameter types:

• string
• number
• boolean
• switch
• secret

Required parameters must be provided unless the script defines a default value. Secret parameters select a secret variable definition, not a plaintext value. Ordyn resolves the variable when the script runs.

String parameter values can use normal Ordyn templates, for example:

{{ endpoint.hostname }}

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.

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:

-certificate_directory "C:\ProgramData\Vendor"

A PowerShell script can receive it with a normal param block:

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:

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

--certificate-directory "/etc/vendor"

A Bash script can parse those arguments normally:

#!/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:

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:

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:

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

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

When a running endpoint script is part of a job or configuration-profile execution, aborting that work requests cancellation on the endpoint. The job remains in Cancelling until the script process has exited.

For blocking Windows scripts, cancellation and task timeout terminate the PowerShell or CMD process and its child-process tree. Stopping or restarting the Ordyn Agent also terminates an active managed script process tree. Child processes intentionally left running after a normally completed script are not terminated. Non-blocking processes are detached from the job and are not stopped by job cancellation.

If the endpoint disconnects before it receives the request, Ordyn keeps the cancellation pending and retries after reconnect. New primary work for that endpoint waits until cancellation is resolved.

Aborting a Runner task requests cancellation from the selected Runner and terminates the managed process tree. A temporary Runner connection interruption keeps the command associated with that Runner and reconciles its state after reconnect.

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.

Runner script output is also 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.

For PowerShell JSON output, send the serialized value through PowerShell's Success stream. Blocking Windows endpoint scripts also capture direct .NET console writes, but the Success-stream form is recommended for structured output.

Example:

{
  "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

Secret parameters are resolved at runtime and passed to the running process. The script can read the plaintext secret because it needs the value to do useful work.

For endpoint scripts, Ordyn sends known secret values to the agent as redaction tokens. Exact matches are redacted from stdout, stderr, command-output logs, and command invocation logs.

Runner script secret parameters travel in the authenticated, signed Runner command. Known values are redacted from captured process output and are not persisted in the Runner's local command state.

Do not print secrets. Avoid passing secrets to child processes that may log command lines. Prefer tools that can read credentials from files or standard input when possible.

For more detail, see Secret variables.

Import And Export

Scripts can be represented as JSON documents with:

{
  "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.