New TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1 · 2013. 6. 20. · [email protected]...

WWW.OPENTUNNEL.NL� [email protected] �[email protected] VERSIE 2013.2

Integratiepatronen

TOEPASSEN VAN INTEGRATIEPATRONEN

MET OPENTUNNEL 1.6


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


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.


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.


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.


Integratiepatronen

Beide bestanden worden op het mapping pallet getoond:

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


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:


Integratiepatronen


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.


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.


Integratiepatronen

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


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.


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.


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.


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


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.


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


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.


Integratiepatronen

New TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1 · 2013. 6. 20. · [email protected]...

Documents

Transcript of New TOEPASSEN VAN INTEGRATIEPATRONEN MET OPENTUNNEL 1 · 2013. 6. 20. · [email protected]...