Postkorb-Nachricht an das Bayernportal Version 2.03

Transkript

1 Postkorb-Nachricht an das Bayernportal Version 2.03 Stand: März 2015 opyright Diese Unterlage der Anstalt für Kommunale Datenverarbeitung in Bayern ist urheberrechtlich geschützt. Nachdruck bzw. Vervielfältigung, auch in Auszügen, sind nur mit schriftlicher Einwilligung bzw. im Rahmen der Verträge mit der AKDB gestattet. Die AKDB haftet nicht für irrtümliche Angaben oder Druckfehler. Änderungen bleiben vorbehalten.

2 Änderungsprotokoll Datum Version Änderungsgrund Autor Ersterstellung Stolz Änderung 3.1 Brandt Änderung Titel / Überarbeitung / Ergänzung der Variante externer Web-Dienst ohne OK.KOMM Stolz Überarbeitung in folgenden Kapiteln: 1, 2, 4.1.1, 4.1.2, 4.2.5, 5, 6, 7 Brandt/Stolz Korrektur in der OK.KOMM-Nachricht Stolz Korrektur Beispielnachricht Kapitel Brandt Inhaltsverzeichnis: 1 Einleitung 3 2 Prinzipieller Ablauf Topologie SOAP-Web-Service 4 3 Adressierung 4 4 Das Format der Postkorb-Nachricht Nachrichtenaufbau informativ Nachrichten-Kopf Nachrichten-Inhalt XML-Nachrichtenschema für eine BSP-Nachricht BSP-Nachricht BSP-Nachrichtenkopf Absender und Empfänger BSP-Nachrichteninhalt Die Schlüsseltabellen Beispielnachricht 12 5 OK.KOMM-Nachrichtenformat Beispiel für ein OK.KOMM-AKDB-XML 14 6 Web-Service-Schnittstelle 15 7 Referenzen 17 opyright Diese Unterlage der Anstalt für Kommunale Datenverarbeitung in Bayern ist urheberrechtlich geschützt. Nachdruck bzw. Vervielfältigung, auch in Auszügen, sind nur mit schriftlicher Einwilligung bzw. im Rahmen der Verträge mit der AKDB gestattet. Die AKDB haftet nicht für irrtümliche Angaben oder Druckfehler. Änderungen bleiben vorbehalten.

3 1 Einleitung Im vorliegenden Dokument wird die Schnittstelle für den Nachrichtenversand an den Postkorb im Bayernportal beschrieben. 2 Prinzipieller Ablauf 2.1 Topologie Für den Transport der Postkorbnachrichten werden im Produktivbetrieb zwei Transportwege vorgesehen. Bevorzugte Variante (OK.KOMM zu OK.KOMM): Der externe Web-Dienst als Absender und das Bayernportal als Empfänger sind beide mit der AKDB-Transportplattform OK.KOMM ausgerüstet. In diesem Fall ist der Nachrichtentransportweg zwischen den externen Web-Dienst und dem Bayernportal automatisch gegen unberechtigte Zugriffe abgesichert. Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 3 von 17

4 Alternative Variante (Bayerisches Behördennetz): Sollte der externe Web-Dienst selbst über kein OK.KOMM verfügen, erfolgt der Nachrichtentransport zwischen dem Web-Dienst und dem zentralen OK.KOMM per HTTPS- Soap ausschließlich über das bayerische Behördennetz. 2.2 SOAP-Web-Service Die Übergabe der Postkorbnachrichten erfolgt über eine synchrone SOAP-Webservice- Schnittstelle per HTTPS (siehe 6). Nach erfolgreichem Empfang und erfolgreicher Übernahme liefert das Bayernportal einen positiven Bestätigungscode ( OK ) an den Aufrufer zurück. Im Fehlerfall wird eine SOAP-Exception ausgelöst. 3 Adressierung Die Postkorb-Nachricht im Umfeld des Bayernportals ist eine spezielle Form der allgemeinen, universellen Nachricht im Bürgerserviceportal. Nachrichten im Bürgerserviceportal können von oder zum Bürgerserviceportal übertragen werden; Postkorb- Nachrichten im Umfeld des Bayernportals kennen nur eine Richtung, von externen Web- Dienst zum Bayernportal. Obwohl die allgemeine Nachricht im Bürgerserviceportal unterschiedliche Adressierungsmethoden vorsieht, ist für die Postkorb-Nachricht zum Bayernportal nur die Adressierung über den sogenannten Postkorb-Handle vorgesehen. Der Postkorb-Handle identifiziert den Postkorb eines Bürgers eindeutig. Jeder registrierte Bürger hat ein einmaliges und eindeutiges Postkorb-Handle, welches sich auf seinen persönlichen Postkorb bezieht. Ein einmal vergebenes Postkorb-Handle wird nicht weitergegeben. Beispiel eines Postkorb-Handles: S0tU_AL6FOnJm9IfIKkdq_1NqqWPLYOl1llptHbbes4 Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 4 von 17

