Workflow Engine

Die ConnectWORKFLOW Engine ist ein YAML-basiertes System für mandantenfähige, ereignisgesteuerte Prozessautomatisierung. Sie verbindet das microtech büro+ ERP-System mit den Bearbeitern und stellt sicher, dass jede Workflow-Ausführung transparent dokumentiert wird – mit einem vollständigen Audit-Trail aller System- und Benutzeraktionen. Dieses Kapitel beschreibt die Architektur, den Datenfluss und die technischen Eigenschaften der Engine im Detail.

1. Architektur und Kernkomponenten

Die Workflow Engine basiert auf einer verteilten, ereignisgesteuerten Architektur mit Fokus auf Mandantentrennung und Beobachtbarkeit.

• WorkflowOrchestrator: Das zentrale Gehirn der Engine. Er ist verantwortlich für:
  • Den Empfang von WorkflowTriggerEvent per HTTP POST direkt vom Microtech On-Premise-Programm.
  • Trigger-Payload: customerID, tenantID, triggerGUID und objectNumber (String).
  • Den Abgleich eingehender Events mit den mandantenspezifischen WorkflowBlueprint-Definitionen, die aus S3 geladen werden.
  • Die Steuerung der sequenziellen Ausführung der Workflow-Schritte.
  • Die Pflege des Workflow-Kontexts (Daten, Dokumente, Entscheidungen) während des gesamten Ausführungszeitraums.
  • Hinweis: Im microtech Spring-Boot-Microservice ist keine Implementierung erforderlich, da der Trigger von der On-Premise-Anwendung ausgelöst wird (Push).
• Microtech API Wrapper: Eine spezialisierte Komponente innerhalb der Workflow-Infrastruktur, die als Brücke zur Microtech-Anwendung (API) dient. Sie verwendet JWT-Token zur Authentifizierung, die bereits in der Microtech-Anwendung implementiert sind. Sie leitet GraphQL-Queries und -Mutations an die Microtech GraphQL API weiter.
• S3Service: Stellt eine belastbare, skalierbare Speicherabstraktion bereit.
  • Workflow-Definitionen: Lädt YAML-basierte Blueprints aus mandantenspezifischen S3-Pfaden.
  • Ausführungsdokumentation: Erzeugt und aktualisiert automatisch JSON-basierte Ausführungsprotokolle für jede Instanz.
  • Zustandspersistenz & Recovery: Speichert den aktuellen Zustand aktiver Workflow-Instanzen und nutzt S3-Versionierung zur Zustandswiederherstellung. Jeder Workflow läuft mit der Blueprint-Version, mit der er gestartet wurde.
  • Atomare Transaktionen: Stellt sicher, dass sowohl der aktuelle Zustand als auch das Ausführungsprotokoll nach jedem abgeschlossenen Schritt gemeinsam aktualisiert werden, um Teilfehler zu vermeiden.
• Distributed Locking (S3): Ein gemeinsam genutzter Locking-Mechanismus zur Vermeidung von Race Conditions. Er nutzt S3-Objekte mit Besitzer- und Ablauf-Metadaten, um sicherzustellen, dass ein Objekt jeweils nur von einer Orchestrator-Instanz verarbeitet wird – insbesondere beim initialen Trigger, beim Recovery-Polling und beim Claiming von Aufgaben.
• Recovery- & Polling-Mechanismus: Ein selbstheilender Hintergrundprozess, der periodisch (stündlich) verwaiste Objekte im Status „MT Freigabe gestartet“ bei Microtech abfragt, um verlorene Workflows erneut zu starten. Er nutzt das Distributed Lock sowie eine Karenzzeit, um Konflikte mit aktiver Trigger-Verarbeitung zu vermeiden.
• Task-Claiming-Logik: Verwaltet die Übergänge zwischen „Offen“, „Beansprucht“ und „Abgeschlossen“ für manuelle Benutzeraufgaben, um gleichzeitige Bearbeitung zu verhindern.
• Blueprint-basiertes Ausführungsmodell:
  • Trigger: Definieren die Filterkriterien für eingehende Objekte/Events.
  • Steps: Geordnete Liste einzelner Arbeitseinheiten (System oder Benutzer).
  • Verzweigung: Unterstützung von nextSteps basierend auf Bedingungen oder Benutzerentscheidungen.

2. Datenfluss und Ablauf

Das folgende Diagramm und die Beschreibung erläutern das Zusammenspiel der Komponenten während eines Workflow-Lebenszyklus.

