Einführung

Dieses Dokument richtet sich an technische Anwender und Beratungsmitarbeiter und beschreibt die Konfiguration und Verwendung des kVASy Adressimports aus Tourendaten V2. V2 läuft parallel zur bestehenden V1-Variante. Sie können eine V1-Konfiguration belassen und V2 dort einsetzen, wo die Trennung zwischen Gruben- und Korrespondenzadresse benötigt wird.

Was ist neu gegenüber V1

• Trennung Gruben-/Korrespondenzadresse: Wenn die Kunden-Adresse (Kunde_*) von der Grubenadresse (DZA_*) abweicht (Strasse, Hausnummer, Zusatzhausnummer, PLZ, Ort), legt V2 zusätzlich eine Korrespondenzadresse an und verknüpft sie über address.correspondence_address_id mit der Grube.
• Update-Schlüssel ist DZA_InvNr (nicht DZAPK wie in V1) und wird auf address.pit_number abgelegt.
• Kundennummer als hostsystem_reference auf Gruben- und Korrespondenzadresse — so bleiben beide Datensätze über das Quellsystem identifizierbar.
• Neue optionale Config Tags:
  • pump_out/client/ident — Client für die Service-Rolle pump_out.
  • drainage/job_type/ident — Job-Typ für die recurring_drainage_definition (Default Abfuhr; viele Bestandskunden setzen Fäkalauftrag).
• Neuer Zähler unchanged in der Job-Zusammenfassung: Zeilen, die verarbeitet wurden, aber zu keiner Datenänderung geführt haben.
• Neue Adressspalte „Verwendung" zeigt auf einen Blick, ob ein Datensatz Grube, Korrespondenz oder Rechnung ist (auch in der erweiterten Suche filterbar).

Funktionsumfang

V2 verarbeitet eine CSV-Datei und führt pro Zeile in genau dieser Reihenfolge aus:

1. Gruben-Upsert anhand DZA_InvNr. Vorhandene Grube → Update bei Abweichung, sonst keine Änderung. Nicht vorhanden → Insert.
2. Korrespondenz-Upsert (nur wenn nötig, siehe Wann entsteht eine Korrespondenzadresse?). Vorhandene Adresse mit gleicher Kundennummer und pit_number IS NULL wird aktualisiert; sonst neu angelegt.
3. Verknüpfung der Grube mit der Korrespondenzadresse (address.correspondence_address_id); ist keine Korrespondenz mehr nötig, wird die Verknüpfung entkoppelt (die Adresse bleibt erhalten).
4. Sekundärdaten nur bei neuen Gruben: Service-Provider (Kläranlage, Abwasserzweckverband, optional Abpumpunternehmen) und eine recurring_drainage_definition werden ausschliesslich für neu angelegte Grubenadressen erzeugt — nie für Updates und nie für Korrespondenzadressen.

Zugriff

Die Import Job Definition für V2 wird beim Setup automatisch angelegt und liegt neben der V1.

So gelangen Sie zur V2-Konfiguration:

1. Navigieren Sie zu Schnittstellen → Import-Job-Definition.
2. Wählen Sie den Eintrag „kVASy Adressimport aus Tourenplanung V2".
3. Direktlink: /interface/import_job_definition/<id> (im obigen Screenshot Id 3).

Fachliche Konfiguration

Die fachliche Konfiguration steuert, welche Stammdaten beim Import an die Grubenadresse angehängt werden. Sie erfolgt ausschliesslich über Configuration Tags (Key/Value-Paare) auf der V2 Import Job Definition.

Bevor Sie speichern, stellen Sie sicher, dass alle referenzierten Idents (Client, Artikel, Job-Typ) tatsächlich in der Datenbank existieren. Ein fehlender Ident bricht den Import mit einer eindeutigen Fehlermeldung ab (siehe Fehler nachverfolgen).

Hinweis: Ein Screenshot der Sektion „Configuration Tags" mit den V2-Werten wird hier ergänzt, sobald config_tags.png im Image-Ordner verfügbar ist.

Erforderliche Config Tags

Optionale Config Tags

Wohnungsnummer (DZA_WHGNR → street_ext)

