Versturen en ontvangen van berichten

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 en Ontvanger, ter illustratie:

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

• Een referentiecomponent Gebruiksomgeving digitaal leermateriaal kan door een Melding-bevestiging ook data bij een 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 de werking van het gebruik van events nader toegelicht:

Berichteninfrastructuur: Abonneren op wijzigingen middels notificaties

In de gegevensuitwisseling is er sprake van een Bron en een Afnemer. 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.

Open

Figuur 1. Berichteninfrastructuur voor Abonneren op wijzigingen middels notificaties

In de toelichting op de figuur starten we linksboven vanuit het perspectief van de Bron. 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 Afnemers wordt gestuurd. Dit 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 Bron de mogelijkheid om notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de Bron te optimaliseren. Alle verzonden notificatieberichten worden door de Bron opgeslagen in een database Send Events.

Aan de zijde van de Afnemer komen alle notificatieberichten synchroon binnen op het POST endpoint /notificaties. Vanuit dit endpoint worden de notificatieberichten op de component Event receive queue gezet. Dit biedt de Afnemer de mogelijkheid om notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de Afnemer te optimaliseren. Vanuit de Event receive queue worden de 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 Bron opgehaald en verwerkt. De wijziging in de entiteit wordt doorgevoerd in de database van de Entiteit aan de zijde van de Afnemer. Alle ontvangen notificatieberichten worden door de Afnemer opgeslagen in een database Received Events.

Het kan voorkomen dat de Afnemer tijdelijk niet beschikbaar is. In dat geval is de Bron herhaaldelijk niet in staat om het notificatiebericht af te leveren op het POST endpoint van de Afnemer. Zodra de Afnemer weer online komt en berichten ontvangt kan de Event Processor van de Afnemer bij de Bron navragen of er notificatieberichten gemist zijn. De Event Processor gebruikt hiervoor de component Event Client. Deze Event Client bevraagt een GET endpoint aan de zijde van de Bron en verzamelt zo alle 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 Asynchrone of georkestreerde uitwisseling.

Open

Figuur 2. Berichteninfrastructuur voor 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 component Event processor van de Ontvanger definieert een bevestigingsbericht en zet deze op zijn component Event send queue. Van daaruit wordt het bevestigingsbericht via de component Event notifier naar de oorspronkelijke Verzender gestuurd. Alle verzonden bevestigingsberichten worden opgeslagen in de database Send Confirmations.

De oorspronkelijke Verzender ontvangt een bevestigingsbericht op het POST endpoint /entity/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 notificatieberichten zodat partijen een stand real-time kunnen bijwerken. Hierbij is het de intentie dat alle notificatieberichten, indien deze correct zijn verstuurd, door de Ontvangende partij worden geaccepteerd. Het niet accepteren van een notificatiebericht kan twee oorzaken hebben:

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

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

   1. De Bron doet nog drie pogingen om het 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 notificatiebericht te versturen dan pauzeert de Bron het versturen van notificatieberichten naar deze Afnemer voor een periode van 24 uur.

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

Technisch: APIs

Het transactiepatroon Abonneren op wijzigingen middels notificaties maakt gebruik van de volgende API:

• Notifications API

Release notes