Notificatie service

Xedule Notificatie service – Functionele documentatie

Inleiding

De Xedule Notificatie service maakt het mogelijk om automatisch een bericht te ontvangen zodra er in Xedule iets wijzigt. Xedule verstuurt die berichten naar een webservice die de instelling zelf beschikbaar stelt, en doet dat alleen voor de entiteiten en attributen die daarvoor zijn ingericht.

Een notificatiebericht meldt uitsluitend dát er iets is gewijzigd: om welke organisatorische eenheid het gaat, welk soort object het betreft, welk object het is, welk attribuut is geraakt en of het om een nieuw, gewijzigd of verwijderd object gaat. Het bericht bevat geen inhoudelijke gegevens. Het afnemende systeem gebruikt de notificatie dus als signaal en haalt de actuele gegevens daarna zelf op, bijvoorbeeld via de beschikbare Xedule-koppelingen.

De module wordt via support aangevraagd en daarna ingericht onder Beheer, Configuratie, Notificaties. Dit document beschrijft die inrichting, de opbouw en inhoud van een notificatiebericht, het moment waarop berichten worden verstuurd en het gedrag bij fouten. Het is bedoeld voor functioneel beheerders en voor de partij die de ontvangende webservice bouwt.

Randvoorwaarden en functionele eisen

Technische randvoorwaarden

Aan de kant van de instelling geldt het volgende:

• De instelling stelt zelf een webservice beschikbaar die het contract van de Xedule Notificatie service implementeert. Dat contract bestaat uit één bewerking, NotifyEntity, die één notificatiebericht ontvangt en een ja/nee-waarde teruggeeft. De teruggegeven waarde wordt door Xedule niet gebruikt.
• De berichten worden als SOAP-bericht over HTTP verstuurd met de methode POST; de inhoud is XML. De bewerking wordt aangeroepen met de actie http://tempuri.org/IXeduleNotificationService/NotifyEntity. Volledige voorbeelden en de servicedefinitie staan in hoofdstuk “Voorbeelden van de berichten”.
• De webservice moet vanaf de Xedule-omgeving bereikbaar zijn en binnen een minuut antwoorden. Duurt het langer, dan wordt de notificatie als mislukt beschouwd.
• Een mislukte notificatie wordt niet bewaard en niet opnieuw aangeboden (zie hoofdstuk “Foutafhandeling en meldingen”). De beschikbaarheid van de eigen webservice bepaalt daarmee of alle wijzigingen doorkomen.
• Elke notificatie wordt als een eigen bericht verstuurd; berichten worden niet gebundeld.
• Omdat een notificatie geen inhoudelijke gegevens bevat, is voor het ophalen van de gewijzigde gegevens een aanvullende koppeling op Xedule nodig.
• De webservice mag beveiligd zijn met een vast token, met OAuth 2.0 (client credentials) of met een gebruikersnaam en wachtwoord; de mogelijkheden staan in paragraaf “Verbinding en authenticatie”.

Functionele inrichtingseisen in Xedule

• De notificatiemodule wordt via support aangevraagd en beschikbaar gesteld.
• Voor het openen van de configuratiepagina is het recht op de actie Beheer notificaties nodig; voor het opslaan van wijzigingen daarnaast het recht om configuratie te beheren.
• Notificaties komen uitsluitend uit de actuele scenario’s van de organisatorische eenheden. Wijzigingen in een niet-actueel scenario leiden niet tot een notificatie.
• De inrichting is organisatiebreed: dezelfde inrichting geldt voor alle organisatorische eenheden. Elk bericht bevat wel de organisatorische eenheid waarin de wijziging plaatsvond, zodat de ontvanger daar zelf op kan filteren.
• Entiteiten en attributen worden vastgelegd met hun datamodelbenaming, inclusief hoofdlettergebruik. Xedule controleert die benamingen niet: een onjuiste naam levert geen melding op, maar simpelweg geen notificaties.

De configuratiepagina Notificaties

