Getrapte overdracht

Stappen

1. Verzoek om de structuur, leerlinggegevens of leerkrachtgegevens

   De EA  stuurt aan het LAS
   

   1. eerst het verzoek om de structuur van de leerlinggegevens,
   2. dan het verzoek om gegevens van de leerlingen van geselecteerde groepen en
   3. als laatste eventueel het verzoek om gegevens van leerkrachten van geselecteerde groepen.

2. Controle bij de aanroep

   Het LAS controleert bij de aanroep:

   • Of de authenticatie van de externe aanbieder correct is.
   • Of de autorisatiesleutel correct is en hoort bij de externe aanbieder.
   • Of de meegegeven school-identificatie valt onder de autorisatiesleutel.

   Als één van de controles faalt, mag het bericht niet verwerkt worden.

3. Controle bij de overdracht

   Het LAS controleert bij de ontvangst van het bericht:

   • Het binnengekomen bericht moet valide zijn volgens de in de WSDL gerefereerde schema’s.
   • Het in het bericht opgenomen XSD-versie moet overeenkomen met een door het systeem ondersteunde XSD-versie.
   • De berichtaanmaakdatum van het bericht moet later zijn dan de berichtaanmaakdatum van het voorgaande bericht (dit uiteraard m.u.v. het allereerste bericht).
   • Indien er vocabulaire-gebonden velden in het bericht staan en de vocabulaire is bekend of kan achterhaald worden, moet het systeem controleren of de veldwaardes met de in de vocabulaire opgenomen waardes kloppen.

   Als één van de controles faalt, mag het bericht niet verder verwerkt worden. Indien de VDEX niet achterhaald kan worden, leidt dit niet tot een fout, maar wordt de waarde van het veld "as is" geaccepteerd.

4. Verwerking van verzoek

   Het LAS heeft een keuze als in het verzoekbericht de datum/tijd van de laatste ontvangen gegevens is opgenomen:

   • Het LAS negeert de meegestuurde datum en stuurt de de leerlinggegevens (structuur, leerling of leerkracht), of deze nu is aangepast of niet. Bijvoorbeeld als het LAS zodanig is ingericht dat het intern niet kan achterhalen of er sinds de aangegeven datum mutaties zijn geweest.
   • Het LAS constateert dat er sinds de meegestuurde datum wijzigingen hebben plaatsgevonden in de leerlinggegevens. Het stuurt de leerlinggegevens.
   • Het LAS constateert dat er sinds de meegestuurde datum geen wijzigingen in de leerlinggegevens zijn geweest en stuurt een (kort) “gegevens up-to-date” bericht terug.

   Als het LAS geen gegevens heeft, bijvoorbeeld als het schooljaar te ver in de toekomst ligt:

   • Het LAS stuurt een “geen gegevens”-bericht terug.

   Het ophalen van leerling- en leerkrachtgegevens gaat in de getrapte versie op basis van een lijst met groepen.

   • Leerlingen en leerkrachten die aan geen enkele groep gebonden zijn, worden opgevraagd als er geen groepsidentificatie mee is geven in het verzoek.
   • Als er in een verzoek naar groepen wordt gerefereerd die niet bestaan, worden ze genegeerd. Dit is geen fout, want tussen het ophalen van de structuur en het ophalen van de inhoud zit tijd. In die tijd zou de groep verwijderd kunnen zijn. Het opvragen van gegevens van een groep die niet bestaat mag daarom niet tot een fout leiden.

   Als er in het berichtenverkeer binnen deze afspraak fouten optreden, dan moet de SOAP-webserver dit melden met behulp van een standaard  SOAP-foutbericht.

5. Antwoord met de structuur, leerlinggegevens of leerkrachtgegevens

   Afhankelijk van het verzoek verstuurt het LAS aan de EA

   • het antwoord met de structuur van de leerlinggegevens, 
   • het antwoord met de gegevens van leerlingen of
   • het antwoord met de gegevens van leerkrachten.

6. Controle bij de overdracht

   De EA controleert bij de ontvangst van het bericht:

   • Het binnengekomen bericht moet valide zijn volgens de in de WSDL gerefereerde schema’s.
   • Het in het bericht opgenomen XSD-versie moet overeenkomen met een door het systeem ondersteunde XSD-versie.
   • De berichtaanmaakdatum van het bericht moet later zijn dan de berichtaanmaakdatum van het voorgaande bericht (dit uiteraard m.u.v. het allereerste bericht).
   • Indien er vocabulaire-gebonden velden in het bericht staan en de vocabulaire is bekend of kan achterhaald worden, moet het systeem controleren of de veldwaardes met de in de vocabulaire opgenomen waardes kloppen.

   Als één van de controles faalt, mag het bericht niet verder verwerkt worden. Indien de VDEX niet achterhaald kan worden, leidt dit niet tot een fout, maar wordt de waarde van het veld "as is" geaccepteerd.

