Workflow-Wiederherstellung sicher ausführen

Prüfen Sie einen fehlgeschlagenen Workflow-Schritt und planen Sie ihn gezielt zur Wiederherstellung ein. Danach ist entweder ein wiederholungssicherer Eintrag geplant oder der Schritt nachvollziehbar als nicht wiederholbar eingeordnet. Workspace wiederholt eine nicht bestätigte Transition oder genau die gespeicherte Action – niemals pauschal den gesamten Workflow.

Voraussetzungen

Sie benötigen:

• eine Anmeldung am betroffenen Mandanten in Workspace oder einen angemeldeten nucli-Mandantenalias,
• die Berechtigung zum Lesen und Wiederholen von Workflow-Dead-Letter-Einträgen,
• Zugriff auf Automatisierung > Workflows > Wiederherstellung oder die UUID des Eintrags aus GET /api/v1/workflow-dead-letters.

Verwenden Sie für einen erreichbaren Server immer nucli oder die tenantgebundene API. Ändern Sie weder Workflow- noch Dead-Letter-Daten direkt in PostgreSQL. numin ist kein Remote-Recovery-Client für diesen Ablauf.

Eintrag in Workspace prüfen

1. Öffnen Sie Automatisierung > Workflows > Wiederherstellung.
2. Grenzen Sie die Arbeitsliste über den Status ein.
3. Prüfen Sie Workflow-Schritt, Instanz, Fehler, Versuche und Dead-Letter-Zeitpunkt.
4. Beheben Sie die fachliche oder technische Ursache.
5. Wählen Sie Wiederholen nur für einen Eintrag mit Status Offen oder Erneuter Versuch geplant und bestätigen Sie das Einplanen.

Die Aktion erscheint nur mit Lese- und Replay-Berechtigung. Einträge mit Eingeplant oder Wird ausgeführt werden bereits bearbeitet. Abgeschlossen benötigt keine weitere Aktion. Nicht wiederholbar darf nicht durch eine Datenbankänderung umgangen werden.

Preflight mit nucli prüfen

Nutzen Sie nucli, wenn Sie den Ablauf skripten, automatisieren oder außerhalb der Administrationsoberfläche nachvollziehen müssen. Führen Sie zuerst den read-only Preflight aus:

nucli --tenant <mandantenalias> workflow recovery replay <dead-letter-uuid>

Für eine maschinenlesbare Ausgabe ergänzen Sie --json. Der Preflight liest den Eintrag, zeigt Wiederherstellungsart, Instanz, Status und Ziel und löst keine Mutation aus. Prüfen Sie insbesondere:

• Ist der richtige Mandant ausgewählt?
• Gehören Instanz, Transition oder Action zum erwarteten Fachvorgang?
• Ist der Eintrag noch offen und ist der ursprüngliche Fehler fachlich oder technisch behoben?
• Ist die Action ausdrücklich replay-sicher? Unklassifizierte Actions bleiben gesperrt.

Wiederherstellung mit nucli einplanen

Wenn der Preflight den erwarteten Eintrag zeigt, planen Sie die Wiederherstellung explizit ein:

nucli --tenant <mandantenalias> workflow recovery replay <dead-letter-uuid> --apply

nucli wiederholt vor dem mutierenden Request den Preflight. Der Server antwortet erst mit queued, nachdem der Recovery-Auftrag persistent gespeichert wurde. Ein Worker übernimmt ihn anschließend mit Lease und monotonem Fence.

Eine Transition-Wiederherstellung führt nur die noch nicht bestätigte Transition erneut aus. Eine Action-Wiederherstellung führt nur die durch ihre persistente UUID identifizierte Action aus und ändert den Workflow-Status kein zweites Mal. Bereits erfolgreiche Action-Checkpoints werden nicht wiederholt.

Fehlgeschlagene Trigger-Materialisierung wieder einplanen

Ein fehlgeschlagener interner Trigger-Transport ist kein Workflow-Dead-Letter-Eintrag. Prüfen Sie diesen Fall separat, wenn ein akzeptiertes Event oder eine geplante Trigger-Ausführung keine Delivery materialisiert hat. Sie benötigen die Berechtigung workflow_triggers:replay.

Wenn die globale Workflow-Trigger-Runtime deaktiviert ist, bleiben bereits eingereihte Materialisierungs- und Delivery-Events ohne zusätzlichen Fehlversuch pausiert. Aktivieren Sie die Runtime erst wieder, nachdem Sie die technische Ursache geprüft haben. Die Verarbeitung wird anschließend automatisch fortgesetzt; ein manueller Replay ist nur für bereits terminal fehlgeschlagene Materialisierungen erforderlich.

