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.
• Server-side scripts use bash and run in the Ordyn server environment.

Windows endpoint scripts can also use a Windows execution context. See Windows Execution Contexts for the available identities and their tradeoffs.

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 scripts, and server-side 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 store an Ordyn secret selection, not the plaintext value. Ordyn resolves the secret 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 Parameters

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

Server-side scripts receive endpoint and script context too:

• ORDYN_ENDPOINT_ID
• ORDYN_ENDPOINT_HOSTNAME
• ORDYN_ENDPOINT_TENANT_ID
• ORDYN_SCRIPT_ID
• ORDYN_SCRIPT_NAME
• ORDYN_SCRIPT_INTERPRETER
• ORDYN_EXECUTION_CONTEXT
• ORDYN_TASK_PAYLOAD_JSON

Server-side scripts run in the Ordyn server environment. They should be treated as trusted 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.

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.

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.

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.

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 Secrets.

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 secrets, must exist or be selected when importing.