Page Comparison

Binnen Edu-V worden verschillende Transactiepatronen gebruikt. Bij enkele processen is directe (real time) distributie van informatie naar ontvangende systemen niet direct noodzakelijk. In andere gevallen is dit juist wel noodzakelijk. Bijvoorbeeld het toewijzen en in gebruik nemen van een leermiddel aan een onderwijsdeelnemer. Edu-V kent processen die daardoor een complexere architectuur eisen.

Een uitwerking van deze berichtuitwisseling met de benodigde architectuur wordt hier beschreven. De transactiepatronen Abonneren op wijzigingen middels notificaties, melding-bevestiging, asynchrone uitwisseling en Georkestreerde uitwisseling gebruiken berichten, vaak wel events genoemd. Deze berichten worden synchroon verzonden en asynchroon verwerkt. Bij de asynchrone (en georkestreerde) uitwisseling wordt er na de verwerking een bevestiging retour gestuurd. Ook voorziet het in een patroon om berichten die vanwege een technisch probleem niet afgeleverd konden worden door de ontvanger alsnog opgehaald kunnen worden.

Naast de logica van rechtstreekse uitwisseling van berichten van Verzender naar Ontvanger zal het mogelijk zijn om de volledige stand uit te wisselen, bijvoorbeeld bij problemen of bij een initiële start van een koppeling. Dit betreft een Bevraging of Melding-bevestiging transactiepatroon. Dit proces kan geïnitieerd worden door zowel Bron of Afnemer of Verzender als en Ontvanger, ter illustratie:

• Een Leermiddelenaanbieder referentiecomponent Gebruiksomgeving digitaal leermateriaal kan door een Bevraging bij de Administratiesysteemaanbieder referentiecomponent Administratiesysteem onderwijsdeelnemers gegevens ophalen.

• Een Leermiddelenaanbieder referentiecomponent Gebruiksomgeving digitaal leermateriaal kan door een Melding-bevestiging ook data bij een Leerportaalaanbieder Dashboard laten bijwerken.

Het gebruik van event berichten lijkt erg veel op de klassieke werkwijze van het verzenden of ophalen van informatie, met het enige verschil dat de berichten al direct bij een aanpassing in het bronsysteem gegenereerd worden en deze voorheen periodiek in bulk werden verzameld en doorgestuurd. De bericht omvang is daardoor vrijwel altijd kleiner terwijl de frequentie en volume sterk toeneemt.

Op deze pagina wordt , aangezien de werking van Bevraging en Melding-bevestiging voor zich spreken, alleen de werking van het gebruik van events nader toegelicht:

...

In de gegevensuitwisseling is er sprake van een Verzender Bron en een OntvangerAfnemer. In onderstaande figuur zijn de componenten weergegeven van de berichteninfrastructuur die iedere Leverancier dient te implementeren indien gebruik gemaakt wordt van het transactiepatroon Abonneren op wijzigingen middels notificaties.

...

In de toelichting op de figuur starten we linksboven vanuit het perspectief van de VerzenderBron. De component Event Mediator is het startpunt van de gegevensuitwisseling. Deze component ontvangt een update op een entiteit (Entity). De update wordt verwerkt in de database van de Entiteit en daarna wordt er een bericht gedefinieerd waarin een notificatie over de wijziging naar alle geabonneerde Ontvangers Afnemers wordt gestuurd. Dit bericht notificatiebericht wordt op de component Event send queue gezet en uiteindelijk door de component Event notifier naar de Consumers toegestuurd. De Event send queue biedt de Verzender Bron de mogelijkheid om berichten notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de Verzender Bron te optimaliseren. Alle verzonden berichten notificatieberichten worden door de Verzender Bron opgeslagen in een database Send Events.

Aan de zijde van de Ontvanger Afnemer komen alle berichten notificatieberichten synchroon binnen op het POST endpoint /eventsnotificaties. Vanuit dit endpoint worden de berichten notificatieberichten op de component Event receive queue gezet. Dit biedt de Ontvanger Afnemer de mogelijkheid om berichten notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de ontvanger Afnemer te optimaliseren. Vanuit de Event receive queue worden de berichten notificatieberichten asynchroon verwerkt door de component Event processor. Uit het bericht blijkt de entiteit die gewijzigd is. Via het GET endpoint wordt de actuele stand van de entiteit bij de resource server van de Verzender Bron opgehaald en verwerkt. De wijziging in de identiteit entiteit wordt doorgevoerd in de database van de Entiteit aan de zijde van de OntvangerAfnemer. Alle ontvangen berichten notificatieberichten worden door de Ontvanger Afnemer opgeslagen in een database Received Events.

Het kan voorkomen dat de Ontvanger Afnemer tijdelijk niet beschikbaar is. In dat geval is de Verzender Bron herhaaldelijk niet in staat om het bericht notificatiebericht af te leveren op het POST endpoint van de OntvangerAfnemer. Zodra de Ontvanger Afnemer weer online komt en berichten ontvangt kan de Event Processor van de Ontvanger Afnemer bij de Verzender Bron navragen of er berichten notificatieberichten gemist zijn. De Event Processor gebruikt hiervoor de component Event Client. Deze Event Client bevraagt een GET endpoint aan de zijde van de Verzender Bron en verzamelt zo alle berichten notificatieberichten aangemaakt na een bepaalde tijdstempel.

