Überblick

BMD → Rimo Invoices ist eine Fabric-Notebook-gesteuerte Automatisierung mit zwei begleitenden Data-Factory-Pipelines. Die Lösung besteht aus:

• Notebook: Python/PySpark (Microsoft Fabric)
• Datenquelle: Fabric Lakehouse (Spark SQL)
• Orchestrierung: 2 Data-Factory-Pipelines
• Zielsystem: Rimo REST-API (Test/Dev)

Architektur

Technologiestack

Seit dem 25.09.2026 läuft das Notebook auf Fabric Runtime 2.0 (Spark 4, Python 3.13); die SQL-Abfragen wurden dafür von parametrisierten Abfragen auf f-Strings umgestellt.

• Notebook/Backend: Python, PySpark (Spark SQL), requests, notebookutils, Python-Logging mit eigenem Logger
• Datenplattform: Fabric Lakehouse, Delta-Tabellen bmd.fibu_erb_buchungen, bmd.fibu_erk_konto, rimo.sdmcompany, rimo.sdmcreditor, rimo.sdmaccount, rimo.sdmsalesorder, rimo.sdmprojectpurchaseorder, spl_gold_lh.bmd.rimo_processed_invoices_log
• Orchestrierung: Fabric Data Factory (Copy-Data, Notebook-Aktivität, If-Condition, Office-365-Outlook-Aktivität)
• Externe API: Rimo REST-API (multipart/form-data für Upload, JSON für Approvals)

Hauptfunktionen

Jeder Lauf durchläuft nach den Health-Checks drei fachliche Phasen; jede Rechnung trägt ihren Stand in der State-Datei, sodass ein abgebrochener Lauf beim nächsten Mal genau dort weitermacht.

1. Datenerfassung

Buchungszeilen werden aus bmd.fibu_erb_buchungen gelesen: alle Buchungen ohne „Spesen“ im Buchungstext, einschließlich Buchungen ohne Buchungstext, mit Erstelldatum ab 27.08.2026, 10:00 Uhr (offenes Zeitfenster). Bereits verarbeitete Zeilen werden per LEFT JOIN gegen spl_gold_lh.bmd.rimo_processed_invoices_log ausgeschlossen; bei mehreren Dateien zum selben Beleg wird die .pdf-Variante bevorzugt. Jede Zeile erhält den Schlüssel intBelegNr_Firmennr und wird in die Warteschlange der State-Datei übernommen.

Buchungen ohne Buchungstext werden ohne userLabel an Rimo übergeben; das Feld fehlt dann im Request.

2. Download-Phase (Belegdokument)

Notebooks können den On-Premises Data Gateway nicht nutzen. Deshalb kopiert die vorgelagerte Copy-Data-Aktivität die Dateien vom Dateiserver (\atwotbmd01\BMDDocs\0\2...) gesammelt ins Lakehouse, anhand eines Abgleichs von bmd.fibu_erb_buchungen mit der Log-Tabelle. Die Download-Phase prüft nur, ob die erwartete Datei im Lakehouse-Zielordner angekommen ist.

3. Upload-Phase (Rechnungsdaten)

BMD-Felder werden auf Rimo-Felder gemappt, Firmen- und Kreditor-IDs per Lakehouse-Lookup ergänzt und Beleg plus Daten per multipart/form-data an POST /v1/invoices übergeben. Ein erfolgreicher Upload liefert die Rimo-externalId.

4. Approval-Phase (Freigaben)

Pro Buchungszeile in bmd.fibu_erk_konto (verknüpft über ErfassNr) wird eine eigene Freigabe an Rimo gesendet, mit mehrstufigem Fallback für die Bestellnummer- und Sales-Order-Zuordnung (siehe Besondere Geschäftslogik). Die Approval-Phase läuft im Modus „all“ mit.

Health-Checks und technische Fehlererkennung

Vor jeder Verarbeitung prüft das Notebook Verbindungen, Tabellen und die eigenen SQL-Abfragen. Ein kritischer Fehler bricht den Lauf ab, bevor eine Rechnung angefasst wird; so landen bei Systemumstellungen (z. B. Runtime-Wechsel) keine Rechnungen fälschlich in dead_letter.

Während des Laufs gilt zusätzlich:

