# Workflowinstanz

Dieses Kapitel beleuchtet den Lebenszyklus einer konkreten Workflowinstanz: Vom Trigger über das Polling der Engine bis hin zur Fehlerbehandlung und Persistenz.

## Start aus einem trade-Vorgang

Eine Workflowinstanz wird nicht über einen aktiven Push-Mechanismus (wie Webhooks) gestartet, sondern durch das **aktive Polling** der Workflow-Engine.

Der Trigger eines Blueprints (siehe [Workflow Blueprint](/knowledge/docs/products/workflow/technical/workflow-blueprint.md)) legt fest, welche trade-Vorgänge einen Workflow auslösen: `objectType: transaction`, die Vorgangsart(en) (`transactionTypes`) und der Status (`statuses`) des Vorgangs. Die Engine fragt trade danach ab; **für jeden passenden Vorgang, der noch keine Instanz dieses Blueprints hat, wird eine Instanz gestartet**. Fehlt im Trigger die Vorgangsart oder der Status, wird der Blueprint nicht abgefragt.

Beim Start übernimmt die Engine:
- **Workflow:** der Blueprint, dessen Trigger den Vorgang erfasst.
- **Objekt-Referenz:** die Vorgangsnummer (`transactionNumber`) als fachliche Referenz, zusätzlich die ID des Vorgangs.
- **Vorgangsdaten:** Kopf, Typdaten (`typeData`) und Positionen (`lines`) des Vorgangs werden einmalig geladen und in der Instanz gespeichert; Bedingungen, Schrittfelder und Übersichtsfelder lesen daraus.

Pro Vorgang kann nur **ein** Workflow aktiv sein. Ein manuell ausgelöster Start (Portal) und das Polling führen daher nie zu zwei Instanzen für denselben Vorgang und Blueprint. Für einen Vorgang, der bereits eine Instanz des Blueprints hatte (in beliebigem Zustand), startet das Polling keine neue.

## Polling-Verhalten und Performance

Die Häufigkeit, mit der die Engine nach neuen Workflows sucht, ist konfigurierbar (Umgebungsvariable `POLLING_INTERVAL`, Minuten). Standard und Produktionswert ist **1 Minute**.

In jedem Polling-Durchlauf prüft die Engine alle aktiven Mandanten und deren Blueprints. Die Vorgänge werden seitenweise (Paging) mit je 100 Treffern abgerufen. Pro Mandant startet ein Durchlauf höchstens 100 Workflows; weitere passende Vorgänge folgen in den nächsten Durchläufen (z. B. nach der ersten Aktivierung mit vielen offenen Vorgängen). Für Mandanten, deren Workflow-Konfiguration deaktiviert ist, startet das Polling nichts mehr, liefert aber ausstehende Status-Rückschreibungen an trade noch nach.

## Zustände einer Instanz

Während ihres Laufs durchläuft eine Instanz verschiedene technische und fachliche Zustände:

```mermaid
flowchart TD
    Start([Start: Polling]) --> CheckTrigger{Trigger-Bedingung erfüllt?}
    CheckTrigger -->|Nein| TriggerNotMatched([TRIGGER_NOT_MATCHED])
    CheckTrigger -->|Ja| Open[Zustand: OPEN]

    subgraph Processing [Aktive Bearbeitung]
        Open --> Steps{Schritte im Blueprint}
        Steps -->|Nächster Schritt| Open
        Open -->|Tenant Admin Abbruch| Cancelled([CANCELLED])
    end

    Steps -->|Finale Entscheidung| Sync[Versuch: Status an trade schreiben]

    subgraph RetryLogic [Fehlerbehandlung trade]
        Sync -->|Fehler| Retrying[Zustand: RETRYING_SYNC]
        Retrying -->|Erneuter Versuch| Sync
    end

    Sync -->|Erfolg| EndStates{Finaler Status}
    EndStates -->|Freigabe| Approved([APPROVED / COMPLETED])
    EndStates -->|Ablehnung| Rejected([REJECTED])

    Approved --> Finish([Archivierung])
    Rejected --> Finish
    Cancelled --> Finish
    TriggerNotMatched --> Finish
```

### Übersicht der Instanz-Zustände

| Zustand | Typ | Beschreibung |
| :--- | :--- | :--- |
| **`OPEN`** | Aktiv | Der Workflow befindet sich in regulärer Bearbeitung. Ein Benutzer oder eine Gruppe ist zugewiesen. Der Vorgang ist in trade gesperrt. |
| **`RETRYING_SYNC`** | Aktiv (Wiederholung) | Die Instanz wartet auf trade: Entweder konnte der Vorgang beim Start nicht geladen werden, oder das Zurückschreiben des Status ist fehlgeschlagen. Die Instanz ist währenddessen schreibgeschützt, das System wiederholt den Versuch mit exponentiellem Backoff. Der Vorgang bleibt in trade gesperrt. |
| **`APPROVED`** | Endzustand | Alle Freigabeschritte wurden erfolgreich durchlaufen. Der Vorgang ist in trade wieder frei. |
| **`REJECTED`** | Endzustand | Ein Bearbeiter hat den Vorgang fachlich abgelehnt. Der Vorgang ist in trade wieder frei. |
| **`COMPLETED`** | Endzustand | Workflow erfolgreich beendet (bei Prozessen ohne explizite Freigabe-/Ablehnungslogik). |
| **`CANCELLED`** | Endzustand | Der Vorgang wurde durch einen Tenant-Administrator administrativ beendet. Der Vorgang ist in trade sofort wieder frei. |
| **`TRIGGER_NOT_MATCHED`** | Endzustand | Die Vorgangsdaten erfüllten beim Start die im Blueprint hinterlegte Bedingung (`trigger.condition` bzw. `trigger.nextStep.condition`) nicht. Die nicht erfüllte Regel steht im Protokoll der Instanz. An den Vorgang wird nichts zurückgeschrieben. |
| **`TECHNICALLY_FAILED`** | Endzustand | Der Start ist an einem technischen oder Konfigurationsfehler gescheitert. An den Vorgang wird nichts zurückgeschrieben. |

