Beschrijving OpenTunnel koppelvlak met MijnOverheid BerichtenBox

Transcriptie

1 Beschrijving OpenTunnel koppelvlak met MijnOverheid BerichtenBox

2 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

3 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: van organisatie >/standaardinternberichtenboxkoppelvlak/ Indien deze dienst via http worden benaderd is dit de URL: van organisatie >/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.

4 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 van organisatie>/prod/berichtenboxvalidatieservice Indien deze dienst via HTTP worden benaderd is dit de URL: van organisatie >/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 : <?xml version="1.0"?> <ns0:abonnementaanvraag xmlns:ns0=" <BerichtLeverancier> <OIN> </OIN> </BerichtLeverancier> <BSNLijst> <BSN> </BSN>

5 <BSN> </BSN> <BSN> </BSN> <BSN> </BSN> </BSNLijst> </ns0:abonnementaanvraag> Het volgende voorbeeldbericht wordt later geretourneerd als antwoord op de vraag: <?xml version="1.0" encoding="utf-8"?> <AbonnementAntwoord xmlns:xsi=" xmlns:xsd=" xmlns=" <BerichtInformatie> <BerichtLeverancier> <OIN> </OIN> </BerichtLeverancier> <DatumTijdVerwerking> T14:51:58+02:00</DatumTijdVerwerking> <VerwerkingsCode>Verwerkt</VerwerkingsCode> </BerichtInformatie> <Actief> </Actief> <BSNLijst> </BSNLijst> </AbonnementAntwoord> <BSN> </BSN> <BSN> </BSN> <BSN> </BSN> 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

6 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: <?xml version="1.0" encoding="utf-8"?> <BerichtenBoxBatch xmlns=" xmlns:xsi= xsi:schemalocation=" ot-bb.xsd"> <BerichtType>{BerichtType zoals geregistreerd bij BerichtenBox via Leveranciersportaal} </BerichtType> <!-- Optioneel--> <PublicatieDatum>{Datum van publicatie, optioneel,formaat: YYYY-MM-DDTHH:MM:SSZ}</PublicatieDatum> <Onderwerp>{Onderwerp van het bericht, max 50 tekens}</onderwerp> <!-- Optioneel maar verplicht als er geen specifieke berichttekst per BSN is ingevuld --> <BerichtTekst>{Tekst van max 4000 tekens}</berichttekst> <Berichten> <Bericht><!-- Hiervan kunnen er velen zijn --> <GebruikerID>{BSN van geadresseerde}</gebruikerid> <BerichtTekst>{Tekst van max 4000 tekens, deze heeft voorrang op de algemene berichttekst hierboven, een van beiden is verplicht} </BerichtTekst> <Referentie>{max 25 tekens}</referentie> <Bijlagen> <!-- Hiervan kunnen er meerdere zijn, max 2 --> <Bijlage> <!-- Optioneel--> <BijlageType>Pdf</BijlageType> <Bestand>{URI van PDF bestand die benaderbaar is door OpenTunnel}</Bestand> <Omschrijving>{Omschrijving bijlage, max 40 tekens}</omschrijving> <Volgorde>{positie van de bijlage zoals deze wordt getoond aan de burger in MijnOverheid} </Volgorde> </Bijlage> </Bijlagen> </Bericht> </Berichten> </BerichtenBoxBatch> De XSD voor dit bericht (ot-bb xsd) bevindt zich in het gecomprimeerde bestand waard dit document deel van uitmaakt (OpenTunnel-BerichtenBox-Documentatie-v2.0.zip)

7 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 van gemeente>/prod/massaalberichtenboxkoppelvlak/ Indien deze dienst via HTTP wordt benaderd is dit de URL: van gemeente>/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), g d etc. Dit kan in OpenTunnel worden geconfigureerd als separaat afleverpunt naast Mijn Overheid BerichtenBox.

8 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

9 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.

10 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.

11 Koppelvlak BerichtenBox