5 4 Das Format der Postkorb-Nachricht 4.1 Nachrichtenaufbau informativ Eine Nachricht besteht aus einem Nachrichtenkopf und dem Nachrichteninhalt: - Der Nachrichtenkopf enthält technische Informationen sowie Absender und Empfänger- Daten. - Der Nachrichteninhalt enthält die eigentliche Nachricht samt Anhängen, sowie zusätzliche fachliche Attribute zur Nachricht. Im Folgenden wird das allgemeine Bürgerserviceportal-Nachrichtenschema beschrieben. Dieses Schema gilt insbesondere auch für Postkorb-Nachrichten. Die für Postkorb-Nachrichten zwingend erforderlichen Felder sind im Folgenden als Pflichtfelder (***) in Fettdruck gekennzeichnet Nachrichten-Kopf NachrichtenID (***) technisch, beliebig, GUID. Erstellungszeitpunkt (***) Datum, Uhrzeit Absender (***) o Postkorb-ID (Postkorb-Handle) o Verfahren (***) o Dienst (***) (wird als Information in der Postkorb-Ansicht verwendet) o Mandant (***) (wird als Information in der Postkorb-Ansicht verwendet) o AGS (***) o Name o Anschrift o -Adresse o Telefon Empfänger (***) o Postkorb-ID (Postkorb-Handle) (***) o Verfahren o Dienst o Mandant o AGS o Name Antwort Auf / Weiterleitung Zu Hinweis: Die Angaben zur Absender-AGS werden benötigt, falls zu einem späteren Zeitpunkt Informationen auch wieder zurückgeschickt werden sollen. Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 5 von 17

6 4.1.2 Nachrichten-Inhalt Betreff (***) Erläuternder Text Kategorie (Statusinformation, allgemeine Information, Information von der Kommune, ) npa-geschützt (Nachricht darf nur nach npa-authentisierung gelesen werden) Vorgang o VorgangsName o VorgangsId o Status (empfangen, aufgenommen, in Arbeit, Rückfrage, fertig, ) Nachrichtentext (***) o encoding: HTML/ASCII (***) o Text (***) Anhänge ( 0.. n) o Inhalt (base64) (***) (Pflichtfeld nur falls o Filetype (text, html, jpeg, pdf) (***) ein Anhang vorhanden) o Dateiname 4.2 XML-Nachrichtenschema für eine BSP-Nachricht Das XML-Nachrichtenschema ist als XSD-Schema definiert und in der online-dokumentation veröffentlicht BSP-Nachricht Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 6 von 17

7 4.2.2 BSP-Nachrichtenkopf Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 7 von 17

8 4.2.3 Absender und Empfänger Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 8 von 17

9 4.2.4 BSP-Nachrichteninhalt Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 9 von 17

10 4.2.5 Die Schlüsseltabellen Die folgenden Schlüsseltabellen legen die zulässigen Werte für die jeweiligen Schlüsselfelder (z.b. bspereignis im BSP-Nachrichtenkopf) in den Postkorbnachrichten fest. Tabelle Nr. 36 Name Beschreibung Schlüssel AGS Amtlicher Gemeindeschlüssel Wert Tabelle Nr Name Beschreibung Schlüssel BspNachricht Ereignisse Liste der möglichen Ereignisse Wert Nachricht vom oder zum Bürgerserviceportal Tabelle Nr Name Beschreibung Schlüssel KAT_STATUS KAT_INFOBSP KAT_INOKOMMUNE Kategorie Nachrichtenkategorien Wert Statusmeldung Information vom Bürgerservice-Portal Information von der Kommune Tabelle Nr Name Beschreibung Schlüssel ST_ERHALTEN ST_GELESEN VorgangStatus Vorgangsstatus Wert Nachricht wurde erhalten Nachricht wurde gelesen Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 10 von 17

