Run

Übersicht

Die Aktion Run startet ein Programm (z. B. robocopy, ein Importprogramm des ERP), eine Batch-Datei (.bat/.cmd), ein PowerShell-Skript (.ps1) oder ein Skript, das direkt in der Aktion steht (PowerShell, PowerShell 7 oder cmd). Sie wartet, bis es fertig ist, und liefert Exit-Code, Ausgabe und Fehlerausgabe, damit folgende Aktionen damit arbeiten können.

Damit das zuverlässig klappt, macht die Aktion Folgendes:

• Werte kommen unverändert an. Argumente als Liste und Werte in Environment erreichen das Programm genau so, wie sie sind, auch mit Leerzeichen, Anführungszeichen oder & darin (z. B. ein {{FilePath}} wie C:\Scans\O'Brien & Partner.pdf).
• Nichts wartet auf eine Eingabe. Das Programm läuft ohne Fenster, und seine Eingabe ist geschlossen: Ein pause oder Read-Host hängt nicht bis zum Zeitlimit.
• Ein Zeitlimit oder ein gestoppter Workflow beendet es vollständig, samt allen Prozessen, die es gestartet hat.
• Der Exit-Code entscheidet. 0 gilt als Erfolg; mit SuccessExitCodes zählen auch andere Codes (robocopy meldet Erfolg z. B. mit 0–7). Jeder andere Code oder das Zeitlimit lässt die Aktion fehlschlagen. Wie bei jeder Aktion endet dann der Lauf oder die Fehlerbehandlung des Workflows greift.
• PowerShell-Skripte halten beim ersten Fehler an ($ErrorActionPreference = 'Stop'), laden kein Profil und werden nicht von der Ausführungsrichtlinie blockiert. Ihre Ausgabe wird als UTF-8 gelesen, Umlaute kommen also richtig an.

Im Workflow-Editor stellen Sie die Aktion in einem Formular zusammen und probieren sie mit Schritt testen aus.

Läuft mit vollen Rechten

Run führt jedes Programm mit den Rechten des Benutzers aus, unter dem RUNOS läuft (bzw. von User). Starten Sie nur Skripte und Programme, die Sie kennen, und legen Sie Skripte in Ordner, die nur Administratoren ändern dürfen.

Struktur

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

Parameter	Standard	Bedeutung
Program	–	Was gestartet wird: ein Programm (C:\Tools\tool.exe oder ein Name aus dem PATH wie robocopy), eine .bat-/.cmd-Datei oder eine .ps1-Datei. Entweder Program oder Script angeben.
Arguments	–	Argumente, siehe unten. Auch Skripte in Script bekommen sie ($args bzw. param() in PowerShell, %~1 in cmd).
Script	–	Ein Skript direkt in der Aktion; es wird von Shell ausgeführt.
Shell	PowerShell	Für Script und .ps1-Dateien: PowerShell (Windows PowerShell 5.1), Pwsh (PowerShell 7, muss installiert sein) oder Cmd (nur für Script)
WorkingDirectory	–	Der Ordner, in dem das Programm läuft. Muss existieren. Ein Program bzw. eine .ps1-/.bat-/.cmd-Datei ohne Ordner wird hier gesucht.
Environment	–	Umgebungsvariablen für das Programm: { "NAME": "Wert" }. Ein Skript liest sie als $env:NAME (PowerShell) bzw. %NAME% (cmd).
User	–	Als anderer Windows-Benutzer ausführen: DOMÄNE\benutzer, benutzer@domäne oder ein lokaler Benutzer. Leer = der Benutzer, unter dem RUNOS läuft.
Password	–	Passwort von User
Wait	true	false: nur starten und sofort weitermachen, siehe unten.
TimeoutSeconds	300	Nach so vielen Sekunden werden das Programm und alles, was es gestartet hat, beendet, und die Aktion schlägt fehl. 0 = ohne Limit.
SuccessExitCodes	0	Exit-Codes, die als Erfolg gelten, z. B. "0;3010" oder ein Bereich "0-7"
FailOnStdErr	false	true: auch fehlschlagen, wenn etwas in die Fehlerausgabe geschrieben wird, selbst bei Exit-Code 0
OutputEncoding	Auto	Wie die Ausgabe gelesen wird: Auto (UTF-8 bei PowerShell, sonst die Codepage der Konsole, z. B. 850), UTF8, OEM oder ANSI. UTF8 für Programme, die UTF-8 schreiben (z. B. git, Node.js), wenn Umlaute falsch ankommen.

Arguments gibt es auf zwei Arten:

• Als Liste (empfohlen): [ "{{FilePath}}", "/quiet" ]. Jeder Eintrag ist genau ein Argument und wird für das Programm bei Bedarf in Anführungszeichen gesetzt. So werden Platzhalter sicher übergeben.
• Als Text: "/MIR /R:2 \"C:\\Meine Dateien\"", geschrieben wie in einer Befehlszeile. Ein Programm bekommt den Text unverändert; für Skripte wird er an Leerzeichen getrennt, doppelte Anführungszeichen fassen zusammen.

Bei PowerShell bindet ein Argument wie -Path oder -Force an den gleichnamigen Parameter des Skripts, wie bei powershell -File.

Werte in Skripte: über Environment

Platzhalter wie {{FilePath}} können auch in Script stehen; sie werden vor dem Lauf in den Skripttext eingesetzt. Ein Wert mit Anführungszeichen oder Leerzeichen kann das Skript dann zerstören. Sicherer: den Wert in Environment übergeben und im Skript als $env:DATEI bzw. %DATEI% lesen.

Platzhalter in cmd-Skripten

RUNOS ersetzt Platzhalter vor dem Lauf in allen Parametern, auch im Skript: neben {{…}} auch %yyyy%, %MM%, %dd%, %date%, %time% und %NAME% von Umgebungsvariablen, die RUNOS selbst kennt (z. B. wird %USERNAME% zum Benutzer, unter dem RUNOS läuft, auch mit User). Variablen aus Environment und solche, die das Skript selbst setzt (set X=…), bleiben für cmd stehen.

PowerShell

• Der Exit-Code ist der aus exit n im Skript; ohne exit der des letzten externen Programms, das das Skript aufgerufen hat, sonst 0. Ein Fehler im Skript beendet es mit Exit-Code 1.
• Darf ein Programm im Skript einen anderen Code als 0 liefern, ohne dass das ein Fehler ist, beenden Sie das Skript mit exit 0.
• Die Ausgabe ist alles, was das Skript ausgibt (Write-Output oder Werte, die nicht zugewiesen werden). Ist sie JSON (z. B. aus ConvertTo-Json), steht sie zusätzlich in Response.Json, und eine folgende Aktion liest einzelne Werte, z. B. {{Pruefsumme.Response.Json.Sha256}}.

Cmd und Batch-Dateien

• Ein Skript in Script beginnt mit @echo off, es erscheint also nur die Ausgabe seiner Befehle.
• Ein Argument mit Leerzeichen oder einem der Zeichen & | < > ^ , ; = ( ) wird in Anführungszeichen übergeben; im Skript lesen Sie es mit %~1 (ohne die Anführungszeichen). Ein Argument mit doppeltem Anführungszeichen oder Zeilenumbruch lässt sich nicht sicher übergeben und lässt die Aktion fehlschlagen; solche Werte über Environment übergeben.

Als anderer Benutzer ausführen

Mit User und Password läuft das Programm als dieser Windows-Benutzer, mit geladenem Benutzerprofil. Legen Sie die Zugangsdaten in einem Basic-Konnektor ab und verweisen Sie mit {{connector.ERP.Username}} und {{connector.ERP.Password}} darauf; dort sind sie verschlüsselt gespeichert.

• Der Benutzer muss sich an diesem PC anmelden dürfen („Lokal anmelden zulassen“). Ein falsches Passwort oder ein fehlendes Recht lässt die Aktion mit einer entsprechenden Meldung fehlschlagen.
• Ohne Environment bekommt das Programm die eigenen Umgebungsvariablen dieses Benutzers. Mit Environment bekommt es die des Benutzers, unter dem RUNOS läuft, plus die angegebenen.
• Windows erlaubt für die Befehlszeile eines Programms, das als anderer Benutzer startet, höchstens 1024 Zeichen. Lange Werte über Environment übergeben.

Ohne Warten

Mit "Wait": false startet die Aktion das Programm nur und ist erfolgreich, sobald es läuft; Response enthält dann nur die ProcessId. Exit-Code und Ausgabe werden nicht gelesen, und TimeoutSeconds gilt nicht. Das passt für Programme, die weiterlaufen sollen, etwa ein Anzeigeprogramm.

Ergebnis

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

Output ist die Standardausgabe und Errors die Fehlerausgabe, jeweils ohne Leerzeilen am Ende und bis zu 1.000.000 Zeichen (was darüber hinausgeht, wird mit einer Warnung abgeschnitten). Json gibt es nur, wenn die ganze Ausgabe JSON ist. Eine folgende Aktion liest die Werte als {{Pruefsumme.Response.Output}} oder {{Pruefsumme.Response.ExitCode}}.

Schlägt die Aktion fehl, steht der Grund in den Fehlern des Ergebnisses: der Exit-Code mit den letzten Zeilen der Fehlerausgabe (bzw. der Ausgabe, wenn die Fehlerausgabe leer ist), das Zeitlimit oder warum das Programm nicht starten konnte (nicht gefunden, falsches Passwort, Ordner fehlt). Eine Warnung erscheint, wenn ein vom Skript gestartetes Programm noch läuft und die Ausgabe offen hält; die Ausgabe bis dahin steht im Ergebnis.

Formular im Editor

Im Diagramm des Workflow-Editors hat die Aktion ein Formular (im Einstellungsfeld und in der mittleren Spalte der Testansicht):

• Was ausgeführt wird: Programm oder Datei oder Skript. Ein Wechsel entfernt die Felder der anderen Art; Strg+Z holt sie zurück. Bei Programm oder Datei Programm und Argumente (wie in einer Befehlszeile, oder ein Argument pro Zeile, wenn Arguments eine Liste ist); bei Skript die Shell (Windows PowerShell, PowerShell 7 oder cmd) und der Skripteditor. Dazu der Arbeitsordner.
• Warten und Ergebnis: Warten, bis es endet (Standard an), Zeitlimit (Standard 300 Sekunden, 0 = keins), Exit-Codes, die als Erfolg gelten (z. B. 0;3010 oder 0-7), Bei Fehlerausgabe fehlschlagen und Kodierung der Ausgabe.
• Weitere Optionen: Umgebungsvariablen als Tabelle sowie Als Benutzer ausführen mit Passwort.

Jedes Feld nimmt auch {{…}}-Platzhalter und Werte, die Sie in der Testansicht aus der Spalte Eingabe hineinziehen; Auswahllisten, Schalter und Zahlenfelder werden mit einem {{…}} zu einem Textfeld. Parameter, die das Formular nicht kennt, stehen unter Weitere Parameter. Schritt testen führt die Aktion sofort einmal aus, mit den Daten der Schritte davor, und zeigt das Ergebnis mit Fehlern und Warnungen. Der Test führt Skript bzw. Programm wirklich auf diesem PC aus; die Ausgabe zeigt ExitCode, Output und Errors.

Beispiel

Den Exportordner jede Nacht auf das NAS spiegeln. robocopy meldet Erfolg mit den Exit-Codes 0 bis 7, deshalb gelten diese als Erfolg:

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

Prüfsumme jeder eingehenden Datei. Ein Datei-Trigger übergibt jedes PDF an ein PowerShell-Skript. Die Datei kommt über Environment herein; das Skript gibt JSON aus, das folgende Aktionen als {{Pruefsumme.Response.Json.Sha256}} lesen:

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

Dateien als Dienstbenutzer an einen ERP-Import übergeben. Die Batch-Datei C:\ERP\import.cmd liest die Datei als %~1 und den Mandanten als %~2. Sie läuft als der Benutzer aus dem Basic-Konnektor ERP und darf bis zu zehn Minuten brauchen:

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