Einführung

Dieses Dokument beschreibt die Konfiguration und Verwendung des kVASy Adressimports aus Tourendaten. Der Import ermöglicht es, Adressdaten aus dem kVASy Tourenplanungssystem zu importieren und automatisch mit zusätzlichen Informationen wie Service-Providern und wiederkehrenden Entsorgungsdefinitionen anzureichern.

Der Import verwendet CSV-Dateien im Windows-1252 Format und verarbeitet diese manuell über die Import Job Definition Oberfläche.

Funktionsweise

Der Import verarbeitet CSV-Dateien mit Adressdaten aus dem kVASy System und:

• Erstellt oder aktualisiert Adressen basierend auf der DZAPK (Gruben-Nummer) als eindeutigem Schlüssel
• Erstellt automatisch Service-Provider für neue Adressen (Kläranlage, Abwasserzweckverband, Abpumpunternehmen)
• Erstellt wiederkehrende Entsorgungsdefinitionen für neue Adressen mit Zyklusinformationen
• Aktualisiert bestehende Adressen wenn sich Daten geändert haben

Voraussetzungen

CSV-Dateiformat

Die CSV-Dateien müssen folgende Anforderungen erfüllen:

• Encoding: Windows-1252
• Trennzeichen: Semikolon (;)
• Quote-Zeichen: Keine (Quote-Handling ist deaktiviert, da kVASy Exporte unescapte Quotes in den Daten enthalten)
• Dateinamen-Muster: .*TP.*\.csv (muss "TP" im Dateinamen enthalten)

Erforderliche CSV-Spalten

Die CSV-Datei muss mindestens folgende Spalten enthalten:

Konfiguration

Import Job Definition einrichten

Die Import Job Definition wird automatisch beim ersten Start des Systems erstellt. Sie können die Konfiguration über die Oberfläche unter Interfaces → Import Job Definition → kVASy Adressimport aus Tourenplanung anpassen.

Basis-Konfiguration

Die Standard-Konfiguration ist bereits voreingestellt:

• Name: kVASy Adressimport aus Tourenplanung
• Import Job Type: address
• Target Type: csv
• Encoding: Windows-1252
• Separator: ;
• Quote: NULL (deaktiviert)
• Locale: de-DE
• File Name Pattern: .*TP.*\.csv
• Path to Watch: NULL (nur manueller Import)

Config Tags

Die Konfiguration erfolgt über Config Tags in der Import Job Definition. Diese werden als key=value Paare konfiguriert.

Erforderliche Config Tags

Optionale Config Tags

Config Tags konfigurieren

1. Öffnen Sie die Import Job Definition kVASy Adressimport aus Tourenplanung
2. Navigieren Sie zum Tab Main attributes
3. Scrollen Sie zum Abschnitt Configuration Tags
4. Fügen Sie die erforderlichen Config Tags hinzu:
   • Klicken Sie auf + Add Tag
   • Geben Sie den Key ein (z.B. sewage_treatment_plant/client/ident)
   • Geben Sie den Value ein (z.B. WTAZV)
   • Wiederholen Sie dies für alle erforderlichen Tags
5. Klicken Sie auf Submit um die Änderungen zu speichern

Wichtig: Stellen Sie sicher, dass die angegebenen Client-Idents und Artikel-Idents in der Datenbank existieren, bevor Sie den Import ausführen.

Verwendung

Manueller Import

1. CSV-Datei vorbereiten:

   • Stellen Sie sicher, dass die CSV-Datei das richtige Format hat (siehe Abschnitt "CSV-Dateiformat")
   • Der Dateiname muss "TP" enthalten (z.B. Adressen_TP_2024.csv)

2. Import starten:

   • Navigieren Sie zu Interfaces → Import Job Definition
   • Öffnen Sie kVASy Adressimport aus Tourenplanung
   • Klicken Sie auf den Tab Import Jobs
   • Klicken Sie auf New Import Job oder verwenden Sie die Upload-Funktion
   • Wählen Sie die CSV-Datei aus
   • Der Import wird automatisch gestartet

3. Import-Status überwachen:

   • Der Status wird in der Import Jobs Tabelle angezeigt
   • Mögliche Status: progress, done, failed
   • Bei Fehlern können Sie die Fehlermeldung in den Job-Details einsehen

Import-Verhalten

Neue Adressen

Wenn eine Adresse mit einer neuen DZAPK (Gruben-Nummer) importiert wird:

1. Adresse wird erstellt mit allen verfügbaren Daten aus der CSV-Datei
2. Service-Provider werden erstellt:
   • sewage_treatment_plant (wenn sewage_treatment_plant/client/ident konfiguriert)
   • wastewater_association (wenn wastewater_association/client/ident konfiguriert)
   • pump_out (wenn pump_out/client/ident konfiguriert)
3. Wiederkehrende Entsorgungsdefinition wird erstellt:
   • Nur wenn DZA_Wartung_Zyklus in der CSV-Datei vorhanden ist
   • Verwendet den konfigurierten waste_material_id/ident
   • Verwendet den Job-Typ "Abfuhr"

Bestehende Adressen

Wenn eine Adresse mit einer bereits vorhandenen DZAPK importiert wird:

1. Adresse wird aktualisiert wenn sich Daten geändert haben
2. Service-Provider werden NICHT erstellt (nur bei neuen Adressen)
3. Wiederkehrende Entsorgungsdefinition wird NICHT erstellt (nur bei neuen Adressen)