11 ST_IN_ARBEIT ST_FERTIG Nachricht wird bearbeitet Nachricht fertig bearbeitet Tabelle Nr Name Beschreibung Schlüssel text/plain text/html text/rtf text/xml TextEncoding Codierungsvarianten für Freitexte Wert Einfacher ASCII-Text Der Inhalt wird im HTML-Format übermittelt. Der Inhalt wird im RTF-Format übermittelt. Der Inhalt wird im XML-Format übermittelt. Tabelle Nr Name Beschreibung Schlüssel application/pdf application/msword text/plain text/html text/rtf image/jpeg image/gif MIMETypes Codierungsvarianten für MIME-Anhänge Wert Der Inhalt wird im PDF-Format übermittelt. Der Inhalt wird im MSWORD-Format übermittelt. Der Inhalt wird als einfacher Text übermittelt Der Inhalt wird im HTML-Format übermittelt. Der Inhalt wird im RTF-Format übermittelt. Der Inhalt wird im JPEG-Format übermittelt. Der Inhalt wird im GIF-Format übermittelt. Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 11 von 17

12 4.2.6 Beispielnachricht <?xml version="1.0" encoding="utf-8"?> <bsp:bspnachricht xmlns:bsp= xmlns:xsi= xsi:schemalocation= version="1.0" fassung=" " produkt="pws" produkthersteller="akdb" produktversion="4.11" /> <NachrichtenKopf> <Identifikation.Nachricht> <Ereignis> <Tabelle>9001</Tabelle> <Schluessel>BspNachricht</Schluessel> </Ereignis> <Erstellungszeitpunkt> T09:30:47.0Z</Erstellungszeitpunkt> <NachrichtenId> XVdggWV112311HH </NachrichtenId> </Identifikation.Nachricht> <Absender> <Verfahren>PWS</Verfahren> <Dienst>Gehaltsnachweis</Dienst> <Mandant>Ingolstadt</Mandant> <Gemeindeschluessel> <Tabelle>36</Tabelle> <Schluessel> </Schluessel> </Gemeindeschluessel> <Name>Paula Panther</Name> <Anschrift>Stadtverwaltung Ingolstadt, Hauptplatz 12, Ingolstadt </Anschrift> <Telefon> </Telefon> </Absender> <Empfaenger> <PostkorbId> </PostkorbId> </Empfaenger> </NachrichtenKopf> <NachrichtenInhalt> <Betreff>Testnachricht </Betreff> <FreiText> <Encoding> <Tabelle>9004</Tabelle> <Schluessel>text/plain</Schluessel> </Encoding> <Text>Sehr geehrter Herr Stolz,\n\n Zur vollständigen Bearbeitung Ihres Antrages... </Text> </FreiText> <DataContainer> <Inhaltfzewbsd63hsdsj3adh dhs...> </Inhalt> <FileName>Bild1.pdf</FileName> <FileType> <Tabelle>9005</Tabelle> <Schluessel>application/pdf</Schluessel> </ FileType > </DataContainer> </NachrichtenInhalt> </bsp:bspnachricht> Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 12 von 17

13 5 OK.KOMM-Nachrichtenformat Postkorb-Nachrichten werden in der Regel über OK.KOMM übermittelt. Deswegen muss die reine Postkorb-Nachricht zusätzlich in ein OK.KOMM-spezifisches XML- Nachrichtenformat eingepackt werden, damit auf jeden Fall das AKDB-interne OK.KOMM die Nachricht weiterleiten/routen kann. Die Postkorb-Nachricht wird dabei als <XML_PROFIL></ XML_PROFIL >-Komponente als base64-codierter String in die OK.KOMM-Nachricht eingebaut. Das XML-Format der OK.KOMM-Nachricht ist in [2] spezifiziert. Folgende OK.KOMM-spezifischen Parameter müssen gesetzt werden, damit die Nachricht korrekt zum Ziel transportiert werden kann: AKT_VERFAHREN BSP AKT_TYP NACHRICHT AKT_AUSFUEHRUNG UEBERMITTELN AKT_ZIEL_AGS Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 13 von 17