Die optionale Tourenplan-Spalte DZA_WHGNR (Spaltenindex BD) wird auf die Grubenadresse als address.street_ext (Beschriftung „Strasse Zusatz") übernommen. Der Wert wird vor dem Speichern getrimmt; ein leerer Wert lässt einen bereits vorhandenen Datenbankwert unverändert (kein Überschreiben mit Leer).

Verhalten der Präfix-Logik:

• Trifft der Wert auf DZA_WHGNR_REGEX zu (Standard: rein numerisch), wird DZA_WHGNR_PREFIX mit einem Leerzeichen vorangestellt — z. B. 3 → WHG 3.
• Trifft er nicht zu (z. B. EG-links), wird der getrimmte Wert ohne Präfix gespeichert.
• Ist DZA_WHGNR_REGEX leer, wird der Präfix nie angewandt.

V2 schreibt street_ext ausschliesslich auf die Grubenadresse, nicht auf die Korrespondenzadresse.

Wann entsteht eine Korrespondenzadresse?

Eine Korrespondenzadresse wird genau dann angelegt (oder aktualisiert), wenn mindestens eines der folgenden Felder zwischen Kunden- und Grubenadresse abweicht (Vergleich ist trim/lowercase-tolerant):

• Kunde_Strasse ↔ DZA_Strasse
• Kunde_Hausnummer ↔ DZA_Hausnummer
• Kunde_Zusatzhausnummer ↔ DZA_Zusatzhausnummer
• Kunde_PLZ ↔ DZA_PLZ
• Kunde_Ort ↔ DZA_Ort

Die Korrespondenzadresse wird über die Kundennummer (in hostsystem_reference) gefunden bzw. aktualisiert. Pro Kundennummer existiert höchstens eine Korrespondenzadresse (deterministische Auswahl der niedrigsten Id, falls historisch mehrere vorliegen).

Stimmen sämtliche Felder bei einem späteren Re-Import wieder überein, bleibt die Korrespondenzadresse als Datensatz erhalten, lediglich die Verknüpfung address.correspondence_address_id der Grube wird auf NULL gesetzt (Zähler correspondence cleared).

Sekundärdaten — Invariante

Service-Provider und recurring_drainage_definition werden ausschliesslich für neu angelegte Grubenadressen erzeugt.

• Updates an existierenden Gruben legen keine zusätzlichen Service-Provider an und ändern keine bestehende Regelentsorgung.
• Korrespondenzadressen erhalten niemals Service-Provider oder eine Regelentsorgung.

Dies entspricht dem Verhalten der V1-Variante.

Welche Felder werden immer auf die Grube übertragen?

Unabhängig davon, ob eine Korrespondenzadresse entsteht, werden bei jedem Import folgende Kunden-Felder auf die Grube synchronisiert:

Pit-spezifische Felder (DZA_Strasse, DZA_PLZ, DZA_Ort, DZA_Anlagenart, DZA_Nutzinhalt, DZA_Personen, DZA_Wartung_Letzte, DZAPK, DZA_Bauart) werden ebenfalls auf die Grube übernommen.

Technische Konfiguration

Die technische Konfiguration legt fest, wie die CSV-Datei eingelesen wird. Sie ist identisch zu V1 und kann auf der Detailseite der Import Job Definition angepasst werden.

Hauptattribute

Format-Settings

CSV-Spalten

Mindestens benötigt:

Datenkonvertierung

• Datum: Erwartet dd.MM.yyyy (auch d.M.yyyy; zweistellige Jahre werden als 20yy interpretiert).
• Dezimal: Komma als Dezimaltrenner (5,5 → 5.5).
• Strasse: DZA_Strasse + " " + DZA_Hausnummer + DZA_Zusatzhausnummer.
• Telefon: Kunde_Vorwahl + "/" + Kunde_Telefon.
• Drainage-Zyklus:
  • 1 / J → 12 Monate (einmal pro Jahr)
  • 2 / J → 6 Monate
  • / J → 12 Monate
  • / K → unbekannt (wird ignoriert)
  • reine Zahl → Anzahl Monate

Datei hochladen / Import starten

Der Import kann von zwei Stellen gestartet werden — am komfortabelsten direkt von der Adressliste.

Schritt 1 — Adressliste öffnen

Das Dropdown „Importieren" zeigt alle für die Domäne address aktiven Import Job Definitionen — V1 und V2 erscheinen hier nebeneinander. In der Tabelle ist die neue Spalte „Verwendung" sichtbar mit Tags Grube, Korrespondenz und Rechnung.

Schritt 2 — V2 wählen und Datei hochladen

Im Dialog „Datei importieren":

1. Datei auswählen — die Datei muss dem Muster .*TP.*\.csv entsprechen (also „TP" im Dateinamen tragen) und Windows-1252-codiert sein.
2. Daten-Vorschau (Testlauf) aktivieren, wenn die Datei vor dem produktiven Import nur validiert werden soll. Im Dry-Run werden keine Datensätze geschrieben, es wird lediglich geprüft, ob:
   • die Pflichtspalten vorhanden sind,
   • die referenzierten Stammdaten (Client/Artikel/Job-Typ) auflösbar sind,
   • die Datei syntaktisch lesbar ist.
3. Importieren klicken.

Schritt 3 — Status verfolgen

Nach dem Klick wird ein Import Job angelegt. Sie finden ihn unter Import-Job-Definition → V2-Detailseite → Tab „Import Jobs". Mögliche Statuswerte:

• progress — wird gerade verarbeitet,
• done — abgeschlossen (auch wenn einzelne Zeilen Fehler hatten),
• failed — Abbruch vor der Zeilenverarbeitung (z. B. wegen fehlender Pflichtspalte oder unauflösbarem Config Tag).

Fehler nachverfolgen

Hinweis: Ein Screenshot des „Import Jobs"-Tabs mit der V2-Zusammenfassung wird hier ergänzt, sobald import_jobs_tab.png im Image-Ordner verfügbar ist.

Wo finde ich was?

Im Tab „Import Jobs" auf der V2-Detailseite stehen pro Lauf:

Die V2-Zusammenfassung (msg)

Beispiel:

Import V2 completed: 5 pit created, 2 pit updated, 4 correspondence created,
1 correspondence updated, 1 correspondence cleared, 3 unchanged, 1 ignored,
0 failed (total: 12 rows)

Invariante: pit created + pit updated + correspondence created + correspondence updated + correspondence cleared + unchanged + ignored + failed = total (jede Zeile fällt in genau einen Bucket; Korrespondenz-Zähler addieren sich zusätzlich, weil eine Zeile sowohl Grube als auch Korrespondenz berühren kann).

Häufige Fehlerbilder

Tiefergehende Diagnose

• verbose=true als Config Tag setzen und den Import erneut starten — die Backend-Logs enthalten dann pro Zeile detaillierte Informationen zur Auflösung und zum Vergleich.
• Beim Verdacht auf Datentyp-Probleme (Datum, Dezimal): die betroffenen Spalten in einem Texteditor prüfen — kVASy verwendet dd.MM.yyyy und , als Dezimaltrenner.
• Cross-Check über die neue Adressliste: Filter „Verwendung = Grube" / „… = Korrespondenz" in der erweiterten Suche, um zu kontrollieren, welche Datensätze tatsächlich angelegt wurden.

Beispiel-Konfiguration & -Resultat

Vollständige Config Tags

sewage_treatment_plant/client/ident=WTAZV
wastewater_association/client/ident=WTAZV
pump_out/client/ident=WTAZV
waste_material_id/ident=Haushaltsabwasser
drainage/job_type/ident=Fäkalauftrag
verbose=false

Beispiel A — Kunde und Grube unterschiedlich

CSV-Zeile (Auszug):

Kundennummer=K001
Kunde_Name1=Mustermann GmbH
Kunde_Strasse=Büroweg
Kunde_Hausnummer=10
Kunde_PLZ=14000
Kunde_Ort=Hauptstadt
Kunde_Vorwahl=030
Kunde_Telefon=1234567
DZA_InvNr=ASG-12345
DZA_Anlagenart=abflusslose Sammelgrube
DZA_Strasse=Hauptstraße
DZA_Hausnummer=42
DZA_PLZ=12345
DZA_Ort=Musterstadt
DZA_Wartung_Zyklus=1 / J

Resultat:

• Grubenadresse — pit_number=ASG-12345, hostsystem_reference=K001, name=Mustermann GmbH, street=Hauptstraße 42, phone=030/1234567, correspondence_address_id → Id der unten erzeugten Korrespondenz.
• Korrespondenzadresse (neu, weil Kunden- ≠ Grubenadresse) — hostsystem_reference=K001, name=Mustermann GmbH, street=Büroweg 10, pit_number IS NULL.
• Service-Provider auf der Grube: sewage_treatment_plant, wastewater_association, pump_out — alle mit Client WTAZV.
• Regelentsorgung auf der Grube: cycle_months=12, job_type=Fäkalauftrag, waste_material=Haushaltsabwasser.
• Zusammenfassung (für 1 Zeile): 1 pit created, 1 correspondence created, 0 unchanged, 0 ignored, 0 failed (total: 1 rows).

Beispiel B — Kunde und Grube identisch

Bei gleicher Kunden- und Grubenadresse (z. B. Eigenheim) entfällt die Korrespondenzadresse:

• Grubenadresse wird wie oben angelegt.
• address.correspondence_address_id bleibt NULL.
• Service-Provider und Regelentsorgung werden ebenfalls erzeugt.
• Zusammenfassung: 1 pit created, 0 correspondence created, 0 unchanged, 0 ignored, 0 failed (total: 1 rows).

Beispiel C — Re-Import ohne Änderung

Wird die identische Datei nochmals importiert:

• Zusammenfassung: 0 pit created, 0 pit updated, 0 correspondence created, 0 correspondence updated, 0 correspondence cleared, N unchanged, 0 ignored, 0 failed (total: N rows).
• Es entstehen keine zusätzlichen Datensätze; vorhandene Service-Provider bleiben unverändert.