Datenverarbeitung

• Datum: Wird im Format TT.MM.JJJJ erwartet und in ein LocalDate konvertiert
• Dezimalzahlen: Komma wird als Dezimaltrennzeichen erkannt und in Punkt konvertiert
• Straße: Wird aus DZA_Strasse, DZA_Hausnummer und DZA_Zusatzhausnummer zusammengesetzt
• Telefon: Wird aus Kunde_Vorwahl und Kunde_Telefon zusammengesetzt (Format: Vorwahl/Telefon)
• Zyklus: Wird aus Werten wie "1 / J" (einmal pro Jahr = 12 Monate) oder "2 / J" (zweimal pro Jahr = 6 Monate) geparst

Fehlerbehebung

"Required column 'DZAPK' not found in CSV"

Problem: Die CSV-Datei enthält nicht die erforderliche Spalte DZAPK.

Lösung: Stellen Sie sicher, dass die CSV-Datei eine Spalte mit dem Namen DZAPK (exakt, case-sensitive) enthält.

"Client with ident 'XYZ' not found"

Problem: Ein in den Config Tags angegebener Client-Ident existiert nicht in der Datenbank.

Lösung:

1. Überprüfen Sie die Config Tags in der Import Job Definition
2. Stellen Sie sicher, dass die angegebenen Client-Idents korrekt sind
3. Erstellen Sie den fehlenden Client oder korrigieren Sie den Config Tag

"Article with ident 'XYZ' not found"

Problem: Der in waste_material_id/ident angegebene Artikel existiert nicht in der Datenbank.

Lösung:

1. Überprüfen Sie den Config Tag waste_material_id/ident
2. Stellen Sie sicher, dass der Artikel mit diesem Ident existiert
3. Erstellen Sie den fehlenden Artikel oder korrigieren Sie den Config Tag

Adressen werden nicht aktualisiert

Problem: Bestehende Adressen werden nicht aktualisiert, obwohl sich Daten geändert haben.

Mögliche Ursachen:

• Die DZAPK in der CSV-Datei stimmt nicht mit der DZAPK in der Datenbank überein
• Die Daten sind identisch (keine Änderung erkannt)

Lösung:

1. Überprüfen Sie die DZAPK-Werte in der CSV-Datei
2. Stellen Sie sicher, dass die DZAPK exakt mit der in der Datenbank gespeicherten übereinstimmt
3. Aktivieren Sie verbose=true in den Config Tags für detaillierte Debug-Informationen

Service-Provider werden nicht erstellt

Problem: Service-Provider werden nicht für neue Adressen erstellt.

Mögliche Ursachen:

• Die Config Tags für die Service-Provider sind nicht konfiguriert
• Die angegebenen Client-Idents existieren nicht

Lösung:

1. Überprüfen Sie die Config Tags sewage_treatment_plant/client/ident, wastewater_association/client/ident und pump_out/client/ident
2. Stellen Sie sicher, dass die Clients existieren
3. Service-Provider werden nur für neue Adressen erstellt, nicht für aktualisierte

Zyklus wird nicht korrekt geparst

Problem: Der Entsorgungszyklus wird nicht korrekt in Monate umgerechnet.

Unterstützte Formate:

• 1 / J = einmal pro Jahr = 12 Monate
• 2 / J = zweimal pro Jahr = 6 Monate
• / J = einmal pro Jahr = 12 Monate
• / K = unbekannt (wird ignoriert)
• Direkte Zahl = Anzahl Monate

Lösung: Verwenden Sie eines der unterstützten Formate oder geben Sie die Anzahl Monate direkt an.

Encoding-Probleme

Problem: Sonderzeichen werden nicht korrekt angezeigt.

Lösung: Stellen Sie sicher, dass:

• Die CSV-Datei im Windows-1252 Encoding gespeichert ist
• Die Import Job Definition encoding auf Windows-1252 eingestellt ist
• Die Datei nicht mit einem anderen Encoding (z.B. UTF-8) gespeichert wurde

Beispiel-Konfiguration

Vollständige Config Tags

sewage_treatment_plant/client/ident=WTAZV
wastewater_association/client/ident=WTAZV
waste_material_id/ident=Haushaltsabwasser
pump_out/client/ident=ENTSO_XYZ
verbose=false

Beispiel-CSV-Zeile

DZAPK;Kundennummer;Kunde_Name1;DZA_Strasse;DZA_Hausnummer;DZA_PLZ;DZA_Ort;DZA_Entsorgungsmenge;DZA_Personen;DZA_Wartung_Letzte;DZA_Wartung_Zyklus
12345;K001;Mustermann GmbH;Hauptstraße;42;12345;Musterstadt;5,5;4;15.03.2024;1 / J

Import-Ergebnis

Nach dem Import wird folgendes erstellt:

• Adresse:

  • pit_number: 12345
  • hostsystem_reference: K001
  • name: Mustermann GmbH
  • street: Hauptstraße 42
  • zip: 12345
  • city: Musterstadt
  • pit_volume: 5.5
  • number_of_inhabitants: 4
  • last_drainage_date: 2024-03-15

• Service-Provider:

  • sewage_treatment_plant → Client WTAZV
  • wastewater_association → Client WTAZV
  • pump_out → Client ENTSO_XYZ

• Wiederkehrende Entsorgungsdefinition:

  • cycle_months: 12 (einmal pro Jahr)
  • waste_material_id: Artikel mit Ident Haushaltsabwasser
  • job_type: Abfuhr