Uitwisseling Leerlinggegevens en Resultaten versie 2.2.1

Alles-in-één-overdracht

Relevant voor
Educatieve Applicatie (EA)
Leerling Administratie Systeem (LAS)
Scenario
Uitwisseling leerlinggegevens
Uitwisseling leerresultaten met authenticeren via overkoepelend systeem
Uitwisseling leerresultaten met matching in zelfstandige EA
Uitwisseling methodegebonden toetsresultaten
Bericht
Leerlinggegevensantwoordbericht
Leerlinggegevensverzoekbericht

Bij de alles-in-één-overdracht worden altijd de gegevens van alle ingeschreven leerlingen van een hele school volledig opgehaald. Het sturen van kleinere deelverzamelingen (afdeling, groep, klas) wordt niet ondersteund.

De belangrijkste reden voor een alles-in-één-overdracht is de eenvoud van het protocol. Als je ook berichten met alleen wijzigingen toestaat, neemt de complexiteit enorm toe: Er zullen bijvoorbeeld faciliteiten ingebouwd moeten worden voor verwijderingen en aanpassingen. Door altijd alles te verzenden voorkom je dit.

Belangrijkste nadeel is de omvang van de data-stromen en de productie/verwerking van de berichten. Gegeven de toename in verwerkingscapaciteit, bandbreedte en de mogelijkheid tot compressie van de berichten zullen hier waarschijnlijk geen onoverkomelijke problemen ontstaan. Mochten de omvang en intensiteit van het verkeer toch een probleem gaan vormen, dan zal een toekomstige versie van de afspraak hierop aangepast moeten worden.

Stappen

  1. Verzoek om leerlinggegevens

    De EA stuurt het verzoek om leerlinggegevens aan het LAS.

  2. Controle bij de aanroep

    Het LAS controleert bij de aanroep:

    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 volledige set leerlinggegevens, 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 volledige set 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.

    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 leerlinggegevens

    Het LAS verstuurt het  antwoord met leerlinggegevens  aan de EA .

  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 (alles-in-één)

Voor de verwerking van leerlinggegevens zal het LAS een webservice moeten implementeren. Voor de definities van de webservice wordt verwezen naar het bij deze afspraak horende WSDL-bestand UWLR_Leerlinggegevens_v2p2.wsdl. Indien de webservice volgens het WSDL-bestand daadwerkelijk wordt 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:

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:

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