2.1 Sequenzdiagramm

2.2 Beschreibung des Datenflusses

1. Auslösung: Der Workflow wird initial durch die On-Premise-Installation von Microtech ausgelöst. Diese sendet eine HTTP-POST-Anfrage mit customerID (Kunde), tenantID (Mandant), triggerGUID und objectNumber an die Workflow Application. Gleichzeitig wird der Objektstatus in Microtech auf „MT Freigabe gestartet“ gesetzt und als „in externer Verarbeitung“ markiert.
2. Initialisierung: Die Workflow Application ermittelt anhand der Kennungen customerID und tenantID den mandantenspezifischen S3-Bucket und lädt über die triggerGUID den passenden Blueprint. Kunde und Mandant werden dabei als reine Zeichenketten behandelt, die vom Benutzer im Frontend eingegeben oder vom Trigger geliefert werden. Der S3-Bucket-Name folgt dem Muster {kunde}-{mandant}-{env}-mbcom-cloud. Dieser Blueprint definiert die Workflow-Schritte sowie die sichtbaren und editierbaren Felder.
3. Workflow-Ausführung: Der Workflow wird iterativ über alle definierten Schritte ausgeführt. Jeder Schritt folgt demselben Muster:
   • Dynamische GraphQL-Query-Generierung: Die Frontend-Anwendung baut die GraphQL-Query auf Basis des Blueprints auf. Felder mit visible: true werden in die Query aufgenommen. Die Feldnamen in GraphQL entsprechen den im Blueprint definierten Namen.
   • Laden im Frontend: Beim Öffnen des Frontends wird die Konfiguration des aktuellen Schritts geladen. Das Frontend sendet die GraphQL-Query per HTTP POST an die Microtech-API-Anwendung, die das JWT-Authentifizierungstoken ergänzt und die Anfrage gegen die GraphQL API ausführt. Die Antwort wird an das Frontend zurückgegeben und in das Datenmodell gemappt.
   • Fehlerbehandlung (Selbstkorrektur): Liefert die Microtech GraphQL API einen Fehler wegen unbekannter Felder (z. B. durch Schemaänderungen), identifiziert das Frontend/der Orchestrator die unbekannten Felder aus der Fehlerantwort, entfernt sie aus der Query und wiederholt die Anfrage.
   • Benutzerinteraktion: Die Oberfläche wird dynamisch anhand der Konfiguration gerendert. Der Benutzer kann verfügbare Daten einsehen, freigegebene Felder bearbeiten, Kommentare hinzufügen und den Schritt genehmigen oder ablehnen.
   • Übermittlung: Die Aktion des Benutzers wird an die Workflow Application zurückgesendet, welche die Ergebnisse und etwaige Änderungen im S3-Bucket speichert.
   • Systemaktualisierung: Wurden Änderungen vorgenommen, erzeugt die Workflow Application eine entsprechende GraphQL-Mutation. Diese Mutation wird über die Microtech API an das Microtech-System gesendet, wo die Aktualisierung ausgeführt wird. Das Ergebnis wird an die Workflow Application zurückgegeben.
4. Workflow-Abschluss: Sobald alle Schritte abgeschlossen sind, wird der Workflow finalisiert. Die Workflow Application aktualisiert den finalen Status des Objekts über eine GraphQL-Mutation via Microtech API. Das Objekt wird aus der externen Verarbeitung entfernt und auf einen Endstatus wie „freigegeben“ oder „abgelehnt“ gesetzt.

3. Workflow-Struktur und -Ausführung

Ein Workflow besteht aus einer sequenziellen Liste von Schritten, wobei jeder Schritt erst nach erfolgreichem Abschluss des vorherigen ausgeführt wird.

3.1 Trigger

• Definieren die Filterkriterien (z. B. Metadatenprüfungen, SpEL-Ausdrücke).
• Bestimmen, ob ein eingehendes Event/Objekt aus einer HTTP-POST-Anfrage eine neue Workflow-Instanz startet.
• Trigger-Quelle: Microtech On-Premise-Programm.
• Payload-Felder:
  • customerID: Eindeutige Kennung des Kunden.
  • tenantID: Der spezifische Mandant innerhalb der Organisation des Kunden.
  • triggerGUID: Eindeutige Kennung des Trigger-Events.
  • objectNumber: Referenzstring für das zugehörige Geschäftsobjekt (z. B. Rechnungsnummer).

3.2 Microtech-Objektstatus

Die Workflow Engine verfolgt und interagiert mit Objekten in Microtech über fünf spezifische Zustände:

1. none: Für das Objekt wurde noch kein Workflow gestartet.
2. MT Freigabe gestartet: Eine Trigger-POST-Anfrage wurde von Microtech gesendet, aber die Workflow App hat noch keine Bestätigung/keinen Start zurückgemeldet.
3. in Freigabe: Der Trigger wurde erfolgreich empfangen und der Workflow ist aktuell in der Workflow Application aktiv.
4. freigegeben: Der Workflow wurde mit der Entscheidung „Genehmigen“ erfolgreich abgeschlossen.
5. abgelehnt: Der Workflow wurde mit der Entscheidung „Ablehnen“ abgeschlossen.

Definition eines verwaisten Objekts: Jedes Objekt, das länger als das erwartete Kommunikationsfenster (z. B. 10 Minuten Karenzzeit) im Status „MT Freigabe gestartet“ verbleibt, gilt als verwaist und wird vom Recovery-Mechanismus übernommen.

3.3 Schritttypen

A) System-Aktionen

• Bedingungen: Prüfen Daten gegen Regeln oder Vergleiche.
• Verzweigung: Bestimmen die nextSteps anhand der Auswertungsergebnisse.
• Funktionen: Führen spezifische code-basierte Aktionen oder externe Serviceaufrufe aus.
• Protokollierung: Erfassen Eingaben, verglichene Werte, Logikergebnisse und Funktionsresultate mit Zeitstempel.

B) Benutzerinteraktionen

• Daten-/Dokumentenansicht: Zeigen konfigurierte Felder und PDFs für den Benutzer an.
• Bearbeitung: Erlauben die Änderung freigegebener Datenfelder.
• Entscheidungen:
  • Genehmigen: Wechsel zum nächsten Schritt.
  • Ablehnen: Übergang in den Ablehnungspfad; erfordert einen Pflichtkommentar.
• Feedback: Unterstützung optionaler Kommentare/Feedback in jedem Schritt.
• Protokollierung: Erfassen des Bearbeiters, der Zeitstempel, der angezeigten Daten, der geänderten Felder und aller Kommentare.

3.4 Vermeidung von Race Conditions (Locking)

Um zu verhindern, dass der Recovery-Job einen Workflow erneut startet, der gerade durch den ereignisgesteuerten Trigger gestartet wird, kommt folgende Locking-Strategie zum Einsatz:

1. Lock-Schlüssel: lock:workflow:{customerID}:{tenantID}:{objectNumber}.
2. Trigger-Verarbeitung: Beim Empfang eines POST-Triggers versucht die Workflow App, ein Distributed Lock zu erwerben (TTL: 5 Minuten). Bei Erfolg fährt sie mit der Initialisierung und der S3-Zustandserstellung fort.
3. Recovery-Job: Für jedes gefundene verwaiste Objekt muss der Job:
   • prüfen, ob der Zeitstempel des Objekts die Karenzzeit von 10 Minuten überschreitet,
   • versuchen, dasselbe Distributed Lock zu erwerben,
   • den Workflow nur dann erneut starten, wenn das Lock erworben wurde UND für diese Instanz noch keine Zustandsdatei in S3 existiert.
4. Freigabe des Locks: Locks werden automatisch nach Ablauf der TTL freigegeben oder explizit, sobald der initiale S3-Zustand erfolgreich persistiert wurde.

4. Ausführungsdokumentation (JSON-Protokollierung)

Für jede Workflow-Instanz wird ein detailliertes JSON-basiertes Ausführungsprotokoll geführt, das Folgendes erfasst:

1. Allgemeine Informationen:
   • Workflow-Name/-ID, Mandant, CustomerID, triggerGuid, objectNumber.
   • Instanz-ID, Trigger-Quelle, Start-/Endzeitpunkt und aktueller Status.
2. Schritt-für-Schritt-Historie:
   • Benutzerschritte: Akteur-ID, Zeitstempel, angezeigte im Vergleich zu geänderten Daten, Entscheidung (Genehmigen/Ablehnen) und Kommentare.
   • Systemschritte: Zeitstempel, verglichene Werte, Bedingungsergebnisse, gewählter nextStep und Funktions-/Aktionsergebnisse.
3. Nachvollziehbarkeit: Vollständige, sequenzielle Aufzeichnung aller Entscheidungen, Verzweigungen und Kontextaktualisierungen zur lückenlosen Nachvollziehbarkeit.

5. Technische Merkmale

