Status | ||
---|---|---|
|
Titel | Versturen en ontvangen van berichten | |
Status |
|
title | DRAFT |
---|
|
|
Stadium
Status | ||||
---|---|---|---|---|
|
Status | ||
---|---|---|
|
Status | ||
---|---|---|
|
|
| ||
Versie | 0.0. |
6 |
Datum |
5 December 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.
...
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.
...
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 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 notificatieberichten te bufferen en daarmee de performance van de gegevensuitwisseling aan de zijde van de Verzender Bron te optimaliseren. Alle verzonden notificatieberichten worden door de Verzender Bron opgeslagen in een database Send Events.
Aan de zijde van de Ontvanger 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 Ontvanger Afnemer de mogelijkheid om 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 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 entiteit wordt doorgevoerd in de database van de Entiteit aan de zijde van de OntvangerAfnemer. Alle ontvangen 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 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 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 notificatieberichten aangemaakt na een bepaalde tijdstempel.
Een Ontvanger Afnemer kan zich abonneren op wijzigingen bij een Verzender Bron via het POST endpoint /subscribe.
...
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.
...
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 referentiecomponent Licentieregistratie een PUT endpoint /entitlements en de Faciliteit voor leveren (of arrangeren) van leermiddelen referentiecomponent Aanspraakmanager een PUT endpoint /entitlements/confirmations.
...
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:
De Ontvanger Afnemer ontvangt het notificatiebericht, maar kan deze om diverse redenen niet verder verwerken.
De Ontvangende partij Afnemer is niet beschikbaar om het notificatiebericht te ontvangen. Dit kan bijvoorbeeld betekenen dat de Ontvanger Afnemer onderhoud uitvoert of overloaded is. In dat geval geldt het volgende protocol:
De Verzender Bron doet nog drie pogingen om het notificatiebericht te versturen: na 1 minuut, na 5 minuten en na 1 uur.
Zodra het na de derde poging niet mogelijk is om het notificatiebericht te versturen dan pauzeert de Verzender Bron het versturen van notificatieberichten naar deze Ontvanger Afnemer voor een periode van 24 uur.
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 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 Ontvanger Afnemer om notificatieberichten correct te verwerken. Ieder bericht heeft een datumstempel (created) waardoor de Ontvanger Afnemer de actuele versie van het object kan verwerken.
...
Het transactiepatroon Abonneren op wijzigingen middels notificaties maakt gebruik van de volgende API:
...
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.
0.0.6: Documentatie aangepast op basis van wijziging in transactierollen Bron, Afnemer, Verzender en Ontvanger.