7. Controle bij de overdracht van leerlinggegevens

   De EA controleert bij de ontvangst van het bericht met leerlinggegevens:

   • De in het antwoordbericht opgenomen school-identificatie moet overeenkomten met de in de aanvraag verzonden school-identificatie.
   • Voor de leerling- en leerkrachtgegevens geldt:
     • Er is óf een achternaam (evt. aangevuld met voorvoegsels, voorletters en/of roepnaam) óf alleen een roepnaam.
     • Als er geen achternaam is dan mogen voorvoegsel en voorletters niet ingevuld zijn en moet er een roepnaam zijn.

8. Verwerking van leerlinggegevens

   Er is sprake van nieuwe gegevens als de EA voor deze school/dit schooljaar-combinatie nog geen leerlinggegevens heeft ontvangen.

   • Sla de gegevens op.
   • Onthoud de berichtaanmaakdatum en -tijd zoals deze in de berichtgegevens is opgenomen.

   Er is sprake van wijzigingen als de EA voor deze school/dit schooljaar-combinatie al eerder leerlinggegevens heeft ontvangen.

   • Indien er leerling-, leerkracht- of groepsgegevens zijn waarvan de identifier nog niet bekend is, maak deze dan aan.
   • Indien er leerling-, leerkracht- of groepsgegevens zijn waarvan de identifier al wel bekend is, werk deze dan bij. Indien er bij deze gegevens een individuele mutatiedatum aanwezig is, mag hiermee rekening gehouden worden.
   • Leerling-, leerkracht- of groepsgegevens die bij eerdere verzending wel maar nu niet meer aanwezig zijn, moeten beschouwd worden als verwijderd. Het is aan de EA en buiten de scope van deze afspraak hoe hiermee om te gaan (direct verwijderen, op inactief zetten etc.)
   • Onthoud de berichtaanmaakdatum en -tijd zoals deze in de berichtgegevens is opgenomen.

Implementatie webservice
Leerlinggegevensservice (getrapt)

De oorspronkelijk webservice waarmee in één keer de leerlinggegevens konden worden opgehaald, is voor het getrapt ophalen opgedeeld in drie verschillende webservices:

• Ophalen van de structuur (school- en groepsgegevens)
• Ophalen van leerlingen behorende bij een bepaalde set van groepen
• Ophalen van leerkrachten behorende bij een bepaalde set van groepen

Voor de verwerking hiervan zal het LAS de drie webservices moeten implementeren. Voor de definities van deze webservices wordt verwezen naar het bij deze aanpassing op de afspraak horende WSDL-bestand UWLR_Leerlinggegevens_v2p2.wsdl. Indien de webservices volgens het WSDL-bestand daadwerkelijk worden geïmplementeerd, zal het hierin genoemde endpoint moeten worden aangepast.

Meer informatie over webservices binnen UWLR is hier te vinden.

Protocollen voor overdracht leerlinggegevens

Bij de overdracht van leerlinggegevens worden, op verzoek van de Educatieve Applicatie (EA), alle gegevens van alle relevante leerlingen, groepen en leerkrachten van een school overgebracht vanuit het leerling administratiesysteem (LAS). Er zijn 2 varianten van ophalen van de gegevens:

• Alles-in-één: Alle gegevens in één keer ophalen.
• Getrapt: De gegevens in blokjes ophalen.

Een zeer belangrijke keuze hierbij is dat het niet verplicht is beide protocollen te implementeren. Een EA of LAS moet één van de twee, of beide, overdrachtsmanieren ondersteunen. Het gevolg daarvan is dat niet iedere EA binnen deze standaard met ieder LAS zal kunnen praten. In de praktijk zal dit minder een probleem zijn dan de beschrijving doet vermoeden:

• De Alles-in-één en de getrapte variant zullen vooral in verschillende onderwijssectoren gebruikt worden.
  • In het po is de schoolomvang relatief klein en zal vooral de alles-in-één variant gebruikt worden. Hier komt de alles-in-één aanpak ook oorspronkelijk vandaan.
  • In het vo/mbo zijn de scholen groter en zal vooral de getrapte variant gebruikt worden.
• Als een partij al één van de varianten heeft geïmplementeerd en het is wenselijk ook de andere te ondersteunen, dan lijkt dit relatief eenvoudig te doen. De data verzamelingen zijn in de basis identiek, alleen het uitvragen ervan is verschillend.

Bijvoorbeeld een EA dat een alles-in-één overdracht ondersteunt, kan niet praten met een LAS dat de getrapte variant heeft geïmplementeerd.