De inrichting gebeurt onder Beheer, Configuratie, Notificaties. De pagina bestaat uit één of meer blokken. Elk blok beschrijft één notificatieservice: het adres van de eigen webservice met de bijbehorende authenticatiegegevens, plus de entiteiten en attributen waarop een notificatie gewenst is. Wat er per entiteit precies wordt verstuurd en wanneer, staat in hoofdstuk “Werking van de Xedule Notificatie service”.

Een gewijzigde inrichting wordt bij het opslaan direct actief; een herstart is niet nodig. Het wijzigen van tokens of wachtwoorden wordt vastgelegd in de logging van configuratiewijzigingen, zonder de waarden zelf (zie hoofdstuk “Foutafhandeling en meldingen”).

Verbinding en authenticatie

Veld	Waarde of voorbeeld	Toelichting
Server	https://school.nl/notificaties.svc	Het adres van de eigen webservice waar de notificatieberichten naartoe worden gestuurd. Wordt gecontroleerd op een geldig adresformaat.
Token	Bearer abc123…	Een vaste waarde die als Authorization-header wordt meegestuurd. De waarde wordt letterlijk overgenomen, dus een voorvoegsel als "Bearer " hoort in het veld zelf te staan. Blijft ongebruikt zodra Token Server is gevuld.
Token Server	https://login.school.nl/token	Het adres van de tokenserver. Is dit veld gevuld, dan haalt Xedule vóór het versturen zelf een token op en gebruikt dat als Bearer-token. Wordt gecontroleerd op een geldig adresformaat.
Client id	xedule-notificaties	De client-id voor de tokenserver. Client id en Client secret worden bij het ophalen van het token als gebruikersnaam en wachtwoord meegestuurd.
Client secret	(geheim)	Het geheim dat bij de client-id hoort.
Scope	notificaties	De scope die bij het ophalen van het token wordt meegestuurd.
Account	xedule	Gebruikersnaam. Is dit veld gevuld, dan worden gebruikersnaam en wachtwoord als netwerkgegevens op de verbinding met de webservice meegegeven; er wordt geen Authorization-header van gemaakt.
Password	(geheim)	Het wachtwoord dat bij Account hoort.
Entities	zie paragraaf “De entiteiten en attributen waarop een notificatie volgt”	De entiteiten en attributen waarop een notificatie gewenst is.

Er zijn drie manieren om de eigen webservice te beveiligen, en ze werken als volgt samen. Is Token Server gevuld, dan haalt Xedule met Client id, Client secret en Scope een nieuw token op en gebruikt dat als Authorization-header; een handmatig ingevulde waarde in Token wordt dan niet gebruikt. Is Token Server leeg en Token gevuld, dan wordt die vaste waarde als Authorization-header meegestuurd. Account en Password staan hier los van en worden, indien gevuld, altijd als netwerkgegevens meegegeven.

Er wordt geen token bewaard tussen verzendrondes: in elke ronde waarin er notificaties zijn, wordt eerst een nieuw token opgehaald. De tokenserver moet dat aantal aanvragen toestaan.

De entiteiten en attributen waarop een notificatie volgt

Bij Entities wordt vastgelegd waarop een notificatie moet volgen. Dat gebeurt met een korte opsomming van entiteiten met daarbinnen hun attributen:

Onderdeel	Invulling	Toelichting
NotifyEntity	–	Omsluit de hele opsomming: het vormt de start en het einde van de ingerichte notificaties.
Entity, met het kenmerk name	De datamodelbenaming van de entiteit, bijvoorbeeld Leeractiviteit	De entiteit waarvan notificaties gewenst zijn. De benaming is die van het datamodel zonder het voorvoegsel I, en wordt exact vergeleken (zie paragraaf “Bepalen welke wijzigingen een notificatie opleveren”).
property	De datamodelbenaming van het attribuut, bijvoorbeeld Naam	Een attribuut waarvan een wijziging tot een notificatie leidt. Per entiteit zijn meerdere attributen toegestaan.

Voorbeeldinvulling met drie entiteiten:

<NotifyEntity>

<Entity name="Leeractiviteit">

<property>Code</property>

<property>Naam</property>

<property>Opmerking</property>

</Entity>

<Entity name="Opdracht">

<property>Code</property>

<property>Naam</property>

</Entity>