Bei verzögerter Materialisierung bleibt der persistierte Erzeugungszeitpunkt des Source-Events maßgeblich. Workspace ordnet das Event nur Triggern zu, deren halboffenes Aktivierungsfenster diesen Zeitpunkt enthält. Ein später aktivierter Trigger übernimmt daher keine älteren, noch wartenden Events desselben Topics. War ein mandantenspezifischer Override zu diesem Zeitpunkt noch nicht aktiv, bleibt die damals gültige Systemdefinition maßgeblich.

Scheitert ausschließlich der interne Transport einer bereits gespeicherten Delivery, bevor die fachliche Ausführung beginnt, bleibt die Delivery erhalten. Workspace reserviert nach Ablauf des kurzen Transport-Lease automatisch eine höhere Transportgeneration. Sie müssen dafür weder einen Dead-Letter-Eintrag wiederholen noch Datenbankdaten ändern. Prüfen Sie die Runtime und die technische Ursache, wenn auch die höheren Generationen wiederholt scheitern.

Erreicht dagegen die fachliche Trigger-Delivery ihre konfigurierte Versuchsgrenze, erscheint ihr Dead-Letter-Eintrag mit dem Status Nicht wiederholbar. Workspace bietet für diesen Eintrag keine Wiederholungsaktion an, weil der bestehende Recovery-Worker nur Transitionen und ausdrücklich replay-sichere Actions unterstützt. Verwechseln Sie diesen Zustand nicht mit einer fehlgeschlagenen Trigger-Materialisierung. Ändern Sie weder Delivery noch Dead-Letter direkt in der Datenbank; dokumentieren Sie den Vorgang und klären Sie den unterstützten betrieblichen Abschluss.

Listen Sie zuerst die offenen Fehler des ausgewählten Mandanten auf:

nucli --tenant <mandantenalias> workflow triggers failures list

Mit --json erhalten Sie eine maschinenlesbare Seite. Wenn die Antwort einen nextCursor enthält, übergeben Sie ihn beim nächsten Aufruf mit --cursor. Die Ausgabe enthält nur sichere fachliche Angaben. Rohes Event-Payload und interne Datenbankfehler werden nicht ausgegeben.

Prüfen Sie anschließend genau ein fehlgeschlagenes Event ohne Änderung:

nucli --tenant <mandantenalias> workflow triggers failures replay <event-uuid>

Beheben Sie zuerst die technische Ursache. Erzeugen Sie das Replay-Event danach ausdrücklich mit:

nucli --tenant <mandantenalias> workflow triggers failures replay <event-uuid> --apply

nucli führt vor dem Apply erneut den Preflight aus. Workspace sperrt die aktuelle fachliche Fortsetzung, prüft Mandant und Fortschrittsstand und erzeugt höchstens ein deterministisches Nachfolgeevent. Ein wiederholter Apply-Aufruf verwendet denselben Nachfolger. Nach erfolgreichem Apply erscheint der Vorgänger nicht mehr in der Liste offener Fehler.

Stoppen Sie bei 404 oder 409. Prüfen Sie Mandant, Event-ID und den aktuellen Workflow-Stand. Umgehen Sie einen veralteten Fortschrittsstand oder Autoritätskonflikt nicht durch eine Datenbankänderung.

Ergebnis prüfen

Aktualisieren Sie die Arbeitsliste und prüfen Sie den Eintrag sowie die Workflow-Instanz erneut. Die Statusfolge beginnt normalerweise mit Eingeplant, wechselt zu Wird ausgeführt und endet bei erfolgreicher Wiederherstellung mit Abgeschlossen. Ein vorübergehender Fehler kann den Eintrag auf Erneuter Versuch geplant setzen. Solange weitere offene Einträge für dieselbe Instanz bestehen, bleibt deren Dead-Letter-Zustand sichtbar.

Die Aufgabe ist abgeschlossen, wenn der Eintrag Abgeschlossen zeigt und die Instanz keinen weiteren offenen Dead-Letter-Eintrag besitzt. Bleibt der Eintrag Nicht wiederholbar, dokumentieren Sie den Fall und klären Sie den unterstützten Operator-Abschluss; verändern Sie den Datensatz nicht direkt.

Behandeln Sie folgende Antworten als Abbruchsignal:

• 401: Melden Sie den ausgewählten Mandantenalias erneut an.
• 403: Verwenden Sie keine höheren Rechte ohne betriebliche Freigabe.
• 404: Prüfen Sie UUID und Mandant; fremde Mandanten bleiben unsichtbar.
• 409: Der Eintrag wird bereits bearbeitet, ist ein nicht wiederholbarer Legacy-Eintrag oder enthält eine nicht freigegebene Action.

Starten Sie bei einem Konflikt keinen Datenbank-Workaround. Klären Sie zuerst den Eintrag, die Action-Klassifikation und den laufenden Worker.