Beschrijving OpenTunnel koppelvlak met MijnOverheid BerichtenBox

Koppelvlak BerichtenBox

Beschrijving OpenTunnel koppelvlak met MijnOverheid BerichtenBox

WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox INHOUDSOPGAVE INLEIDING ............................................................................................................................................................................ 3 OPVRAGEN GEABONNEERDEN ..................................................................................................................................... 4 MASSALE AANLEVERING OP BASIS VAN META-‐DATA VIA XML ......................................................................... 5 MASSALE AANLEVERING MET EEN CSV BESTAND MET OPENTUNNEL PDF GENERATIE .......................... 7 SAMENVATTING ............................................................................................................................................................. 10


Koppelvlak BerichtenBox INLEIDING OpenTunnel van JNet BV is een integratiemakelaar en enterprise servicebus oplossing met faciliteiten specifiek voor de Nederlandse overheid. In dit document worden de interne koppelvlakken besproken voor Mijn Overheid BerichtenBox. Bij het aansluiten op de BerichtenBox met OpenTunnel zijn er meerdere alternatieven: 1. De interne aanleverende applicaties houden zich precies aan het berichtformaat van de berichtenbox. De applicatie (service consumer) is dan verantwoordelijk voor: •

Het orkestreren van de synchrone en asynchrone services van MijnOverheid

•

Het interpreteren van de foutmeldingen van MijnOverheid

•

Het implementeren van de berichtstructuur van MijnOverheid

•

Het omzetten van PDF’s naar een base64 representatie

OpenTunnel wordt in dit scenario alleen ingezet als Digikoppeling adapter Deze dienst is beschikbaar op de volgende URL: •

https://:9433/opentunnel//standaardInternBerichtenboxKoppelvlak/

Indien deze dienst via http worden benaderd is dit de URL: •

https://:7080/opentunnel//standaardInternBerichtenboxKoppelvlak/

De poortnummers zijn overigens instelbaar. De XSDs van de BerichtenBox zijn onderdeel van het zip bestand waar dit document onderdeel van uitmaakt. Deze werkwijze is ten allen tijde mogelijk met OpenTunnel. 2. OpenTunnel biedt ook op verzoek een eenvoudiger koppelvlak aan om applicaties eenvoudiger te laten aansluiten op de BerichtenBox. OpenTunnel heeft minimaal de BSN, onderwerp,berichttekst en optioneel een PDF nodig om een bericht succesvol te kunnen afleveren. Het berichtformaat is vrij te kiezen. 3. OpenTunnel kan ook PDF bestanden genereren op basis van PDF sjablonen. De tunnel die de PDF’s aanmaakt als onderdeel van het aanmaken van het totale BerichtenBox bericht moet gevoed worden met de gegevens die nodig zijn om de PDF sjabloon specifiek te maken c.q. te personaliseren. Deze input kan uit een bestand komen of via een webservice worden aangeboden. 4. Massale BerichtenBox aanlevering via een XML(bestand) met meta-data en verwijzigingen naar PDF’s via een URL/URI (zie hoofdstuk 3) 5. Aanlevering van geadresseerden via een CSV bestand gecombineerd met PDF generatie in OpenTunnel.


Koppelvlak BerichtenBox OpenTunnel ondersteunt ook het mechanisme om abonnementsgegevens van Mijn Overheid door te geven aan interne systemen. Dat maakt het mogelijk om een redundante registratie bij te houden of voor de generatie van een groot aantal documenten de abonnee-populatie te controleren. Daarnaast is er een synchrone webservice beschikbaar om per BSN te verifiëren of een burger geïnformeerd wil worden via MijnOverheid door een overheidsorganisatie. Het is mogelijk om deze service te combineren in een tunnel-orkestratie.

OPVRAGEN GEABONNEERDEN Met de Berichtenbox Validatieservice biedt Mijn Overheid een koppelvlak om vast te stellen of een burger met een zeker burgerservicenummer berichten wil ontvangen van uw organisatie. De XSD van dit koppelvlak is ook onderdeel van het zip bestand. De aanbevolen synchrone standaard bevragingswebservice voor validatie van BSN’s is beschikbaar op URL •

https://:9433/opentunnel//prod/berichtenboxValidatieservice

Indien deze dienst via HTTP worden benaderd is dit de URL: •

http://:7080/opentunnel//prod/berichtenboxValidatieservice

