TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1.6

Integratiepatronen

TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1.6

WWW.OPENTUNNEL.NL [email protected] [email protected]

VERSIE 2013.2

Integratiepatronen INHOUDSOPGAVE INHOUDSOPGAVE ............................................................................................................................................................. 2 INLEIDING ............................................................................................................................................................................ 3 OPENTUNNEL ..................................................................................................................................................................... 3 BREEDTE KOPPELVLAK .................................................................................................................................................. 4 BERICHTTRANSFORMATIE OP BASIS VAN XSLT 1.0 ............................................................................................. 5 UNIVERSELE STUF INTERFACE ..................................................................................................................................... 9 GATEWAY VOOR SERVICES VOOR ZAAKSYTEMEN EN DMS 1.0 (VOORHEEN StUF ZAKEN DMS) ........ 10 BERICHTVOLGORDELIJKHEID ................................................................................................................................... 12 VERTRAAGDE (DOOR) LEVERING ............................................................................................................................. 12 SPlITSEN VAN DE INPUT .............................................................................................................................................. 14 CONDITIONEEL ZETTEN VAN EEN DIGITALE HANDTEKENING ...................................................................... 15 CONDITIONEEL AANPASSEN VAN EEN BERICHT ................................................................................................. 16 CONTENT BASED ROUTING ........................................................................................................................................ 16 ASYNCHRONE CONTINUERING .................................................................................................................................. 16 CONDITIONEEL VERZENDEN BERICHT ................................................................................................................... 17 ARCHIVERING T.B.V. ONWEERLEGBAARHEID ..................................................................................................... 17 OPZETTEN VAN EEN ROLGEBASEERDE XML FILTER SERVICE ........................................................................ 18 UITGAANDE ROUTERING VAN BERICHTEN VIA GATEWAY / LOADBALANCER ......................................... 18


VERSIE 2013.2

Integratiepatronen INLEIDING OpenTunnel van JNet BV is een integratiemakelaar en enterprise servicebus oplossing met faciliteiten specifiek voor de Nederlandse overheid. In dit document worden veel voorkomende integratievraagstukken aangestipt en de oplossingen die OpenTunnel in dit kader biedt. Er zullen regelmatig aanvullingen op dit document komen.

OPENTUNNEL OpenTunnel is een platform die berichten die binnenkomen (via alle door OpenTunnel ondersteunde protocollen) transformeert en (meervoudig aflevert). Dit kan zowel synchroon (bericht wordt meteen doorgezet, denk aan vraag/antwoord) of asynchroon (denk aan notificaties en kennisgevingen). Bij asynchrone communicatie wordt getracht het bericht direct door te zetten naar een afnemend systeem maar deze behoeft niet online te zijn. OpenTunnel zal trachten het bericht alsnog af te leveren. Het begrip bericht dient ruim opgevat te worden. OpenTunnel kan zelfs met HTTP Get requests overweg en kan deze ook gebruiken bij een transformatie naar een bepaald doelbericht. OpenTunnel heeft ook faciliteiten voor ondersteuning van berichtvolgorde en bij de aflevering van berichten kan een bepaald interval in acht worden genomen. Dit voorkomt dat een doelsysteem wordt overspoeld door berichten. OpenTunnel synchroniseert en accommodeert systemen met totaal andere service karakteristieken. Wat er met een bericht dient te gebeuren na ontvangst wordt gespecificeerd in een tunnel. Met name het MIME type van het inkomend bericht is belangrijk. Is deze bijvoorbeeld gedefinieerd als ‘application/ebms’ dan wordt het ebMS protocol geactiveerd en zal OpenTunnel het bericht valideren op basis van dit protocol en een ontvangstbevestiging gaan sturen. OpenTunnel kent ook functionele bevestigingsberichten die geconfigureerd kunnen worden. Denk hierbij bijvoorbeeld aan StUF Bv berichten als antwoord op een asynchrone kennisgeving. Een tunnel bepaalt hoe het bericht wordt ontvangen (protocol van entrypoint en mimetype), welke controles er dienen te worden uitgevoerd (authenticatie, autorisatie, controle digitale handtekening, xsd validaties, business rules), hoe het bericht moet worden omgezet (meervoudig) en waar het moet worden afgeleverd (meervoudig). Verder kunnen er allerlei extra service karakteristieken worden toegevoegd (bewaartermijn, aantal afleverpogingen, notificaties, definitie mappingtabellen t.b.v. transformatie). Vanuit een tunnel kan ook een aanroep worden gedaan naar een ander systeem om waarden op te halen die gebruikt worden bij de transformatie van het bronbericht in doelbericht(en). In OpenTunnel heet dit een tunnelfunctie.