1. S3-Integration & Blueprint-Versionierung:
   • Mandantenfähige Bucket-Struktur zur Trennung nach customerID (Kunde) und tenantID (Mandant).
   • Bucket-Namenskonvention: {kunde}-{mandant}-{env}-mbcom-cloud. Kunde und Mandant sind reine Zeichenketten.
   • Robustes YAML-Parsing und -Validierung für Blueprints.
   • Blueprint-Versionierung: Blueprints werden versioniert. Jede Workflow-Instanz ist an die Blueprint-Version gebunden, mit der sie gestartet wurde. Neue Trigger-Events verwenden stets die aktuellste Version.
   • JSON-Protokollierung: Strukturierte Ablage der Ausführungsprotokolle: workflow/docs/{tenantId}/{workflowId}/{instanceId}.json.
   • Zustandspersistenz: Aktueller Instanzzustand wird in S3 gespeichert und aktualisiert.
   • Zustandswiederherstellung: Nutzung der S3-Bucket-Versionierung, um Ausfallsicherheit zu gewährleisten und bei Beschädigung ein Rollback auf frühere Ausführungspunkte zu ermöglichen.
2. Trigger Engine & Sicherheit:
   • Echtzeitprüfung eingehender Objekte (customerID, tenantID, triggerGUID, objectNumber) gegen alle aktiven mandantenspezifischen Blueprints.
   • Sicherheit: Der Empfangs-Endpunkt (/api/workflow/trigger) ist über JWT-Token und optional API-Key-/IP-Whitelisting abgesichert.
   • Mandantentrennung: Sichergestellt durch customerID (Kunde + Mandant), die in jeder Nachricht enthalten ist.
   • Effiziente Filterlogik zur Verarbeitung großer Event-Volumen.
3. Benutzerinteraktionsebene & Aufgabenverwaltung:
   • API-Endpunkte zum Auflisten „offener Aufgaben“ für Benutzer auf Basis von Gruppenzuweisungen.
   • Zuweisungs- & Claiming-Logik:
     • Aufgaben werden den im Blueprint definierten Identity-Provider-Gruppen zugewiesen.
     • Deduplizierung: Gehört ein Benutzer zu einer zugewiesenen Gruppe, sieht er genau einen Aufgabeneintrag.
     • Claiming-Mechanismus: Ein Benutzer aus einer zugewiesenen Gruppe muss eine Aufgabe „beanspruchen“ (Claim), bevor er sie bearbeiten/abschließen kann. Dies verhindert parallele Bearbeitung.
     • (Eine benutzerspezifische Zuweisung wird im Modell unterstützt, ist für die initiale Implementierung jedoch auskommentiert).
   • Zustandsverwaltung zur Behandlung gleichzeitiger Benutzeraktionen und Race Conditions.
4. Kontextweitergabe & atomare Updates:
   • Unveränderlicher oder versionierter Workflow-Kontext, der durch jeden Schritt weitergereicht wird.
   • Atomarer Schrittabschluss: Jeder abgeschlossene Schritt muss den Instanzzustand und das JSON-Ausführungsprotokoll in S3 atomar aktualisieren, um Konsistenz zu gewährleisten.
   • Nachfolgende Schritte müssen Zugriff auf die vollständige Historie der Datenänderungen und Kommentare haben.
5. Fehlerbehandlung:
   • Kontrollierte Fehlerbehandlung (Graceful Degradation) und Erfassung von Fehlerzuständen.
   • Detaillierte Fehlerprotokollierung innerhalb des Ausführungsprotokolls zur Fehleranalyse.

6. Kommunikationsstrategie

Der primäre Trigger-Mechanismus der Workflow Engine ist eine Push-Strategie per HTTP POST, die direkt vom Microtech On-Premise-Programm an die Workflow-Anwendung gesendet wird.

• Die On-Premise-Anwendung benachrichtigt die Workflow Engine unmittelbar nach relevanten Ereignissen (z. B. Dokument-Upload).
• Die Workflow Engine stellt einen standardisierten, nur empfangenden Endpunkt bereit (z. B. /api/workflow/trigger), um diese eingehenden Anfragen zu verarbeiten.
• Wichtig: Für diesen Trigger-Mechanismus ist keine Integrationslogik oder Implementierung im microtech Spring-Boot-Microservice erforderlich.
• Dies gewährleistet eine sofortige Workflow-Initiierung ohne Polling-Verzögerungen oder Abhängigkeiten von anderen Microservices.

7. Recovery- und Polling-Mechanismus

