ein Service der IV/DDS-11 ()info
ein Service der IV/DDS-11 ()info
🟢 TLP:GREEN Das Dokument darf innerhalb der Organisation und an Partner frei weitergegeben werden, aber nicht veröffentlicht werden.
Erzeugt am: . Die jeweils aktuellste Fassung ist hier verfügbar.
Dieses Dokument beschreibt, die Konfigurationsmöglichkeiten und Funktionsweise der Batchverarbeitung des Stammzahlenregister (SZR).
Das SZR ist als Front-End zum Zentralen Melderegister (ZMR) und Ergänzungsregister natürlicher Personen (ERnP) aufgebaut, um bereichsspezifische Personenkennzeichen (bPK) berechnen zu können.
Es erfolgt keine Speicherung personenbezogener Daten in der Anwendung, sondern es wird mit personenbezogenen Daten lediglich eine Suche im ZMR und ERnP gemacht. Wenn diese Suche ein eindeutiges Ergebnis liefert, so wird die Stammzahl der gefundenen Identität anhand ihrer Basiszahl im ZMR oder ERnP berechnet und daraus ein oder mehrere bPKs abgeleitet.
Im Detail wird in diesem Dokument das erforderliche Format der Eingabe-Dateien und das Format, sowie der Inhalt der Ausgabedateien beschrieben. Die Batchverarbeitung dient grundsätzlich für die erstmalige Ausstattung der Datensätze einer Organisation mit bPK.
Stammzahlenregisterbehörde
Zuständigkeiten:
Bundesministerium für Inneres
Sektion IV – IT und Service
Direktion für Digitale Services
Abteilung 11 – IKT Anwendungen
Referat b – Verwaltungsanwendungen
Zuständigkeiten:
Als Rechtsgrundlage dient das E-Government-Gesetz in Verbindung mit der Stammzahlenregisterbehördenverordnung sowie der Ergänzungsregisterverordnung in den jeweils gültigen Fassungen.
Voraussetzung für die technische Freischaltung des Webservices in einer bestimmten Rolle ist ein genehmigter Antrag auf Ausstattung einer Datenverarbeitung mit bPK.
Ein Antrag auf bPK-Ausstattung kann jederzeit online erfolgen. Dazu muss man sich mittels eID unter folgendem Link einloggen: BürgerPortal.
Sollte kein eID bzw. kein Äquivalent zur Verfügung stehen, kann ein Antrag ebenso per Mail an die Stammzahlenregisterbehörde übermittelt werden.
Dazu sind entsprechende Formulare für bPK und vbPK unter folgendem Link vorhanden: Formulare Stammzahlenregisterbehoerde.
Ausstattungsvorhaben müssen dem BMI mitgeteilt werden und werden in weiterer Folge mit Technik und Anforderer koordiniert.
Anforderungen für Fileverarbeitungen werden so rasch wie möglich umgesetzt. Das Ergebnis wird der genannten bzw. zuständigen Kontaktperson meist innerhalb von 1-3 Werktagen – gegebenenfalls auch erst nach mehreren Werktagen bereitgestellt.
Hierbei gilt es noch zu erwähnen, dass sich alle Teilnehmer im eGovernment Umfeld, welche die Fileverarbeitung im SZR in Anspruch nehmen, die gleiche Warteschlange teilen.
Grundsätzlich können gleichzeitig mehrere Files nacheinander hochgeladen und in der Warteschlange eingereiht werden. Prinzipbedingt wird daher darauf hingewiesen, Dateien nur in dem Ausmaß und in der Frequenz hochzuladen, die zur Erfüllung des Zweckes bei der hochladenden Stelle unbedingt erforderlich sind.
Unzulässige Filenamen, korrupte Datensätze oder Falschkonfigurationen, sowie hohes Anfragevolumen für Fileverarbeitungen können die Durchlaufzeit entsprechend erhöhen und müssen bei der Planung in zeitlicher Hinsicht vom Anforderer der Fileverarbeitung berücksichtigt werden. Sind gravierende formelle Fehler in einem File vorhanden, kann das File erst nach entsprechender Korrektur durch die anfordernde Stelle und erneuter Bereitstellung verarbeitet werden.
Teilnehmer mit Berechtigung zum Self-Service können ihre Dateien selbstständig im SZR-GUI hochladen und das Ergebnis wieder herunterladen. Die höchste zulässige Anzahl an Datensätze in einem einzigen File ist auf 100.000 Datensätze beschränkt.
Für Teilnehmer, die Fileverarbeitungen im BMI einbringen (z.B. im Zuge einer Erstausstattung) besteht die Möglichkeit Files mit maximal 1 Million Datensätze in einem einzigen File verarbeiten zu lassen.
Der Austausch der Files mit produktiven Personendaten darf ausschließlich verschlüsselt erfolgen. Das BMI stellt hierfür einen geeigneten Übertragungsdienst samt Kurzanleitung für die User zur Verfügung. Es wird ausdrücklich darauf hingewiesen, dass aus Datenschutzgründen kein Datenaustausch per Mail akzeptiert wird.
Files werden grundsätzlich nach dem First-Come-First-Serve Prinzip verarbeitet. Das SZR verarbeitet gleichzeitig maximal ein File. Urgenzen können aufgrund dieser Tatsache, in der Regel nicht berücksichtigt werden.
Insbesondere technischer Support kann nur gewährleistet werden, wenn bei der Problemmeldung zumindest die gesendeten Anfragedaten und der exakte Anfragezeitpunkt mitgeteilt werden. Sollten diese Informationen nicht bereitgestellt werden können, kann Support nur sehr eingeschränkt angeboten werden. Bei Problemen die nicht direkt die Verarbeitung einer Datei betreffen, ist eine möglichst präzise Fehlerbeschreibung erforderlich, um eine effiziente Fehleranalyse beginnen zu können.
Die Kontaktaufnahme in Support Fällen, ist via Mail an die genannte Ansprechstelle beim technischen Dienstleister vorgesehen.
Durch die Verwendung des bPK-Batchverfahrens stimmt die jeweilige Organisationseinheit in fachlicher Hinsicht den oben beschriebenen Nutzungsbedingungen zu. Sollte grobes Zuwiderhandeln in einem Ausmaß festgestellt werden, welches den reibungslosen Betrieb des SZR und nachgelagerter Systeme entgegensteht, so wird dieser Umstand dem Verantwortlichen für das SZR zur weiteren geeigneten Veranlassung zur Kenntnis gebracht.
Eine Erklärung des bPK Konzept befindet sich in der SZR-Onlineschnittstelle-SOAP Doku.
Die einzige Besonderheit beim BPK Batch ist, dass der Präfix meist weggelassen wird (der Header heißt z.B: BPKBEREICH=SA und nicht BPKBEREICH=urn:publicid:gv.at:cdid+SA)
Die Eingabe-Datei muss im CSV-Format vorliegen und die Dateinamen sollten der nachfolgend beschriebenen Dateinamen-Konvention folgen: BPK_<Verwaltungskennzeichen_Org>_<laufnr>.csv
Verwaltungskennzeichen_Org (bzw. VKZ), ist eine der Organisation zugeordnete eindeutige Nummer und wird beim Filenamen, als auch in den Headerinformationen, zur Unterscheidung herangezogen. Für Organisationen, denen kein VKZ zugeordnet ist, wird im Portalverbund als Verwaltungskennzeichen die Firmenbuchnummer, die Vereinsregisternummer oder die Nummer aus dem Ergänzungsregister sonstiger Betroffener verwendet.laufnr ist ein alphanummerischer Wert und wird durch die Organisation vergeben, Sonderzeichen sind nicht zulässig. Der Wert hat nichts mit der Spalte LAUFNR zu tun.Jede Datei gliedert sich in drei Teile, damit neben den eigentlichen Personendaten auch Informationen über die Verarbeitung der Personen angegeben werden können:
Der gesamte Datei-Inhalt muss die UTF-8 Zeichenkodierung nutzen, damit alle Sonderzeichen wie Umlaute etc. korrekt verarbeitet werden können. Falsch kodierte Zeichen führen in der Regel zu nicht-Treffern oder Fehlern bei der Verarbeitung.
MS Excel speichert CSV Dateien klassischerweise mit Windows-1252 Zeichenkodierung. Um stattdessen UTF-8 zu nutzen, muss im Speichern Dialog explizit CSV UTF-8 gewählt werden. In neueren Excel Versionen ist diese Option verfügbar:
Der Datei-Header besteht aus diversen Verarbeitungsinformationen, welche für die Protokollierung benötigt werden und den Batchlauf konfigurieren.
<VKZ>+<Bereich>; oder | (Semikolon oder Strich)JJJJ-MM-TT oder TT.MM.JJJJ oder JJJJMMTTFALSETRUE oder FALSETRUE ist ausschließlich behördlichen Anwendern vorenthalten.Beispiel Spalten-Header mit Trennzeichen Semikolon: LAUFNR;NACHNAME;VORNAME;GEBDATUM;NAME_VOR_ERSTER_EHE;GEBORT;GESCHLECHT;STAATSANGEHÖRIGKEIT;ANSCHRIFTSSTAAT;GEMEINDENAME;PLZ;STRASSE;HAUSNR
Im Folgenden werden die relevantesten Spalten-Header genauer erklärt bzw. spezifiziert.
| Geschlecht | Abkürzung |
|---|---|
| männlich | M |
| weiblich | W |
| inter | I |
| divers | D |
| offen | O |
| keine Angabe | K |
| unbekannt | U |
<BEREICH> im Header einzusetzen.Im Folgenden werden hilfreiche Informationen zum Suchablauf beschrieben
Bei jeder Eingabe-Person müssen folgende Felder mindestens ausgefüllt sein:
Doppelnamen wie „Karl-Heinz“ gelten als ein Vorname. Mehrfachnamen wie „Karl Heinz“ gelten als zwei Vornamen.
Beispiel: Es gibt im ZMR „Hans“ „Hans Peter“, „Hans-Peter“ und „Hans Peter Josef“
Hier die gefundenen Personen, wenn jeweils der linke Wert gesucht wird:
Im ZMR ist jedoch sehr oft nur der 1. Vorname gespeichert und somit würde die Suche nach mehreren Vornamen in manchen Fällen zu keinem Treffer führen.
Wir empfehlen daher nur mit dem 1. Vornamen zu suchen.
Beim Geburtsdatum besteht die Möglichkeit, nur mit Jahr oder nur mit Jahr und Monat anstelle eines vollständigen Datums zu suchen. Dabei kann der Tag bzw. das Monat ausgelassen oder mit 00 gesetzt werden.
In den seltenen Fällen wo eine Person ein unvollständiges Geburtsdatum hat welches z.B. in die MEHRFACHTREFFER Datei kommt, wird 00 gesetzt. D.h. eine Person die als Geburtsdatum nur das Jahr 2000 hat, würde beim Datumsformat TT.MM.JJJJ den Wert 00.00.2000 stehen haben.
Es wird festgehalten, dass das Stammzahlenregister ein reines Rechenregister ist. Die Inputdaten werden 1:1 in einer Suche im ZMR und Ergänzungsregister natürlicher Personen zu einem Treffer oder keinem Treffer führen.
Im Gegensatz zur SZR Onlineabfrage, nutzt der Batch die sogenannte Hierarchische Suche. Das heißt Suchkriterien werden nur herangezogen, sofern höherwertige Kriterien noch keinen eindeutigen Treffer erzeugt haben.
Ein Beispiel-Suchablauf wäre:
Daraus ergibt sich die Empfehlung möglichst alle bekannten Suchdaten zu spezifizieren. Falls z.B. die Hausnummer doch nicht passen würde, kommt sie in den allermeisten Fällen bei der Suche sowieso nicht zum Tragen, sofern die vorherigen Kriterien eindeutig genug sind.
KONTAKT=Der Name der Kontaktperson für die Daten + Tel
EMAIL=die Mailadresse der Kontaktperson für Verständigungen
REFERENZ=Ausstattung mit vbPKs gemaess Paragraph 18 ESTG
VKZ=Verwaltungskennzeichen_Org
BPKBEREICH=Verwaltungskennzeichen_Org
VERSCHLÜSSELTEBPK=BMF+SA
DATUMSFORMAT=TT.MM.JJJJ
MEHRFACHTREFFER=FALSE
LAUFNR;NACHNAME;VORNAME;GEBDATUM;NAME_VOR_ERSTER_EHE;GEBORT;GESCHLECHT;STAATSANGEHÖRIGKEIT;ANSCHRIFTSSTAAT;GEMEINDENAME;PLZ;STRASSE;HAUSNR
1;XXXSZR;XXXTEST;02.02.1970;;Baden
2;XXXSZR;XXXTest;02.02.1950;;Wien
3;XXXSZR;XXXTest;01.01.1985;;Wien;;;AUT;Testgemeinde;77;Teststrasse;44
4;XXXSZR;XXXTest;01.01.1985;;Wien;;;AUT;Testgemeinde;77;Testgasse;99
5;XXXSZR;XXXTest;03.03.1990;;Wien;;;AUT;Testgemeinde 09988;;;
6;XXXSZR;XXXTest;02.06.1990;;Wien
7;XXXSZR;XXXTest;07.07.1990;;Eisenstadt;;;;;;;
8;XXXSZR;XXXTest;10.10.2000;;Salzburg;;;;;;;
9;XXXSZR;XXXTest ZweiterVn;01.01.1985;;Baden;;;;;;;
Jeder Batchlauf erzeugt mehrere unterschiedliche Ausgabedateien, wobei der Name jeder Datei Informationen über deren Inhalt liefert.
Die Dateinamen der Ausgabe-Dateien leiten sich vom Dateinamen der Eingabe-Datei ab. Dieser wird übernommen und um die Verarbeitungszeit und die Bezeichnung des Inhaltes der Datei ergänzt.
Als Ergebnisdatei wird eine ZIP-Datei erstellt. Diese hat folgenden Dateinamen <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>.zip
Die Eingabedatei wie sie tatsächlich verarbeitet wurde, wird im Ergebnis-ZIP retour geliefert und dient der Nachvollziehbarkeit und Dokumentation.
Zusätzlich können folgende Dateien enthalten sein, wobei diese nur bei Bedarf erzeugt werden. Würde eine Datei keine Person enthalten, fehlt sie. Gab es z.B. keine Fehler, wird auch keine ERROR-Datei generiert.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_ERROR.csv
Spalten: wie im Eingabefile + neue Spalte ZUSATZINFO mit Erklärung des Fehlers
Sind alle jene Einträge in der Inputdatei, die zu einem fachlichen Error bei der Verarbeitung geführt haben. Ein fachlicher Error ist z.B. ein fehlendes Geburtsdatum, Geburtsdatum vor dem 1.1.1850, ein unbekanntes Geschlecht (nicht lt. Tabelle).
Es besteht die Möglichkeit, das ERROR direkt zu bearbeiten (zum Beispiel Fehler korrigieren oder mehr Daten zur Verfügung stellen) und anschließend erneut hochzuladen. Der bPK-Batch ignoriert die Spalte ZUSATZINFO falls vorhanden.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_KEINTREFFER.csv
Spalten: wie im Eingabefile
Das sind alle jene Einträge der Inputdatei, welche zu keinem Treffer geführt haben. Die Gründe für einen nicht-Treffer wurden im vorigen Abschnitt bereits näher erläutert.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_NICHT_EINDEUTIG.csv
Spalten: wie im Eingabefile
Dieses File bekommen User für all jene Einträge der Inputdatei, die zu einem nicht eindeutigen Ergebnis geführt haben, sofern der Header MEHRFACHTREFFER=FALSE gesetzt wurde. (für privatrechtliche Organisationen verpflichtend)
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_MEHRFACHTREFFER.csv
Spalten: wie im Eingabefile + REGISTER (Register wo Person ist: ZMR oder ERnP) + Registerdaten der Mehrfachtreffer
Das sind alle jene Einträge der Inputdatei, welche zu einem Mehrfachtreffer mit höchstens drei Treffern geführt haben.
Die Mehrfachtreffer werden nur behördlichen Usern inklusive der Personendaten ausgewiesen, sofern der Header MEHRFACHTREFFER=TRUE lautet. Für alle nicht öffentlichen Organisationen (Header MEHRFACHTREFFER=FALSE verpflichtend), wird eine Datei …NICHT_EINDEUTIG.csv generiert.
Die Datei enthält zunächst alle spezifizierten Suchspalten der Eingabedatei, dann eine Spalte für das Register in dem die Person gefunden wurde und danach erneut alle Suchspalten in gleicher Reihenfolge wie in der Eingabedatei mit REG- Prefix. Falls nicht alle Suchspalten spezifiziert wurden, folgen anschließend die übrigen Spalten (die lt. dieser Tabelle Daten liefern sollten) in einer fixen Reihenfolge.
Diese komplexe Spalten-Reihenfolge wird derzeit aus Rückwärtskompatibilität eingehalten, jedoch müssen BPK Batch Nutzer damit rechnen, dass sich die Reihenfolge zukünftig womöglich vereinfachen wird (z.B. auf eine fix vorgegebene Reihenfolge aller REG-Spalten)
Achtung: Wie erwähnt werden nicht alle Personendaten bei Mehrfachtreffern returniert (siehe Tabelle). Falls die Eingabedatei solche Spalten enthält (z.B. SONSTIGER_NAME), gibt es an der entsprechenden Stelle in der MEHRFACHTREFFER Datei zwar eine Spalte REG-SONSTIGER_NAME (damit die Suchspalten-Reihenfolge 1zu1 wiederholt wird), diese enthält jedoch niemals Daten. Falls die Eingabedatei aber keine SONSTIGER_NAME Spalte enthält, gibt es auch keine REG-SONSTIGER_NAME Spalte.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_<BPK-Bereich>.csv
Spalten: wie im Eingabefile + REGISTER (Register wo Person ist: ZMR oder ERnP) + Spalte BPK_BEREICH= welche die bPK enthält + ZUSATZINFO (derzeit ungenutzt)
Das sind alle jene Einträge der Inputdatei, die zu einem eindeutigen Treffer bei der Abfrage der bPK des angegebenen Bereichs geführt haben. Diese ist in einer eigenen Spalte den Inputdaten angehängt.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_VERSCHL_BPK.csv
Spalten: wie im Eingabefile + REGISTER (Register wo Person ist: ZMR oder ERnP) + pro vbPK eine weitere Spalte wie zb "VBPK_FÜR=BMF+SA" + ZUSATZINFO (derzeit ungenutzt)
Das sind alle jene Einträge der Inputdatei, die zu einem eindeutigen Treffer bei der Abfrage der verschlüsselten bPK geführt haben. Jede vbPK wird in einer eigenen Spalte den Inputdaten angehängt.
Dateiname: <EINGABEDATEINAME>_<JJJJMMTT-HHMMSS>_STATISTIK.csv
Die Statistik Datei enthält Informationen über Start- und Endzeitpunkt der Verarbeitung, sowie die Anzahl der verarbeiteten Datensätze inkl. der Trefferquoten (Anzahl Treffer, Anzahl Mehrfachtreffer, etc.)
Die SZR-Onlineschnittstelle-SOAP Doku beschreibt wie sich die BPK Batch-Felder im Vergleich zu den SZR Online-Feldern verhalten und welche Suchkriterien mindestens vorhanden sein müssen (ist äquivalent zur SZR Online Abfrage).
In diesem Abschnitt wird die Website des Self-Service GUI als ein möglicher Weg der Batchfile-Einbringung beschrieben.
Ist der Zugang zum SZR gegeben und man befindet sich in der GUI des Self-Service Verfahrens wird beim erstmaligen Login eines Users nochmal nach den Daten des Users verlangt und danach steht die GUI vollumfänglich zur Verfügung. Bei weiteren Logins ist die Welcome Seite immer die Startseite. Sollten sich Userdaten ändern, können diese hier editiert werden.
Die Angaben zum User werden im SZR hinterlegt, um aus Sicht des SZR Betriebes Kontaktmöglichkeiten zu den Usern zu haben, sollten Änderungen oder sonstige relevante Informationen kommuniziert werden müssen.
Auf der Seite Information gibt es einen kurzen Text, der den bPK-Batch beschreibt und wie der Ablauf einer Ausstattung üblicherweise/idealerweise erfolgt.
Ebenso auf dieser Seite befindet sich der sogenannte Header-Builder welcher beim Aufbau des korrekten Datei-Headers hilft.
Der Header-Builder hat diverse relevante Eingabefelder, die befüllt werden können, wobei der entsprechende Headerblock, wie er im CSV-File sein muss, dynamisch an die Eingaben angepasst wird. Es besteht nun die die Möglichkeit, den generierten Header in der Ausgabe zu kopieren und in eine eigene bestehende Datei einzufügen oder es besteht ebenso die Möglichkeit sich eine Beispieldatei erzeugen zu lassen.
Aus technischen Gründen kann es sein, dass das VKZ bzw. die Stammzahl nicht aus den Portalverbundprotokoll-Daten (diese werden vom aufrufenden Portal hinzugefügt) extrahiert werden können. In diesem Fall muss das VKZ bzw. die Stammzahl im Feld "Ihr VKZ" ergänzt werden.
Die Upload Maske bietet einen Datei-Dialog, um eine Datei für den Upload vom Gerät des Users auszuwählen und einen Button um das ausgewählt File hochzuladen. Während des Uploads wird der Upload-Fortschritt angezeigt.
Beim Upload des Files wird der Inhalt der Datei rudimentär validiert. Speziell der Headerblock und der Spaltenheader werden auf Eingabe- und Formatierungsfehler geprüft. Es werden zwecks Stichprobe auch die ersten 500 Personen einer Datei auf etwaige Fehler geprüft. (zum Beispiel Diskrepanz zwischen Spalten Anzahl im Spaltenheader und in den Daten, Encoding Fehler, etc.) Wenn die Header und 20% der geprüften Datensätze in Ordnung sind, wird das File automatisch zur Verarbeitung freigegeben und in die Warteschlange des bPK-Batch eingereiht. Sollte es hier zu Fehlern kommen, werden die Fehler in der „Server Response“ Textbox angezeigt. In Problemfällen ist diese Fehlermeldung bekannt zu geben.
Files werden auf dieser Seite in einer Liste dargestellt mit dem jeweiligen Status (Warten auf Verarbeitung, Batch läuft, Fertig verarbeitet, Fehler)
Der User hat hier auch die Möglichkeit eine noch nicht gestartete Verarbeitung mittels Button abzubrechen oder fertige Verarbeitungen mittels Button herunterzuladen.
Ergebnisse werden im zuvor beschriebenen zip-Format ausgeliefert und bereits abgeholte Einträge verbleiben bis zum nächsten Refresh der Seite in dieser Ansicht. Anschließend können vergangene Batchergebnisse bei Bedarf noch eine Zeit lang über "Upload Log" heruntergeladen werden.
Die Seite Upload Log bietet eine Übersicht aller bisherigen und aktuellen Uploads eines Users. Sollten Probleme auftreten, kann in dieser Ansicht die ID des Batchs eingesehen werden, welche bei Support Anfragen anzugeben ist.
Pro Batch gibt es für abgeschlossene Verarbeitungen eine Statistik, die angezeigt werden kann. Die Anzeige erfolgt in Form eines Popups nach Klick auf „anzeigen“. Die Inhalte dieser Statistik sind ebenso dem Ergebnis einer Verarbeitung beigefügt.
Weiters sind in dieser Übersicht zusätzliche Metadaten zu den Verarbeitungen einsehbar, wie etwa Upload- und Downloadzeitpunk, welche bPK angefordert wurden, etc.