Run

Overview

The Run action starts a program (e.g. robocopy, an ERP import tool), a batch file (.bat/.cmd), a PowerShell script (.ps1) or a script written directly into the action (PowerShell, PowerShell 7 or cmd). It waits until it has finished and returns its exit code, its output and its error output, so that following actions can use them.

To make this reliable, the action does the following:

• Values arrive unchanged. Arguments given as a list and values in Environment reach the program exactly as they are, even with spaces, quotes or & in them (e.g. a {{FilePath}} like C:\Scans\O'Brien & Partner.pdf).
• Nothing waits for input. The program runs without a window, and its input is closed: a pause or Read-Host does not hang until the timeout.
• A timeout or a stopped workflow ends it completely, together with every process it started.
• The exit code decides. 0 counts as success; with SuccessExitCodes other codes can count too (robocopy, for example, reports success with 0–7). Any other code, or a timeout, makes the action fail. As with every action, the run then ends or the workflow’s error handling applies.
• PowerShell scripts stop at the first error ($ErrorActionPreference = 'Stop'), do not load a profile and are not blocked by the execution policy. Their output is read as UTF-8, so umlauts arrive correctly.

In the workflow editor you put the action together in a form and try it with Test step.

Runs with full rights

Run runs any program with the rights of the user RUNOS runs as (or of User). Only start scripts and programs you know, and keep scripts in folders that only administrators can change.

Structure

{
  "Type": "Run",
  "Name": "Checksum",
  "Parameters": {
    "Script": "(Get-FileHash -Path $env:FILE -Algorithm SHA256).Hash",
    "Environment": { "FILE": "{{FilePath}}" }
  }
}

Parameter	Default	Meaning
Program	–	What to start: a program (C:\Tools\tool.exe, or a name found on the PATH such as robocopy), a .bat/.cmd file or a .ps1 file. Give either Program or Script.
Arguments	–	Arguments, see below. Inline scripts get them too ($args or param() in PowerShell, %~1 in cmd).
Script	–	A script written directly into the action; it is run by Shell.
Shell	PowerShell	For Script and .ps1 files: PowerShell (Windows PowerShell 5.1), Pwsh (PowerShell 7, must be installed) or Cmd (only for Script)
WorkingDirectory	–	The folder the program runs in. Must exist. A Program or .ps1/.bat/.cmd path without a folder is looked for here.
Environment	–	Environment variables for the program: { "NAME": "value" }. A script reads them as $env:NAME (PowerShell) or %NAME% (cmd).
User	–	Run as another Windows user: DOMAIN\user, user@domain or a local user. Empty = the user RUNOS runs as.
Password	–	Password of User
Wait	true	false: only start it and continue at once; see below.
TimeoutSeconds	300	After that many seconds the program and everything it started are ended and the action fails. 0 = no limit.
SuccessExitCodes	0	Exit codes that count as success, e.g. "0;3010" or a range "0-7"
FailOnStdErr	false	true: fail as well if anything is written to the error output, even with exit code 0
OutputEncoding	Auto	How the output is read: Auto (UTF-8 for PowerShell, the console code page, e.g. 850, otherwise), UTF8, OEM or ANSI. Set UTF8 for programs that write UTF-8 (e.g. git, Node.js) when umlauts come out wrong.

Arguments can be given in two ways:

• As a list (recommended): [ "{{FilePath}}", "/quiet" ]. Each entry is exactly one argument and is quoted for the program if needed. This is the safe way to pass placeholders.
• As text: "/MIR /R:2 \"C:\\My Files\"", written as on a command line. A program gets the text unchanged; for scripts it is split at spaces, and double quotes group.

For PowerShell an argument such as -Path or -Force binds to the script’s parameter of that name, as with powershell -File.

Values into scripts: use Environment

Placeholders such as {{FilePath}} can also be written into Script; they are inserted into the script’s text before the run. A value with a quote or a space can then break the script. Safer: pass the value in Environment and read it in the script as $env:FILE or %FILE%.

Placeholders in cmd scripts

RUNOS replaces placeholders in all parameters before the run, including the script: besides {{…}} also %yyyy%, %MM%, %dd%, %date%, %time% and %NAME% of environment variables that RUNOS knows itself (e.g. %USERNAME% becomes the user RUNOS runs as, even with User). Variables from Environment and variables the script sets itself (set X=…) are left for cmd.

PowerShell

• The exit code is the one from exit n in the script; without exit that of the last external program the script called, otherwise 0. An error in the script ends it with exit code 1.
• If a program in the script may return a code other than 0 without that being an error, end the script with exit 0.
• The output is everything the script writes (Write-Output, or values that are not assigned). If it is JSON (e.g. from ConvertTo-Json), it is also in Response.Json and a following action reads single values, e.g. {{Checksum.Response.Json.Sha256}}.

Cmd and batch files

• A script in Script starts with @echo off, so only the output of its commands appears.
• An argument with a space or one of & | < > ^ , ; = ( ) is passed in quotes; read it in the script with %~1 (without the quotes). An argument with a double quote or a line break cannot be passed safely and makes the action fail; pass such values in Environment.

Run as another user

With User and Password the program runs as that Windows user, with that user’s profile loaded. Store the credentials in a Basic connector and refer to them with {{connector.ERP.Username}} and {{connector.ERP.Password}}; they are stored encrypted there.

• The user must be allowed to sign in on this PC (“Allow log on locally”). A wrong password or a missing right makes the action fail with a message saying so.
• Without Environment the program gets that user’s own environment variables. With Environment it gets those of the user RUNOS runs as plus the ones given.
• Windows allows at most 1024 characters for the command line of a program started as another user. Pass long values in Environment.

Without waiting

With "Wait": false the action only starts the program and succeeds as soon as it is running; Response then only contains the ProcessId. The exit code and output are not read, and TimeoutSeconds does not apply. Use this for programs that are meant to keep running, such as a viewer.

Result

"Response": {
  "ExitCode": 0,
  "Output": "{\n  \"File\": \"C:\\\\RUNOS\\\\Spooler\\\\…\\\\INV-2026-0001.pdf\",\n  \"Sha256\": \"9F86D0…\"\n}",
  "Errors": "",
  "Json": {
    "File": "C:\\RUNOS\\Spooler\\…\\INV-2026-0001.pdf",
    "Sha256": "9F86D0…"
  },
  "TimedOut": false,
  "ProcessId": 8124,
  "DurationSeconds": 1.42
},
"Meta": {
  "Host": "PC-01",
  "User": "OFFICE\\scanner",
  "Mode": "PowerShell",
  "CommandLine": "powershell.exe -File <Script>"
}

Output is the standard output and Errors the error output, each with trailing blank lines removed and up to 1,000,000 characters (anything beyond that is cut off with a warning). Json is only present if the whole output is JSON. A following action reads the values as {{Checksum.Response.Output}} or {{Checksum.Response.ExitCode}}.

If the action fails, the reason is in the errors of the result: the exit code with the last lines of the error output (or of the output, if the error output is empty), the timeout, or why the program could not be started (not found, wrong password, folder missing). A warning appears if a program started by the script is still running and keeps the output open; the output up to that point is in the result.

Form in the editor

In the diagram of the workflow editor the action has a form (in the settings panel and in the middle column of the test view):

• What runs: Program or file or Script. Switching removes the other mode’s fields; Ctrl+Z brings them back. For Program or file, Program and Arguments (as on a command line, or one argument per line when Arguments is a list); for Script, the Shell (Windows PowerShell, PowerShell 7 or cmd) and the script editor. Plus the Working folder.
• Waiting and result: Wait until it ends (on by default), time limit (default 300 seconds, 0 = none), Exit codes that count as success (e.g. 0;3010 or 0-7), Fail on error output and Output encoding.
• More options: Environment variables as a table, and Run as user with password.

Every field also takes {{…}} placeholders and values you drag in from the Input column of the test view; lists, switches and number fields become a text field when given a {{…}}. Parameters the form does not know are kept under Other parameters. Test step runs the action once, right away, with the data of the earlier steps, and shows the result with errors and warnings. The test really runs the script or program on this PC; the output shows ExitCode, Output and Errors.

Example

Mirror the export folder to the NAS every night. robocopy reports success with exit codes 0 to 7, so these count as success:

{
  "Name": "Mirror export",
  "Autostart": true,
  "Trigger": { "Type": "Time", "Name": "Nightly", "Parameters": { "CronExpression": "0 0 2 * * ?" } },
  "Actions": [
    {
      "Type": "Run",
      "Name": "Mirror",
      "Parameters": {
        "Program": "robocopy",
        "Arguments": [ "C:\\Export", "\\\\nas\\backup\\Export", "/MIR", "/R:2", "/W:5", "/NP" ],
        "SuccessExitCodes": "0-7",
        "TimeoutSeconds": 3600
      }
    }
  ]
}

Checksum of every incoming file. A file trigger hands each PDF to a PowerShell script. The file comes in through Environment; the script returns JSON, which following actions read as {{Checksum.Response.Json.Sha256}}:

{
  "Name": "Checksums",
  "Autostart": true,
  "Trigger": { "Type": "File", "Name": "Inbox", "Parameters": { "Pool": "C:\\Import\\Invoices", "Filter": "*.pdf" } },
  "Actions": [
    {
      "Type": "Run",
      "Name": "Checksum",
      "Parameters": {
        "Script": "$hash = Get-FileHash -Path $env:FILE -Algorithm SHA256\n@{ File = $env:FILE; Sha256 = $hash.Hash } | ConvertTo-Json",
        "Environment": { "FILE": "{{FilePath}}" }
      }
    }
  ]
}

Hand files to an ERP import as a service user. The batch file C:\ERP\import.cmd reads the file as %~1 and the client as %~2. It runs as the user from the Basic connector ERP and may take up to ten minutes:

{
  "Type": "Run",
  "Name": "ErpImport",
  "Parameters": {
    "Program": "C:\\ERP\\import.cmd",
    "Arguments": [ "{{FilePath}}", "Client 01" ],
    "WorkingDirectory": "C:\\ERP",
    "User": "{{connector.ERP.Username}}",
    "Password": "{{connector.ERP.Password}}",
    "TimeoutSeconds": 600
  }
}