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 en Georkestreerde uitwisseling gebruiken berichten, vaak wel events genoemd. Deze berichten worden synchroon verzonden en asynchroon verwerkt. Bij de 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 Verzender als Ontvanger, ter illustratie:

• Een Leermiddelenaanbieder kan door een Bevraging bij de Administratiesysteemaanbieder gegevens ophalen.

• Een Leermiddelenaanbieder kan door een Melding-bevestiging ook data bij een Leerportaalaanbieder 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:

Berichteninfrastructuur: Abonneren op wijzigingen middels notificaties

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 Abonneren op wijzigingen middels notificaties.

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

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

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

Berichteninfrastructuur: 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 uitwisseling.

In een 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 /events. 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.

Operationeel: Afspraken bij niet succesvol kunnen afleveren van berichten

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

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

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

   1. De Verzender doet nog drie pogingen om het bericht 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 te versturen dan pauzeert de Verzender het versturen van berichten naar deze Ontvanger voor een periode van 24 uur.

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

Technisch: APIs

De berichteninfrastructuur maakt gebruik van de volgende APIs:

• Events API

Release notes