Leitfaden für die Erstellung von Staging Schichten (Gateways)

Zielstellung

Eine Staging Schicht spiegelt die Daten aus einem Produktivsystem in eine Datenbank zur Weiterverarbeitung. Die Daten werden dabei weitgehen 1:1 gespiegelt, d.h.

• die Datenstuktur bleibt unverändert (eine staging Tabelle pro Quelltabelle / API Route)

Regeln für lesende API Zugriff

Eine API ist ein Webservice eines Drittprogrammes, mit welchem man aus diesem Daten lesen, Daten schreiben oder Aktionen ausführen kann. Dieser Leitfaden beschreibt Regeln für die Erstellung von lesenden API Anbindungen für OCT. Diese sind darauf ausgelegt kontinuierlich die Daten aus einem Drittsystem an OCT zu übertragen.

• Die Anbindung erfolgt als simple Spieglung der API Inhalt - zunächst unabhängig von der späteren Verwendung als universelle Staging Schicht

• Das Staging von Werten sollte 1:1 den API Requests entsprechen

  • eine Staging Tabelle pro API Request

  • Tabellen werden per SQL Script vorab generiert, nicht automatisch durch Python / Powershellcode (für die Steuerung des Datentyps und damit Views, welche diese Tabellen nutzen sofort in der Datenbank eingespielt werden können)

  • der Tabellennamen entspricht dem API Request Namen

  • Feldnamen der Stagingtabelle entsprechen den Feldnamen des API Outputs

  • es werden nach Möglichkeit alle Spalten des API Request abgerufen und gespeichert, eine Einschränkung erfolgt nur

    • bei Performanceproblemen

    • bei großer Anzahl von Spalten mit vom Endanwender nicht nutzbarem Inhalt (Druckparameter etc.)

    • bei Spalten mit hohem Datenvolumen ohne regelmäßige Verwendung (Binärspalten mit Dokumenten / Videos etc.)

  • komplexe Rückgabewerte innerhalb von Tabellen (JSON Objekte, Arrays etc.) werden im Stagingprozess nicht aufgelöst, sondern als String gespeichert. Die Auflösung erfolgt erst innerhalb der nächsten Prozessstufe bei der Überführung in die Integration Schicht.

  • nur für die weitere Verarbeitung notwendige Ergänzungsspalten (meist Schlüssel) werden zusätzlich in die Stagingtabelle aufgenommen (i.d.R. die URL Parameter - z.B. Mandant oder Jahr)

• Die Staging sollte partitioniert erfolgen können, alternativ kann ein DeltaLoad erfolgen

  • um möglichst schnell feingranulare Aktualisierungen vornehmen zu können

  • manche APIs berechen pro abgerufenem Datensatz eine Gebühr, diese soll gering gehalten werden und nur notwendige Daten gelesen werden

  • z.B. pro Mandant, Jahr, Monat - um einen einzelnen Monat eines Mandanten aktualisieren zu können

  • falls ein DeltaLoad implementiert wird, muss auch ein Fulload implementiert sein, um im Fehlerfall das gesamte System neu laden zu können

• Die Spiegelung sollte über eine Steuerungstabelle gesteuert werden können

  • in dieser lassen sich z.B. Mandanten / Jahre / Monate für die Spiegelung aktivieren

  • in dieser lassen unterschiedliche Spiegelungsbestände aktivieren (z.B. FiBu, KoRe, Offene Posten, Anlagevermögen)

• Die Stagingtabellen und die Steuerungstabellen sollten darauf ausgelegt sein, mehrere Instanzen dieses Vorsystems zu stagen - z.B. zwei DATEV Systeme und die Systeme durch ein führende Spalte (z.B. “DATEV_SystemID”) zu unterscheiden

• Technik

  • Die Umsetzung sollte aufgrund der weiteren Verbreitung bevorzugt in Python 3.13 erfolgen, alternativ in Powershell 7

  • es können bliebige übliche Python Bibliotheken zur Umsetzung genutzt werden (bspw. requests, pandas, pyodbc, sqlalchemie)

  • die Implementierung kann in mehreren Scripten erfolgen

  • die Daten

    • werden aus der Quelle gelesen und in einem pandas Dataframe gespeichert

    • diese Dataframe erhält die Anreicherungen etc.

    • der DataFrame wird im Outputformat geschrieben (SQL, CSV…)

  • es sollten ein main script gestartet werden können, welchem ein Parameter Ausführungsmodus übergeben wird

    • Modus 1 = Steuerungstabelle aufbauen bzw. aktualisieren

    • Modul 2 = Daten gemäß Konfiguration der Steuerungstabelle lesen

    • Modus 3 = das System leeren / die Daten in allen Tabellen löschen

  • bei on-premises Installation von OCT wird das Script lokal ausgeführt werden, in der Cloud Version von OCT wird es in einem Container ausgeführt (die Bereitstellung des passenden Containers erfolgt durch Saxess)

  • das Script sollte vorlaufend die gelesenen Partionen in die Datenbank schreiben

    • FALSCH: das Script liest alle angeforderten Mandanten / Jahre in den Arbeitsspeicher und schreibt am Ende alles in die Datenbank

    • RICHTIG: das Script schreibt jeden angeforderten Mandanten / Jahr sofort nach Abruf in die Datenbank

    • die Vorteile dabei sind:

      • der Arbeitspeicher des lesenden Rechners wird nicht stark beansprucht

      • die datenhaltenden Objekte (DataFrames etc.) bleiben schlank und schnell

      • in der Datenbank ist kontinuierlich der Fortschritt der Datenübernahme zu sehen

  • Logging

    • Die Aktivität soll kontinuierlich in einem Logfile dokumentiert werden

      • Aktion mit Parametern und Zeitstempel

      • Anzahl gelesener Zeilen / Spalten

      • Fehler / Warnungen

  • Indexierung der Tabellen der Staging Schicht

    • A: Spalte RowKey als IDENTITY Primärschlüssel mit Clustered Index (vermeidet aufblähen der Tabellen durch ungenutzen Speicherplatz)

    • B: die Tabellen haben keinen Primärschlüssel (höhere Schreibperformance, aber Gefahr des aufblähens), müssen dann aber regelmäßig per TRUNCATE gelöscht werden

• Sicherheit

  • die API Credentials / Datenbankpasswörter dürfen nicht im Hauptsript main.py definiert sein. Sie müssen aus einer separaten Credentials Datei gelesen werden um das Projekt jederzeit ohne Zugangsdaten kopieren / einchecken zu können

  • ggf. können Credentials verschlüsselt abgelegt werden etc., sondern nicht das Abrufscript den Schlüssel speichert, sondern OCT den Schlüssel dafür beim Aufruf übergibt

Python Basisprozess

Das Python Framework aus dem Repo nutzen.

Beispiel für DATEV Connect

Tabellennamen (hier noch im Schema integration, besser im Schema staging speichern

Spalten der Steuerungstabelle