Changes for page BMD NLZ-Zulagen Import

Summary

• Attachments (0 modified, 0 added, 1 removed)
  • Dokumentation_BMD_NLZ_Zulagen_Import.md

Details

Dokumentation_BMD_NLZ_Zulagen_Import.md

Author

...	...	@@ -1,1 +1,0 @@
1		-XWiki.drupp

Size

...	...	@@ -1,1 +1,0 @@
1		-9.5 KB

Content

...	...	@@ -1,249 +1,0 @@
1		-# BMD NLZ-Zulagen Import – Prozessdokumentation
2		-
3		-**Version:** 1.0
4		-**Erstellt:** 2026-05-22
5		-**Erstellt von:** Patrick Sonderegger
6		-**Workspace:** Fabric / 08_Data for Sharing / BMD NLZ-Zulagen Import
7		-
8		----
9		-
10		-## 1. Überblick
11		-
12		-Dieser Prozess liest täglich CSV-Dateien (NLZ und Zulagen) von einem Windows-Fileserver ein, transformiert sie gemäss definierten Regeln und legt die verarbeiteten Dateien wieder auf dem Fileserver ab. Zusätzlich werden Testfiles für die Firma 260 erstellt.
13		-
14		-Der Prozess läuft vollautomatisch einmal täglich über Microsoft Fabric (Pipeline + Notebook) und ist über ein On-Premises Data Gateway mit dem Fileserver verbunden.
15		-
16		----
17		-
18		-## 2. Prozessablauf (funktional)
19		-
20		-### 2.1 Was passiert täglich?
21		-
22		-1. Die Pipeline wird automatisch gestartet (Scheduled Trigger)
23		-2. NLZ- und Zulagen-Files werden vom Fileserver in das Fabric Lakehouse kopiert
24		-3. Das Notebook transformiert die Files gemäss den Geschäftsregeln
25		-4. Die transformierten Files werden zurück auf den Fileserver geschrieben
26		-5. Die ursprünglichen Source-Files werden auf dem Fileserver archiviert und gelöscht
27		-6. Testfiles für Firma 260 werden erstellt
28		-7. Ein Log-Protokoll wird im Lakehouse abgelegt
29		-
30		-### 2.2 Ordnerstruktur Fileserver
31		-
32		-| Umgebung | Typ | Pfad |
33		-|---|---|---|
34		-| **Test** | NLZ Source | `\\atvietfs01\daten\Orbyte_Testordner\NLZ\Rohdaten` |
35		-| **Test** | NLZ Output | `\\atvietfs01\daten\Orbyte_Testordner\NLZ` |
36		-| **Test** | NLZ Archiv | `\\atvietfs01\daten\Orbyte_Testordner\NLZ\Rohdaten\Archiv` |
37		-| **Test** | Zulagen Source | `\\atvietfs01\daten\Orbyte_Testordner\Zulagen\Rohdaten` |
38		-| **Test** | Zulagen Output | `\\atvietfs01\daten\Orbyte_Testordner\Zulagen` |
39		-| **Test** | Zulagen Archiv | `\\atvietfs01\daten\Orbyte_Testordner\Zulagen\Rohdaten\Archiv` |
40		-| **Live** | NLZ Source | `\\atvietfs01\daten\IT\BMD\BMD\LV\NLZ\Rohdaten` |
41		-| **Live** | NLZ Output | `\\atvietfs01\daten\IT\BMD\BMD\LV\NLZ` |
42		-| **Live** | NLZ Archiv | `\\atvietfs01\daten\IT\BMD\BMD\LV\NLZ\Rohdaten\Archiv` |
43		-| **Live** | Zulagen Source | `\\atvietfs01\daten\IT\BMD\BMD\LV\Zulagen\Rohdaten` |
44		-| **Live** | Zulagen Output | `\\atvietfs01\daten\IT\BMD\BMD\LV\Zulagen` |
45		-| **Live** | Zulagen Archiv | `\\atvietfs01\daten\IT\BMD\BMD\LV\Zulagen\Rohdaten\Archiv` |
46		-
47		-### 2.3 Ordnerstruktur Fabric Lakehouse (shared_data_lh)
48		-
49		-```
50		-Files/
51		-└── CSV_Transformation/
52		- ├── NLZ/
53		- │ ├── Raw/ ← Eingang vom Fileserver
54		- │ ├── Output/ ← Transformierte Files
55		- │ └── Archive/ ← Archiv der Source-Files
56		- ├── Zulagen/
57		- │ ├── Raw/
58		- │ ├── Output/
59		- │ └── Archive/
60		- └── Logs/ ← Run-Protokolle und Summaries
61		-```
62		-
63		----
64		-
65		-## 3. Transformationsregeln
66		-
67		-### 3.1 Zulagen-Files
68		-
69		-Erkennungsmerkmal: Dateiname enthält **"Zulagen"**
70		-
71		-| Bedingung | Spalte | Aktion |
72		-|---|---|---|
73		-| Spalte D == `7590` | F (idx 5) | Wert auf `1` setzen |
74		-| Spalte D == `7590` | G (idx 6) | Aktuellen Monat aus Spalte A (YYYYMMDD) als Zahl eintragen (z.B. April → `4`) |
75		-| Spalte D != `7590` | — | Zeile bleibt unverändert |
76		-
77		-### 3.2 NLZ-Files
78		-
79		-Erkennungsmerkmal: Dateiname enthält **"NLZ"**
80		-
81		-**Schritt 1 – Zeilen löschen** (Spalte D):
82		-
83		-| Wert in Spalte D | Aktion |
84		-|---|---|
85		-| 3, 7, 8, 11, 16 | Zeile löschen |
86		-
87		-**Schritt 2 – Werte ersetzen** (Spalte D):
88		-
89		-| Ursprungswert | Neuer Wert |
90		-|---|---|
91		-| 4 | 1 |
92		-| 6 | 2 |
93		-| 9 | 3 |
94		-
95		-**Schritt 3 – Spalten neu anordnen:**
96		-
97		-| Output-Spalte | Quelle |
98		-|---|---|
99		-| A | Source Spalte B |
100		-| B | Source Spalte C |
101		-| C | Source Spalte D (nach Ersetzung) |
102		-| D | Fix-Wert `3` |
103		-| E | Source Spalte A (Datum) |
104		-| F | Source Spalte A (Datum, dupliziert) |
105		-
106		-### 3.3 Testfiles Firma 260
107		-
108		-Aus den transformierten Output-Files werden zusätzliche Testfiles erstellt:
109		-
110		-| File | Filterkriterium | Änderung |
111		-|---|---|---|
112		-| `260_Zulagen.csv` | Spalte B (idx 1) == `70` | Spalte B wird auf `260` gesetzt |
113		-| `260_NLZ.csv` | Spalte A (idx 0) == `70` | Spalte A wird auf `260` gesetzt |
114		-
115		----
116		-
117		-## 4. Technische Dokumentation
118		-
119		-### 4.1 Systemübersicht
120		-
121		-```
122		-Fileserver (\\atvietfs01)
123		- │
124		- │ On-Premises Data Gateway (SPL_Datagateway)
125		- │
126		-Microsoft Fabric
127		- ├── Data Pipeline (Pipeline_CSV_Transform)
128		- │ ├── Copy NLZ FS → Lakehouse
129		- │ ├── Copy Zulagen FS → Lakehouse
130		- │ ├── Notebook (csv_transformation)
131		- │ ├── Copy NLZ Lakehouse → FS
132		- │ ├── Copy Zulagen Lakehouse → FS
133		- │ ├── Archive NLZ on FS
134		- │ ├── Delete NLZ on FS
135		- │ ├── Archive Zulagen on FS
136		- │ └── Delete Zulagen on FS
137		- └── Lakehouse (shared_data_lh)
138		- └── Files/CSV_Transformation/...
139		-```
140		-
141		-### 4.2 Fabric Komponenten
142		-
143		-| Komponente | Name | Workspace | Typ |
144		-|---|---|---|---|
145		-| Pipeline | Pipeline_CSV_Transform | Fabric / 08_Data for Sharing / BMD NLZ-Zulagen Import | Data Pipeline |
146		-| Notebook | csv_transformation | Fabric / 08_Data for Sharing / BMD NLZ-Zulagen Import | Notebook |
147		-| Lakehouse | shared_data_lh | Fabric | Lakehouse |
148		-| Gateway | SPL_Datagateway | On-Premises | Data Gateway |
149		-
150		-### 4.3 Pipeline-Activities im Detail
151		-
152		-| Activity | Typ | Von | Nach |
153		-|---|---|---|---|
154		-| Copy NLZ FS → Lakehouse | Copy data | FS: `NLZ\Rohdaten\*.csv` | Lakehouse: `NLZ/Raw` |
155		-| Copy Zulagen FS → Lakehouse | Copy data | FS: `Zulagen\Rohdaten\*.csv` | Lakehouse: `Zulagen/Raw` |
156		-| Notebook (csv_transformation) | Notebook | Lakehouse: `NLZ/Raw` + `Zulagen/Raw` | Lakehouse: `NLZ/Output` + `Zulagen/Output` |
157		-| Copy NLZ Lakehouse → FS | Copy data | Lakehouse: `NLZ/Output` | FS: `NLZ\` |
158		-| Copy Zulagen Lakehouse → FS | Copy data | Lakehouse: `Zulagen/Output` | FS: `Zulagen\` |
159		-| Archive NLZ on FS | Copy data | FS: `NLZ\Rohdaten\*.csv` | FS: `NLZ\Rohdaten\Archiv` |
160		-| Delete NLZ on FS | Delete data | FS: `NLZ\Rohdaten\*.csv` | — |
161		-| Archive Zulagen on FS | Copy data | FS: `Zulagen\Rohdaten\*.csv` | FS: `Zulagen\Rohdaten\Archiv` |
162		-| Delete Zulagen on FS | Delete data | FS: `Zulagen\Rohdaten\*.csv` | — |
163		-
164		-### 4.4 Notebook-Konfiguration
165		-
166		-Das Notebook ist in Python geschrieben und verwendet pandas für die Transformation. Alle konfigurierbaren Pfade sind am Anfang des Notebooks im Abschnitt **KONFIGURATION** zusammengefasst:
167		-
168		-```python
169		-BASE_DIR = "/lakehouse/default/Files/CSV_Transformation"
170		-NLZ_SOURCE_DIR = f"{BASE_DIR}/NLZ/Raw"
171		-NLZ_OUTPUT_DIR = f"{BASE_DIR}/NLZ/Output"
172		-NLZ_ARCHIVE_DIR = f"{BASE_DIR}/NLZ/Archive"
173		-ZUL_SOURCE_DIR = f"{BASE_DIR}/Zulagen/Raw"
174		-ZUL_OUTPUT_DIR = f"{BASE_DIR}/Zulagen/Output"
175		-ZUL_ARCHIVE_DIR = f"{BASE_DIR}/Zulagen/Archive"
176		-LOG_DIR = f"{BASE_DIR}/Logs"
177		-```
178		-
179		-### 4.5 Logging & Monitoring
180		-
181		-Pro Run werden zwei Dateien im Lakehouse unter `CSV_Transformation/Logs/` erstellt:
182		-
183		-| Datei | Inhalt |
184		-|---|---|
185		-| `YYYYMMDD_HHMMSS_run.log` | Vollständiges Zeilenprotokoll mit Timestamps |
186		-| `YYYYMMDD_HHMMSS_summary.json` | Kompakte Zusammenfassung: Status, verarbeitete Files, Fehler |
187		-
188		-**Run History in Fabric:**
189		-Pipeline → oben in der Toolbar → **View run history** → Status, Dauer und Fehlerdetails pro Activity sichtbar.
190		-
191		----
192		-
193		-## 5. Fehlerbehandlung & Troubleshooting
194		-
195		-### 5.1 Wo sehe ich ob der Prozess erfolgreich war?
196		-
197		-1. **Fabric Portal** → Workspace → Pipeline → **View run history**
198		- Hier ist jeder Lauf mit Status (✅ Succeeded / ❌ Failed), Startzeit und Dauer sichtbar.
199		-
200		-2. **Lakehouse Logs** → `shared_data_lh` → Files → CSV_Transformation → Logs
201		- Die `_summary.json`-Dateien geben einen schnellen Überblick. Die `_run.log`-Dateien enthalten alle Details.
202		-
203		-### 5.2 Häufige Fehler und Lösungen
204		-
205		-| Fehler | Mögliche Ursache | Lösung |
206		-|---|---|---|
207		-| `FileNotFoundError: .../Raw` | Lakehouse-Ordner fehlt | Ordner manuell im Lakehouse anlegen |
208		-| `Source-Ordner nicht erreichbar` | Gateway offline oder Pfad falsch | Gateway-Status prüfen; Pfad in Pipeline-Activity kontrollieren |
209		-| `Cannot connect to \\atvietfs01\...` | Falscher UNC-Pfad (Dopplung) | Wildcard folder path in der Pipeline-Activity prüfen – der Basispfad der Verbindung (`\\atvietfs01\Daten`) darf nicht nochmals angegeben werden |
210		-| `Keine CSV-Files gefunden` | Source-Ordner leer | Prüfen ob Files korrekt im Source-Ordner abgelegt wurden |
211		-| Notebook schlägt fehl, Pipeline läuft weiter | Falsches Notebook verknüpft | In Pipeline-Activity Settings das korrekte Notebook auswählen |
212		-| Output-File fehlt | Transformation-Fehler | `_run.log` im Lakehouse öffnen und nach `ERROR` suchen |
213		-
214		-### 5.3 Manueller Test
215		-
216		-Falls der Prozess manuell gestartet werden soll:
217		-1. Source-Files manuell in den `Raw`-Ordner im Lakehouse hochladen (Lakehouse → Files → NLZ/Raw oder Zulagen/Raw → Upload)
218		-2. Notebook direkt öffnen und **Run all** klicken
219		-3. Output-Files im Lakehouse unter `NLZ/Output` bzw. `Zulagen/Output` prüfen
220		-
221		-### 5.4 Anpassungen vornehmen
222		-
223		-| Was ändern? | Wo? |
224		-|---|---|
225		-| Fileserver-Pfade | In den jeweiligen Pipeline-Activities (Source/Destination) |
226		-| Transformationsregeln | Im Notebook, Funktionen `transform_nlz()` / `transform_zulagen()` |
227		-| Firma-260-Logik | Im Notebook, Funktion `create_260_files()` |
228		-| Scheduled Trigger (Uhrzeit) | Pipeline → **Schedule** oben in der Toolbar |
229		-| Lakehouse-Pfade | Im Notebook, Abschnitt KONFIGURATION (oben) |
230		-
231		----
232		-
233		-## 6. Zuständigkeiten
234		-
235		-| Bereich | Zuständig |
236		-|---|---|
237		-| Fachliche Transformationsregeln | BMD-Team |
238		-| Fabric Pipeline & Notebook | IT / Patrick Sonderegger |
239		-| Fileserver & Gateway | IT-Infrastruktur |
240		-| Monitoring & Fehleranalyse | IT / Patrick Sonderegger |
241		-
242		----
243		-
244		-## 7. Änderungshistorie
245		-
246		-| Version | Datum | Änderung | Autor |
247		-|---|---|---|---|
248		-| 1.0 | 2026-05-22 | Erstversion | Patrick Sonderegger |
249		-