<Entity name="Groep">

<property>StudentenLidVan</property>

</Entity>

</NotifyEntity>

Neem bij elke entiteit ten minste één attribuut op. Een entiteit zonder attributen verhindert het versturen van alle notificaties van die notificatieservice (zie hoofdstuk “Foutafhandeling en meldingen”). Welke rol de attributen bij het filteren spelen, staat in paragraaf “Bepalen welke wijzigingen een notificatie opleveren”.

Een tweede notificatieservice

Door een extra blok toe te voegen wordt een tweede notificatieservice ingericht, met een eigen adres, eigen authenticatiegegevens en een eigen opsomming van entiteiten. Zo kan een tweede ontvanger andere notificaties krijgen dan de eerste. Elke notificatieservice wordt onafhankelijk van de andere gefilterd en beleverd; een storing bij de één heeft geen gevolgen voor de ander. Dezelfde wijziging kan naar meerdere notificatieservices gaan wanneer die dezelfde entiteit hebben ingericht.

Worden alle blokken verwijderd en wordt de pagina zo opgeslagen, dan blijft de laatst bekende inrichting actief. Om notificaties te beëindigen, is het daarom nodig de niet meer gewenste entiteiten uit de inrichting te halen.

Werking van de Xedule Notificatie service

Inhoud van het notificatiebericht

Elk notificatiebericht wordt met de bewerking NotifyEntity naar het adres uit het veld Server van de betreffende notificatieservice gestuurd. Het bericht bevat de volgende velden:

Veld (exacte benaming)	Betekenis	Herkomst in Xedule	Verwerking / bijzonderheden
OrganisatorischeEenheidId	De organisatorische eenheid waarin de wijziging plaatsvond.	Het actuele scenario van de organisatorische eenheid.	Altijd gevuld. Filteren op organisatorische eenheid doet de ontvanger zelf.
EntityId	Het gewijzigde object.	De identificatie van het object.	Bij een wijziging die niet aan één object hangt, blijft de waarde 0.
EntityType	Het soort object dat is gewijzigd, bijvoorbeeld Leeractiviteit.	De datamodelbenaming van de entiteit, zonder het voorvoegsel I.	Moet exact overeenkomen met een ingerichte entiteit (zie paragraaf “Bepalen welke wijzigingen een notificatie opleveren”).
EntityProperty	Het attribuut waarop de wijziging betrekking heeft.	De datamodelbenaming van het attribuut.	Leeg bij een nieuw of verwijderd object. Bij samengevoegde wijzigingen wordt één van de gewijzigde attributen meegegeven die in de inrichting staan (zie paragraaf “Verzendmoment en het samenvoegen van wijzigingen”).
Operation	De bewerking op het object: Create, Update of Delete.	Afgeleid van de actie in Xedule.	Zie paragraaf “Het soort bewerking in een notificatie”.
RelationIds	De objecten aan de andere kant van een gewijzigde relatie.	De identificaties van de gerelateerde objecten.	Leeg wanneer de wijziging geen relatie betreft. Bij samengevoegde wijzigingen staan alle betrokken objecten in deze lijst.
RelationOperation	De bewerking op de relatie: None, Create, Update of Delete.	Afgeleid van de actie in Xedule.	None wanneer er geen relatie is gewijzigd; zie paragraaf “Het soort bewerking in een notificatie”.

Omdat het bericht alleen verwijzingen bevat en geen waarden, haalt de ontvanger na een notificatie de actuele gegevens van het genoemde object zelf op.

Het soort bewerking in een notificatie

Het veld Operation volgt uit de actie die in Xedule is uitgevoerd. Een nieuw object levert Create op en een verwijderd object Delete. Wordt alleen een attribuut van een bestaand object geraakt, dan is de bewerking altijd Update, ook wanneer daarbij een waarde wordt toegevoegd of verwijderd.

De bewerking in het veld Operation, afhankelijk van de actie in Xedule.

Raakt de wijziging een relatie tussen twee objecten, bijvoorbeeld een student die lid wordt van een groep, dan staat in RelationIds het object aan de andere kant van die relatie en geeft RelationOperation aan of die relatie is toegevoegd, gewijzigd of verwijderd. Is er geen relatie in het spel, dan is RelationOperation gelijk aan None en blijft RelationIds leeg.

