🟢 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.
Bereichsspezifische Personenkennzeichen sind eindeutige Identifier, die eine Person in einem Verwaltungsbereich eindeutig identifizierbar machen. Um eine bPK zu berechnen, wird eine Anfrage an das SZR übermittelt, welches mit den angegebenen Suchdaten eine Suche im ZMR und im ERnP durchführt. Führt diese Suche zu einem eindeutigen Ergebnis, wird aus der ZMR-Zahl, respektive der Ordnungsnummer im ERnP von dieser Person die Stammzahl mittels kryptografischer Verfahren berechnet.
Aus der Stammzahl können dann mittels mathematischer Einwegfunktion bPK für die verschiedenen Verwaltungsbereiche abgeleitet werden. Daraus ergibt sich, dass eine bPK nicht auf eine Person rückführbar ist. Werden verschlüsselte bPK angefordert, werden diese in einem zusätzlichen Schritt mittels des Schlüssels (ist im SZR hinterlegt) des Empfängers der vbPK verschlüsselt, dieser hat bei sich das erforderliche Schlüsselmaterial, um die vbPK wiederum entschlüsseln zu können.
Für die bPK Abfrage ist auf jeden Fall Vorname, Nachname und ein weiteres Kriterium erforderlich.
Eine unverschlüsselte bPK bleibt für eine Person innerhalb eines Verwaltungsbereiches immer gleich und ist immer 28 Zeichen lang. Unverschlüsselte bPK dienen wie bereits erwähnt, der Speicherung und Verwendung bei der ausgestatteten Organisation und sind nicht dafür vorgesehen, an dritte weitergegeben zu werden um sie beispielsweise als „gemeinsamen Identifier“ zu verwenden.
Details über die Berechnung einer bPK können unter folgendem Link nachgelesen werden: Bereichsspezifische Personenkennzeichen (bPK)
Spricht/schreibt man über vbPK, ist es essenziell, den Empfänger der vbPK immer dazu zu nennen. Es hat sich die Schreibweise Ziel-VKZ+Bereich etabliert.
Die Länge einer vbPK ist abhängig vom verwendeten Schlüssel. Nach Stand der Technik, werden im SZR nurmehr neue Schlüssel hinterlegt, welche 4096bit Länge haben, daraus ergeben sich vbPK mit einer Länge von knapp 700 Zeichen. Sofern Schlüsselmaterial bereits länger im SZR gespeichert ist, ist davon auszugehen, dass zum Hinterlegungszeitpunkt der Schlüssel mit einer Länge dem damaligen Stand der Technik entsprechend hinterlegt wurde. Mindestens ist ein Schlüssel jedoch 1024bit lang, was eine vbPK mit einer Länge von knapp 200 Zeichen ergibt. Auf diesen Umstand sollte aus technischer Perspektive frühzeitig Rücksicht genommen werden.
Fragt man z.B. mit folgenden Personendaten:
die bPK BF-FO sowie vbPK BBA-STA+AS ab, bekommt man:
bPK BF-FO (28 Zeichen)
wGZUpYj8rz7XNxVCYtDlN0lK24Y=
vbPK BBA-STA+AS (172 Zeichen):
R4LUrsRoiWqIsMAYDnbsMxo528R3U87Aa80+KcOWHsEphcx3OOXlEaO034RsQBLLJFR+dM1bWhityc/8QBtD59BwXnY0NxFs0go0Uy+cx0GmGNY1lQVg24cu40azxtQ9VAil4Z+EmRLoyjz9ASkDcQxkGY1FukB3maJl3qw6B2M=
Beispiel einer anderen vbpk mit 4096bit Key (684 Zeichen):
wW00S7Biy23G31pE3dDjfQ8sjDdDJ1NgrKTgwQ+tJnLKph/pxKd0xmhxLlN/3qCpivqBwo93cHeL37fIq/rwVQV2q4Th/QziOOF/kcEUbSVEmjon4naXTm8OythtKg1JAs/23dqhpfuLW8P4nhsVQlFGvzGKsFB2FaaJJHk9NeCpoNhfx3L0V+17mJOuR+X0l+1bTyFBeFLbdE69QeCeVLtj5wUPiWW/LqOL62kjOgEp6XdwZsDT+WyUqcx18bpcjG5vOMjH671G5sqK6fVbZxyJY3GHsS3UBLtwn8KPxivKbAZq1PDVCXHqQS7mwJoRo5m18k7kFomNLGVDs0JePXAXhy7+Ewh29PlvzdwNuZr/aMZ/0/L5mzS8v/pOFwBIAj12fGdbNd6dZ7pcTYQLHIatJCJmnHCq/h8hP6MAzmgh/IihZbbkU6u9xxe6skqyR1LGOeDWwTGSUuUp9Om8p8dwGBYv5FQlEGjFx0m8H86w2qgpQLS5uNXUdrSTKHO0TI5vUgg9q7L4Xy3EVMQfWZJkZil+TyhWrEAMQ+tEE+0XDHY1glNhbHMrsLxVvRsrUBmtlRYzOy5+nLFX4MQGBOuelJJqaoT2ospdI0nTG0DYLL3SIdietymzHSz5OiftUI0pCiTqJFasX9AFygzxs0bHQddXrQLcC3oEv7l4H3Y=
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.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 JJJJMMTTTRUE 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. Ungenutzte Spalten können weggelassen werden.
| 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>_MEHRFACHTREFFER.csv
Spalten: wie im Eingabefile + 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.
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>_<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.)
Folgende Tabelle zeigt die möglichen Spaltennamen im Batch und deren Relation zur SZR Onlineschnittstelle.
Die Spalte "Information" ergänzt relevante Informationen zum Feld im Rahmen des Suchablaufs:
| Batch-Feld im .csv | Online-Feld im SZR.wsdl | Beschreibung | Information |
|---|---|---|---|
| ID_BPK_<BEREICH> | Person.Identification.Value+Type | ID der Person | suchbar, 3. Suchkriterium |
| Person.Name.PrefixedDegree | vorangestellte akademische Grade | nur Service, nicht suchbar (nur für Insert) | |
| VORNAME | Person.Name.GivenName | Vorname | suchbar, Pflichtfeld für Suche |
| NACHNAME | Person.Name.FamilyName | Familienname | suchbar, Pflichtfeld für Suche |
| Person.Name.SuffixedDegree | nachgestellte akademische Grade | nur Service, nicht suchbar (nur für Insert) | |
| NAME_VOR_ERSTER_EHE | Person.AlternativeName.FamilyName | Name vor Ehe | suchbar |
| SONSTIGER_NAME | Person.AlternativeName.SonstigerName | Sonstiger Name | nicht suchbar (nur für Insert) |
| GESCHLECHT | Person.Sex | Geschlecht | suchbar, 3. Suchkriterium |
| GEBDATUM | Person.DateOfBirth | Geburtsdatum | suchbar, 3. Suchkriterium auch wenn teilbefüllt |
| Person.PlaceOfBirth | Geburtsort | nur Service, suchbar, 3. Suchkriterium | |
| GEBORT | Person.CountryOfBirth | Geburtsstaat | suchbar, 3. Suchkriterium |
| STAATSANGEHÖRIGKEIT | Person.Nationality | Staatsangehörigkeit | suchbar (ISO3 oder Name), 3. Suchkriterium |
| PLZ | RegularDomicile.PostalCode | Postleitzahl | suchbar, 3. Suchkriterium |
| GEMEINDENAME | RegularDomicile.Municipality | Gemeindename | suchbar, 3. Suchkriterium |
| RegularDomicile.Locality | Ort bzw Ortschaft | nur Service, suchbar, 3. Suchkriterium | |
| ANSCHRIFTSSTAAT | RegularDomicile.StateCode3 | ISO3 Staatencode der Adresse | suchbar |
| RegularDomicile.DeliveryAddress.AddressLine | Adresszusatz | nur Service, nicht suchbar (nur für Insert) | |
| STRASSE | RegularDomicile.DeliveryAddress.StreetName | Straße | suchbar, 3. Suchkriterium |
| HAUSNR | RegularDomicile.DeliveryAddress.BuildingNumber | Hausnummer | suchbar, 3. Suchkriterium |
| RegularDomicile.DeliveryAddress.Unit | Stiege | nur Service, suchbar, 3. Suchkriterium | |
| RegularDomicile.DeliveryAddress.DoorNumber | Tür | nur Service, suchbar, 3. Suchkriterium | |
| DOKUMENTENNR | TravelDocument.DocumentNumber | Dokumentnummer | suchbar, nicht in Mehrfachtreffer Antwort |
| DOKUMENTART | TravelDocument.DocumentType | Dokumentart | suchbar, nicht in Mehrfachtreffer Antwort |
| AUSSTELLUNGSDATUM | TravelDocument.IssueDate | Ausstelldatum | suchbar, nicht in Mehrfachtreffer Antwort |
| AUSSTELLUNGSBEHÖRDE | TravelDocument.IssuingAuthority | Ausstellbehörde | suchbar, nicht in Mehrfachtreffer Antwort |
| AUSSTELLUNGSSTAAT | TravelDocument.IssuingCountry | Ausstellstaat | suchbar, nicht in Mehrfachtreffer Antwort |
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.
Alternativ zum GUI ist eine programmatische Einbringung über HTTP möglich.
"ergebnisVorhanden": true aufweist). Ist er nicht fertig wird Status 404 returniert. Dateien können beliebig oft heruntergeladen werden, solange sie serverseitig verfügbar sind (nach einigen Tagen bzw Wochen werden sie serverseitig entfernt)Daraus ergibt sich im einfachsten Fall folgender Ablauf:
Achtung: Um unnötige Last für das Zielsystem zu vermeiden sollten Sie bitte folgendes beachten:
Für mehr Details gibt es eine OpenAPI Dokumentation der Schnittstelle, welche vom oben erwähnten technischen Ansprechpartner angefragt werden kann.
Request
POST {szrurl}/batch/files/upload/BPK_BMI_123Test.csv
Content-Type: text/csv
KONTAKT=Test
EMAIL=test@test.at
REFERENZ=Ausstattung für ABC
VKZ=BMI
BETRIEBSUMGEBUNG=TEST
BPKBEREICH=T1
VERSCHLÜSSELTEBPK=BMI+T1
TRENNZEICHEN=;
DATUMSFORMAT=JJJJ-MM-TT
MEHRFACHTREFFER=FALSE
LAUFNR;NACHNAME;VORNAME;GEBDATUM;NAME_VOR_ERSTER_EHE;GEBORT;GESCHLECHT;STAATSANGEHÖRIGKEIT;ANSCHRIFTSSTAAT;GEMEINDENAME;PLZ;STRASSE;HAUSNR
1;nachname;vorname;
Response
{
"id": "168777730426905100",
"dateiname": "BPK_BMI_123Test.csv",
"dateigroesse": "354",
"angekommen": "2023-06-26T13:01:44.269+02:00",
"status": "WARTE_AUF_BATCH",
"header": {
"kontakt": "Test",
"email": "test@test.at",
"referenz": "Ausstattung für ABC",
"vkz": "BMI",
"bereiche": [
"T1"
],
"fremdbereiche": [
"BMI+T1"
],
"trennzeichen": ";",
"datumsformat": "JJJJ-MM-TT",
"specialSettings": [
"MEHRFACHTREFFER=FALSE"
]
},
"ergebnisVorhanden": false
}
Request
GET {szrurl}/batch/files?id=168777730426905100
Response
[
{
"id": "168777730426905100",
"dateiname": "BPK_BMI_123Test.csv",
"dateigroesse": "1153",
"angekommen": "2023-06-26T13:01:44.269+02:00",
"statistik": {
"start": "2023-06-26T13:01:53.000+02:00",
"ende": "2023-06-26T13:01:53.712+02:00",
"treffer": 0,
"keinTreffer": 0,
"error": 1,
"content": "KONTAKT=Test\nEMAIL=test@test.at\nREFERENZ=Ausstattung für ABC\nVKZ=BMI\nBETRIEBSUMGEBUNG=TEST\nBPKBEREICH=T1\nVERSCHLÜSSELTEBPK=BMI+T1\nTRENNZEICHEN=;\nDATUMSFORMAT=JJJJ-MM-TT\nMEHRFACHTREFFER=FALSE\n\nBatch-Parameter:\n\nEingabedateiname: 168777730426905100_BPK_BMI_123Test.csv\nAusgabedateiname: 168777730426905100_BPK_BMI_123Test_20230626-130153_*.csv\n\nBatch-Start: 2023-06-26 13:01:53.000\nBatch-Ende: 2023-06-26 13:01:53.712\nBatch-Dauer: 0 Sekunden\n\nAnzahl Datensätze: 1\nÜbersprungen: 0\nVerarbeitet: 1\n\nTreffer: 0 0,00%\nKeine Treffer: 0 0,00%\nNicht eindeutig: 0 0,00%\nFehler: 1 100,00%"
},
"status": "ZUR_ABHOLUNG",
"header": {
"kontakt": "Test",
"email": "test@test.at",
"referenz": "Ausstattung für ABC",
"vkz": "BMI",
"bereiche": [
"T1"
],
"fremdbereiche": [
"BMI+T1"
],
"trennzeichen": ";",
"datumsformat": "JJJJ-MM-TT",
"specialSettings": [
"MEHRFACHTREFFER=FALSE"
]
},
"ergebnisVorhanden": true
}
]
Request
GET {szrurl}/batch/files/168777730426905100/content
Accept: application/zip
Response
Würde man wie oben erwähnt jetzt nochmal den Status abfragen bekommt man ein leeres Ergebnis weil die Datei mit dem Zip-Download erledigt und damit historisch ist. Man kann aber historische Daten inkludieren
GET {szrurl}/batch/files?id=168777730426905100&inklHistorische=true
dann bekommt man auch jetzt noch den Verarbeitungsstatus des Batchlaufs. Im Gegensatz zu Vorher sieht man dass der abgeholt Wert und der Status entsprechend geändert wurden
[
{
"id": "168777730426905100",
"dateiname": "BPK_BMI_123Test.csv",
"dateigroesse": "1153",
"angekommen": "2023-06-26T13:01:44.269+02:00",
"abgeholt": "2023-06-26T13:15:52.241+02:00",
"statistik": {
"start": "2023-06-26T13:01:53.000+02:00",
"ende": "2023-06-26T13:01:53.712+02:00",
"treffer": 0,
"keinTreffer": 0,
"error": 1,
"content": "KONTAKT=Test\nEMAIL=test@test.at\nREFERENZ=Ausstattung für ABC\nVKZ=BMI\nBETRIEBSUMGEBUNG=TEST\nBPKBEREICH=T1\nVERSCHLÜSSELTEBPK=BMI+T1\nTRENNZEICHEN=;\nDATUMSFORMAT=JJJJ-MM-TT\nMEHRFACHTREFFER=FALSE\n\nBatch-Parameter:\n\nEingabedateiname: 168777730426905100_BPK_BMI_123Test.csv\nAusgabedateiname: 168777730426905100_BPK_BMI_123Test_20230626-130153_*.csv\n\nBatch-Start: 2023-06-26 13:01:53.000\nBatch-Ende: 2023-06-26 13:01:53.712\nBatch-Dauer: 0 Sekunden\n\nAnzahl Datensätze: 1\nÜbersprungen: 0\nVerarbeitet: 1\n\nTreffer: 0 0,00%\nKeine Treffer: 0 0,00%\nNicht eindeutig: 0 0,00%\nFehler: 1 100,00%"
},
"status": "WURDE_ABGEHOLT",
"header": {
"kontakt": "Test",
"email": "test@test.at",
"referenz": "Ausstattung für ABC",
"vkz": "BMI",
"bereiche": [
"T1"
],
"fremdbereiche": [
"BMI+T1"
],
"trennzeichen": ";",
"datumsformat": "JJJJ-MM-TT",
"specialSettings": [
"MEHRFACHTREFFER=FALSE"
]
},
"ergebnisVorhanden": true
}
]
Request
POST {szrurl}/batch/files/upload/BPK_BMI_123Test.csv
Content-Type: text/csv
KONTAKT=Test
EMAIL=test@test.at
REFERENZ=Ausstattung für ABC
VKZ=BMI
BETRIEBSUMGEBUNG=PROD
BPKBEREICH=T1
VERSCHLÜSSELTEBPK=BMI+T1
TRENNZEICHEN=;
DATUMSFORMAT=JJJJ-MM-TT
MEHRFACHTREFFER=FALSE
LAUFNR;FAMILIENNAME;VORNAME;GEBDATUM;NAME_VOR_ERSTER_EHE;GEBORT;GESCHLECHT;STAATSANGEHÖRIGKEIT;ANSCHRIFTSSTAAT;GEMEINDENAME;PLZ;STRASSE;HAUSNR
1;nachname;vorname;01.02.2000
Response
{
"criticalErrors": [],
"headerErrors": [
"BETRIEBSUMGEBUNG=PROD muss in der aktuellen Betriebsumgebung (Testumgebung) den Wert TEST haben",
"Unbekannte Spalte im Zeilenheader: FAMILIENNAME",
"Fehlende Spalte im Zeilenheader: NACHNAME"
],
"contentErrors": [
"Leeres oder fehlendes Feld NACHNAME bei Person: 1;nachname;vorname;01.02.2000",
"GEBDATUM im falschen Datums-Format: 1;nachname;vorname;01.02.2000"
]
}