De WSDL en XSDs van dit standaard koppelvlak treft u aan in de directory ‘XSD+WSDL Berichtenbox Validatieservice v1.0’ in het ZIP bestand. Er is ook een mogelijkheid om alle burgers (BSN’s) die geïnformeerd willen worden via MijnOverheid (een abonnement hebben) op te vragen. Het koppelvlak biedt ook de mogelijkheid om als extra een lijst BSN’s aan te bieden en deze te controleren op abonnement status. Dan worden als antwoord alleen de BSN’s geretourneerd die actief zijn bij MijnOverheid. In het eerste geval worden alle BSN’s geretourneerd die voor uw organisatie bereikbaar zijn op Mijn Overheid. Hieronder een voorbeeld van een abonnement status verzoek voor een lijst BSN’s vanuit een organisatie met OIN 00000000000000000000: <ns0:AbonnementAanvraag xmlns:ns0="http://schemas.overheid.nl/GEB/AbonnementServiceProcessor/2014/02"> 00000000000000000000 900009342


Koppelvlak BerichtenBox 900009391 900009378 900009391

Het volgende voorbeeldbericht wordt later geretourneerd als antwoord op de vraag:

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

00000003560458830000 2014-09-01T14:51:58+02:00 Verwerkt 900009342 900009378 900009391

De XSD van dit koppelvlak is ook onderdeel van het zip bestand (Abonnementservice berichtvoorkeuren xsd en voorbeeldbestanden.zip)

MASSALE AANLEVERING OP BASIS VAN META-DATA VIA XML OpenTunnel

kan

ook

een

grote

hoeveelheid

berichten

en

persoon

specifieke

bijlagen

(bijvoorbeeld

waardebeschikkingen, taxatieverslagen) sturen naar de Berichtenbox. Hiervoor zijn nodig: een set aan PDF WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox bestanden en een XML indexbestand met meta-data. Dit geheel wordt opgenomen in een zip bestand. De metadata XML bevat: •

Een lijst van BSN’s

•

Een lijst van bij de BSN horende PDF bestandsnamen (gedefinieerd als URI). De PDF bestanden dienen wel benaderbaar te zijn voor OpenTunnel via een protocol als FTP, http, een fileshare of in het zelfde ZIP bestand als de meta-data.

•

Informatie die getoond wordt aan de burger (onderwerp, berichttekst). Deze elementen kunnen afhankelijk van de locatie in het meta-dat bestand gelden voor alle burgers of specifiek per geadresseerde burger.

Het zip bestand met meta-data in XML formaat (en optioneel PDF’s) kan aangeboden worden via FTP, file protocol of via het berichtenbox-portaal van JNet. OpenTunnel moet luisteren op de directory waar het ZIP bestand wordt geplaatst. De structuur van de XML ziet er als volgt uit: {BerichtType zoals geregistreerd bij BerichtenBox via Leveranciersportaal} {Datum van publicatie, optioneel,formaat: YYYY-MM-DDTHH:MM:SSZ} {Onderwerp van het bericht, max 50 tekens} {Tekst van max 4000 tekens} {BSN van geadresseerde} {Tekst van max 4000 tekens, deze heeft voorrang op de algemene berichttekst hierboven, een van beiden is verplicht} {max 25 tekens} Pdf {URI van PDF bestand die benaderbaar is door OpenTunnel} {Omschrijving bijlage, max 40 tekens} {positie van de bijlage zoals deze wordt getoond aan de burger in MijnOverheid}

De XSD voor dit bericht (ot-bb-2.0.0.xsd) bevindt zich in het gecomprimeerde bestand waard dit document deel van uitmaakt (OpenTunnel-BerichtenBox-Documentatie-v2.0.zip) WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox Een bericht met bovenstaande structuur dient met de PDF’s (optioneel) opgenomen te worden in een zip bestand die actief worden ingeschoten in een OpenTunnel tunnel of kan worden opgepikt via een file entrypoint. Per bericht element in het batch bestand wordt een transactie gestart in OpenTunnel. Per bericht is de status van aflevering bekend en te volgen via de beheerconsole van OpenTunnel. De standaard HTTPS URL voor het insturen (HTTP XML Post) is •

https://:9433/opentunnel//prod/massaalBerichtenboxKoppelvlak/

Indien deze dienst via HTTP wordt benaderd is dit de URL: •

http://:7080/opentunnel//prod/massaalBerichtenboxKoppelvlak /

