Szenarien außerhalb des Editors ausführen

Ein Szenario, das Sie im Editor speichern, ist eine gewöhnliche .json-Datei. Es lässt sich ausführen, ohne dass das Editor-Fenster geöffnet ist – mit einem einzigen Befehl, aus einem Scheduler heraus oder über Prefect. Der Roboter tut genau das, was Sie im Editor sehen würden; er zeigt dabei lediglich nichts auf dem Bildschirm an.

Wann was verwenden

Bedarf	Verwenden Sie
Geplante Läufe, während der Editor auf einer Workstation oder VM geöffnet bleibt	Orchestrator
Läufe ganz ohne Editor-Fenster – CI, ein Server, ein externer Scheduler	diese Seite

---

Ausführen mit einem Befehl

Neben dem Szenario benötigen Sie ein Roboterprofil – das Profil, das Sie im Dialog Umgebung öffnen speichern und das ebenfalls eine .json-Datei ist.

aiviro-editor run --scenario invoices.json --profile robot_profile.json

Beide Optionen sind erforderlich.

Option	Wirkung
--scenario PATH	Das auszuführende .json-Szenario. Erforderlich.
--profile PATH	Das Roboterprofil, mit dem es ausgeführt wird. Erforderlich.
--prod / --test	Produktions- oder Testmodus. --prod ist der Standard, ein Szenario läuft also live, sofern Sie nicht --test angeben.
--run-log PATH	Schreibt ein Lauf-Log als .zip (Aktionszustände plus Logs) an diesen Pfad. Sie können es über Datei → Externes Log öffnen im Log-Viewer des Editors anzeigen.
--vault-file PATH	Eine aus dem Editor exportierte .vault-Datei, die die Geheimnisse für den Lauf liefert. Siehe Geheimnisse ohne Schlüsselbund.
--config PATH	Eine YAML- oder JSON-Datei mit Variablennamen und Werten, die vor dem Start in den Lauf übernommen werden. Siehe Werte pro Umgebung.

Zwei Optionen gelten für den Befehl als Ganzes und können auch aus der Umgebung kommen:

Option	Umgebungsvariable	Wirkung
--log-to-console, -l	AIVIRO__LOG_TO_CONSOLE	Protokolliert in die Konsole – sinnvoll für die CI-Ausgabe.
--debug	AIVIRO__DEBUG	Aktiviert die nur für das Debugging gedachte Oberfläche. Headless nicht nützlich.

Wenn Sie aiviro-editor ohne Unterbefehl ausführen, wird die Desktop-Oberfläche gestartet.

Exit-Codes

Der Befehl endet bei Erfolg mit 0 und bei einem Fehler mit 1, sodass er sich in jeden Scheduler und jedes Shell-Skript einbinden lässt. Bei einem Fehler gibt er außerdem Scenario failed: <summary> auf der Standardfehlerausgabe aus.

aiviro-editor run --scenario invoices.json --profile robot_profile.json --run-log run.zip || echo "failed"

warnung

Interaktive Aktionen funktionieren headless nicht. Ein Szenario mit Eingabeformular schlägt mit Interactive action encountered in headless mode fehl – ohne Fenster gibt es niemanden, den man fragen könnte. Beschränken Sie solche Aktionen mit Aktiviert (Test) auf Testläufe, damit sie in der Produktion nie ausgeführt werden.

tipp

Die Pfade zum Szenario und zum Profil können absolut sein oder relativ zu dem Verzeichnis, aus dem Sie den Befehl ausführen.

---

Geheimnisse ohne Schlüsselbund

Ein Headless-Lauf hatte früher keinen Zugriff auf den Tresor: Jedes Geheimnis wurde zu einem leeren Wert aufgelöst, sodass ein Szenario, das Zugangsdaten benötigte, außerhalb des Editors überhaupt nicht laufen konnte.

--vault-file schließt diese Lücke. Im Editor schreibt Tresor exportieren im Dialog Sicherer Tresor eine .vault-Datei; übergeben Sie sie dem Lauf, und ihre Geheimnisse werden nur für diesen Lauf im Arbeitsspeicher gehalten:

aiviro-editor run --scenario invoices.json --profile robot_profile.json --vault-file secrets.vault

In den Schlüsselbund des Rechners wird nichts geschrieben, sodass ein CI-Worker oder ein Container sauber bleibt und überhaupt keinen Schlüsselbund benötigt – genau das machte Container früher umständlich.

Jedes Geheimnis steht dem Szenario außerdem als Variable unter seinem Schlüsselnamen zur Verfügung, sodass sich ein Wert, den Sie im Tresor aufbewahren, genauso lesen lässt wie eine gewöhnliche Variable.

Fehlt in der Datei ein Geheimnis, das das Szenario anfordert, protokolliert der Lauf eine Warnung und läuft weiter, statt anzuhalten – prüfen Sie daher beim ersten Headless-Lauf eines Szenarios das Log und nicht nur den Exit-Code.

warnung

Eine .vault-Datei enthält Ihre Zugangsdaten in einer portablen Datei. Committen Sie sie nicht in Git, übergeben Sie sie dem Lauf aus dem Secret Store Ihres CI-Systems und löschen Sie sie danach.

Werte pro Umgebung

--config übernimmt Variablen vor dem Start in den Lauf. So richten Sie ein Szenario auf eine Test- und eine Produktionsumgebung aus, ohne das Szenario selbst zu bearbeiten:

# config-test.yaml
invoice_folder: C:\data\test\invoices
portal_url: https://test.example.com
account_number: "123456789"

aiviro-editor run --scenario invoices.json --profile robot_profile.json --config config-test.yaml

JSON funktioniert ebenfalls – die Datei kann in beiden Formaten vorliegen. Die Schlüssel sind Variablennamen, die Werte sind die Anfangswerte dieser Variablen.

Beide Dateien werden validiert, bevor der Roboter angesprochen wird: Eine fehlerhafte Konfigurations- oder Tresordatei wird mit einer eindeutigen Meldung abgelehnt, statt mitten in einem Lauf fehlzuschlagen, der bereits eine Anwendung geöffnet hat.

---

Geplante Läufe über Prefect

Für wiederkehrende Läufe wird das Szenario in einen Prefect-Flow eingebettet. Kopieren Sie diese Vorlage in eine Datei im Verzeichnis flows/ Ihres Projekts – zum Beispiel flows/flow_invoices.py – und passen Sie die darunter aufgeführten Werte an.

import aiviro
from aiviro.modules.prefect_v3.storage import AiviroGitDockerStorage
from aiviro_editor.headless.runner import run_editor_scenario
from prefect import flow

from src import get_file_path, get_work_dir

SCENARIO_FILE = "scenarios/invoices.json"
PROFILE_FILE = "data/robot_profile.json"


@flow(log_prints=True, name="Invoice processing")
def main() -> None:
    result = run_editor_scenario(
        get_file_path(SCENARIO_FILE),
        profile=get_file_path(PROFILE_FILE),
        is_prod=True,
    )
    if not result.success:
        raise RuntimeError("Scenario failed: " + result.error_summary)


if __name__ == "__main__":
    main.from_source(
        source=AiviroGitDockerStorage(project_path=get_work_dir(), git_branch="main"),
        entrypoint="flows/flow_invoices.py:main",
    ).deploy(
        name="main",
        work_pool_name="aiviro-local",
        work_queue_name="default",
        cron="0 6 * * *",
        job_variables={aiviro.AIVIRO_DEBUG_KEY: "0"},
    )

Was Sie in Ihrer Kopie ändern

Wert	Bedeutung
SCENARIO_FILE, PROFILE_FILE	Pfade zum Szenario und zum Roboterprofil. Relativ zum Projektstammverzeichnis angegeben, mit Schrägstrichen /, weil der Server sie liest.
name bei @flow	Der Name, unter dem der Flow in Prefect erscheint.
entrypoint	Muss genau mit Speicherort und Namen der Datei übereinstimmen, sonst findet der Server sie nicht.
git_branch	Der Branch, aus dem das Szenario genommen wird.
cron	Wann ausgeführt wird. None bedeutet nur manuelle Läufe.
is_prod	True für einen Live-Lauf, False für einen Testlauf.

warnung

Das Szenario und das Profil müssen im Projekt gespeichert und in Git committet sein – zur Laufzeit liest der Server sie von dort, nicht von Ihrem Computer.

---

Die Python-API

run_editor_scenario ist ein Wrapper für einen einzelnen Aufruf und akzeptiert mehr, als die Vorlage zeigt:

Parameter	Bedeutung
scenario	Pfad zur .json oder ein bereits geladenes Szenario.
profile	Pfad zum Profil oder ein geladenes Profilobjekt.
robot	Ein vorhandener Roboter, der anstelle von profile verwendet wird. Genau eines von profile / robot muss angegeben werden.
is_prod	True (Standard) für Produktion, False für Test.
run_log_path	Wohin das Lauf-Log als .zip geschrieben wird.
wait_after	Sekunden, die nach dem Ende des Szenarios gewartet wird.
config_variables	Variablen, die vor dem Start in den Lauf übernommen werden – das API-Gegenstück zu --config.
vault_export	Ein exportierter Tresor, der die Geheimnisse für den Lauf liefert – das API-Gegenstück zu --vault-file.

Er gibt ein Ergebnis mit success, error_summary und run_log_path zurück.

tipp

Um mehrere Szenarien mit einem Roboter auszuführen, verwenden Sie EditorRunner direkt, statt run_editor_scenario wiederholt aufzurufen – er verbindet den Roboter einmal und verwendet ihn wieder, was pro Szenario die gesamten Kosten für Verbindungsaufbau und Start spart.

---

Checkliste vor dem Wechsel zu Headless

• Alle Zugangsdaten liegen im Tresor, und der Lauf kann darauf zugreifen: Entweder existieren die Schlüssel im Schlüsselbund des Rechners, der das Szenario ausführt, oder Sie übergeben mit --vault-file eine exportierte .vault-Datei – dafür ist überhaupt kein Schlüsselbund nötig.
• In der Produktion wird kein Eingabeformular und keine andere interaktive Aktion ausgeführt.
• Das Szenario verschickt am Ende einen Bericht – siehe So übersteht das Szenario unbeaufsichtigte Läufe.
• --run-log ist gesetzt, sodass ein fehlgeschlagener Lauf etwas zum Nachlesen hinterlässt.
• Das Roboterprofil auf dem Zielrechner hat die richtige Adresse, die richtigen Zugangsdaten und die richtige Anzeige.