Voor wijzigingen in het tijdsraster geldt een uitzondering: die worden gemeld als een wijziging op het object waartoe het raster hoort, met TimeslotSet als attribuut.

Verzendmoment en het samenvoegen van wijzigingen

Notificaties worden niet op het moment van opslaan verstuurd. Xedule verwerkt de wijzigingen in een cyclus die standaard elke 30 seconden loopt; de notificaties van een wijziging gaan in de eerstvolgende cyclus mee. Het versturen gebeurt op de achtergrond en houdt het werken in Xedule niet op.

Van een wijziging in Xedule naar een bericht op de eigen webservice.

Binnen één cyclus wordt eerst elke wijziging afzonderlijk beoordeeld volgens de regels in paragraaf “Bepalen welke wijzigingen een notificatie opleveren”. Alleen de wijzigingen die daarbij overblijven, worden samengevoegd: wijzigingen die dezelfde organisatorische eenheid, hetzelfde object, hetzelfde soort bewerking en dezelfde relatiebewerking betreffen, komen samen in één notificatie. Van die samengevoegde wijzigingen wordt één attribuutnaam in EntityProperty meegegeven, altijd een attribuut dat in de inrichting staat, terwijl de identificaties van alle betrokken relaties samen in RelationIds komen.

Dat samenvoegen heeft één gevolg dat bij het inrichten van belang is. Wijzigen meerdere ingerichte attributen van hetzelfde object binnen één cyclus, dan komt er één bericht waarin niet elk gewijzigd attribuut is terug te vinden; de ontvanger moet daarom altijd de actuele gegevens van het object ophalen en niet op EntityProperty alleen vertrouwen. Omdat het filteren vóór het samenvoegen gebeurt, levert een wijziging van een ingericht attribuut altijd een notificatie op, ook wanneer in dezelfde cyclus andere, niet ingerichte attributen van hetzelfde object wijzigen. Dat geldt ook voor de gegevens die Xedule bij elke wijziging automatisch bijwerkt, zoals het tijdstip en de gebruiker van de laatste wijziging: die verhinderen geen notificatie op een ingericht attribuut.

Bepalen welke wijzigingen een notificatie opleveren

Per notificatieservice wordt afzonderlijk bepaald welke wijzigingen worden verstuurd. Die beoordeling vindt per afzonderlijke wijziging plaats, vóór het samenvoegen uit paragraaf “Verzendmoment en het samenvoegen van wijzigingen”. Daarbij gelden de volgende regels:

• De naam van de entiteit moet exact overeenkomen met een ingerichte entiteit, inclusief hoofdlettergebruik. Jokertekens zijn niet mogelijk.
• Bij een nieuw object (Create) en een verwijderd object (Delete) telt alleen de naam van de entiteit; de ingerichte attributen spelen dan geen rol.
• Bij een wijziging (Update) moet het gewijzigde attribuut daarnaast exact overeenkomen met een van de ingerichte attributen van die entiteit.
• Een wijziging op een entiteit die niet is ingericht, levert geen notificatie en geen melding op.

Beoordeling van een wijziging per notificatieservice.

Voorbeelden van de berichten

Alle notificaties hebben dezelfde opbouw: een SOAP-envelope met daarin de bewerking NotifyEntity en één notificatie. Alleen de waarden verschillen per soort wijziging. De voorbeelden in dit hoofdstuk dekken samen alle berichten die de Xedule Notificatie service kan versturen; met deze opbouw is de ontvangende webservice volledig te bouwen. Een variant in JSON bestaat niet: het bericht is altijd XML.

Naast deze voorbeelden is er een servicedefinitie in WSDL-vorm, XeduleNotificationService.wsdl, die via support beschikbaar is. Daarin liggen de bewerking, het schema van het notificatiebericht en het antwoord vast, zodat de ontvangende webservice er rechtstreeks uit te genereren is. Het adres in de definitie is een voorbeeld en wordt vervangen door het eigen adres, hetzelfde adres dat in Xedule in het veld Server wordt vastgelegd.