VERSIE 2013.2

Integratiepatronen

Vereenvoudige weergave van een tunnel configuratie

BREEDTE KOPPELVLAK Een entrypoint kan door de bepaling van het adres (via een url contextpad) en een set validaties heel specifiek worden ingericht voor ontvangst van bepaalde berichttypen. Een entrypoint kan ook worden ingericht voor de ontvangst van allerlei niet of nauwelijks bij elkaar behorende berichten. Indien de gewenste berichttransformaties of afleverpunten anders zijn, dan zijn in dat geval ook de tunneldefinities anders. Deze bepalen immers de controles, transformaties en afleverwijzen van het inkomende bericht. Bij een generiek entrypoint moet dus bij een tunnel worden opgegeven hoe een specifiek bericht moet worden herkend. Dit gebeurt door bij de tunnelidentificatie een aanwijzing op te nemen. Een WS-Addressing of ebMS action kan worden gebruikt. Een andere mogelijkheid is een XPath expressie op te geven met een waarde waaraan een element moet voldoen of d.m.v. transport parameters zoals HTTP headers of JMS properties. Op deze wijze is het mogelijk om voor de buitenwereld een breed afleverpunt te bieden (voor OpenTunnel betekent dit een entrypoint) waarbij toch de juiste handelingen op het inkomende bericht worden gepleegd. WWW.OPENTUNNEL.NL [email protected] [email protected]

VERSIE 2013.2

Integratiepatronen

BERICHTTRANSFORMATIE OP BASIS VAN XSLT 1.0 Een belangrijke functie van OpenTunnel is het transformeren van een bericht. In deze paragraaf wordt uit de doeken gedaan hoe dit kan met behulp van XSLT. OpenTunnel ondersteunt in de huidige versie nog geen visuele mapping op basis waarvan een XSLT wordt aangemaakt. JNet gebruikt hiervoor meestal Altova Mapforce die wij eventueel meeleveren met OpenTunnel. In Altova Mapforce kan een input bestand (XML of XSD) en outputbestand (XML of XSD) worden geïmporteerd. Visueel kunnen de element transformaties worden getekend. De definieerde transformaties kunnen worden vastgelegd in een XSLT 1.0 bestand. Deze XSLT kan in OpenTunnel worden geïmporteerd en worden gekoppeld aan een transformatie in een tunnel.

Het proces begint bij de creatie van een nieuwe mapping (het hoeft geen volledig project te zijn):

Vervolgens worden bron- en doel bericht (of de xsd definities) geïmporteerd. In dit geval is het ShortPO.xml/xsd en ExtendedPO.xml/xsd. WWW.OPENTUNNEL.NL [email protected] [email protected]

VERSIE 2013.2

Integratiepatronen

Beide bestanden worden op het mapping pallet getoond:

Hierna kunnen de mappings worden aangebracht. Een van de mappings bevat een functie.


VERSIE 2013.2

Integratiepatronen

Vervolgens wordt met de functie File->GenerateCodeIn -> XSLT 1.0 de mapping geëxporteerd naar een XSLT bestand. In dit geval wordt deze genaamd MappingMapToExtendedPO.xslt. Deze XML transformatie wordt als volgt in OpenTunnel geïmporteerd:


VERSIE 2013.2

Integratiepatronen


VERSIE 2013.2

Integratiepatronen

Deze transformatie kan vervolgens in tunnels worden gebruikt. Inputberichten met dezelfde structuur als ShortPO.xml kunnen op vele manieren aan OpenTunnel worden aangeboden. Het resultaat van de transformatie kan op vele wijzen worden aangeboden aan andere systemen.

UNIVERSELE STUF INTERFACE Een OpenTunnel entrypoint kan over meerdere protocollen een universele XML of JSON interface aanbieden. Indien geen extra maatregelen zijn getroffen zoals controles of het instellen van beveiligingsopties kan alles aan één entrypoint worden aangeboden. Validatie tegen een XML Schema maakt het entrypoint robuuster. In OpenTunnel kan al het StUF verkeer indien gewenst naar één punt worden geleid. Indien XML schema validatie wordt aangezet kunnen er geen StUF berichten binnenkomen die niet aan de XSDs voldoen. Afhankelijk van de inhoud en type van een StUF bericht worden de berichten gerouteerd naar het juiste systeem. Zaakberichten naar een zaaksysteem, BG berichten naar een gegevensmagazijn etc. De routering (en eventuele transformaties) werken op basis van expressies (XPath, waarden van tunnelvariabelen, uitkomst van een tunnelfunctie) Indien de entrypoints specifieker worden ingericht hoeft OpenTunnel in mindere mate in de berichten te kijken. Dit heeft een positieve invloed op de performance.