• Technische Fehler: Scheitert eine Lookup-Abfrage technisch (SQL-Fehler statt „nicht gefunden“), wird das als technischer Fehler gesammelt und an die IT gemeldet. Ab 5 technischen Fehlern bricht der Lauf ab.
• Lookup-Trefferquote: Finden Company-, Kreditor-, Account-, Sales-Order- oder Purchase-Order-Lookups bei mindestens 3 Versuchen zu 80 % oder mehr nichts, wird das als vermutliches Daten- oder Abfrageproblem gemeldet.
• Caches: Lookup-Caches werden zu Beginn jedes Laufs geleert, damit bei wiederverwendeten Sessions keine veralteten Stammdaten verwendet werden.

Fehler-Orchestrierung und Benachrichtigungen

Die Pipeline trennt seit Ende September 2026 fachliche Fehler (Mail an die Buchhaltung) von technischen Auffälligkeiten (Mail an die IT); bricht das Notebook ab, geht ein eigener Alarm an die IT.

Fehler-Orchestrierung · drei Mails, zwei Empfängergruppen

Beide If-Conditions hängen parallel am Erfolgspfad der Notebook-Aktivität und lesen Flags aus dem exitValue.

• Keine Doppelmeldungen: Gemeldete Fehler werden in der State-Datei markiert (notified_at) und nur einmal gemailt.
• Health-Warnungen mit Schwelle: Eine leere bmd.fibu_erb_buchungen wird erst nach 3 Läufen in Folge gemeldet, einmal pro Serie; der Zähler steht in der State-Datei und zählt über Tagesgrenzen. Andere Warnungen werden beim ersten Auftreten gemeldet.
• Lieferperiode ungültig: bleibt in pending statt dead_letter und wird nach Korrektur in BMD automatisch neu versucht.
• Download-Fehler nach Erreichen der Retry-Grenze erhalten eine verständliche Meldung, z. B. „Datei nach Pipeline-Lauf nicht im Lakehouse gefunden“.

Logging, State-Datei und Backups

Jeder Lauf wird als eigener Block oben in rimo_pipeline.log geschrieben, der neueste Lauf steht damit immer am Anfang der Datei.

Logging

• Das Notebook nutzt einen eigenen Logger (rimo_pipeline), unabhängig vom Root-Logger der Fabric-Runtime. Hintergrund: Runtime 2.0 konfiguriert den Root-Logger selbst, wodurch seit 25.09.2026 nach 07:08 Uhr keine Einträge mehr in der Logdatei landeten.
• Während des Laufs wird lokal nach /tmp geloggt; am Ende fügt das Notebook den Lauf als Block (Kopfzeile LAUF Start bis Ende) oben in die Lakehouse-Logdatei ein, innerhalb des Blocks chronologisch.
• Das Log wird auch bei einem Abbruch geschrieben (try/finally um den Hauptlauf).
• Zeitstempel im Log in Wiener Zeit (Europe/Vienna); Zeitstempel in der State-Datei in UTC.

Dateien im Lakehouse

Die State-Datei wird atomar geschrieben (Temp-Datei, Prüfung, Umbenennen), damit ein Abbruch keine halbe Datei hinterlässt. Die Backups liegen bewusst außerhalb von BMD_Invoices, weil das Cleanup am Ende jedes Laufs dort alle Unterordner löscht; .log- und .json-Dateien bleiben dabei erhalten.

Pipelines und Konfiguration

Die wichtigsten Einstellungen stehen als Konstanten in der Konfig-Zelle des Notebooks; Filter und Zugangsdaten sind noch nicht parametrisiert.

Sicherheit

Die Rimo-Zugangsdaten stehen weiterhin im Klartext im Notebook; die Umstellung auf einen Key Vault ist vorbereitet, aber noch nicht umgesetzt.

Authentifizierung

• Rimo-API-Token: wird per Benutzer/Passwort über /v1/auth/fetch-token einmal pro Lauf geholt. Der Health-Check bricht den Lauf ab, wenn der Abruf fehlschlägt. Eine automatische Token-Erneuerung bei HTTP 401 gibt es noch nicht.
• Zugangsdaten: Benutzer und Passwort stehen im Klartext im Notebook und damit auch im Versionsverlauf. Empfehlung: über notebookutils.credentials.getSecret aus einem Key Vault beziehen und das Passwort ändern.
• Fabric-API-Token: wird nicht mehr verwendet, da der Kopiervorgang vollständig in der vorgelagerten Copy-Data-Aktivität läuft.