Zusätzlich zum ereignisgesteuerten Trigger sorgt ein periodischer Recovery-Mechanismus für die Ausfallsicherheit des Systems.

• Häufigkeit: Die Workflow Application führt stündlich eine GraphQL-Query über die Microtech API aus.
• Zielzustand: Identifiziert Objekte im Status „MT Freigabe gestartet“. Dieser Status zeigt an, dass in Microtech ein Workflow gestartet wurde, die initiale HTTP-Trigger-Anfrage jedoch möglicherweise verloren ging oder nicht verarbeitet werden konnte.
• Auto-Discovery: Wird ein solches Objekt erkannt, werden die benötigten Informationen – CustomerId, objectId und triggerGuid – direkt aus den Objektmetadaten abgeleitet.
• Selbstheilung: Auf Basis dieser Informationen startet die Workflow Application die entsprechende Workflow-Instanz erneut.
• Ergebnis: Dieser Mechanismus stellt sicher, dass durch Kommunikationsausfälle keine Workflows verloren gehen, und bietet eine Selbstheilungsfähigkeit für die gesamte Automatisierungsstrecke.

8. Frontend

Die Workflow Engine umfasst ein spezialisiertes Frontend-Modul zur Handhabung von Benutzerinteraktionen und manueller Aufgabenverwaltung.

8.1 Aufgabenübersicht und -verwaltung

Ein zentrales Dashboard zeigt Benutzern alle offenen Aufgaben, die ihnen direkt oder über ihre Gruppenzugehörigkeit zugewiesen sind. Die Ansicht unterstützt Filterung nach Mandant, Objekttyp und Status (offen/beansprucht) sowie die Claiming-/Unclaiming-Interaktion zum Beanspruchen und Freigeben von Aufgaben. Neue Aufgaben werden angezeigt, sobald ein Workflow einen manuellen Schritt erreicht – in Echtzeit per WebSocket oder über periodisches Polling.

8.2 Dynamische Aufgabenansicht

Die Oberfläche für einen Schritt wird dynamisch anhand der Konfiguration im WorkflowBlueprint erzeugt: Nur die als sichtbar konfigurierten Felder werden angezeigt, und je nach Blueprint sind Felder schreibgeschützt oder editierbar. Der Backend-Aufruf getTaskMetadata lädt den gesamten benötigten Kontext in einer einzigen Anfrage. Für Kunde/Mandant unterstützt der Designer zusätzlich Freitext-Eingabefelder für eine flexible, ad-hoc Mandantenzuordnung.

8.3 Dokumentenintegration und Ausführungshistorie

Ein integrierter, leistungsfähiger PDF-Viewer ermöglicht die Prüfung der in S3 gespeicherten Belege (z. B. Rechnungen) direkt in der Aufgabenansicht, optional in einer Nebeneinander-Ansicht mit dem Datenformular. Über den getExecutionLog-Endpunkt lässt sich zudem die vollständige Ausführungshistorie einer Workflow-Instanz einsehen.

8.4 Entscheidungsverarbeitung

Für jeden Schritt kann der Bearbeiter genehmigen oder ablehnen: Genehmigen führt den Workflow zum nächsten definierten Schritt weiter, Ablehnen löst den Ablehnungspfad aus und erfordert zwingend einen Kommentar zur Begründung. Zusätzlich können Bearbeiter an jedem Schritt allgemeines Feedback hinterlassen, das im Workflow-Kontext und im Ausführungsprotokoll dauerhaft erhalten bleibt.

8.5 Benutzerauthentifizierung und -autorisierung

Das Frontend ist über einen OIDC-Login-Provider abgesichert. Die Aufgabenfilterung basiert auf der vom Authentifizierungsanbieter bereitgestellten Benutzer-ID und den zugehörigen Gruppenzuweisungen: Für jedes Mitglied einer zugewiesenen Identity-Provider-Gruppe wird eine Aufgabe geöffnet; ist zusätzlich ein bestimmter Benutzer explizit zugewiesen, erhält dieser dennoch nur einen einzigen Aufgabeneintrag (Überschneidungsbehandlung). Eine Gruppenzuweisung ist verpflichtend, sofern im Blueprint kein spezifischer Benutzer hinterlegt ist. Vor der Bearbeitung müssen Benutzer eine gruppenzugewiesene Aufgabe explizit beanspruchen (Claiming); beanspruchte Aufgaben werden als „In Bearbeitung“ markiert und für andere Gruppenmitglieder gesperrt.