VERSIE 2013.2

Integratiepatronen StUF afnemerindicaties kunnen op generieke wijze worden geadministreerd in een op abonnementen gebaseerd datadistributiesysteem. Dit betekent twee dingen: Het zetten van afnemerindicaties moet worden gefaciliteerd en mutaties in een gegevensmagazijn, zakenmagazijn of dms moeten worden doorgegeven aan het datadistributiesysteem zodat deze kan bepalen of er geïnteresseerde afnemers zijn van deze gewijzigde gegevens. Het datadistributiesysteem geeft deze mutaties door (eventueel weer gebruik makend van OpenTunnel). Een universele StUF interface kan de intentie tot zetten van een afnemerindicatie ontdekken. Er zijn hiervoor twee mechanismen: via een toevoeging kennisgeving of het stellen van een vraag met afnemerindicatie = true. Als een van deze constructies voorkomen in een vraag dan kan dit bericht ‘verdubbeld’ worden door OpenTunnel via een extra exitpoint. Bij het retourneren van een antwoord kan OpenTunnel via een stylesheet de waarde afnemerindicatie op true zetten indien het zetten van een afnemerindicatie via een vraag ging en de afnemerindicatie door het datadistributiesysteem succesvol gezet is. Het achterliggende systeem hoeft alleen de vraag te beantwoorden en hoeft geen zorg te dragen voor de administratie.

GATEWAY VOOR SERVICES VOOR ZAAKSYTEMEN EN DMS 1.0 (VOORHEEN STUF ZAKEN DMS) StUF Services voor Zaaksystemen en DMS 1.0 is een nieuwe standaard. OpenTunnel ondersteunt deze standaard door een specifieke inrichting van OpenTunnel (entrypoints, sjablonen, meerdere tunnels, CMIS exitpoints en CMIS changelog listener). Het gedrag is dan ook aanpasbaar. Voor de verwerking van inkomende StUF berichten worden twee entrypoints gedefinieerd. Een voor synchrone en een voor asynchrone communicatie. Bij asynchrone communicatie worden de berichten en documenten in de OpenTunnel runtime database geplaatst voor gegarandeerde aflevering. De tunnels die ingericht worden voor het ondersteunen van de standaard kunnen de StUF berichten doorzetten naar het zaaksysteem. Indien het zaaksysteem geen StUF ondersteunt kan OpenTunnel het StUF koppelvlak bieden en dit in de tunnels die de standaard implementeert een transformatie uitvoeren naar de API van het zaaksysteem. Op basis van de inhoud van het aangeboden bericht bepaalt OpenTunnel welke tunnelconfiguratie van toepassing is en of het bericht via CMIS moet worden doorgegeven aan het DMS of naar het zaaksysteem (of beide). Mutaties die plaatsvinden in het DMS worden via de CMIS changelog listener (OpenTunnel entrypoint) doorgegeven aan het zaaksysteem.


VERSIE 2013.2

Integratiepatronen

Asynchroon verkeer in het kader van standaard services voor zaaksysteem en DMS


VERSIE 2013.2

Integratiepatronen

Synchroon verkeer in het kader van standaard services voor zaaksysteem en DMS

BERICHTVOLGORDELIJKHEID Het is wenselijk dat berichten in volgorde worden verwerkt. Een bericht is vaak een weerslag van een gebeurtenis in de werkelijkheid en heeft meestal een element die het tijdstip van de gebeurtenis representeert, bijvoorbeeld het StUF element tijdstipRegistratie. Indien berichten in een keten worden doorgegeven kan op ieder knoopunt om technische redenen deze volgordelijkheid worden doorbroken. Met name het parallel verwerken van gegevens in een cluster kan tot gevolg hebben dat een later aangeboden bericht eerder verwerkt wordt dan. Ook vele messaging implementaties bieden geen ondersteuning voor volgordelijk verwerken. In OpenTunnel kan een business timestamp worden gedefinieerd die er voor zorgt dat de verwerking in volgorde van deze business timestamp. In aanvulling hierop kan er een wachttijd worden ingebouwd in een tunnel alvorens het bericht wordt opgepakt ter verwerking en doorlevering. De combinatie van deze twee strategieën verhoogt de kans aanzienlijk dat berichten in volgorde worden verwerkt. De kans is echter geen volle 100% omdat niet gegarandeerd kan worden dat berichten die (heel veel) later binnenkomen dan de wachttijd niet voorkomen.

