State Machine — Flexible Prozessorchestrierung

Das Aufteilen von Workflows in Sinnabschnitte funktioniert gut wenn der Ablauf immer gleich ist. Aber was wenn ein Prozess flexibel sein muss? Wenn manche Schritte übersprungen werden können, die Reihenfolge variiert, oder ein Schritt mehrfach ausgeführt wird?

Genau dafür gibt es das State Machine Pattern.

---

Was ist eine State Machine?

Eine State Machine (Zustandsmaschine) ist ein Konzept aus der Informatik: ein System das sich immer in genau einem definierten Zustand befindet, und das auf Basis dieses Zustands entscheidet was als nächstes passiert.

Übertragen auf 42°OS bedeutet das:

• Jeder Prozess (eine Bestellung, ein Dokument, ein Auftrag) hat einen aktuellen Status
• Der State Machine Agent liest diesen Status aus einer Tabelle
• Er wählt auf Basis des Status den passenden Workflow aus und startet ihn
• Der Workflow verarbeitet seinen Teil und schreibt den neuen Status zurück
• Der State Machine Agent wird erneut aufgerufen — und wählt den nächsten Workflow

Eingehende Nachricht (run_id)
        ↓
State Machine Agent
        ↓
Status aus Tabelle lesen → "new"
        ↓
Workflow "Bestellung validieren" starten
        ↓
Workflow schreibt neuen Status → "validated"
        ↓
State Machine Agent erneut aufgerufen
        ↓
Status lesen → "validated" → nächsten Workflow starten
        ↓
...

---

Wann ist die State Machine das richtige Muster?

Die State Machine ist dann sinnvoll wenn mindestens eine dieser Bedingungen zutrifft:

• Flexible Reihenfolge — die Schritte können je nach Datenlage in unterschiedlicher Reihenfolge ablaufen
• Optionale Schritte — manche Schritte werden nur unter bestimmten Bedingungen ausgeführt
• Wiederverwendung von Teilschritten — mehrere übergeordnete Prozesse teilen sich dieselben Workflows
• Langläufige Prozesse — ein Prozess dauert Stunden oder Tage und wird in mehreren separaten Runs durchgeführt
• Manuelle Eingriffe — ein Mitarbeiter setzt den Status manuell weiter (z. B. nach einer Freigabe)

---

Der State Machine Agent in 42°OS

Die Status-Tabelle

Der State Machine Agent verwaltet eine eigene Tabelle im Internal Storage. Der Tabellenname folgt dem Schema:

state_machine_{AGENT_ID}

Die Agent-ID findest du in der URL der Agent-Detailansicht. Wenn die Agent-ID 1851 ist, heißt die Tabelle state_machine_1851. Du kannst die Tabelle jederzeit im Internal Storage einsehen.

Pflichtfelder in der Tabelle:

Spalte	Typ	Bedeutung
run_id	TEXT (Primary Key)	Eindeutige ID des Prozesses (z. B. Bestellnummer)
current_status	TEXT	Aktueller Status des Prozesses

Weitere Spalten sind frei konfigurierbar — z. B. für Produkt, Menge, Kundennummer oder andere Prozessdaten.

Schema-Änderungen löschen Daten

Wenn du das Tabellenschema des State Machine Agents änderst, wird die Tabelle neu erstellt — alle bestehenden Einträge gehen verloren. Eine automatische Backup-Tabelle wird angelegt, aber exportiere wichtige Daten vorher zur Sicherheit.

Status-Workflow-Mappings

Im Agent konfigurierst du für jeden möglichen Status den zugehörigen Workflow und einen Task-Key:

[
  {"status": "new",       "workflow_id": 12, "task_key": "validate_order"},
  {"status": "validated", "workflow_id": 12, "task_key": "process_payment"},
  {"status": "paid",      "workflow_id": 13, "task_key": "prepare_shipment"},
  {"status": "shipped",   "workflow_id": 14, "task_key": "send_confirmation"}
]

Wichtig: Verwende die numerische Workflow-ID, die du in der URL der Workflow-Detailansicht findest — nicht die GUID.