14 5.1 Beispiel für ein OK.KOMM-AKDB-XML <?xml version="1.0" encoding="iso "?> <ZKOCXML> <XML_SYSTEM> <SYSTEM> <AKTION> <AKT_VERFAHREN>BSP</AKT_VERFAHREN> <AKT_TYP>NACHRICHT</AKT_TYP> <AKT_AUSFUEHRUNG>UEBERMITTELN</AKT_AUSFUEHRUNG> <AKT_ZIEL_AGS> </AKT_ZIEL_AGS> </AKTION> <AKT_LOGIN> <AKT_TECHUSER/> <AKT_TECHPWD/> </AKT_LOGIN> <ANTWORT> <ANT_TYP/> <ANT_APPS/> <ANT_STRUKTUR/> <ANT_DATUM/> <ANT_UHRZEIT/> <FEHLER> <FEH_TYP/> <FEH_TEXT/> <FEH_WERT/> <FEH_FELD/> </FEHLER> </ANTWORT> <APPS_INFO> <APPS_TYP>PWS</APPS_TYP> <APPS_NAME>Gehaltsabrechnung</APPS_NAME> <APPS_VERSION>00.01</APPS_VERSION> <APPS_AGS> </APPS_AGS> <APPS_DATUM> </APPS_DATUM> <APPS_UHRZEIT>13:29:18</APPS_UHRZEIT> <APPS_REQUEST_ID/> <APPS_SOURCE_ID/> <APPS_KENNUNG/> <APPS_IP_ADRESSE> </APPS_IP_ADRESSE> <APPS_ZIEL_URL/> <APPS_RETURN_QUEUE/> </APPS_INFO> </SYSTEM> </XML_SYSTEM> <XML_DATEN> <DATEN /> </XML_DATEN> <XML_PROFIL> <SUCHE> <OK_KOMM_RAW_BASE64> PD94bWwgdmVyc2lvbj0iMS... Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 14 von 17

15 ... <-- Die serialisierte BSP-Nachricht --></OK_KOMM_RAW_BASE64> </ SUCHE > </XML_PROFIL> </ZKOCXML> 6 Web-Service-Schnittstelle Der Postkorb-Service wird über eine Webservice-Schnittstelle mit folgender WSDL angesprochen: <definitions name='postkorbkommservice' targetnamespace='urn:akdb:bsp:postkorb:komm:webservice' xmlns=' xmlns:soap=' xmlns:tns='urn:akdb:bsp:postkorb:komm:webservice' xmlns:xsd=' <types> <xs:schema targetnamespace='urn:akdb:bsp:postkorb:komm:webservice' version='1.0' xmlns:tns='urn:akdb:bsp:postkorb:komm:webservice' xmlns:xs=' <xs:element name='sendbspnachricht' nillable='true' type='tns:sendbspnachricht'/> <xs:element name='sendbspnachrichtoutput' nillable='true' type='tns:sendbspnachrichtoutput'/> <xs:complextype name='sendbspnachricht'> <xs:sequence> <xs:element name='okkommbspnachrichtinput' type='xs:base64binary'/> </xs:sequence> </xs:complextype> <xs:complextype name='sendbspnachrichtoutput'> <xs:sequence> <xs:element name='okkommbspnachrichtoutput' type='xs:base64binary'/> </xs:sequence> </xs:complextype> </xs:schema> </types> <message name='postkorbkommporttype_sendbspnachricht'> <part element='tns:sendbspnachricht' name='sendbspnachricht'></part> </message> <message name='postkorbkommporttype_sendbspnachrichtresponse'> <part element='tns:sendbspnachrichtoutput' name='sendbspnachrichtoutput'></part> </message> <porttype name='postkorbkommporttype'> <operation name='sendbspnachricht' parameterorder='sendbspnachricht'> <input message='tns:postkorbkommporttype_sendbspnachricht'></input> <output message='tns:postkorbkommporttype_sendbspnachrichtresponse'></output> </operation> </porttype> <binding name='postkorbkommporttypebinding' type='tns:postkorbkommporttype'> <soap:binding style='document' transport=' <operation name='sendbspnachricht'> <soap:operation soapaction=''/> <input> <soap:body use='literal'/> </input> <output> <soap:body use='literal'/> </output> </operation> </binding> <service name='postkorbkommservice'> <port binding='tns:postkorbkommporttypebinding' name='postkorbkommport'> <soap:address location='xxxxxxxxxx/bspx-postkorb-okkomm-ws/bspservices/postkorbkomm'/> </port> </service> </definitions> Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 15 von 17

16 Dies entspricht folgender Java-Signatur: byte[] sendbspnachricht(byte[] input) Die Eingabe input ist ein base64-codiertes Byte-Array, welches das OK.KOMM-XML mit eingebetteter BSP-Nachricht (siehe 5.1) enthält. Ausgabe ist ein Ergebnis-String (in der Regel OK ), ebenfalls base64-codiert als Byte-Array. Hinweis: Die eingebettete BSP-Nachricht ist damit effektiv zweifach base64-codiert. Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 16 von 17

17 7 Referenzen [1] Nachrichtenschema BSP-Nachricht [2] Nachrichtenschema OK.KOMM-Nachricht [3] OK.KOMM-Thin-Client Nachrichtenversand an BSP über OK.KOMM V 2.03 Seite 17 von 17