Datenhandler: Steuerung & Läufe

Wie das IMS den Pull-Server beschreibt, wie die Pipeline ihn baut und was jede Zeile in der Lauf-Tabelle bedeutet.

Drei Rollen, ein Datensatz

Der Datenhandler ist ein Datensatz am System des Kundenprojekts im Bilendo-IMS. Drei Parteien lesen und schreiben ihn, jede mit einer eigenen Tür:

Rolle	Tür	Was sie tut
Bilendo-Mitarbeiter	`GET/POST/PUT …/data-handlers`	Beschreibt den Soll-Zustand: Zeitplan, Buchungskreise, Objekte, Lieferweg, SAP-API-Basis, Aufbewahrung — und die Namen der drei Secrets. Nie einen Wert.
Deployment-Pipeline (Terraform)	`GET …/data-handlers/:id/desired-state`	Liest den Soll-Zustand als JSON und legt den Stack an: EventBridge-Zeitplan, Step Functions, Lambdas, S3, DynamoDB. Meldet danach den Status `active`.
Sammler (Lambda, zur Laufzeit)	`GET …/data-handlers/:id/mapping` · `POST /api/data-handler-runs`	Holt beim Start das Feld-Mapping der Variante, transformiert damit, liefert an Bilendo und meldet jeden Lauf als Manifest zurück.

flowchart LR
    subgraph IMS[Bilendo IMS]
        DH[(Datenhandler<br/>Soll-Zustand)]
        MAP[(Variante<br/>Feld-Mapping)]
        RUNS[(Läufe)]
    end
    PIPE[Terraform-Pipeline]
    subgraph AWS[AWS · Kundenprojekt]
        EB[EventBridge<br/>Zeitplan] --> SF[Step Functions]
        SF --> L[Lambda Collector / Transform / Deliver / Report]
        L --> S3[(S3 Rohdaten)]
        L --> WM[(DynamoDB<br/>Wasserzeichen)]
        SM[(Secrets Manager)] -.Werte.-> L
    end
    SAP[SAP BTP API-Management<br/>→ S/4HANA Utilities FI-CA]
    BIL[Bilendo Loader<br/>API-POST oder SFTP]

    DH -- "desired-state (JSON)" --> PIPE
    PIPE -- "legt Stack an" --> AWS
    DH -. "Secret-NAMEN" .-> SM
    MAP -- "mapping" --> L
    L -- "OData, seitenweise, Delta" --> SAP
    L -- "Delta-Batches ≤ 5 000 Zeilen" --> BIL
    L -- "Manifest je Lauf" --> RUNS

Das IMS beschreibt und sieht, es betreibt nicht: es hält keinen Zugang zu SAP oder Bilendo, sondern den Namen, unter dem der Zugang im Secret Store des Kunden liegt. Deshalb ist der Soll-Zustand gefahrlos lesbar und kann eine Pipeline in einem fremden Konto steuern.

Der Lebenszyklus des Datenhandlers

Der Status des Datenhandlers beantwortet, ob der Stack existiert und ob er gesund ist. Zwei Übergänge schreibt niemand von Hand: ein Lauf mit failed setzt error, der nächste erfolgreiche Lauf setzt aus error zurück auf active. Pausieren ist eine Entscheidung eines Menschen und wird von keinem Lauf überschrieben.

stateDiagram-v2
    [*] --> draft : im IMS beschrieben
    draft --> provisioning : Pipeline liest Soll-Zustand
    provisioning --> active : Stack steht
    active --> error : Lauf meldet failed
    error --> active : Lauf meldet delivered
    active --> paused : von Hand
    error --> paused : von Hand
    paused --> active : von Hand

Status	Bedeutung
`draft`	Beschrieben, noch nichts gebaut. Der Soll-Zustand ist vollständig, sobald SAP-API-Basis, Lieferweg und die drei Secret-Namen gesetzt sind.
`provisioning`	Die Pipeline arbeitet. Der Zeitplan ist noch nicht aktiv.
`active`	Der Stack läuft nach Zeitplan; der letzte gemeldete Lauf war erfolgreich.
`paused`	Zeitplan abgeschaltet, Stack bleibt. Gedacht für Wartungsfenster in SAP oder Bilendo.
`error`	Der letzte Lauf ist fehlgeschlagen. Die Wasserzeichen stehen, das Fenster wird beim nächsten Lauf erneut geliefert.