Der Task-Key

Der Task-Key ist ein Bezeichner der dem aufgerufenen Workflow mitgeteilt wird. Er erklärt dem Workflow welche Aufgabe ausgeführt werden soll.

Das ermöglicht einen wichtigen Effizienzgewinn: statt für jeden Status einen eigenen Workflow zu bauen, kann ein einziger Workflow mehrere Tasks übernehmen — und per Switch Agent auf den Task-Key verzweigen:

Workflow empfängt Nachricht:
{
  "task": "validate_order",
  "run_id": "ORDER-123",
  "status": "new"
}
        ↓
Switch Agent: was ist task?
  → "validate_order"  → Validierungs-Abschnitt
  → "process_payment" → Zahlungs-Abschnitt
  → "prepare_shipment"→ Versand-Abschnitt

Ein Workflow für mehrere Aufgaben — statt zehn Workflows, ein Workflow mit zehn klar benannten Tasks.

Neuen Prozess automatisch anlegen

Mit der Option auto_create_initial legt der Agent automatisch einen neuen Eintrag in der Status-Tabelle an, wenn für eine eingehende run_id noch kein Eintrag existiert. Der initiale Status wird über initial_status konfiguriert.

Das ist nützlich wenn der erste Auslöser (z. B. eine eingehende Bestellung) direkt den State Machine Agent aufruft, ohne dass vorher manuell ein Tabelleneintrag angelegt werden muss.

Exit-Status

Du kannst einen exit_status konfigurieren. Wenn der aktuelle Status des Prozesses diesem Exit-Status entspricht, führt der Agent keinen weiteren Workflow aus und gibt die Nachricht einfach an den nächsten Agent im Workflow weiter. So wird das Ende eines Prozesses sauber signalisiert.

---

Status aktualisieren

Der neue Status wird auf zwei Wegen in die Tabelle geschrieben:

Automatisch — wenn der aufgerufene Workflow in seiner Ausgabe ein Feld status zurückgibt, wird es automatisch auf die konfigurierte Status-Spalte gemappt.

Explizit per SQL — ein Workflow kann die Status-Tabelle direkt per SQL-Nachricht aktualisieren:

{
  "sql": "UPDATE state_machine_1851 SET current_status = 'paid' WHERE run_id = 'ORDER-123'",
  "target_agent": "1851"
}

Der explizite Weg gibt dir volle Kontrolle — du kannst nicht nur den Status, sondern auch andere Felder in der Tabelle aktualisieren.

---

Praxisbeispiel: Auftragsverarbeitung

Ein Auftrag durchläuft je nach Produkt unterschiedliche Schritte. Standardaufträge werden direkt verarbeitet, Sonderaufträge brauchen eine manuelle Freigabe.

Status-Tabelle:
┌─────────────┬────────────────┬──────────────┐
│ run_id      │ current_status │ order_type   │
├─────────────┼────────────────┼──────────────┤
│ ORDER-001   │ new            │ standard     │
│ ORDER-002   │ approval       │ custom       │
└─────────────┴────────────────┴──────────────┘

Mappings:
"new"       → Workflow A, task_key: "validate"
"approval"  → Workflow B, task_key: "request_approval"  (Human Task)
"approved"  → Workflow A, task_key: "process"
"processed" → Workflow C, task_key: "ship"
"shipped"   → EXIT

ORDER-001 durchläuft new → processed → shipped. ORDER-002 durchläuft new → approval → approved → processed → shipped.

Derselbe State Machine Agent, dieselben Workflows — unterschiedliche Pfade.

---

Wichtige Hinweise

Status-Matching ist case-sensitive. approved und Approved sind zwei verschiedene Status. Wenn ein Mapping nicht greift, prüfe die genaue Schreibweise in der Tabelle und im Mapping.

Incoming Message Daten werden bei jedem Lauf automatisch in passende Tabellenfelder geschrieben. Um unerwünschte Daten zu vermeiden, schalte einen Message Formatting Agent vor den State Machine Agent um die Nachricht auf die relevanten Felder zu reduzieren.