Opbouw van een aanroep

Onderstaand voorbeeld is een volledige aanroep voor de meest voorkomende situatie: een gewijzigd attribuut van een bestaand object. De regel met Authorization is alleen aanwezig wanneer een token of een tokenserver is ingericht (zie paragraaf “Verbinding en authenticatie”).

POST /notificaties.svc HTTP/1.1

Host: school.nl

Content-Type: text/xml; charset=utf-8

SOAPAction: "http://tempuri.org/IXeduleNotificationService/NotifyEntity"

Authorization: Bearer abc123...

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<NotifyEntity xmlns="http://tempuri.org/">

<notification

xmlns:a="http://schemas.datacontract.org/2004/07/Api.Ipc.Entities"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:EntityId>1234567</a:EntityId>

<a:EntityProperty>Naam</a:EntityProperty>

<a:EntityType>Leeractiviteit</a:EntityType>

<a:Operation>Update</a:Operation>

<a:OrganisatorischeEenheidId>42</a:OrganisatorischeEenheidId>

<a:RelationIds/>

<a:RelationOperation>None</a:RelationOperation>

</notification>

</NotifyEntity>

</s:Body>

</s:Envelope>

De betekenis van de afzonderlijke velden staat in paragraaf “Inhoud van het notificatiebericht”. De voorvoegsels s, a en i zijn vrij te kiezen; de bijbehorende naamruimten staan vast.

De overige soorten berichten

In de volgende voorbeelden is alleen het onderdeel notification opgenomen; de envelope, de kopregels en de naamruimten zijn gelijk aan die in paragraaf “Opbouw van een aanroep”. Een nieuw object levert Create op en heeft geen gewijzigd attribuut:

<a:EntityId>1234568</a:EntityId>

<a:EntityProperty i:nil="true"/>

<a:EntityType>Opdracht</a:EntityType>

<a:Operation>Create</a:Operation>

<a:OrganisatorischeEenheidId>42</a:OrganisatorischeEenheidId>

<a:RelationIds/>

<a:RelationOperation>None</a:RelationOperation>

Een verwijderd object is hetzelfde bericht met Delete als bewerking:

<a:EntityId>1234568</a:EntityId>

<a:EntityProperty i:nil="true"/>

<a:EntityType>Opdracht</a:EntityType>

<a:Operation>Delete</a:Operation>

<a:OrganisatorischeEenheidId>42</a:OrganisatorischeEenheidId>

<a:RelationIds/>

<a:RelationOperation>None</a:RelationOperation>

Betreft de wijziging een relatie, bijvoorbeeld een student die lid wordt van een groep, dan staat het object aan de andere kant van de relatie in RelationIds en geeft RelationOperation aan wat er met die relatie is gebeurd. Het gewijzigde attribuut is dan het attribuut waarmee de relatie is vastgelegd:

<a:EntityId>55010</a:EntityId>

<a:EntityProperty>StudentenLidVan</a:EntityProperty>

<a:EntityType>Groep</a:EntityType>

<a:Operation>Update</a:Operation>

<a:OrganisatorischeEenheidId>42</a:OrganisatorischeEenheidId>

<a:RelationIds

xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">

<b:int>77001</b:int>

</a:RelationIds>

<a:RelationOperation>Create</a:RelationOperation>

Worden binnen dezelfde cyclus meerdere relaties van hetzelfde object op dezelfde manier gewijzigd, dan komen ze samengevoegd in één bericht (zie paragraaf “Verzendmoment en het samenvoegen van wijzigingen”). RelationIds bevat dan meerdere objecten, en bij een verwijderde relatie is de bewerking Delete:

<a:EntityId>55010</a:EntityId>

<a:EntityProperty>StudentenLidVan</a:EntityProperty>

<a:EntityType>Groep</a:EntityType>

<a:Operation>Update</a:Operation>

<a:OrganisatorischeEenheidId>42</a:OrganisatorischeEenheidId>

<a:RelationIds

xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">

<b:int>77001</b:int>

<b:int>77002</b:int>

</a:RelationIds>