VERTRAAGDE (DOOR) LEVERING Probleem: Het systeem waar gegevens door OpenTunnel moet worden afgeleverd heeft een matige performance of accepteert slechts een aantal berichten per tijdseenheid. WWW.OPENTUNNEL.NL [email protected] [email protected]

VERSIE 2013.2

Integratiepatronen Oplossing: Het definiëren van een interval tussen de aflevering van berichten in een tunnel. OpenTunnel accommodeert op deze wijze systemen met totaal verschillende service karakteristieken. OpenTunnel treedt op als ‘man-in-the-middle’. Het buffert de berichten en levert in een rustig tempo door. Deze functionaliteit werkt ook in onze high availability versie. Des gewenst kan deze functionaliteit worden gecombineerd met een wachttijd in de verwerking en het definiëren van een business timestamp zoals besproken in de vorige paragraaf. In onderstaande twee schermafdrukken is sprake van een wachttijd tot verwerking van 20 seconden en een interval van 5 seconden tussen doorleveringen. Daarnaast een business timestamp expressie op element ts_expr waarbij de berichten in volgorde van business timestamp worden doorgeleverd.


VERSIE 2013.2

Integratiepatronen

SPLITSEN VAN DE INPUT Input kan leiden tot een veelvoud aan outputberichten. Denk aan csv bestanden of StUF samengestelde kennisgevingen (Lk03). OpenTunnel kan deze samengestelde berichten splitsen in kleinere eenheden. Deze kleinere eenheden worden vervolgens verder verwerkt (getransformeerd en afgeleverd). Het splitsen gebeurt in de tunnel. Een EntryPoint (bijvoorbeeld een FileEntryPoint) leest een groot bestand. Bij een tunnel kan worden opgegeven hoe de input moet worden gesplitst. De gesplitste output wordt in nieuwe tunnelinstanties geplaatst met een referentie naar het oorspronkelijke bericht. Dit is inzichtelijk in de OpenTunnel beheer module. De gesplitste berichten worden na transformatie doorgezet aan een andere systeem. Via deze functionaliteit hebben wij bijvoorbeeld een CSV import bestand omgezet naar zaak creatie berichten. OpenTunnel ondersteunt de volgende splitters: • • •

nl.jnc.gateway.message.ctrl.splitter.NewLineSplitter. Splitst de input op basis van ‘new line’ karakters. nl.jnc.gateway.message.ctrl.splitter.CSVSplitter. CSV splitter waarbij iedere lijn een nieuw bericht wordt. nl.jnc.gateway.message.ctrl.splitter.XPathSplitter. Het bericht wordt behandeld als DOM document. Deze wordt geconfigureerd met een XPath expressie die een lijst van DOM nodes produceert. Elke DOM node wordt een nieuw bericht.

De splitter wordt geconfigureerd via runtime variabelen in de beheer console.


VERSIE 2013.2

Integratiepatronen CONDITIONEEL ZETTEN VAN EEN DIGITALE HANDTEKENING Probleem: Vanuit een OpenTunnel server moet namens meerdere partijen een digitale handtekening gezet worden. Denk aan het volgende scenario: Een applicatie beheert gegevens volgens een multi-tenant model. Deze applicatie wil berichten uitsturen die voorzien dienen te worden van een digitale handtekening. De applicatie wil de berichten slechts op één punt afleveren geen rekening houdend met de ‘eigenaar’ van het uit te sturen bericht. Oplossing: In OpenTunnel dient dan per tunnel per tenant een eigen verzoekprofiel te worden samengesteld waarbij voor iedere tenant een eigen private key aan het profiel wordt gekoppeld t.b.v. het plaatsen van de digitale handtekening. Vervolgens moet er nog iets in bericht of protocol gevonden worden op basis waarvan een expressie gedefinieerd kan worden die de selectie van het gewenste requestprofiel stuurt. De StUF standaard bijv. definieert in de StUF header een element die hiervoor gebruikt kan worden. In onderstaand voorbeeld wordt een ander element gebruikt, namelijk een gemeentecode. Hieronder als voorbeeld een schermafdruk waarbij de gemeentecode in het StUF-WOZ bericht de selector is die voorschrijft welk verzoekprofiel met gekoppeld certificaat en transformer moet worden geselecteerd. Zoals u kunt zien is het exitpoint gelijk. Op deze wijze hoeft een bestaande applicatie niet te worden aangepast. In onderstaande schermafdruk is de selectie van een verzoekprofiel (met alle benodigde berichtoperaties) afhankelijk gemaakt van de waarde van het XML element gemeenteCode.


