Leitfaden für die Erstellung von Gateways

Zielstellung

Eine Staging Schicht spiegelt die Daten aus einem Produktivsystem in eine Datenbank zur Weiterverarbeitung. Die Daten werden dabei weitgehend 1:1 gespiegelt. Die Staging Schicht soll breit sein und verschiedenen Folgeprozessen / Modulen eine Datenbasis bieten.

Fünf Wünsche an Staging Prozesse von Benutzern

1. Erlaube mir eine einfache und sichere Konfiguration

   1. erstelle eine config Datei, welche der Hauptprozess einliest

   2. alle Konfigurationsparameter für Verbindungen und Passwörter kommen in die config Datei

   3. lass mich den Hauptprozess mit einer ausgewählten config Datei starten

   4. so kann ich den Hauptprozess jederzeit in eine Versionsverwaltung ohne credentials einchecken

2. Berücksichtige, dass ich vielleicht mehrere Instanzen eines Vorsystems in die Zieldatenbank einlesen möchte

   1. lass mich daher in der config Datei eine DatenquellenID definieren und stelle die Spalte DatenquellenID als führende Spalte vor jede Tabelle

   2. TRUNCATE Tabellen nur mit meiner Zustimmung, normalerweise erfolgt nur ein DELETE für die bei Aktualisierungen

3. Gib mir ein Inhaltsverzeichnis und eine Auswahlmöglichkeit

   1. zeige mir zunächst den Bestand an Mandanten und Geschäftsjahren, lass mich dort auswählen, welche ich gespiegelt haben möchte

   2. teile umfangreiche Datenbestände in logische Partitionen (Buchhaltung, Warenwirschaft, Vertrieb…) um bestimmte Bestände einzuschließen oder auch nicht

   3. lass mich flexibel entscheiden, welche Mandanten / Geschäftsjahre / Datenbestände ich jeweils aktualisiert haben möchte

   4. rechne damit, dass ich ausgewählte Datenbestände (ein Geschäftsjahr von einem Mandanten) schnell mal außerordentlich aktualisieren möchte

   5. rechne damit, dass meine Wünsche wachsen werden falls ich glücklich bin - ich werde mehr Bestände haben wollen und mehr mit der Datenbasis tun wollen

4. Gib mir meine Daten in meiner Sprache und in meiner Struktur

   1. kopiere meine Daten 1:1 so wie sie in der Quelle sind - gib mir viele Attribute, welche für mich nützlich sein könnten

   2. ändere keine Namen und gib mir jede Tabelle einzeln mit ihrem originalen Namen, dann kann ich die Daten leicht wiedererkennen und auch in der Herstellerdokumentation dazu nachschlagen

   3. wandle Spalteninhalte nur um, wenn sie dadurch für mich leichter konsumierbar werden

   4. füge mir ggf. Spalten ein, welche mir das joinen der Tabellen erleichtern

5. Lass mich sehen, ob alles funktioniert

   1. zeige mir ein gut lesbares Log

   2. zeige mir, wie viele Daten im Bestand sind und ob sie aktuell sind

   3. validiere Summen, wo es universtell möglich ist

Grundaufbau

Die Entwicklung eines Gateways erfolgt in einem Bitbucket Repository mit folgendem Aufbau

• Ordner Entwicklung

  • Ordner Datenbank

    • Datenbankscripte pro Objekt

    • Paketierungsscript

  • Ordner config

    • Datei config.json

    • ggf. weitere config Dateien

  • Ordner setup

    • Datenbankscripte zum Setup

    • requirements.txt mit Definition der benötigten Python Bibliotheken

    • releaselog.txt mit Versionnummer nach Semantic Versioning Konvention

  • Ordner oct_helper

    • unterstützenden Module

  • main.py

• Ordner Releases

  • Enthält einen Ordner mit Datum pro Release

  • Enthält einen Ordner Gateway_xxx mit dem letzten Release, um diesen festen Pfad verlinken zu können

Desginregeln

Grundregeln

• Das OCT Python Framework aus dem Repo sollte genutzt werden

• Die Anbindung sollte einem Entwurfsmuster folgen

Datenbank

• Sollte als setup Script mit Tabellen und ohne Tabellen bereitgestellt werden, um die Logik bei geladenen Tabellen updaten zu können

• Pipelines müssen benannten ID besitzen, um diese im Publish Prozess reorganisieren zu können

• Tabellen bei übersichtlicher Anzahl manuell erstellen mit passenden Datentypen

• API Aufruf liefern je nach Kontext (pro Mandant etc.) mehr oder weniger Spalten zurück (Spalten die nur NULL enthalten würden werden teilweise automatisch unterdrückt), daher immer das maximale Spalteset definieren und die nicht Schlüsselspalten als NULL able klassifizieren

• dynamisch erstellte Tabelle erhalten von Pandas für Dezimalwerte oft den Typ float - dieser ist unpassend (erzeugt Rundungsprobleme) → immer Decimal oder Money verwenden bzw. konvertieren

DataFrame schreiben

• soll über geprüfte Methode passieren (ca. 20.000 Zeilen nach Azure / 1.000.000 Zeilen lokal sollten erreicht werden)

• soll bei großen Datenmengen Fortschrittsbalken im Log zeigen

• soll Durchsatz messen und ins Log schreiben

• Daten sollen fortlaufend in die Datenbank geschrieben um den Arbeitsspeicher zu entlasten und in der Datenbank den Fortschritt zu sehen

Ausführbarkeit

• das Gateway soll in einer lokalen Umgebung ausführbar sein

• Gateways mit Scriptcode müssen in Cloudumgebungen im Container ausführbar sein

Komplexe Typen

• komplexe Rückgabewerte innerhalb von Tabellen (JSON Objekte, Arrays etc.) werden im Stagingprozess in der Regel nicht aufgelöst, sondern als String gespeichert, sofern sich dieser über SQL gut auflösen lässt

Logging

• Aktion mit Parametern und Zeitstempel

• Anzahl gelesener Zeilen / Spalten

• Fehler / Warnungen

• Errorcounter um zwischenzeitliche Fehler zu zählen und am Ende den Exit Code zu steuern

• für die Übergabe noch OCT sollte zwischen den Debuggleveln Error, Warning und Info umgeschalten werden können

Indexierung der Tabellen

• noch nicht konzeptioniert

• A: kein Index (Heap) - höchste Schreibperformance, aber Aufblähgefahr

• B: Spalte RowKey als Clustered Index - vermeidet aufblähen, Index ist aber ansonsten nutzlos

Die Implementierung sollte in Python erfolgt