Einführung

Mit Hilfe dieses Dienstes können Bestände aus einem Dateisystem importiert werden. Die zu importierenden Bestände werden aufbereitet und der stock-API zugeführt. Ein Reporting des Importerfolges wird dauerhaft in der Tabelle task_log festgehalten.

Technische Details zur Funktionsweise des File-System-Watchers

Der Namespace werner-backend.crosscutting.interface.file-system-watch dient dazu, ein Verzeichnis zu überwachen und neue Dateien, die in dieses Verzeichnis abgelegt werden, zu verarbeiten. Nachfolgend sind die Hauptfunktionen und der Ablauf des Watchers aus der Sicht eines technischen Nutzers beschrieben:

1. Überwachung des Verzeichnisses

Der Watcher überwacht kontinuierlich ein angegebenes Verzeichnis (path-to-watch) auf das Auftreten neuer Dateien, die einem bestimmten Muster entsprechen (files-to-watch-regex-pattern). Sobald eine neue Datei erkannt wird, wird diese in eine Liste der Kandidaten-Dateien aufgenommen.

2. Überprüfung der Dateistabilität

Nachdem eine Datei als Kandidat erkannt wurde, überwacht der Watcher für eine festgelegte Zeitspanne (expected-time-of-file-being-of-constant-size), ob sich die Dateigröße ändert. Dies stellt sicher, dass die Datei vollständig geschrieben wurde und stabil ist, bevor mit der Verarbeitung begonnen wird.

3. Verschieben der Datei

Sobald die Datei als stabil erkannt wurde, wird sie in ein temporäres data-Verzeichnis innerhalb des definierten Verzeichnisses (path-to-copy-to) verschoben. Diese Verschiebung stellt sicher, dass die Originaldatei nicht weiter verändert wird, während sie verarbeitet wird.

4. Verarbeiten der Datei

Nach dem Verschieben in das data-Verzeichnis wird die Datei von einer benutzerdefinierten Lambda-Funktion (lambda) verarbeitet. Diese Funktion kann beliebige Aufgaben ausführen, wie z.B. das Parsen der Datei, das Extrahieren von Daten und das Übergeben dieser Daten an andere Systemkomponenten.

5. Abschluss der Verarbeitung

Nach erfolgreicher Verarbeitung wird die Datei in das save-Verzeichnis verschoben. Falls bei der Verarbeitung Fehler auftreten, wird die Datei stattdessen in das failure-Verzeichnis verschoben. Dies erleichtert die Fehlersuche und das erneute Verarbeiten fehlerhafter Dateien.

6. Beenden des Watchers

Der Watcher kann durch einen Aufruf der zurückgegebenen Lambda-Funktion (fn [] (reset! stop true)) gestoppt werden. Dies beendet die Überwachung des Verzeichnisses und alle damit verbundenen Hintergrundprozesse.

Zusammenfassung der Aufgaben:

• Überwachen eines Verzeichnisses: Der Watcher wartet auf neue Dateien in einem festgelegten Verzeichnis.
• Überprüfen der Dateistabilität: Der Watcher stellt sicher, dass Dateien vollständig geschrieben sind, bevor sie verarbeitet werden.
• Verschieben und Verarbeiten der Datei: Dateien werden in ein temporäres Verzeichnis verschoben und dort von einer benutzerdefinierten Funktion verarbeitet.
• Speichern oder Fehlerbehandlung: Verarbeitete Dateien werden entweder gespeichert oder bei Fehlern in ein Fehlerverzeichnis verschoben.

Durch diese Schritte stellt der File-System-Watcher sicher, dass Dateien zuverlässig und geordnet verarbeitet werden können, ohne dass es zu Inkonsistenzen oder Datenverlusten kommt.

Konfiguration

1. Die Konfiguration mittels .edn-Datei

Die Konfiguration des Dienstes erfolgt über eine .edn-Datei, welche verschiedene Spezifikationen enthält, die definieren, wie die Bestände importiert werden sollen. Jede Spezifikation in der .edn-Datei beschreibt eine bestimmte Importaufgabe, einschließlich des zu überwachenden Verzeichnisses, des CSV-Formats und der zu importierenden Datenfelder.

Der Dienst verwendet diese Konfigurationen, um Dateisystem-Überwachungen (File Watchers) einzurichten, die auf bestimmte Muster in Dateinamen achten und die Dateien entsprechend den gegebenen Spezifikationen verarbeiten. Die Ergebnisse des Importvorgangs, einschließlich Erfolg oder Fehler, werden in der task_log-Tabelle protokolliert.

2. Beispiel einer .edn-Spezifikation

Hier ist ein Beispiel einer .edn-Konfiguration, die zwei unterschiedliche Importaufgaben definiert:

{:server/jetty {:handler #ig/ref :werner/app :port 8080}
 :werner/router {}
 :werner/app {:jdbc-url #ig/ref :db/postgres :router #ig/ref :werner/router}
 :werner/walkable-parser {:jdbc-url #ig/ref :db/postgres}
 ;; Dont need to set this here, werner-backend uses the docker container configuration
 :db/postgres {}
 :domain/job {:werner/app #ig/ref :werner/app}
 :domain/device {:werner/app #ig/ref :werner/app}
 :tasks/import_stocks_from_filesystem {
  :db/postgres #ig/ref :db/postgres
  :specs [{
    :separator ","
    :quote \"
    :encoding "UTF-8"
    :locale "de_CH" ;; Beispiel-LOCALE für die Schweiz (Deutsch)
    :job_name "import books initially"
    :columns [["PID" :hostsystem_reference :string]
              ["Barcode" :barcode :string]
              ["Call Number" :call_no :string]
              ["Title" :ident :string]
              ["Author" :author :string]
              ["Publication Date" :year_of_publication :string]]
    :invariants {"article/ident" "Buch", :dy 30}
    :path-to-watch "/tmp/cds-job-import"
    :path-to-copy-to "/tmp/werner/interface/unibas-stock-import"
    :files-to-watch-regex "\\._initial.*\\.csv"}
   {
    :job_name "import book updates"
    :locale "en_US" ;; Beispiel-LOCALE für die Vereinigten Staaten
    :columns [["PID" :hostsystem_reference :string]
              ["Barcode" :barcode :string]
              ["Call Number" :call_no :string]
              ["Title" :ident :string]
              ["Author" :author :string]
              ["Publication Date" :year_of_publication :string]]
    :invariants {"article/ident" "Buch", :dy 30}
    :path-to-watch "/tmp/cds-job-import"
    :path-to-copy-to "/tmp/werner/interface/unibas-stock-import"
    :files-to-watch-regex "\\._update.*\\.csv"}]}}

3. Elemente der Spezifikation

Die Spezifikationen in der .edn-Datei bestehen aus mehreren Schlüsseln, die die Konfiguration des Importprozesses steuern. Hier sind die wichtigsten Elemente der Spezifikation in einer Tabelle erläutert:

Strukturen

1. Datenbankstruktur von stock

Die folgende Tabelle zeigt die Struktur der stock-Tabelle, die für den Import verwendet wird:

2. Requeststruktur

Die folgende Tabelle beschreibt die Struktur des Requests für die stock-API:

Beispiel-Request

{
  "updateKey": "hostsystem_reference",
  "stocks": [
    {
      "hostsystem_reference": "12345",
      "barcode": "A1001389689",
      "call_no": "UBH BS 143:35",
      "title": "Baltische Bibliographie 2000",
      "author": "",
      "year_of_publication": "2005"
    }
  ]
}