<a:RelationOperation>Delete</a:RelationOperation>

Het antwoord van de webservice

De webservice antwoordt met HTTP-status 200 en een envelope met de uitkomst van de bewerking. De waarde zelf wordt door Xedule niet gebruikt; alleen het uitblijven van een antwoord, een HTTP-foutstatus of een SOAP-fout wordt als een mislukte notificatie gezien (zie hoofdstuk “Foutafhandeling en meldingen”).

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">

<s:Body>

<NotifyEntityResponse xmlns="http://tempuri.org/">

<NotifyEntityResult>true</NotifyEntityResult>

</NotifyEntityResponse>

</s:Body>

</s:Envelope>

Aandachtspunten bij het inlezen

• De elementen staan in alfabetische volgorde binnen notification. Lees ze op naam en niet op positie, zodat een toekomstige uitbreiding geen gevolgen heeft.
• Een veld zonder waarde kan als leeg element of met het kenmerk i:nil="true" voorkomen. Behandel beide vormen als "geen waarde".
• RelationIds is een lijst van getallen in een eigen naamruimte, met per object een element int. Zonder gewijzigde relatie is de lijst leeg.
• Operation en RelationOperation bevatten altijd een van de vaste waarden None, Create, Update of Delete; behandel een onbekende waarde als "niet ondersteund" in plaats van als fout.
• Negeer elementen die de webservice niet kent, zodat een uitbreiding van het bericht niet tot een fout leidt.
• Dezelfde notificatie kan in uitzonderlijke gevallen meer dan eens aankomen; verwerk een bericht daarom idempotent.

Foutafhandeling en meldingen

De Xedule Notificatie service kent geen wachtrij en geen herhaalmechanisme. Een notificatie die niet kan worden afgeleverd, is daarmee definitief niet gemeld; het is aan de ontvangende partij om periodiek te controleren of de eigen gegevens nog gelijk zijn aan die in Xedule. Alle verstuurde notificaties en alle fouten worden vastgelegd in de logging van de Xedule-omgeving, die via support is op te vragen. Per verstuurde notificatie wordt vastgelegd om welke organisatorische eenheid, welk object, welk soort object en welke bewerking het ging.

Situatie	Gedrag van de notificatieservice	Wat te doen
De eigen webservice is niet bereikbaar, geeft een fout terug of antwoordt niet binnen een minuut	De fout wordt vastgelegd in de logging. De notificatie wordt niet opnieuw aangeboden en de resterende notificaties voor diezelfde notificatieservice worden in die cyclus niet meer verstuurd. Andere notificatieservices worden wel afgehandeld.	Controleer de beschikbaarheid van de eigen webservice en het adres in het veld Server.
Er kan geen token bij de tokenserver worden opgehaald	De fout wordt vastgelegd in de logging; voor die notificatieservice worden in die cyclus geen notificaties verstuurd.	Controleer Token Server, Client id, Client secret en Scope (zie paragraaf “Verbinding en authenticatie”).
Bij een entiteit is geen enkel attribuut ingericht	Voor die notificatieservice worden geen notificaties verstuurd zolang die inrichting bestaat.	Neem bij elke entiteit ten minste één attribuut op (zie paragraaf “De entiteiten en attributen waarop een notificatie volgt”).
De naam van een entiteit of attribuut is onjuist gespeld	De wijziging wordt stilzwijgend overgeslagen; er volgt geen melding.	Controleer de datamodelbenaming en het hoofdlettergebruik.
Er is geen inrichting aanwezig	Er worden geen notificaties verstuurd; dit wordt in de logging vastgelegd.	Richt ten minste één notificatieservice in (zie hoofdstuk “De configuratiepagina Notificaties”).
In Server of Token Server staat geen geldig adres	De configuratiepagina accepteert de waarde niet en toont de melding „De invoer van dit veld is niet in het correcte formaat.”	Vul een volledig adres in, inclusief protocol.
Een token of wachtwoord is aangepast	De wijziging wordt vastgelegd in de logging van configuratiewijzigingen met de tekst „Token(s) en/of wachtwoord(en) aangepast”. De waarden zelf worden niet vastgelegd.	–