Ein Lauf, Schritt für Schritt

sequenceDiagram
    autonumber
    participant EB as EventBridge
    participant L as Lambda
    participant IMS as Bilendo IMS
    participant SAP as SAP BTP / FI-CA
    participant BIL as Bilendo Loader

    EB->>L: Zeitplan feuert (run_id vergeben)
    L->>IMS: GET mapping (Feld-Mapping der Variante)
    L->>L: Wasserzeichen je Objekt lesen
    loop je Objekt: Debitoren → Vertragskonten → Posten → Zahlungen → Abschläge
        L->>SAP: OData $filter ≥ Wasserzeichen − Überlappung, $top/$skip
        SAP-->>L: Seite n
        L->>L: Rohdaten nach S3, transformieren, Clearing-Regeln
        L->>BIL: Batch (≤ 5 000 Zeilen, Idempotenzschlüssel)
        BIL-->>L: angenommen / je Zeile abgewiesen
    end
    alt alle Batches bestätigt
        L->>L: Wasserzeichen auf Startzeitpunkt vorrücken
        L->>IMS: POST /data-handler-runs {status: delivered, received, stored, rejected}
    else ein Batch scheitert
        L->>IMS: POST /data-handler-runs {status: failed, error}
        Note over L: Wasserzeichen bleiben stehen
    end

Die Reihenfolge der Objekte ist fest: ein Posten braucht seinen Debitor, ein Abschlag seinen Vertrag. Ein Lauf meldet sich je Objekt einmal — die Lauf-Tabelle im IMS zeigt deshalb für einen Lauf mehrere Zeilen mit derselben Lauf-Id.

Was die Zeilen in der Lauf-Tabelle sagen

Jede Zeile ist ein Manifest, das der Sammler nach einem Objekt eines Laufs gemeldet hat. Eine zweite Meldung mit derselben Lauf-Id und demselben Objekt überschreibt die erste (so wird aus running am Ende delivered oder failed).

Spalte	Bedeutung	Wonach man schaut
Lauf	Lauf-Id des Sammlers plus Startzeitpunkt.	Zeilen mit derselben Id gehören zu einem Zeitplan-Ereignis.
Objekt	Was geliefert wurde: Debitoren, Vertragskonten, Offene Posten, Zahlungen, Abschlagspläne.	Fehlt ein Objekt aus dem Soll-Zustand, hat der Lauf es nicht erreicht.
Fenster	`watermark_from` → `watermark_to`: das Delta-Fenster, das gelesen wurde (Buchungs- bzw. Ausgleichsdatum).	Ein Fenster, das größer ist als der Abstand zweier Läufe, heißt: der Vorgänger ist fehlgeschlagen und wurde nachgeholt.
gelesen	`received`: Zeilen, die SAP geliefert hat.	0 an einem Werktag ist verdächtig — Delta-Filter oder Berechtigung prüfen.
gespeichert	`stored`: Zeilen, die Bilendo angenommen hat.	Sollte `received` minus Abweisungen sein.
abgewiesen	`rejected`: von Bilendo abgelehnt (Pflichtfeld leer, unbekannter Debitor) · `rejected_local`: schon vor der Lieferung verworfen (kein Mapping, Regel greift).	Lokale Abweisungen zeigen auf das Mapping im IMS, Bilendo-Abweisungen auf die Daten in SAP.
Status	`running` · `delivered` · `failed` — mit Fehlertext.	`failed` färbt den Datenhandler auf `error`; der Fehlertext steht in der Zeile.

Ein gesunder Tag liest sich so: je Zeitplan-Ereignis fünf Zeilen mit derselben Lauf-Id, Fenster von der letzten bis zu dieser Ausführung, „abgewiesen" bei 0 oder einer kleinen, erklärbaren Zahl, Status „geliefert".

Was das IMS bewusst nicht tut

Es startet keinen Lauf und hält keine Zugangsdaten — beides liegt im Konto des Kundenprojekts.
Es rechnet keine Zahlen nach: gelesen/gespeichert/abgewiesen sind die Angaben des Sammlers.
Es spricht nicht mit Bilendo — ob eine Zeile dort angekommen ist, sagt nur das Manifest.