Titel | Versturen en ontvangen van berichten | ||||||||||||||||||||||
Status |
| ||||||||||||||||||||||
Stadium |
| ||||||||||||||||||||||
Versie | 0.0.45 | ||||||||||||||||||||||
Datum | 25 Mei 13 Juli 2023 | ||||||||||||||||||||||
Auteur | Architectenraad Edu-V | ||||||||||||||||||||||
Acties | Architectenraad Edu-V
|
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 Verzender als Ontvanger, ter illustratie:
...
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 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 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 de mogelijkheid om berichten notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de Verzender te optimaliseren. Alle verzonden berichten notificatieberichten worden door de Verzender opgeslagen in een database Send Events.
Aan de zijde van de Ontvanger 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 de mogelijkheid om berichten notificatieberichten 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 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 opgehaald en verwerkt. De wijziging in de identiteit entiteit wordt doorgevoerd in de database van de Entiteit aan de zijde van de Ontvanger. Alle ontvangen berichten notificatieberichten 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 notificatiebericht 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 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 en verzamelt zo alle berichten notificatieberichten aangemaakt na een bepaalde tijdstempel.
...
Een Ontvanger kan zich abonneren op wijzigingen bij een Verzender 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.
...
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 component Licentiekantoor een PUT endpoint /entitlements en de Faciliteit voor leveren (of arrangeren) van leermiddelen 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:
De Ontvanger ontvangt het berichtnotificatiebericht, maar kan deze om diverse redenen niet verder verwerken.
De Ontvangende partij is niet beschikbaar om het bericht notificatiebericht te ontvangen. Dit kan bijvoorbeeld betekenen dat de Ontvanger onderhoud uitvoert of overloaded is. In dat geval geldt het volgende protocol:
De Verzender doet nog drie pogingen om het bericht notificatiebericht te versturen: na 1 minuut, na 5 minuten en na 1 uur.
Zodra het na de derde poging niet mogelijk is om het bericht notificatiebericht te versturen dan pauzeert de Verzender het versturen van berichten notificatieberichten naar deze Ontvanger voor een periode van 24 uur.
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 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 om berichten notificatieberichten correct te verwerken. Ieder bericht heeft een datumstempel (created) waardoor de Ontvanger 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:
...
Release notes
Deze uitwerking is gebaseerd op basis van de volgende stappen:
0.0.1: De documentatie is overgenomen vanuit het SEM Ecosysteem. De terminologie is in lijn gebracht met de gegevensdefinities van Edu-V.
0.0.2: Tijdens de werkconferentie van de Architectenraad Edu-V op 18 april is gesproken over de draft uitwerking. Dit heeft geleid tot een aanpassing op de introductie en een splitsing in de berichteninfrastructuur voor de transactiepatronen Abonneren op wijzigingen middels notificaties en Georkestreerde uitwisseling.
0.0.3: Events API verplaatst naar sectie APIs en draft documentatie toegevoegd.
0.0.4: De uitwerking is besproken tijdens de Architectenraad Edu-V van 24 mei 2023. De Architectenraad Edu-V stemt in met deze uitwerking om te beproeven in de POCs. In aanloop naar het publiceren van de 100% specificatie september 2023 wordt de Events API nog aangepast conform de transactiepatronen van Edu-V.
0.0.5: Berichteninfrastructuur is aangepast naar het transactiepatroon Abonneren op wijzigingen middels notificaties. De Events API betreft een abonnee en notificatieservice om notificaties van wijzigingen in een stand te krijgen. In de asynchrone en georkestreerde uitwisseling kan ook gebruik worden van gemaakt van een Event Driven Architectuur. Echter alle (bevestiging)berichten worden via PUT endpoints per objecttype in een eigen endpoint aangeboden aan de Ontvangende partij. Dit stelt deze partij in staat om op dit endpoint een schemavalidatie uit te voeren en vervolgens het bericht door te zetten op de Event Queue waarna deze opgepakt kunnen worden door de Event mediator of Event processor.