Op verzoek kan het formaat van de XML aangepast worden. De credentials of certificaten die nodig zijn bij benadering van het bestand via de URI worden gedefinieerd op (Bestands)tunnelniveau en worden dus niet ‘gecommuniceerd’ via het XML meta-data bestand. Niet afgeleverde documenten worden regelmatig (bijv. iedere 24 uur) gerapporteerd, niet verzonden PDF’s worden in een ‘afgewezen’ directory geplaatst of op andere wijze gecommuniceerd. Alle OpenTunnel protocollen staan ter beschikking voor de wijze van aflevering.

MASSALE AANLEVERING MET EEN CSV BESTAND MET OPENTUNNEL PDF GENERATIE

Op dezelfde wijze waarop het ZIP bestand wordt aangeboden kan ook een CSV bestand worden gebruikt als basis. Voor iedere rij in de CSV creëert OpenTunnel een BerichtenBox tunnelinstantie. De kolommen in iedere rij zijn als variabelen beschikbaar in de tunnel. Deze variabelen worden gebruikt voor het vullen van een PDF sjabloon. Indien berichttype, onderwerp of begeleidende berichttekst niet in de CSV zitten kan deze eventueel worden gedefinieerd in OpenTunnel (waarbij de tunnel dan wel heel specifiek wordt voor een bepaald berichttype, per input(directory) is dan een aparte tunnel nodig). Een alternatief is het gebruik van het JNet BerichtenBox portaal waarmee deze attributen kunnen worden gedefinieerd vóór de upload van de CSV naar OpenTunnel. OpenTunnel maakt in dit scenario dus ook de PDF op basis van een sjabloon! OpenTunnel kan vele sjablonen ondersteunen. De PDF output wordt direct opgenomen in het bericht dat wordt uitgestuurd naar de BerichtenBox. De PDF kan daarnaast ook natuurlijk worden opgenomen in een DMS (bijv. via StUF Zaken DMS koppelvlak), gemaild etc. Dit kan in OpenTunnel worden geconfigureerd als separaat afleverpunt naast Mijn Overheid BerichtenBox. WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox Niet verzonden PDF’s worden gerapporteerd en tevens geplaatst in een ‘afgewezen’ directory. Hieronder een afbeelding van een voorbeeld CSV en een voorbeeld PDF sjabloon. De kolomwaarden in de CSV komen (uiteindelijk) in de gegenereerde PDF.

Afbeelding: Voorbeeld CSV

Afbeelding: Voorbeeld PDF Sjabloon WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox Vereenvoudigd ziet de oplossing er als volgt uit: •

Een CSV wordt geplaatst in een directory waarop OpenTunnel staat te ‘luisteren’

•

OpenTunnel verwerkt de rijen in de CSV en creëert tunnelinstanties

•

In de tunnel instantie worden de meta-data gebruikt voor de PDF generatie

•

De gegeneerde PDF wordt met de andere meta data (berichttype, onderwerp, berichttekst) opgenomen in het bericht naar de berichtenbox en wordt via ebMS/Digikoppeling verzonden.

•

Indien het bericht wordt afgewezen wordt deze geplaatst in een output directory zodat deze anderszins kan worden verwerkt (bijvoorbeeld printen en verzenden of mailen of ….)

PDF sjablonen kunnen via de OpenTunnel beheerconsole worden geupload. WWW.JNET.NL [email protected]

Koppelvlak BerichtenBox SAMENVATTING In de volgende plaat worden de mogelijke koppelvlakken gezamenlijk getoond. Via het BerichtenBox Portaal van JNet kunnen de meta-data worden geupload (in CSV of XML formaat) en afgewezen documenten worden gedownload en rapportages worden ingezien. Deze component is optioneel omdat de bestanden en rapportages ook via andere middelen kunnen worden aangeboden. Alle OpenTunnel protocollen staan hierbij ter beschikking. Gebruikmakend van de orkestratie mogelijkheden van OpenTunnel kan de oplossing kan verder worden uitgebreid met verzending van documenten en opslag van documenten in een DMS.

JNET BERICHTENBOX PORTAAL Deze wordt tevens aangeboden in de JNet Cloud. Iedere klant kan eigen gebruikers en definities beheren en zowel ad-hoc berichten als de genoemde CSV bestanden uploaden en verwerkingsstatus monitoren. Meer informatie in de documentatie van het JNet BerichtenBoxPortaal.


Koppelvlak BerichtenBox


Beschrijving OpenTunnel koppelvlak met MijnOverheid BerichtenBox

Recommend Documents