VERSIE 2013.2

Integratiepatronen CONDITIONEEL AANPASSEN VAN EEN BERICHT In OpenTunnel zijn er drie manieren om de output van een berichttransformatie dynamisch te maken: •

Het gebruik maken van een mapping tabel tussen inputelementen en de gewenste output elementen

•

Het gebruik van meerdere berichtsjablonen op basis van een expressie uitgevoerd op de input (bericht of protocol)

•

Een combinatie van beiden

CONTENT BASED ROUTING Via expressies bij de definitie van een afleveradres kan een expressie worden opgegeven onder welke voorwaarden dit afleverpad moet worden gevolgd. Dit werkt op basis van expressies.

ASYNCHRONE CONTINUERING OpenTunnel kan berichten direct bij de ontvanger afleveren. Indien een ontvangend systeem traag is of vaak niet beschikbaar kan de berichtverwerkingstransactie verkort worden door gebruik te maken van asynchrone continuering gebruik maken van een message queue. WWW.OPENTUNNEL.NL [email protected] [email protected]

VERSIE 2013.2

Integratiepatronen Voorbeeld: in de Landelijke voorziening WOZ is bepaald dat de beschikbaarheid en performance van berichtenarchief geen invloed mag hebben op het hoofdverwerkingspad, n.l. het verwerken van het bericht in de database en het aanmaken van orders voor SAP. Een inkomend bericht zou normaliter dus afgeleverd worden op drie exitpoints (archief, SAP en WOZ database logica). Maar in plaats van het direct sturen van het bericht naar het archief wordt het in een JMS message queue geplaatst. De transactie is dan korter. Er is in OpenTunnel een extra tunnel gedefinieerd die via een JMS entrypoint de queue weer leest en het bericht alsnog via WebDAV protocol (exitpoint!) in het archief plaatst. De verdere verwerking gebeurt zo dus op de achtergrond.

CONDITIONEEL VERZENDEN BERICHT Niet altijd behoeven berichten die aan OpenTunnel aangeboden worden automatisch te worden doorgeleverd. Dit kan ook onder condities gebeuren. Een voorbeeld is het sturen van een bericht aan de BerichtenBox van MijnOverheid. Het heeft geen zin berichten te versturen indien de burger geen berichtenbox heeft. OpenTunnel kan een WebService Call uitvoeren via een OpenTunnel functie. Het resultaat van een aanroep kan worden opgeslagen in een of meerdere zelf te creëren runtime variabelen. Deze worden geëvalueerd in een conditioneel exitpoint. Indien de conditie waar is wordt het bericht afgeleverd (eindstatus = DELIVERED) of niet (eindstatus = PROCESSED). In de tunnel wordt dus eerst de webservice aangeroepen die bekijkt of de BSN in het bericht een MijnOverheid account heeft. Afhankelijk van het resultaat wordt het bericht doorgezonden.

ARCHIVERING T.B.V. ONWEERLEGBAARHEID


VERSIE 2013.2

Integratiepatronen

Bovengenoemde parameters worden verstuurd als metadata naar de MongoDB archivering server(s). De parameters kunnen gebaseerd zijn op Xpath statements uit het ingestuurde bericht, resultaten van een tunnelfunctie of een reeds gevulde tunnel runtime variabele. Daarnaast wordt natuurlijk het bericht zelf naar de archivering server(s) gestuurd ter opslag.

OPZETTEN VAN EEN ROLGEBASEERDE XML FILTER SERVICE Deze beschrijving wordt binnenkort toegevoegd.

UITGAANDE ROUTERING VAN BERICHTEN VIA GATEWAY / LOADBALANCER Indien OpenTunnel zich bevindt achter een TLS offloader (Gateway, Proxy, LoadBalancer) kan het bij uitgaand verkeer voor de gateway onduidelijk zijn naar welke partij de (TLS) verbinding moet worden opgezet. Dit kan worden ondervangen door vanuit OpenTunnel met een HTTP header de loadbalancer te instrueren. Het uitgaande bericht kan dan worden doorgeleverd door de Gateway. De URL wordt in onderstaand voorbeeld bepaald door een tunnelfunctie die in het CPA contract kijkt wat het uiteindelijke afleveradres is. Deze wordt geplaatst in het de HTTP header ‘outboundUrl’. Het exitpoint van de OpenTunnel tunnel is in dit geval dus de Gateway zelf! OpenTunnel kan dus zelf TLS endpoint zijn maar kan ook samenwerken met een TLS Offloader.


VERSIE 2013.2

Integratiepatronen


VERSIE 2013.2

TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1.6

Recommend Documents