## Blueprint-Inspektion zur Laufzeit

Jede Workflow-Instanz ist fest an die Version des Blueprints gebunden, mit der sie gestartet wurde. Um Nachvollziehbarkeit und Fehlersuche zu gewährleisten, stellt ConnectWORKFLOW für jede Instanz eine Blueprint-Vorschau bereit:

* **Abruf:** Über das Portal können Benutzer und Administratoren direkt an der Aufgabe oder in der Instanzenliste die Blueprint-Definition öffnen.
* **Grafische Visualisierung:** Das Portal rendert den Blueprint über die Komponente `WorkflowCanvas` als interaktiven Graphen aller Schritte, Verzweigungen und Bedingungen.
* **YAML-Quelltext:** Die bereinigte Blueprint-Definition kann im YAML-Format eingesehen und per Klick in die Zwischenablage kopiert werden.

## Wichtige Datenfelder

Jede Instanz führt einen „Rucksack“ an Daten mit sich, der über die gesamte Laufzeit erhalten bleibt:
- **`currentStep`:** Zeigt an, in welchem Schritt des Blueprints sich der Workflow gerade befindet.
- **`claimedBy`:** Dokumentiert den aktuellen Besitzer einer Aufgabe (siehe [Aufgabeaktionen](/knowledge/docs/products/workflow/technical/task-actions.md)). Um Blockaden zu vermeiden, wird die Übernahme nach 24 Stunden automatisch aufgehoben.
- **`history`:** Eine lückenlose, revisionsfähige Spur aller Aktionen, Zeitstempel und beteiligten Personen.
- **`data`:** Der Datenspeicher der Instanz: der Schnappschuss des Vorgangs (Kopf, `typeData`, `lines`) vom Start sowie Eingaben aus Workflow-eigenen Feldern und Zwischenstände. Vorgangsfelder bleiben schreibgeschützt.

## Fehlerbehandlung und Retrying

Der Status einer Instanz wird nach jeder Entscheidung an den trade-Vorgang zurückgeschrieben (siehe [trade-Integration](/knowledge/docs/products/workflow/technical/erp-integration.md)). Typische Ursachen für Fehler dabei:
- **Unerreichbarkeit:** trade ist temporär nicht erreichbar oder das Netzwerk ist gestört.
- **Fehler beim Start:** Der Vorgang konnte beim Start nicht aus trade geladen werden.

In solchen Fällen wechselt die Instanz automatisch in den technischen Zustand `RETRYING_SYNC`. Die Entscheidung (z. B. Freigabe) ist damit nicht verloren: Sie wird festgehalten und an trade übermittelt, sobald trade wieder erreichbar ist.

### Die Retry-Strategie
Das System nutzt eine **exponentielle Wiederholungs-Strategie**:

- **1. Versuch:** Nach 1 Minute
- **2. Versuch:** Nach weiteren 2 Minuten
- **3. Versuch:** Nach weiteren 4 Minuten
- **4. Versuch:** Nach weiteren 8 Minuten
- **ab dem 5. Versuch:** alle 16 Minuten

### Es gibt keine Obergrenze
Die Wiederholungen werden **nicht** nach einer bestimmten Zahl von Versuchen aufgegeben. Ein Abbruch würde den Vorgang in trade dauerhaft sperren, obwohl der Workflow beendet ist. Nach mehreren erfolglosen Versuchen wird der Fehler vom Betrieb als Fehlermeldung (ERROR) protokolliert; die Prozess-Historie enthält den Eintrag, dass der Status nicht geschrieben werden konnte.

- **Sichtbarkeit:** Das Portal zeigt an der Aufgabe den Zustand `RETRYING_SYNC`. Die Instanz ist währenddessen schreibgeschützt.
- **Erwartete Reaktion:** In der Regel ist kein Eingriff nötig. Hält der Zustand an, ist die Verbindung zu trade zu prüfen (z. B. mit der Funktion **Konfiguration prüfen**).
- **Vorgang nicht mehr vorhanden:** Wurde der Vorgang in trade gelöscht, wird die Rückschreibung nicht wiederholt.

## Persistenz und Nachvollziehbarkeit

Nach jedem abgeschlossenen Schritt wird der aktuelle Stand der Instanz inklusive der gesamten Historie dauerhaft in der Datenbank `workflow` gespeichert. Die Speicherung ist durch eine Revisionsprüfung gegen gleichzeitige Änderungen abgesichert: Schreiben zwei Prozesse (z. B. eine Übernahme und der automatische Timeout) gleichzeitig, wird die zweite Änderung abgelehnt statt die erste zu überschreiben. Jede Änderung einer Instanz erfolgt unter einer Sperre pro Instanz. Dies stellt sicher, dass auch bei einem Systemneustart oder einem schwerwiegenden Fehler keine Prozessdaten verloren gehen und jeder Schritt jederzeit auditierbar bleibt.
