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 zeichnet lediglich nichts auf den Bildschirm.

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. Es lässt sich im Log-Viewer des Editors über Datei → Externes Log öffnen öffnen.

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 – das, was Sie in der CI-Ausgabe haben möchten.
--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 einfügt. 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. Versehen Sie solche Aktionen mit Aktiviert (Test), 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.

---

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. Vom Projektstamm aus 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, mit dem statt profile ausgeführt 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.

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 die Schlüssel existieren auf dem Rechner, der das Szenario ausführt.
• In der Produktion wird kein Eingabeformular und keine andere interaktive Aktion ausgeführt.
• Das Szenario endet mit einer Berichterstattung – siehe Das Szenario für unbeaufsichtigte Läufe robust machen.
• --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.