Datenschutz

Zugriff auf Buchungs- und Stammdaten ausschließlich über die Fabric-Lakehouse-Berechtigungen. Das Notebook greift nicht direkt auf den On-Premises-Dateiserver zu; das läuft ausschließlich über die Gateway-Pipeline.

Besondere Geschäftslogik

Vier fachliche Sonderregeln weichen bewusst von einer 1:1-Übernahme der BMD-Daten ab.

• Vorzeichen-Korrektur beim Upload: Ist der Bruttobetrag (grossAmount) positiv, der Nettobetrag (netAmount) aber negativ, wird der Betrag ohne Vorzeichen als netAmount übergeben. Alle anderen Kombinationen bleiben unverändert.
• Mehrstufiger Fallback bei Approvals:
  1. Bestellnummer-Kandidaten (Purchase-/Sales-Order-Paare) einzeln probieren
  2. bei Scheitern ein firmenbasierter Sales-Order-Kandidat ohne Bestellung
  3. sonst endgültig gescheitert (approval_dead)
• Sales-Order-Ausnahme: Gibt es für eine Firma keinen Sales Order mit getsalesordernumber = '0000 {4 Ziffern}', wird ersatzweise nach dem Muster „{Firmennummer}000 0001“ gesucht (Firma 68 → „68000 0001“). Dieser Fallback greift nur, wenn die reguläre Suche keine Kandidaten liefert.
• Ungültige Lieferperiode: Ist eine falsch formatierte Lieferperiode der einzige Fehler, bleibt die Rechnung in pending statt in dead_letter und wird nach Korrektur in BMD automatisch erneut versucht.

Server / Umgebung

Notebook und Pipelines laufen im Microsoft Fabric Workspace auf Runtime 2.0; ausgelöst wird stündlich über die Orchestrierungs-Pipeline oder manuell.

• Workspace: wegen des Kapazitätschecks laufen Pipeline und Notebook derzeit über den Fabic_test_workspace, angehängt an das im Fabric Workspace liegende bmd_invoice_execution.
• Runtime: Fabric Runtime 2.0 seit 25.09.2026. Bei künftigen Runtime-Wechseln vorab in einer Kopie testen; die Health-Checks fangen grundlegende Probleme ab.
• Erreichbarkeit Rimo-API: über die im Notebook hinterlegten Zugangsdaten.
• Belegquelle: \atwotbmd01\BMDDocs\0\2..., nur über die On-Premises-Gateway-Pipeline erreichbar.

Offene Punkte und bekannte Einschränkungen

Das größte offene Risiko sind doppelte Rechnungen in Rimo bei Timeouts; die Lösung ist ausgearbeitet, aber noch nicht eingebaut.

• ☐ Schutz vor doppelten Uploads: Bei Timeout oder 5xx wiederholt upload_invoice den Upload, obwohl Rimo die Rechnung womöglich schon angelegt hat. Geplant: Status upload_uncertain, kein automatischer Retry, Meldung an die IT, Hilfsfunktion resolve_upload_uncertain.
• ☐ Token-Erneuerung bei HTTP 401 für Upload und Approval, damit lange Läufe nicht abbrechen.
• ☐ Zugangsdaten in Key Vault verschieben und Passwort ändern.
• ☐ Leere Firmennr im Schlüssel: CONCAT mit NULL ergibt NULL; COALESCE in der Abfrage ergänzen.
• ☐ Copy-Data-Abfrage angleichen: Buchungen ohne Buchungstext müssen auch dort mitkopiert werden, sonst scheitert ihr Download.
• ☐ Startdatum parametrisieren statt fest im SQL.
• ☐ Gleichnamige PDFs aus verschiedenen BMD-Ordnern überschreiben sich im flachen Lakehouse-Ordner; Copy-Pipeline sollte den relativen Pfad oder den Schlüssel als Dateinamen verwenden.
• ☐ Atomares Schreiben prüfen: Erscheint im Log „Atomares Ersetzen der State-Datei nicht möglich“, unterstützt der OneLake-Mount os.replace nicht.
• ☐ Health-Check-Werte ergänzen: bekannten Kreditor und Kontonummer in KNOWN_LOOKUPS eintragen.
• ☐ Approvals bei Timeout: submit_approval wiederholt bei Timeout und 5xx; im schlimmsten Fall entsteht eine Freigabezeile doppelt.