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.
Das ERnP bietet eine HTTP REST API welche XML und JSON als Datenformat unterstützt.
Um diese zu nutzen, muss man im BMI-Portal für die jeweilige Umgebung des ERnP berechtigt sein und die passenden Rollen für die jeweilige Operation haben.
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 Ergänzungsregisterverordnung in den jeweils gültigen Fassungen.
Grundsätzlich sollten Abfragen sofern möglich nur sequentiell und nicht parallel abgesetzt werden, um die Last aus ERnP Sicht berechenbar zu halten.
Aufgrund des unverhältnismäßig hohen Administrationsaufwandes individualisierter Testidentitäten in der Produktivumgebung werden grundsätzlich keine Testidentitäten auf User-Wunsch erzeugt.
Es existieren definierte Testidentitäten in allen Betriebsumgebungen, welche in der Datei testdaten.csv im Schnittstellenpaket enthalten sind. Anhand dieser bereitgestellten Identitäten können User alle gängigen lesenden Usecases im Zuge der Implementierung testen.
Achtung: Diese Personen sind nur für lesende Tests gedacht und dürfen unter keinen Umständen geändert werden! Es sollten bei neuen Personen nie ähnliche Namen vergeben werden, damit sich das Testverhalten (z.B. Ergebnislisten bei Suchen) mit diesen Personen nicht unerwartet ändert.
Für Tests von modifizierenden Operationen (Anlage, Änderung, ...) sollten Vorname+Familienname von angelegten Testpersonen folgende Struktur haben XXX<Applikationskennung><WeitereNamensteile> und dürfen nicht den Eindruck erwecken echte Personen zu sein.
XXXZMRGUI Vorname123 und Familiennamen XXXZMRGUI Familienname123 habenInsbesondere technischer Support kann nur gewährleistet werden, wenn bei der Problemmeldung zumindest folgende Daten mitgeteilt werden:
POST https://pvawp.bmi.gv.at/at.gv.bmi.erpsrv-p/srv/rest/beh/person/suchen
Content-Type: application/json
Accept: application/json
Client-Name: MEINE-GUI v1.2.3
Client-Behkz: 111237
{
"begruendung": "test",
"suchoptionen": {
"historisch": "AktuellUndHistorisch",
"formalisiert": true,
"sucheMitNamensteilen": true,
"suchwizard": true,
"zmr": true
},
...
}
Sollten diese Informationen nicht bereitgestellt werden können oder stattdessen lediglich Screenshots von Fehlermeldungen, Code-Auszüge und dergleichen aus den User-eigenen Implementierungen übermittelt werden, kann Support nur sehr eingeschränkt angeboten werden.
Durch Implementierung bzw. Anbindung an die ERnP-Schnittstelle und Partizipation im Portalverbund stimmt die jeweilige Organisationseinheit in fachlicher Hinsicht und Softwareentwickler sowie Softwaretester im entsprechenden Ausmaß, den oben beschriebenen Nutzungsbedingungen zu.
Sollte grobes Zuwiderhandeln in einem Ausmaß festgestellt werden, welches den reibungslosen Betrieb des ERnP und nachgelagerter Systeme entgegensteht, so wird dieser Umstand dem Verantwortlichen für das ERnP zur weiteren geeigneten Veranlassung zur Kenntnis gebracht.
Das ERnP ist ein REST Webservice hinter dem BMI Portal, weshalb Abfragen über den Portalverbund gemacht werden müssen. Weiterführende Informationen.
Für den Zugriff muss man im BMI-Portal für die jeweilige Umgebung des ERnP berechtigt sein und die passenden Rollen für die jeweilige Operation haben.
Nachdem das ERnP über das Portal aufgerufen wird und unterschiedliche Umgebungen und Nutzerkreise bietet, ist die Zusammensetzung der URL sehr dynamisch. Zu beachten ist, dass dort das 3-Zeichen-Kürzel verwendet wird, weshalb das Register dort ERP heißt. Grundsätzlich sieht die URL so aus: [Portal-Domain]/at.gv.bmi.erpsrv-[Umgebung]/srv/rest/[Nutzerkreis]
Das ERnP erfordert als Portalapplikation die typischen PVP Header + Chained PVP Header des Ursprungsusers.
Die Toplevel PVP Header werden normalerweise vom Portal angehängt bei dem sich die Clientapplikation via Client-Zertifikat authentifiziert. Sobald ein Request in diesem Portal ankommt, hängt es automatisch die zum Zertifikat hinterlegten PVP Header der Clientapplikation (wie X-AUTHENTICATE-userId, X-AUTHORIZE-roles, ...) an den Request an und leitet ihn weiter.
Die Chained PVP Header müssen hingegen auf jeden Fall von der Clientapplikation selbst mitgeschickt werden (weil das Portal nicht weiß, wer der Ursprungsuser des jeweiligen Requests war).
Laut Portal Verbund Protokoll ist es wichtig den Ursprungsuser zu erkennen und durch die gesamte Aufrufkette an Applikationen durchzureichen, damit auch die letzte Applikation in der Kette weiß, welcher menschliche User den Request ursprünglich ausgelöst hat.
Daher muss die Clientapplikation (welche das ERnP aufruft) die PVP Daten des Ursprungsusers an das ERnP weiterleiten. Wenn die Clientapplikation selbst hinter dem Portal liegt, sollten die PVP Daten des Ursprungsusers ebenfalls in Form von eingehenden PVP Headern vorliegen welche unverändert an den ERnP Request angehängt werden können. Das jeweilige Portal leitet dann den untersten PVP User in der Chain an das ERnP weiter.
Die Daten des Ursprungsusers sind für das ERnP besonders wichtig, weil damit folgende Dinge gemacht werden:
Das folgende Beispiel bezieht sich nur auf PVP Header. In echten Requests würde man natürlich auch die weiter unten erwähnten ERnP spezifischen Client-Header sowie Accept, Content-Type, ... Header schicken.
Für ein korrektes PVP Chaining müsste die Clientapplikation folgenden PVP Daten des Ursprungsusers einfach 1zu1 als HTTP Header beim ERnP Request mitschicken (die Werte a, b, c, ... sind natürlich nur simple Ersatzwerte für echte PVP Daten eines Users):
X-AUTHENTICATE-participantId: a
X-AUTHENTICATE-gvOuDomain: b
X-AUTHENTICATE-mail: c
X-AUTHENTICATE-userId: d
X-AUTHENTICATE-gvGid: e
X-AUTHENTICATE-gvOuId: f
X-AUTHENTICATE-ou: g
X-AUTHENTICATE-cn: h
X-Version: 1.8
Sobald diese Header an das Portal geschickt werden, ermittelt es aufgrund des Client Certificates (welches ebenfalls geschickt werden muss) die PVP Daten und Rollen der Clientapplikation (in diesem Bsp sind es nur Dummy-Daten) und leitet den Request mit angepassten Headern ans ERnP weiter.
Im weitergeleiteten Request sind die PVP Daten der Clientapplikation als Toplevel PVP Daten ersichtlich und die Daten des Originalusers stehen als PVP Chain im Request (erkennbar am X-01- Prefix).
Das ERnP kennt so den Ursprungsuser und kann diesen protokollieren bzw an das ZMR weiterleiten:
X-AUTHENTICATE-participantId: AT:B:112
X-AUTHENTICATE-cn: XXXAPP Applikationsbenutzer
X-AUTHENTICATE-gvOuId: AT:B:112-000
X-AUTHENTICATE-Ou: OU Appluser
X-AUTHENTICATE-UserID: xxxappy@abc.at
X-AUTHORIZE-roles: ERnP-XYZ-Rolle
X-AUTHENTICATE-gvSecClass: 3
X-Version: 1.8
X-01-AUTHENTICATE-participantId: a
X-01-AUTHENTICATE-gvOuDomain: b
X-01-AUTHENTICATE-mail: c
X-01-AUTHENTICATE-userId: d
X-01-AUTHENTICATE-gvGid: e
X-01-AUTHENTICATE-gvOuId: f
X-01-AUTHENTICATE-ou: g
X-01-AUTHENTICATE-cn: h
Im Folgenden wird die Schnittstelle beschrieben, sodass ein Zugriff mithilfe eines beliebigen HTTP Clients implementiert werden kann.
Während hier allgemeine Konzepte beschrieben werden, kann ein Schnittstellenpaket für den jeweiligen Nutzerkreis angefordert werden, welches mehr Details und Hilfsmittel für die Implementierung der Client-Applikation liefert.
Grundsätzlich akzeptiert das ERNP UTF-8.
Nachdem darin auch viele unerwünschte Zeichen (z.B. control characters) enthalten sind, gibt es allgemeine Validierungsregeln die für alle Strings der API gelten:
€ erlaubt und folgende Zeichen verboten < > | %_ und ? sind bis auf wenige Spezialfälle verboten* wird von manchen Suchfeldern als Wildcard genutzt und hat daher spezielle Regeln bzw darf meist nicht im ERNP gespeichert werdenDas ERnP unterstützt primär JSON als Datenübertragungsformat, akzeptiert in den meisten UseCases bis auf weiteres aber auch auch XML (wobei der XML Support vermutlich irgendwann auslaufen wird). Der im Schnittstellenpaket enthaltene Java Beispiel-Client kann für beide Übertragungsformate konfiguriert werden.
Die JSON-Struktur ist so weit es geht an die XML-Struktur angelehnt mit folgenden Besonderheiten:
Die Empfehlung ist: bei Requests an das ERnP möglichst strikt sein, Responses aber möglichst tolerant parsen. So ist man zukunftssicher bezüglich neuer ERnP Anpassungen.
Das heißt auch, dass Responses nie gegen das Ernp.xsd Schema validiert werden sollten. Es gibt teilweise sehr alte ERnP-Personen, die sich nicht an alle Regeln halten; trotzdem wollen wir deshalb die für die restlichen 99,99% gültigen Regeln nicht aufweichen (z.B. haben manche alte ERnP Personen keine Begründung, obwohl diese seit Jahren Pflicht wäre). Außerdem würde eine Schemavalidierung fehlschlagen sofern in ERnP Responses neue Felder eingefügt werden, selbst wenn der eigene Client diese gar nicht benötigt.
Auch im Rahmen der Meldegesetznovelle gab es Fälle die für eine tolerante Responseverarbeitung sprechen (der Beispielclient Client setzt diese Empfehlungen um):
Im ERnP gibt es einige enumerations, jedoch hat sich am Beispiel des Geschlechts gezeigt, dass sie manchmal unerwartet geändert bzw erweitert werden müssen.
Deshalb wurden alle enumerations im xsd stattdessen als union aus der jeweiligen enum und string abgebildet; das entspricht einer erweiterbaren enum (= ein String mit den derzeit bekannten Ausprägungen).
Echte enumerations werden nur genutzt, wenn sie ausschließlich eingehende Daten betreffen (wenn eine enum niemals vom ERnP returniert wird, kann es auch keine Probleme mit der Rückwärtskompatibilität geben).
Für den Beispielclient bedeutet das, dass statt enums Strings in die Klassen generiert werden und die Verwendung dadurch leider etwas unbequemer wird. Allerdings bieten wir für alle enumerations eine Java enum Klasse an (z.B. Geschlecht.java) mit der man auf die derzeit bekannten Werte über die .value() Methode zugreifen kann.
ACHTUNG: Nutzt man diese Hilfsklassen z.B. via Geschlecht.fromValue(personendaten.getGeschlecht()) ist unbedingt erforderlich den Aufruf in ein try/catch zu packen und die Exception (welche geworfen wird, wenn kein bekannter enum Wert gefunden wird) entsprechend zu behandeln (z.B. loggen, dass ein unerwarteter Wert vom ERnP zurückgekommen ist und null setzen). Nur dann funktioniert das eigene Service auch problemlos mit neuen enum-Werten.
Falls man die enum Werte nur anzeigt, empfiehlt es sich die Hilfsklassen nicht zu nutzen, dann funktioniert die Anzeige auch für zukünftig neue Werte automatisch.
Neben den zuvor erwähnten PVP HTTP Headern für die Token-Chain, müssen bei jedem Request folgende 2 HTTP Header mitgeschickt werden:
Zusätzlich können folgende 2 Header geschickt werden, um mögliche Fehleranalysen zu vereinfachen:
Falls die ERNP Client-Applikation TPA Logs schreibt und somit bereits eine WFLID erzeugt hat, welche vom ERnP für TPA Logs weiterverwendet werden soll, kann diese über den Header TPA-WFLID übergeben werden. Der Wert muss das Pattern [a-zA-Z0-9\-]{1,64} erfüllen und wird, falls vorhanden, für ERnP TPA Logs gesetzt. Falls der Header fehlt, erzeugt das ERnP für TPA Logs selbstständig passende UUIDs als WFLID.
Achtung: Alle Header Values dürfen nur US-ASCII Zeichen enthalten (keine Umlaute etc).
Der Response liefert einige nützliche ERnP-spezifische HTTP Header:
Das ERnP liefert passende HTTP Statuscodes aus, d.h. 200-299 wenn alles OK ist, 400-499 für Client Fehler und 500-599 für Serverfehler.
Ruft man z.B. eine nicht existierende URL auf bekommt man einen "404 Not Found" vom ERnP.
Hat das ERnP weitere Informationen über den Fehler (z.B. bei Validierungsfehler was genau schiefgegangen ist), so steht diese im Response (siehe Beispiel weiter unten).
Das ERnP erzeugt für alle Personen-Anpassungen ein technisches Protokoll und für die meisten Operationen auch weiterhin historisch gültige Datensätze.
Für Schnittstellennutzer ist die Historie in erster Linie relevant, weil dadurch Personen auch mit vorherigen Daten (wie z.B. alten Familiennamen) gefunden werden können.
Ein konkretes Beispiel einer historisierten Änderung wäre eine Person mit dem Familiennamen Müller, welcher anschließend (z.B. aufgrund einer Eheschließung) auf Hofer geändert wurde.
Nach der Änderung kann, sofern die Suchoption SucheHistorisch z.B. den Wert AktuellUndHistorisch hat, die Person sowohl mit dem Familiennamen Müller als auch mit dem Familiennamen Hofer gefunden werden, obwohl die Person aktuell nur mehr Hofer heißt.
Im Gegensatz zur erwähnten Ändern-Operation bietet das ERnP auch die Option Korrigieren, welche zwar ebenfalls die Daten wie gewünscht anpasst, jedoch keine Historie erzeugt. Korrekturen werden typischerweise nur gemacht, wenn die vorherige Eingabe z.B. einen Tippfehler hatte. Hat man unabsichtlich Müler angelegt, wollte aber Müller schreiben, korrigiert man den Eintrag, sodass nach der Korrektur die Person mit dem vorherigen Familiennamen Müler nicht mehr gefunden werden kann.
Achtung: eine Korrektur darf nur von jener Behörde durchführt werden, die den zu korrigierenden Datensatz zuletzt bearbeitet bzw. angelegt hat.
Beendigungsoperationen historisieren ebenfalls Datensätze. Falls gewünscht ist auch beendete Personen zu finden, so kann wie zuvor erwähnt die Option SucheHistorisch mit dem Wert AktuellUndHistorisch genutzt werden.
Das zuvor erwähnte Schnittstellenpaket besteht aus folgenden Teilen:
Die im Schnittstellenpaket enthaltene Datei Nutzerkreis-XYZ.html enthält erweiterte Dokumentation und Beispiele für diesen Nutzerkreis.
Die Struktur der Beispiele ist beim Request immer HTTP Operation (z.B. POST), die zu verwendende URL und der HTTP Request/Response Inhalt (=Payload). Beim Response steht der HTTP Response Status und ebenfalls der Payload.
Beim 1. Beispiel stehen außerdem die HTTP Header für Request+Response. Nachdem diese überall deckungsgleich sind, wurden sie bei den weiteren Beispielen weggelassen.
Außerdem gibt es einen Einleitungstext der den genauen Ablauf der Operation und der Objekte beschreibt (z.B. welche Metadatenfelder gibt es, was muss ich alles in Änderungsblöcken schicken, um nicht unabsichtlich Inhalte zu löschen, etc).
Die OpenAPI Specification ist ein Standard um HTTP REST APIs zu beschreiben (grob vergleichbar mit einem WSDL für SOAP APIs).
Falls Sie im Portal entsprechend berechtigt sind, kann für das ERnP eine aktuelle OpenAPI Spezifikation mit HTTP GET auf [Portal-Domain]/at.gv.bmi.erpsrv-[Umgebung]/srv/rest/[Nutzerkreis]/openapi/openapi.json abgerufen werden.
Aus diesem File kann man auch direkt Client Code generiert werden wie z.B. unter https://swagger.io/tools/swagger-codegen/ oder https://github.com/openapitools/openapi-generator beschrieben wird.
Alternativ dazu, kann man auch die XSD Files nutzen, um z.B. in Java mit JAXB die HTTP Payload Objekte zu generieren. Diese schickt man dann mit einem beliebigen HTTP Client and die jeweilige URL.
Das Schnittstellenpaket enthält das Verzeichnis Beispielclient welches 2 Subdirs hat:
Achtung: Vor der Verwendung müssen unbedingt die nötigen Anpassungen wie Portal-ClientCert und ERnP Client HTTP Header vorgenommen werden!
Der Beispielclient dient in erster Linie als Implementierungshilfe und zum Absetzen erster Testrequests, jedoch gibt es für den Client keinen Changelog, Support oder Garantien irgendeiner Art!
Wird z.B. ein neues optionales Suchfeld in die ERnP API aufgenommen (was aus API-Sicht rückwärtskompatibel ist), können sich die generierten Java Klassen des Beispielclients durch das neue Feld im Konstruktor rückwärtsinkompatibel ändern. Das muss man bedenken, wenn man auf eine neue Version des Beispielclients wechselt (oder man bleibt bei rückwärtskompatiblen API Änderungen bei der alten Beispielclient Version, weil die alten Requests weiterhin funktionieren).
Wenn man damit leben kann, spricht nichts dagegen den Client in Teilen oder als Ganzes auch produktiv einzusetzen.
Sinnvolle Nutzungsvarianten des Beispielcodes sind:
Früher hat der Beispielclient den Apache HttpClient (gemeinsam mit einer BMI-Hilfslibrary) und zugehörige jar Files ausgeliefert.
Nachdem dadurch das Schnittstellenpaket unnötig groß wurde und manche Nutzer Probleme wegen strikter Firewalls/Virenscanner berichtet haben, werden inzwischen nur noch simple Java Files ausgeliefert die man bei Bedarf anpassen und kompilieren kann.
Um Dependencies zu reduzieren wurde der Apache HttpClient durch HttpURLConnection.java ersetzt und slf4j entfernt.
Außerdem wurden manche Klassen umbenannt oder in andere Packages verschoben, damit sie nicht im selben Package wie generierte Klassen liegen.
Man kann den alten Client falls gewünscht aber in die neue Struktur integrieren, indem man das Interface ErnpReqSender implementiert und dort Requests via Apache HttpClient absendet.
Zu Beachten ist, dass ErnpCallException nicht mehr wie bisher HttpCallExceptionWithResponse extended, wodurch manche catch-Blöcke sich evtl anders verhalten. Um sicherzustellen, dass sich alles wie bisher verhält, sollte man die Programmlogik nach catch(HttpCallException* durchsuchen, weil catches der 3 Exceptions deren Name mit HttpCallException beginnt zukünftig keine ErnpCallException catchen!