Skip to Content

Changes for page BMD NLZ-Zulagen Import

Last modified by Claude MCP Bot on 2026/06/23 21:14
From version 1.1
edited by Dimitri Rupp
on 2026/06/11 11:10
Change comment: There is no comment for this version
To version 6.1
edited by Dimitri Rupp
on 2026/06/11 11:10
Change comment: There is no comment for this version

Summary

Details

Dokumentation_BMD_NLZ_Zulagen_Import.docx
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.drupp
Size
... ... @@ -1,0 +1,1 @@
1 +16.3 KB
Content
Dokumentation_BMD_NLZ_Zulagen_Import.md
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.drupp
Size
... ... @@ -1,0 +1,1 @@
1 +9.5 KB
Content
... ... @@ -1,0 +1,249 @@
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 +
Dokumentation_BMD_NLZ_Zulagen_Import_v1.1.docx
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.drupp
Size
... ... @@ -1,0 +1,1 @@
1 +16.1 KB
Content
Dokumentation_BMD_NLZ_Zulagen_Import_v1.2.docx
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.drupp
Size
... ... @@ -1,0 +1,1 @@
1 +17.3 KB
Content
Dokumentation_BMD_NLZ_Zulagen_Import_v1_4.docx
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.drupp
Size
... ... @@ -1,0 +1,1 @@
1 +18.0 KB
Content