...

Een Afnemer kan zich abonneren op wijzigingen bij een Bron via het POST endpoint /subscribe.

Berichteninfrastructuur: Asynchrone en georkestreerde uitwisseling

In de gegevensuitwisseling is er sprake van een Verzender en een Ontvanger. In onderstaande figuur zijn de componenten weergegeven van de berichteninfrastructuur die iedere Leverancier dient te implementeren indien gebruik gemaakt wordt van het transactiepatroon Georkestreerde Asynchrone of georkestreerde uitwisseling.

...

In een asynchrone of georkestreerde uitwisseling vraagt de Verzender een terugmelding van de Ontvanger zodra het bericht is verwerkt. De blauwe kleur beschrijft de berichteninfrastructuur die ingezet wordt om terugmeldingen te versturen en te ontvangen. Hierbij is ook zichtbaar dat de initiële Ontvanger van de melding juist weer Verzender wordt voor de terugmelding. De rollen zijn hier gespiegeld.

...

De oorspronkelijke Verzender ontvangt een bevestigingsbericht op het POST endpoint /eventsentity/confirmations. Dit bevestigingsbericht wordt op de component Event receive queue gezet. Op een gegeven moment zal de Event processer het bevestigingsbericht gaan verwerken. Deze constateert dat het een terugmelding betreft en zal deze doorsturen naar de Event mediator. De Event mediator kan op zijn beurt de entiteit gaan wijzigen, waarmee de berichtencyclus weer opnieuw start. Alle ontvangen bevestigingsberichten worden door de oorspronkelijke Verzender opgeslagen in de database Received Confirmations.

Ook voor bevestigingsberichten geldt dat de oorspronkelijke Verzender tijdelijk niet beschikbaar kan zijn. Net als voor de normale berichten kan de oorspronkelijke Verzender bij de oorspronkelijke Ontvanger de bevestigingsberichten verzamelen die na een bepaalde tijdstempel zijn aangemaakt.

Berichten die verstuurd worden via een asynchrone of georkestreerde uitwisseling worden niet via de Events API verstuurd. Voor ieder bericht is in de betreffende API een PUT endpoint opgenomen waarbij een Verzender een bericht (inclusief de data) af kan leveren bij de Ontvanger. Dit is het melding-bevestigen patroon. In aanvulling hierop heeft de Verzender een PUT endpoint om de bevestiging (confirmation) van de asynchrone verwerking van het bericht door de Ontvanger te ontvangen. Dit is het terugmelding-bevestiging persoon. Als voorbeeld heeft de referentiecomponent Licentieregistratie een PUT endpoint /entitlements en de referentiecomponent Aanspraakmanager een PUT endpoint /entitlements/confirmations.

Voor leveranciers is het hierdoor mogelijk om in deze specifieke endpoints de berichtvalidatie te implementeren zodat de berichten in goede orde ontvangen kunnen worden. Uiteraard kunnen de berichten en bevestigingsberichten wel door een Event mediator en Event processor asynchroon worden verwerkt.

Operationeel: Afspraken bij niet succesvol kunnen afleveren van

...

notificatieberichten

Edu-V maakt gebruik van Events notificatieberichten zodat partijen berichten asynchroon kunnen verwerkeneen stand real-time kunnen bijwerken. Hierbij is het de intentie dat alle berichtennotificatieberichten, indien deze correct zijn verstuurd, door de Ontvangende partij worden geaccepteerd. Het niet accepteren van een bericht notificatiebericht kan twee oorzaken hebben:

1. De Ontvanger Afnemer ontvangt het berichtnotificatiebericht, maar kan deze om diverse redenen niet verder verwerken.

2. De Ontvangende partij Afnemer is niet beschikbaar om het bericht notificatiebericht te ontvangen. Dit kan bijvoorbeeld betekenen dat de Ontvanger Afnemer onderhoud uitvoert of overloaded is. In dat geval geldt het volgende protocol:

   1. De Verzender Bron doet nog drie pogingen om het bericht notificatiebericht te versturen: na 1 minuut, na 5 minuten en na 1 uur.

   2. Zodra het na de derde poging niet mogelijk is om het bericht notificatiebericht te versturen dan pauzeert de Verzender Bron het versturen van berichten notificatieberichten naar deze Ontvanger Afnemer voor een periode van 24 uur.

   3. Indien er nieuwe wijzigingen optreden in de periode dat de Verzender Bron de berichten probeert te versturen of de berichtenstroom heeft gepauzeerd, dan worden deze als nieuwe berichten notificatieberichten toegevoegd aan de queue. Het is niet zo dat tussenliggende berichten notificatieberichten over hetzelfde object niet meer verstuurd hoeven te worden. Het is de verantwoordelijkheid van de Ontvanger Afnemer om berichten notificatieberichten correct te verwerken. Ieder bericht heeft een datumstempel (created) waardoor de Ontvanger Afnemer de actuele versie van het object kan verwerken.

Technisch: APIs

De berichteninfrastructuur Het transactiepatroon Abonneren op wijzigingen middels notificaties maakt gebruik van de volgende APIsAPI:

• Events Notifications API

...

Release notes