UWLR: Uitwisseling Leerlinggegevens en Resultaten

UWLR: Uitwisseling Leerlinggegevens en Resultaten Technische beschrijving van de afspraak Versienummer: 2.0 (Mei 2015) 2015 Edustandaard.nl

2 / 34 Inhoudsopgave 1 Inleiding 4 1.1 1.2 Afhankelijkheid van DTDL 4 Notatie datamodel 5 1.3 Aanvullende bestanden 5 1.4 Aanvullende documenten 5 2 2.1 Uitwisselingsscenario s leerling en resultaat gegevens 6 Achtergronden 6 2.2 Stap 0: Technische systeem koppeling 6 2.3 Scenario 1: Uitwisseling leerlinggegevens en leerresultaten met gebruik overkoepelend systeem 7 2.4 Scenario 2: Uitwisseling leerlinggegevens en leerresultaten met zelfstandige EA 9 2.5 Scenario 3: Alleen overdracht toetsdefinities 10 3 3.1 Algemeen 11 Overkoepelende ontwerpbeslissingen 11 3.2 Gegevenstransport 11 3.3 3.4 Beveiliging onderlinge communicatie 11 Authenticatie en autorisatie 11 3.5 School identificatie 12 3.6 3.7 Bericht identificatie 12 XML binding 13 3.8 Omgang met vocabulaires 13 3.9 Verplichte controles 14 4 Alles-in-één overdracht leerlinggegevens 15 4.1 Ontwerpbeslissingen 15 4.2 Functionele beschrijving aanroep (request) 16 4.3 Functionele beschrijving antwoord (response) 16 4.4 4.5 XML binding 19 Impleme nt at ie 19 4.6 Aanvullende verplichte controles 19 4.7 Aanwijzingen verwerking door EA 19 5 Getrapt ophalen leerlinggegevens 20 5.1 Ontwerpbeslissingen 20 5.2 Implementatie aanroepen (requests) 20 5.3 5.4 Implementatie antwoorden (responses) 21 XML binding 22 5.5 Implementatie webservices 22 6 6.1 Overdracht leerresultaten 23 Ontwerpbeslissingen 23 6.2 6.3 Resultaten 23 Correcties en aanpassingen van toetsdefinities 24 6.4 Functionele beschrijving aanroep (request) 24 6.5 Functionele beschrijving antwoord (response) 26 6.6 6.7 XML binding 26 Impleme nt at ie 26 6.8 6.9 Aanvullende verplichte controles 27 Aanwijzingen verwerking door LAS 27 7 Appendix A: Foutafhandeling SOAP verkeer 28 8 Appendix B: Beperkte overdracht toetsdefinities 30 8.1 Beschrijving data formaat 30 8.2 XML binding 30 8.3 Verplichte controles 30 8.4 Aanwijzingen verwerking door LAS 30 9 Appendix C: Aanwijzingen implementatie vocabulaires 31 9.1 Het VDEX formaat 31 9.2 9.3 Zoeken en vinden van VDEX bestanden 32 Controleren van codes tegen een vocabulaire 34

3 / 34 Colofon Projectteam: Auteur(s): Geconsulteerde organisaties: Jos vd Arend; Brian Dommisse; Jim Bijlstra; Erik Siegel Jos van der Arend; Erik Siegel Boom test uitgevers; Bureau ICE; Cita Verde College; Cito; DataCare; De Rode Planeet; Deviant; Dotcomschool; DUO; Edia; Edu'Actief; GEU; Iddink; Malmberg; Noordhoff Uitgevers; OMO; Paragin; Questionwise; Roadside; Rovict; Schoolmaster; ThiemeMeulenhoff; Topicus; Unilogic; Zwijsen Documentgeschiedenis Versie Datum Omschrijving V1.0 November 2012 De definitieve versie zoals in beheer genomen bij EduStandaard. 2.0 Mei 2014 Inhoudelijke aanpassingen: Verwijzingen naar EDEXML 2.0 (i.p.v. versie 1.03) Getrapt ophalen toegevoegd Verwijzingen naar Afspraak OSO 1.1 (i.p.v. ELD) Uitbreiding van resultaten om naast bestaande opties een ander resultaat volgens eigen formaat te kunnen gebruiken. Juni 2014 November 2014 Mei 2015 Betekenis van de afkorting UWLR aangepast: Uitwisseling Leerlinggegevens en Resultaten. Inhoudelijke aanpassingen: Update van EDEXML 2.0 naar V0.992 (i.p.v. V0.991), door toevoeging van veld Startdatum onderwijs (niveau) jaargroep 3. Inhoudelijke aanpassingen: Update van EDEXML 2.0 naar V0.993 (i.p.v. V0.992), door toevoeging van enkele velden en business rules (bedrijfsregels) m.b.t. rol van leerkracht en jaargroep & vestigingscode bij leerling. Inhoudelijke aanpassingen: Alle inperkingen van de leerlinggegevens uit deze afspraak gehaald; inperkingen worden opgenomen in profielen die worden beschreven in een apart document.

4 / 34 1 Inleiding Binnen het Nederlandse onderwijsveld wordt steeds meer digitaal getoetst. Dit gebeurt veelal op systemen van de aanbieders van de toetsen: de educatieve uitgevers. Deze systemen worden ook wel Educatieve Applicaties (EA s) genoemd. Scholen hebben vrijwel altijd een centraal leerling administratie systeem (LAS) waarin, naast basis zaken als NAW-gegevens, ook de resultaten worden bijgehouden. Het dus wenselijk de op een EA behaalde resultaten over te brengen naar het LAS, het liefst uiteraard zonder al te veel handmatige handelingen. Deze afspraak beschrijft de gegevensoverdracht die hiervoor plaats moet vinden. Het opzetten van deze afspraak is ooit begonnen met twee uitkomsten als doel: Eén afspraak voor het PO en één voor het VO + MBO. Gaandeweg bleek echter dat het mogelijk was de uiteindelijke resultaten te integreren tot de overkoepelende afspraak die nu voor u ligt. Dat wil natuurlijk niet zeggen dat de situaties in de verschillende onderwijssectoren volledig met elkaar overeenkomen. Er zijn wel degelijk verschillen, maar die uiten zich voornamelijk in afwijkingen in vocabulaires. Zo zal bijvoorbeeld het PO een geheel andere vakgebiedenlijst kennen dan het MBO. In deze afspraak komt dit als volgt tot uitdrukking: Waar er sprake is van een veld dat vocabulaire gebonden kan zijn (bijvoorbeeld een vakgebied of een toetscode) kan hierbij de desbetreffende vocabulaire worden aangeduid. Op deze manier hopen we de verschillen tussen de sectoren voldoende ruimte te bieden. Dit document is de technisch uitwerking van deze afspraak. Het beschrijft het datamodel, de berichten en het protocol om tot een uitwisseling van leerresultaten te komen. Doel van dit document is om zowel LAS bouwer als EA ontwikkelaar van voldoende informatie te voorzien om de afspraak te implementeren. Naast deze tekst horen hier ook nog een aantal (XML) bestanden met voorbeelden en schema s bij. Doelgroepen zijn daarmee met name software ontwikkelaars van school administratie en toetssystemen. Van de lezer wordt voldoende achtergrondkennis van XML en webservices verwacht. Dit toepassingsprofiel maakt onderdeel uit van de resultaten van het Kennisnet ECK2 (Educatieve Content Keten 2) deelproject Uitwisseling Leerresultaten. Hierin is ook een toepassingsprofiel uitwisseling leerresultaten binnen SCORM opgesteld. Dit behandelt het doorgeven en verwerken van scores/resultaten binnen een SCORM omgeving. Bij dit document hoort een functionele beschrijving van de afspraak: [UWLR-BAF] 1. Hierin wordt het hoe en waarom en de plaats van de afspraak beschreven. 1.1 Afhankelijkheid van DTDL Voor een deel is dit project afhankelijk van een ander ECK2 project: Distributie en Toegang Digitale Leermiddelen (DTDL). Binnen DTDL wordt onder andere beschreven hoe een leerling (en leerkracht) in de content keten geïdentificeerd wordt. Dit is belangrijk voor deze afspraak omdat leerresultaten uiteraard aan de goede leerling gekoppeld moeten worden. DTDL wordt beschouwd als een belangrijke architectuur, onderliggend aan de afspraak Uitwisseling Leerlinggegevens en Resultaten (UWLR). De DTDL afspraak versie 1.5 van september 2014 [DTDL15] is definitief. Leveranciers zijn hun huidige implementaties stapsgewijs aan het overzetten naar deze standaard. De huidige implementaties verschillen per sector en per leverancier. Op dit moment wordt gewerkt aan harmonisatie van deze verschillende implementaties. Omdat deze DTDL afspraak (Definities en procesmodel & Functioneel en technisch model) nog in ontwikkeling is, raden wij aan om bij het implementeren van UWLR zoveel mogelijk de DTDL afspraak te volgen. 1 Verwijzingen naar aanvullende documenten staan tussen rechte haken, [] en zijn op te zoeken in par. par. 1.3/blz. 3

5 / 34 1.2 Notatie datamodel In deze afspraak wordt het datamodel (de technische invulling) alleen functioneel omschreven. Voor details als bijvoorbeeld veldtype en -lengte wordt verwezen naar de bijbehorende XML Schema bestanden. De informatie om dit mogelijk te maken (welk XML element hoort bij welk veld is in de tabellen opgenomen. In de tabellen die het datamodel omschrijven komen tevens de volgende coderingen in de kolom aantal voor: Aantal Betekenis codering? Optioneel veld, komt nul of één keer voor 1 Verplicht veld, komt altijd voor * Optioneel meervoudig veld, komt nul of meerdere keren voor + Verplicht meervoudig veld, komt één of meerdere keren voor 1.3 Aanvullende bestanden Bij deze afspraak horen, naast dit document, diverse aanvullende bestanden: Schema s met de definities van de verschillende berichten WSDL bestanden met de webservice definities Voorbeeld XML bestanden met berichten 1.4 Aanvullende documenten [UWLR-BAF] [UWLR-GOL] [IMS-LTI] [IMS-VDEX] [PARN-RT] Uitwisseling Leerlinggegevens en Resultaten - Beschrijving Afspraak UWLR: Uitbreidingsvoorstel getrapt ophalen leerlinggegevens; V0.1; November 2012 IMS GLC Learning Tools Interoperability Basic LTI Implementation Guide V1.0; Final; 17 mei 2010 IMS Vocabulary Definition Exchange - Best Practice and Implementation Guide V1.0; Final Specification; 2004 ParnasSys - Resultaten terugkoppeling Topicus; V1.0; Definitief; 26-10-2011 [OSO] Overstapservice Onderwijs http://www.overstapserviceonderwijs.nl/ [OSO121] EduStandaard: Afspraak OSO Gegevensset, versie 1.2.1, Februari 2015 http://www.edustandaard.nl/ [SOAP-NOTE] Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 http://www.w3.org/tr/2000/note-soap-20000508 [DTDL15] [EDEXML2] [Edukoppeling] [TLS] Afspraak Distributie en Toegang Digitale Leermiddelen Kennisnet; V1.5; september 2014 Handleiding en technische bestanden (XML schema en voorbeelden) EDEXML 2.0 definitief; Mei 2014 http://www.edustandaard.nl/standaarden/afspraken/afspraak/edexml/ Edukoppeling Transactiestandaard. Verkrijgbaar via http://www.edustandaard.nl/standaarden/afspraken/afspraak/edukoppeling/ [OASIS-CAT] XML Catalogs - OASIS Standard V1.1; 7 October 2005 http://www.oasis-open.org/committees/download.php/14809/xmlcatalogs.html https://www.logius.nl/fileadmin/pki/richtlijnen/ict- beveiligingsrichtlijnen_voortransport_layer_security TLS v1.0_- _webversie.pdf).

6 / 34 2 Uitwisselingsscenario s leerling en resultaat gegevens Dit hoofdstuk beschrijft de basisscenario s voor de uitwisseling van leerling en resultaatgegevens. Deze scenario s zijn het uitgangspunt geweest bij de ontwikkeling van deze standaard. Het sluit niet uit dat er mogelijk andere scenario s zijn waarop deze standaard van toepassing is (volledig of in onderdelen). Hier wordt echter verder niet op ingegaan. 2.1 Achtergronden De uitwisseling van leerresultaten gaat uit van twee systemen in een bepaalde rol: Rol: Leerling Administratie Systeem (LAS): Een LAS administreert de gegevens van leerlingen binnen een school. Het gaat hier om de gegevens van de leerling (NAW) en zijn leerresultaten. Een LAS neemt zelf geen toetsen af. De school is eigendom van de gegevens en gebruikt het LAS als bronsysteem. Voor wat betreft namen, groepsindelingen en identifiers is het LAS dus leidend. Ook een Leerlingvolgsysteem (LVS) of een administratieve module binnen een ELO kunnen binnen deze standaard als LAS beschouwd worden, mits ze de rol hebben van eigenaar van leerling- en groepsgegevens. Rol: Educatieve Applicatie (EA): Een EA is een systeem dat, mogelijk naast andere educatieve activiteiten, bij leerlingen toetsen kan afnemen en hiervan een resultaat bepaalt. Een EA kan binnen de school staan of door een derde partij (veelal een uitgever) worden geëxploiteerd. Soms biedt een uitgever meerdere EA s aan die door een school gebruikt worden. Er kan dan ook sprake zijn van een centrale leerling/groepsgegevens module per uitgever die door alle EA s van deze uitgever gedeeld wordt. In de scenario s hebben we te maken met de volgende uitwisselingen van gegevens tussen een LAS en een EA: Leerlinggegevens: Overdracht van leerlinggegevens is noodzakelijk om een aantal redenen: De EA moet weten hoe de leerling in het LAS geïdentificeerd wordt, zodat als er leerresultaten naar het LAS gaan deze aan de juiste leerling gekoppeld worden. Dit gebeurt middels identifiers of andere identificerende attributen die buiten de context van LAS/EA niet tot een leerling kunnen worden herleid. Voor de gebruikersvriendelijkheid is het prettig dat de EA een aantal minimale kenmerken van de leerling weet, zoals bijvoorbeeld zijn/haar naam. Voor de docent is het prettig dat de EA iets weet van de in het LAS mogelijk al bekende groepsindeling(en), zodat bijvoorbeeld in één keer aan een groep een toets uitgedeeld kan worden. Leerresultaten: De resultaten van een op de EA afgenomen toets moeten geadministreerd worden in het LAS. Deze zullen dus daarheen moeten worden verzonden. Het spreekt waarschijnlijk voor zich, maar het is aan de EA en het LAS om een duidelijke foutafhandeling en -melding te implementeren als er bij één van de onder deze afspraak vallende uitwisselingen een probleem optreedt. Over hoe dit in de user interface geïntegreerd moet worden (melding, log, fout e-mail, etc.) doet de afspraak geen uitspraken. 2.2 Stap 0: Technische systeem koppeling Voor scenario s 1 en 2 geldt dat voorafgaand aan de daadwerkelijke uitwisselingen, de EA en het LAS technisch aan elkaar gekoppeld moeten worden. Zaken die mogelijk geregeld moeten worden zijn onder andere: Instellen van adressen (URL s) voor de webservices Instellen van authenticatiegegevens (zoals de autorisatiesleutel) Inregelen SSL beveiligingscertificaten Firewall instellingen aanpassen

7 / 34 2.3 Scenario 1: Uitwisseling leerlinggegevens en leerresultaten met gebruik overkoepelend systeem In dit scenario hebben we te maken met een overkoepelend systeem ten behoeve van de authenticatie van de leerling. Voor de vormgeving van de interactie met een dergelijk systeem gebruiken we de uitkomsten van het ECK2 project Distributie en Toegang Digitale Leermiddelen (DTDL). De huidige versie van deze standaard is V1.4 van 22 juni 2012. Het architectuur document heet Afspraak Distributie en Toegang Digitale Leermiddelen [DTDL]. Tussen de verschillende versies van DTDL zijn nogal wat verschillen te zien. Dit is in het verleden ook tot uitdrukking gekomen in deze afspraak Uitwisseling Leerlinggegevens en Resultaten (UWLR) met als gevolg vervelende verschillen in de XML formaten tussen de versies. Paragraaf 1.1/blz. 4 gaat hier verder op in. 2.3.1 Scenario 1, stap 1: Overdracht leerlinggegevens aan overkoepelend systeem Het LAS (in DTDL termen: Profile Service) vraagt aan het overkoepelend systeem (In DTDL termen: Account Service) een account voor een leerling aan te maken: Toegang verlenend systeem (account service) Maak account aan ok LAS EA Hierbij gaat een minimum aan gegevens mee: Gebruikersnaam Wachtwoord Gebruikers identifier Vooral deze laatste is van belang: het LAS moet ervoor zorgen dat dit een ketenbrede unieke identifier is voor deze gebruiker. De bedoeling is dat de gebruiker overal in de educatieve contentketen altijd met dezelfde identifier wordt geïdentificeerd. Dat betekent dat waarschijnlijk de interne LAS identifier niet voldoende (uniek) is. Een uniek makende aanvulling kan bijvoorbeeld de URL van de school zijn. Een voorbeeld van zo n identifier is dan 13788990@mijnschool.nl. 2.3.2 Scenario 1, stap 2: Overbrengen LAS leerlinggegevens naar de EA De EA verzoekt het LAS om de leerlinggegevens (hfdst. 4/blz. 15): Verzoek LAS Leerlinggegevens (met als identifier de ketenbrede identifier) EA Belangrijk: 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: 1. Alles-in-één: Alle gegevens in één keer ophalen. 2. Getrapt: De gegevens in blokjes ophalen. Bij de eerste variant Alles-in-één is er 1 Request en 1 Response bericht. Bij de tweede variant Getrapt zijn er 3 Request en bijbehorende Response berichten gedefinieerd: 1. Basisgegevens Request/Response voor relevante schoolgegevens en groepen. 2. Leerlinggegevens Request/Response voor leerlinggegevens bij de aangegeven groepen. 3. Leerkrachtgegevens Request/Response voor leerkrachtgegevens bij de aangegeven groepen. Via herhaling kunnen alle leerlinggegevens en leerkrachtgegevens in blokjes (per groep of setje van groepen) opgehaald worden.

8 / 34 Een zeer belangrijke keuze hierbij is dat het niet verplicht is beide manieren 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: Bijvoorbeeld een EA dat een alles-in-één overdracht ondersteunt, kan niet praten met een LAS dat de getrapte variant heeft geïmplementeerd. We hebben als het ware twee soorten, niet goed op elkaar passende, stekkers/stopcontacten geïntroduceerd. Dat is erg jammer, maar we denken dat dit in de praktijk minder een probleem is 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. Belangrijk: De identifier die hierbij voor een leerling wordt meegegeven moet dezelfde zijn als waarmee in stap 1 (par. 2.3.1/blz. 7) de leerling is aangemeld bij het accounthuis/account service (en dus niet de interne LAS identifier zoals in voorgaande versies van deze afspraak). 2.3.3 Scenario 1, stap 3: Klaarzetten en afname toets De EA zal moeten weten welke toets(en) aan welke leerling(en) moeten worden aangeboden. Het kan zijn dat dit onderdeel is van lopend educatief programma op de EA zodat de leraar hier geen specifieke actie op hoeft te ondernemen Een andere optie is dat de leraar specifiek een toets moet klaarzetten. De leraar moet dan aangeven welke toets aan wie gegeven moet worden. De toets wordt afgenomen. Hiervoor zijn verschillende opties: De leerling neemt op de EA de toets af. De resultaten worden eerst op de EA vastgelegd. De leerling neemt op een buiten de EA liggend systeem de toets af. Een mogelijke koppeling tussen EA en extern systeem hiervoor is LTI (zie [IMS-LTI]) De toets wordt op papier afgenomen en de resultaten worden handmatig in de EA ingebracht In alle gevallen authentiseert de leerling zich bij de EA met bemiddeling van het overkoepelend systeem/account service. De EA krijgt tijdens het authenticatie proces de ketenbrede identifier voor deze leerling terug en weet daarmee dus wier in ingelogd heeft. Klaarzetten en afname maken geen deel uit van de afspraak leerresultaten maar zijn wel onderdeel van het scenario. 2.3.4 Scenario 1, stap 4: Overdracht leerresultaten De leerresultaten van een toets worden overgedragen (hfdst. 6/blz. 23). De EA stuurt hierover een bericht: LAS Leerresultaten EA Bevestiging Het initiatief voor deze overdracht ligt bij de EA. Er zijn diverse triggers voor de overdracht mogelijk: De EA stuurt automatisch na de afname van een toets direct de leerresultaten naar het LAS. Dit kan zowel per toets zijn als per leerling-toetsafname (druppelsysteem). Diegene die verantwoordelijk is voor de toetsafname (meestal de docent) geeft expliciet opdracht aan de EA om de gegevens door te sturen. De instelling hiervan en de mate waarop de gebruiker hierover controle heeft is een belangrijk punt: gebruikers van EA s zijn de eigenaars van de resultaatgegevens en zullen daarom controle moeten houden over deze overdracht. Een EA moet dit correct implementeren en presenteren aan de gebruiker. Belangrijk is hier dat de verzonden leerresultaten correct binnen het LAS geadministreerd kunnen worden: De leerling wordt geïdentificeerd middels zijn/haar ketenbrede identifier.

9 / 34 Ter identificatie van de toets worden een aantal gegevens meegezonden. Deze zijn deels vocabulaire gebonden en deels vrij. 2.4 Scenario 2: Uitwisseling leerlinggegevens en leerresultaten met zelfstandige EA In dit scenario hebben we niet te maken met een overkoepelend systeem, maar neemt de EA zelf de authenticatie van de leerling ter hand. Om dit te kunnen doen zijn de leerlingen binnen de EA al bekend (hebben een account ). Dit staat los van hun registratie in het LAS. We zullen dus op de één of andere manier de leerlinggegevens/accounts in het LAS en in de EA aan elkaar moeten koppelen. Dit scenario wordt verder uitgewerkt in de hoofdstukken 3, 4 en 5. 2.4.1 Sc enario 2, stap 1: Overdracht LAS leerlinggegevens naar de EA De EA moet weten welke leerlingen bij het LAS bekend zijn. De EA stuurt hiervoor een verzoek naar het LAS om deze te sturen: Verzoek LAS Leerlinggegevens EA Met de leerlinggegevens komen mee: Een identifier voor de leerling. Dit is om privacy redenen niet het BSN of het leerlingnummer maar een door het LAS bepaalde identifier die buiten de context van deze uitwisseling niet met een leerling kan worden geassocieerd. Optionele gegevens over groepen en leerkrachten Belangrijk: 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 overbrengen van de gegevens: 1) Alles-in-één: Alle gegevens in één keer en 2) Getrapt: De gegevens in blokjes. Zie hierover par. 2.3.2/blz. 7. Overbrengen LAS leerlinggegevens naar de EA. De overdracht van leerlinggegevens wordt verder uitgewerkt in hfdst. 4/blz. 15. 2.4.2 Scenario 2, stap 2: Matching LAS gegevens tegen interne accounts De EA heeft nu twee sets leerlinggegevens: Interne accounts en LAS gegevens. Omdat voor het terugsturen van leerresultaten de LAS identifier noodzakelijk is, zal men deze met elkaar moeten gaan matchen: Welke LAS leerling hoort bij welk intern account: Hoe dit precies plaatsvindt valt buiten de scope van deze afspraak, maar de suggestie is te kijken naar naam en geboortedatum en vergevingsgezind te zijn over kleine schrijffouten: fuzzy matching dus. Als er geen match gevonden kan worden of er is gerede twijfel, dan is menselijk ingrijpen hier onvermijdelijk. De EA zal hiervoor een user interface moeten aanbieden.

10 / 34 Er zijn partijen die dit al hebben geïmplementeerd en de ervaringen hiermee zijn goed. De manier waarop dit daar gebeurt is: Definieer een set van velden (optionele velden kunnen ook helpen), bijvoorbeeld: voornaam, achternaam, geboortedatum. Kijk per leerling of er een exacte match is bij de reeds bekende data. Is dit het geval kan de leerling automatisch gekoppeld worden. Komen velden niet overeen, krijg de docent twee lijsten te zien van de leerlingen (een lijst van beide systemen) Per kant kan een leerling gekozen worden om te koppelen. Ook kan een leerling als 'nieuw' worden beschouwd of genegeerd. 2.4.3 Sc enario 2, Stap 3: Klaarzetten en afname toets Zie hierover par. 2.3.3/blz. 8. Authenticatie vind plaats tegen het EA account van leerling/leerkracht. 2.4.4 Stap 4: Overdracht leerresultaten De leerresultaten van een toets worden overgedragen naar het LAS. Zie hierover par. 2.3.4/blz. 8. 2.5 Scenario 3: Alleen overdracht toetsdefinities Scenario 3 is een secundair scenario. Dat betekent: Om te voldoen aan deze standaard is de implementatie van dit scenario niet verplicht. Het is een optionele uitbreiding. Partijen die alleen dit specifieke scenario implementeren voldoen niet aan deze afspraak Uitwisseling Leerlinggegevens en Resultaten. In dit scenario hebben we te maken met systemen die (nog) niet automatisch gekoppeld zijn. Aan de LAS kant moeten echter toetsresultaten worden ingevoerd en het zou erg handig zijn als de toetsdefinities al wel op het LAS bekend zijn. Gevallen waarin dit voorkomt zijn bijvoorbeeld: Op een EA uitgevoerde toetsen waarvan de resultaten, bij gebrek aan een rechtstreekse koppeling, handmatig in het LAS moeten worden ingebracht Bij een methode horende standaardtoetsen die niet-digitaal worden afgenomen. In al deze gevallen zou het handig zijn als de toetsleverancier de toetsdefinities in een standaard formaat aan een LAS zou kunnen aanleveren. Het LAS kan dan het invoeren van de gegevens vereenvoudigen door het presenteren van lijsten, controleren van waarden, etc. De te volgen stappen voor dit scenario zijn heel simpel: De toetsleverancier levert een volgens deze standaard opgezet XML bestand aan met daarin de toetsdefinities. Dit bestand wordt op een niet nader gedefinieerde manier (mail, ftp, cd-rom, etc.) overgebracht naar het LAS. Het LAS importeert het bestand, controleert het en verwerkt het vervolgens in zijn interne administratie. Scenario 3 is secundair aan scenario 1 en 2. Ook de technische uitwerking hiervan is gebaseerd op de andere scenario s. Deze vindt u in appendix B, blz. 30.

11 / 34 3 Algemeen 3.1 Overkoepelende ontwerpbeslissingen Initiatief bij EA: Voor beide transacties (de overdracht van leerlinggegevens en leerresultaten) ligt het initiatief bij de EA. Dat betekent dat het LAS de bij deze standaard horende webservices implementeert en dat de EA ze aanroept. Belangrijkste reden hiervoor is eenvoud van authenticatie/autorisatie. Deze kan nu eenzijdig door het LAS geregeld worden omdat deze de altijd de ontvanger is van de webservices: Bij het inregelen van de overdracht krijgt de EA authenticatie/autorisatie gegevens van het LAS (par. 3.4/blz. 11) Deze worden bij iedere aanroep vanuit de EA meegegeven. Het LAS controleert deze. Tekstvelden lengte beperkt: De informatie in de berichten zal over het algemeen in en uit relationele database gelezen/geschreven worden. In de praktijk zijn daardoor de tekstvelden in lengte beperkt. Om dit te faciliteren zijn ook de tekstvelden binnen deze afspraak allemaal in lengte beperkt. Informatie hierover in de bijbehorende schema s. 3.2 Gegevenstransport De primaire manier om de leerling- en leerresultaatgegevens uit deze afspraak te transporteren is via online webservices. Om dit te faciliteren is de afspraak voorzien van de bijbehorende webservice definities (WSDL bestanden). 3.3 Beveiliging onderlinge communicatie Leerlinggegevens en leerresultaten zijn privacy gevoelige informatie. Deze afspraak schrijft daarom voor dat de communicatie tussen LAS en EA conform TLS beveiligd is (zie [TLS]). Verder moet gebruik gemaakt worden van SOAP voor de metadatering van berichten ( envelop ). Beide zaken (TLS en SOAP) zijn ook onderdeel van de Edukoppeling transactiestandaard waar UWLR in de toekomst naar toe zal gaan groeien. Het is aan de betrokken partijen ervoor te zorgen dat de vertrouwelijkheid van de informatie niet geschaad wordt, bijvoorbeeld door het toepassen van aanvullende encryptie. Partijen hebben het recht hebben om, met het oog op de vertrouwelijkheid, deze manier van overbrengen te weigeren. 3.4 Authenticatie en autorisatie Authenticatie is het proces waarbij de identiteit van, in dit geval, een systeem wordt vastgesteld. De autorisatie bepaalt wat dit systeem vervolgens mag. Omdat binnen deze afspraak het initiatief tot communicatie altijd bij de EA ligt, ligt de verantwoordelijkheid voor het opzetten van zowel authenticatie als autorisatie bij het ontvangende systeem, het LAS. Hiervoor deelt (de aanbieder van) het LAS een aantal codes uit aan (de aanbieder van) de EA. Deze gegevens worden bij ieder verbindingsverzoek meegegeven en door het LAS gecontroleerd. 3.4.1 Authenticatie van de externe aanbieder Iedere externe aanbieder, meestal een uitgever, die een EA met het LAS wil koppelen moet, onafhankelijk van over welke scholen het gaat, zich identificeren bij het LAS. Daartoe krijgt de aanbieder van de EA van de aanbieder van het LAS twee gegevens: Een toegekende naam (bijvoorbeeld Malmberg, ThiemeMeulenhoff, Zwijsen, etc.) Een hierbij behorende code. Beide moeten bij iedere aanroep binnen deze afspraak worden overgedragen. Het LAS controleert deze gegevens.

12 / 34 3.4.2 Autorisatie op schoolniveau Iedere school die wil dat het LAS en de EA leerresultaat gegevens gaan uitwisselen moet hiervoor het volgende doen: De school vraagt, onder vermelding van één of meerdere schoolidentificaties (zie par. par. 3.5/blz. 12), bij de LAS aanbieder een autorisatiesleutel aan. Dit kan mogelijk ook geautomatiseerd: De school geeft bij het LAS aan te willen koppelen met een geregistreerde partij, waarna het LAS de school een sleutel en de technische gegevens levert. Deze worden vervolgens in de EA ingevoerd. Het LAS genereert een autorisatiesleutel. Deze wordt intern gekoppeld aan de lijst van schoolidentificaties. De school ontvangt van de LAS aanbieder de autorisatiesleutel. De autorisatiesleutel wordt, samen met de lijst van schoolidentificaties, door de school overgedragen aan de EA aanbieder. 3.4.3 Controles Iedere aanroep binnen deze afspraak bevat zowel de autorisatiesleutel als de schoolidentificatie (deze staat in de berichtidentificatie, zie par. par. 3.6/blz. 12). Het LAS controleert bij iedere aanroep: Of de authenticatie van de externe aanbieder (par. 3.4.1/blz. 11) correct is Of de autorisatiesleutel (par. 3.4.2/blz. 12) correct is en hoort bij de externe aanbieder Of de in de bericht identificatie (par. 3.6/blz. 12) meegegeven schoolgegevens vallen onder de autorisatiesleutel. Als één van de controles faalt mag het bericht niet verwerkt worden. 3.4.4 XML binding De XML binding wordt gedefinieerd in het bij deze afspraak horende W3C XML Schema UWLR_Autorisatie_v2p0.xsd. De XML elementen voor autorisatie binnen deze afspraak hebben de namespace: http://www.edustandaard.nl/leerresultaten/2/autorisatie. Hieronder een voorbeeld van een autorisatie XML fragment: <autorisatie xmlns="http://www.edustandaard.nl/leerresultaten/2/autorisatie"> <autorisatiesleutel>pk77881fg-hj99777737=</autorisatiesleutel> <klantcode>89ty55661==866fffg</klantcode> <klantnaam>uitgeverx</klantnaam> </autorisatie> 3.5 School identificatie Een school wordt binnen deze afspraak als volgt gedefinieerd: Middels een BRIN code, optioneel aangevuld met een (vrij in te vullen) dependance code. Een BRIN code bestaat uit twee cijfers en twee letters, een dependancecode uit twee cijfers. De dependancecode 00 (nul, nul) betekent hetzelfde als geen dependancecode. - of - Voor scholen die geen BRIN code hebben: Middels een (zelf te bepalen) schoolsleutel. Deze moet, in ieder geval binnen de betreffende LAS-EA context, uniek zijn. Hoe deze tot stand komt is voor deze afspraak buiten scope. 3.6 Bericht identificatie In ieder bericht (leerlinggegevens én leerresultaten) is altijd dezelfde identificatie opgenomen. Deze is gebaseerd op de schoolidentificatie uit EDEXML2 (omringend element: school): Veld XML element Aantal Opmerkingen Schooljaar schooljaar 1 Het schooljaar waar deze leerlinggegevens bij horen, volgens het patroon jjjj-jjjj (bijvoorbeeld 2011-2012 ) Schoolidentificatie brincode + dependancecode 1 Zie par. 3.5/blz. 12. - of - schoolkey Bericht datum/tijd aanmaakdatum 1 Wordt gebruikt om de verwerking te sturen, zie par. 4.6/blz. 19 en par. 6.8/blz. 27.

13 / 34 Veld XML element Aantal Opmerkingen Naam verzender auteur? Door verplaatsing van dit veld van achter naar vóór het veld xsdversie is UWLR weer in overeenstemming met EDEXML. XSD versie xsdversie 1 Moet overeenkomen met de versie van het bijbehorende berichtschema (technisch: Met de waarde van het version attribuut op het root element van het schema). Commentaar commentaar? Voor mensen bedoeld veld. Aangezien de uitwisseling tussen systemen plaatsvindt zal dit meestal weinig toepassing hebben. Er zijn echter uitzonderingsgevallen (testberichten bijvoorbeeld) waarin dit een rol kan spelen. 3.7 XML binding Hieronder een voorbeeld van een bericht identificatie: <school> <schooljaar>2011-2012</schooljaar> <brincode>99xx</brincode> <dependancecode>16</dependancecode> <aanmaakdatum>2011-11-14t12:12:12</aanmaakdatum> <xsdversie>1.0</xsdversie> </school> 3.8 Omgang met vocabulaires Zie voor implementatie details appendix C op blz. 31. Voor een aantal velden binnen deze afspraak is het mogelijk dat er vocabulaires zijn of in de toekomst komen. De afspraak biedt de mogelijkheid deze velden hieraan te koppelen. Een voorbeeld is, bij de identificatie van een toets, het veld toetscode. Dit kan als volgt worden ingevuld: Er is voor de betreffende toets geen vocabulaire met toetscodes beschikbaar: Het veld wordt gevuld met een, door de EA te bepalen, toetscode. Er is wél een vocabulaire beschikbaar. De identificatie van de vocabulaire wordt aan het veld toegevoegd. De waarde van het veld moet voldoen aan de vocabulaire. Dit ziet er in de XML dan als volgt uit: <toetscode vocabulaire="http://www.vbuitgeverij.nl/codes/toetscodes">t1654</toetscode> Het koppelen van een veld aan een vocabulaire heeft een aantal voordelen: Het verkleint de kans op foute coderingen en verschillen in schrijfwijze (bijvoorbeeld toetsen die binnenkomen met code AC567s en AC-567-S terwijl dezelfde toets wordt bedoeld). Omdat het vocabulaire vastligt worden de gegevens eenvoudiger vergelijkbaar en uitwisselbaar. Een code kan middels de vocabulaire vertaald worden naar een korte, voor mensen bedoelde, omschrijving. Een vocabulaire kan aanvullende informatie ter beschikking stellen, bijvoorbeeld een uitgebreidere omschrijving. Waar deze vocabulaire vandaan komt en wat de scope daarvan is ligt niet vast. Mogelijkheden zijn bijvoorbeeld: Voor toetsen binnen een bepaald schooltype en vakgebied, beheerd door Edustandaard. Voor toetsen behorend bij een methode, beheerd door een uitgever Voor internationaal erkende toetsen, beheerd door een internationale organisatie. 3.8.1 Vocabulaire implementatie Een vocabulaire wordt altijd geïmplementeerd middels een VDEX (Vocabulary Definition Exchange) XML bestand. Dit is een door het IMS vastgelegd formaat (zie [IMS-VDEX]). Een vocabulaire wordt geïdentificeerd door middel van een URI, bijvoorbeeld: http://www.uitgeverijnaam.nl/vocabs/aardrijkskunde/1756. Let op: Dit is een URI (Uniform Resource Identifier) en daarmee niet per definitie een URL (Uniform Resource Locator): Het hoeft dus niet de vorm van een web adres aan te nemen en, als dit wel het geval is, hoeft dat niet te leiden naar de betreffende VDEX.

14 / 34 3.8.2 XML binding Indien een veld een vocabulaire kan hebben, zijn er op het betreffende element twee optionele attributen: vocabulaire: De URI van de betreffende vocabulaire vocabulairelocatie: Een hint voor de locatie van de betreffende vocabulaire VDEX in de vorm van een URL. Het attribuut vocabulairelocatie is alleen betekenisvol en mag alleen gebruikt worden als er ook een vocabulaire attribuut aanwezig is. Opmerking: Een andere optie om de vocabulaire aan te duiden was geweest om altijd een resolvable URI te gebruiken: De opgenomen URI moet dan naar een VDEX verwijzen. Er is echter bewust voor gekozen om vocabulaire URI en locatie van elkaar te scheiden. Belangrijkste reden: De vocabulaire URI is hiermee nu altijd eenduidig en niet afhankelijk van waar de VDEX op te halen is. Een eenduidige naam maakt het mogelijk om de VDEX ook op andere manieren te lokaliseren. Zie hierover de volgende paragraaf. 3.8.3 Verwerking vocabulaire velden door het LAS Als het LAS een veld gekoppeld aan een vocabulaire binnenkrijgt, heeft het de volgende mogelijkheden de VDEX te achterhalen: De URI is bekend en de vocabulaire VDEX is intern beschikbaar (bijvoorbeeld omdat het LAS weet dat deze veel gebruikt wordt). De URI is niet bekend maar er is een locatie bij vermeld waarmee de VDEX achterhaald kan worden De URI is niet bekend maar middels een interne of externe XML catalog (zie [OASIS-CAT]) kan de locatie van de VDEX achterhaald worden. Het is bijvoorbeeld denkbaar dat Edustandaard ooit een VDEX XML catalog gaat aanbieden. Als er een VDEX wordt gevonden moet de inhoud van het veld tegen de VDEX worden gecontroleerd. Een niet in de VDEX voorkomende waarde maakt het bericht invalide. Indien de VDEX niet achterhaald kan worden leidt dit niet tot een fout maar wordt de waarde van het veld as is geaccepteerd. 3.9 Verplichte controles Zowel het LAS als de EA moeten op ieder ontvangen bericht verplicht de volgende controles uitvoeren. Als één van de controles faalt mag het bericht niet verder worden verwerkt: Is het binnengekomen bericht valide volgens de in de WSDL gerefereerde schema s? Als er vocabulaire gebonden velden in het bericht staan (zie par. 3.8/blz. 13) en de vocabulaire is bekend (of kan achterhaald worden): Kloppen de veldwaardes met de in de vocabulaire opgenomen waardes? Voor het LAS geldt: Zijn de authenticatie en autorisatie gegevens correct (par. 3.4/blz. 11)

15 / 34 4 Alles-in-één overdracht leerlinggegevens Binnen deze afspraak is er voor gekozen om 2 manieren te ondersteunen voor de overdracht van leerlinggegevens: 1. Alles-in-één: Alle leerlinggegevens in één keer ophalen. 2. Getrapt: De leerlinggegevens in blokjes ophalen. Een zeer belangrijke keuze hierbij is dat het niet verplicht is beide manieren te implementeren. Een EA of LAS moet één van de twee, of beide, overdrachtsmanieren ondersteunen. In dit hoofdstuk wordt de Alles-in-één overdracht van leerling gegevens beschreven. In het volgende hoofdstuk wordt het getrapt ophalen van leerlinggegevens beschreven. 4.1 Ontwerpbeslissingen Alles-in-één overdracht: Bij de Alles-in-één overdracht worden altijd de gegevens van alle ingeschreven leerlingen van een hele school volledig verzonden. Een school wordt gedefinieerd middels een BRIN code + een optionele dependance code. Het sturen van kleinere deelverzamelingen (afdeling, groep, klas) wordt niet ondersteund. De belangrijkste reden hiervoor 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 natuurlijk 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 verwachten we hier echter geen onoverkomelijke problemen. Ook de mogelijkheid om alleen overdracht te doen bij wijzigingen (zie volgende punt) zal waarschijnlijk al veel verkeer schelen. 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. 2) Getrapt ophalen Hierbij worden de gegevens van alle ingeschreven leerlingen getrapt opgehaald. De volgorde is: 1. Eerst de organisatorische gegevens van school en groepen (basisgegevens), 2. Dan de leerlinggegevens (eventueel in blokjes per groep of verzameling groepen) en 3. Tenslotte de leerkrachtgegevens (eventueel in blokjes per groep of verzameling groepen). Voor meer informatie zie volgende hoofdstuk 5 Getrapt ophalen leerlinggegevens.

16 / 34 UWLR profielen op EDEXML2: Voor de overdracht van leerlinggegevens wordt EDEXML 2.0 (EDEXML2) gebruikt. Omdat voor bepaalde processen een aantal gegevens voor de UWLR uitwisseling niet noodzakelijk wordt geacht (o.a. privacy en doelbinding), worden bovenop EDEXML2 UWLR profielen gedefinieerd. In zo n profiel die toegespitst is op een specifiek proces worden een aantal gegevenselementen van EDEXML2 verboden, verplicht of aanbevolen. UWLR profielen worden in een apart document beschreven. Het gebruik van een profiel voor het specifieke proces wordt aanbevolen. In afwijking, kan bij koppelingen in bepaalde processen in onderling overleg van dit profiel worden afgeweken. In dit geval zal de exacte inhoud van de leerlinggegevens onderling moeten worden afgesproken. Optie voor alleen overdracht bij wijzigingen: De aanvrager van de leerlinggegevens (de EA) kan in zijn aanvraag de datum/tijd uit het laatste door hem ontvangen leerlinggegevensbericht opnemen. In dat geval heeft het LAS een keuze: 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 geen wijzigingen in de leerlinggegevens zijn geweest en stuur een (kort) gegevens up-to-date bericht terug. Het LAS constateert dat er sinds de meegestuurde datum wijzigingen hebben plaatsgevonden in de leerlinggegevens. Het stuurt de volledige set leerlinggegevens. Actie bij geen gegevens: Het is in theorie mogelijk dat er een aanvraag om leerlinggegevens wordt gedaan waarbij het LAS geen gegevens heeft, bijvoorbeeld als het schooljaar te ver in de toekomst ligt. In dat geval stuurt het LAS een geen gegevens bericht terug. Groepsindelingen: Binnen deze afspraak is er voor gekozen de groepsindeling zoals deze al binnen EDEXML2 bestaat in stand te laten. Een leerling kan optioneel ingedeeld zijn binnen één hoofdgroep (stamgroep) of in één of meerdere samengestelde groepen. De hoofdgroep heeft verplicht een koppeling met een jaargroep. Samengestelde groepen hebben geen koppeling met een jaargroep, die jaargroep kan individueel per leerling worden aangegeven. Leerlingen en docenten (leerkrachten) mogen bij nul of meer van de samengestelde groepen zijn ingedeeld. De lijst van groepen bevat hoofdgroepen (stamgroepen) en samengestelde groepen door elkaar. 4.2 Functionele beschrijving aanroep (request) Een verzoek (request) om leerlinggegevens is gebaseerd op de algemene berichtidentificatie (par. 3.6/blz. 12). Dit definieert ook de school waarvan men de gegevens wil hebben (omringend element: leerlinggegevensverzoek): Veld XML element Aantal Opmerkingen Schooljaar schooljaar 1 Het schooljaar waar deze leerlinggegevens bij horen, volgens het patroon jjjj-jjjj (bijvoorbeeld 2011-2012 ) Schoolidentificatie brincode + dependancecode 1 Zie par. 3.5/blz. 12. - of - schoolkey XSD versie xsdversie 1 Moet overeenkomen met de versie van het bijbehorende berichtschema (technisch: Met de waarde van het version attribuut op het root element van het schema). Datum/tijd laatste ontvangen gegevens laatstontvangengegevens? Indien ingevuld mag het LAS besluiten de leerlinggegevens te sturen als er wijzigingen zijn sinds de hierin aangegeven datum. Als dit veld afwezig is moet het LAS altijd de volledige set leerlinggegevens sturen. Zie ook de opmerkingen hierover in par. 4.1/blz. 15. 4.3 Functionele beschrijving antwoord (response) Een antwoordbericht met leerlinggegevens in het kader van deze standaard bestaat uit de volgende gegevens(structuren).

17 / 34 4.3.1 Algemene identificatie Algemene identificatie van het bericht en de school: Zie par. par. 3.6/blz. 12. De verplichte velden hierin moeten exact overeenkomen met de corresponderende velden in de aanroep (request) van het bericht. 4.3.2 Leerlinggegevens Een bericht bevat altijd één of meer leerlingen, met per leerling de volgende gegevens (omringend element: leerlingen/leerling) dat is afgeleid van het EDEXML2 gegevenselement LeerlingType. In de volgende tabel worden de deelelementen van het element leerling uit EDEXML beschreven. Voor leerling is de Identifier (key), Achternaam of Roepnaam en Jaargroep verplicht: Veld XML element of attribuut Aantal Opmerkingen Identifier @key 1 Dit is een door het LAS toegekende identifier. In een DTDL scenario is dit de ketenbrede identifier. De identifier moet om privacy redenen buiten de context van de uitwisseling leerresultaten geen betekenis hebben. Een BSN is dus bijvoorbeeld niet toegestaan. Achternaam achternaam?/1 Er is óf een achternaam (evt. aangevuld met Voorvoegsel voorvoegsel? voorvoegsels, voorletters en/of roepnaam) óf alleen een roepnaam. Voorletters voorletters-1? Roepnaam roepnaam?/1 Geboortedatum geboortedatum? Geslacht geslacht? Dit volgt de door EDEXML2 aangehouden codering: 1 = Mannelijk 2 = Vrouwelijk 9 = Niet gespecificeerd Start jaargroep 3 start_ondw_jgr3? Startdatum van het onderwijs in jaargroep 3. Jaargroep jaargroep 1 Aanduiding van het leerjaar of de niveaugroep waarin een individuele leerling of stamgroep zich in het huidige schooljaar bevindt. Vocabulaire gebonden lijst van waarden. Hoofdgroep groep identifier? Identifier van de stamgroep (groep met jaargroep) van de leerling. Samengestelde samengestelde_groep * Lijst van identifiers van de samengestelde groepen identifier groepen middels XML elementen samengestelde_groep. Vestiging vestiging identifier? Identifier van de aanduiding van de vestiging. Gebruikersnaam string? Door de school toegekende gebruikersnaam van de leerling. Deze gebruikersnaam kan gebruikt worden om in te loggen in digitale systemen. E-mail adres emailadres? Optioneel het e-mail adres van de leerling Foto URL fotourl? Optionele URL naar een fotobestand (in het LAS) Etniciteit Land van herkomst Land van herkomst Vader Land van herkomst Moeder Persoonsidentificatie, zie (*) Gewicht (nieuw) Gewicht Postcode (NL, BE of Overig) Instroomdatum Uitstroomdatum? Deze velden zijn allen onderdeel van EDEXML, maar worden om privacy redenen niet aanbevolen Toevoeging toevoeging? Het uitbreidingsblok voor leerling Mutatiedatum mutatiedatum? Datum van aanmaak of laatste gegevensmutatie van deze leerling Regels (uit EDEXML2): 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. EDEXML2 definieert een aanzienlijke set van gegevens over een leerling. Velen daarvan worden binnen deze afspraak ten behoeve van het uitwisselen van leerlinggegevens en toetsresultaten om privac y redenen echter niet aanbevolen.

18 / 34 4.3.3 Groepen Er kunnen optioneel groepen worden gedefinieerd. De lijst van groepen bestaat uit hoofdgroepen en samengestelde groepen. Beide hebben een eigen datamodel. De hoofdgroep (omringend element: groepen/groep) dat is afgeleid van het EDEXML2 gegevenselement GroepType. In de volgende tabel worden de deelelementen van groep uit EDEXML2 beschreven: Veld XML element of attribuut Aantal Opmerkingen Identifier @key 1 Naam naam 1 Jaargroep jaargroep 1 Optioneel vocabulaire gebonden Omschrijving omschrijving? Toevoeging toevoeging? Het uitbreidingsblok voor een groep Mutatiedatum mutatiedatum? Datum van aanmaak of laatste gegevensmutatie van deze groep De samengestelde groep (omringend element: samengestelde_groepen/samengestelde_groep) dat is afgeleid van het EDEXML2 gegevenselement SamengesteldeGroepType. In de volgende tabel worden de deelelementen van samengestelde_groep uit EDEXML2 beschreven. Merk op de het enige verschil met groep het ontbreken van veld Jaargroep is: Veld XML element of attribuut Aantal Opmerkingen Identifier @key 1 Naam naam 1 Omschrijving omschrijving? Toevoeging toevoeging? Het uitbreidingsblok voor een samengestelde groep Mutatiedatum mutatiedatum? Datum van aanmaak of laatste gegevensmutatie van deze groep 4.3.4 Leerkrachten Er kunnen optioneel gegevens over leerkrachten worden opgenomen (omringend element: leerkrachten/leerkracht) dat is afgeleid van het EDEXML2 gegevenselement LeerkrachtType. In de volgende tabel worden een aantal deelelementen uit EDEXML2 voorbeeldmatig beschreven: Veld XML element of Aantal Opmerkingen attribuut Identifier @key 1 Dit is een door het LAS toegekende identifier. In een DTDL scenario is dit de ketenbrede identifier. Deze moet om privacy redenen buiten de context van de uitwisseling leerresultaten geen betekenis hebben. Een BSN is dus bijvoorbeeld niet toegestaan. Achternaam achternaam?/1 Er is óf een achternaam (evt. aangevuld met Voorvoegsel voorvoegsel? voorvoegsels, voorletters en/of roepnaam) óf alleen een roepnaam. Voorletters voorletters-1? Roepnaam roepnaam?/1 Gebruikersnaam string? Door de school toegekende gebruikersnaam van de leerkracht. Deze gebruikersnaam kan gebruikt worden om in te loggen in digitale systemen. E-mail adres emailadres? Rollen rol / rolomschrijving * Aanduiding van de algemene rol(len) die een leerkracht heeft. Deze rol geldt onafhankelijk van de aan de leerkracht gekoppelde groep (stamgroep of samengestelde groep). Bij een leerkracht kan bijvoorbeeld aangegeven worden dat deze een algemene rol heeft als ICT-coördinator. Rol verwijst bij voorkeur naar een lijst met voorgedefinieerde rollen, maar er kan ook gekozen worden voor een vrij in te vullen rolomschrijving. Groepen groepen * Lijst van identifiers van de hoofdgroepen en samengestelde groepen van de leerkracht, middels XML elementen groep en samengestelde_groep. Toevoeging toevoeging? Het uitbreidingsblok voor leerkracht Mutatiedatum mutatiedatum? Datum van aanmaak of laatste gegevensmutatie van deze leerkracht Regels: Er is óf een achternaam (evt. aangevuld met voorvoegsels, voorletters en/of roepnaam) óf alleen een roepnaam.

19 / 34 Als er geen achternaam is dan mogen voorvoegsel en voorletters niet ingevuld zijn en moet er een roepnaam zijn. Het gebruik van de in EDEXML2 voorgedefinieerde rollen van leerkrachten is besproken in de Edustandaard werkgroep. Duidelijk is daarbij geworden dat er nadere verfijning of inperking nodig is qua rollen. Deze rollen moeten ook samen met het onderwijs worden bepaald. Er wordt verder ook getwijfeld of standaardrollen wel haalbaar zijn. Scholen willen ontzorgd worden, maar toch ook de flexibiliteit behouden. Belangrijk is dat de rol in het LAS niet automatisch 1-op-1 doorvertaald kan worden naar toegang tot specifieke data in een andere applicatie. 4.4 XML binding De XML binding wordt gedefinieerd in het bij de EDEXML2 afspraak horende W3C XML Schema s EDEXML.structuur.xsd en EDEXML.elementen.xsd. Tevens zijn bij deze afspraak voorbeeldbestanden opgenomen. De XML berichten voor leerlinggegevens binnen deze afspraak hebben de namespace: http://www.edustandaard.nl/leerresultaten/2/leerlinggegevens. 4.5 Implementatie Voor de verwerking hiervan 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.wsdl. Indien de webservice volgens het WSDL bestand daadwerkelijk wordt geïmplementeerd zal het hierin genoemde endpoint moeten worden aangepast. 4.6 Aanvullende verplichte controles Bovenop de algemene verplichte controles (zie par. 3.9/blz. 14) gelden voor de overdracht van leerlinggegevens de volgende aanvullende verplichte controles: Beide partijen moeten controleren of de in het bericht opgenomen XSD versie overeenkomt met een door hun ondersteunde XSD versie. De bericht XSD versie staat in de header (zie par. 4.2/blz. 16), de versie van de bij deze standaard horende XSD s is te vinden in het version attribuut op het XSD root element <xs:schema>. De EA moet controleren of de in het antwoordbericht opgenomen schoolidentificatie overeenkomt met de in de aanvraag verzonden schoolidentificatie. De EA moet controleren of de in het antwoordbericht opgenomen berichtaanmaakdatum later is dan de berichtaanmaakdatum van het voorgaande bericht (dit m.u.v. uiteraard van het allereerste bericht met leerlinggegevens) 4.7 Aanwijzingen verwerking door EA Er is sprake van nieuwe gegevens als de EA voor deze school/leerjaar combinatie nog geen leerlinggegevens heeft ontvangen. Sla de gegevens op. Onthoud de berichtaanmaakdatum en tijd zoals deze in de bericht gegevens is opgenomen. Er is sprake van wijzigingen als de EA voor deze school/leerjaar 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 bericht gegevens is opgenomen

20 / 34 5 Getrapt ophalen leerlinggegevens Binnen deze afspraak is er voor gekozen om 2 manieren te ondersteunen voor de overdracht van leerlinggegevens: 1. Alles-in-één: Alle leerlinggegevens in één keer ophalen. 2. Getrapt: De leerlinggegevens in blokjes ophalen. Een zeer belangrijke keuze hierbij is dat het niet verplicht is beide manieren te implementeren. Een EA of LAS moet één van de twee, of beide, overdrachtsmanieren ondersteunen. In voorgaand hoofdstuk is de Alles-in-één overdracht van leerlinggegevens beschreven. In dit hoofdstuk wordt het getrapt ophalen van leerlinggegevens beschreven. 5.1 Ontwerpbeslissingen Getrapt ophalen: Hierbij worden de gegevens van alle ingeschreven leerlingen getrapt opgehaald. De volgorde is: 1. Eerst de organisatorische gegevens van school en groepen (basisgegevens), 2. Dan de leerlinggegevens (eventueel in blokjes per groep of verzameling groepen) en 3. Tenslotte de leerkrachtgegevens (eventueel in blokjes per groep of verzameling groepen). Opdeling in drie webservices 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 Response structuur ongewijzigd: De basis response structuur van de oorspronkelijke leerlinggegevens response (par. 4.3) blijft ongewijzigd, alleen worden nu i.p.v. het geheel onderdelen teruggegeven: Antwoord onderdeel Omringend element Bij volledig ophalen Bij getrapt ophalen structuur Bij getrapt ophalen leerlingen Bij getrapt ophalen leerkrachten Schoolgegevens <school> X X X X Groepenlijst <groepen> X X Leerlingen <leerlingen> X X Leerkrachten <leerkrachten> X X De schoolgegevens worden altijd (in iedere response) doorgegeven. Het gaat hier om een zeer beperkte hoeveelheid dat die altijd nodig is om de verplichte controles (par. 3.4.3) uit te kunnen voeren. Met de beslissing om de response structuren uit te splitsen maar verder ongewijzigd te laten hopen we het partijen die al de oorspronkelijk webservice hebben geïmplementeerd eenvoudig te maken ook de getrapte variant te implementeren. In principe is het antwoord op een getrapt verzoek niets anders dan een filtering van het volledige antwoord, iets wat technisch relatief eenvoudig te realiseren moet zijn. Ophalen leerlingen en leerkrachten op groepsbasis Het ophalen van leerling- en leerkrachtgegevens gaat in de getrapte versie op basis van een lijst met groepen. In theorie kunnen er leerlingen en leerkrachten aanwezig zijn die aan geen enkele groep gebonden zijn. Deze kunnen ook opgevraagd worden (door geen groepsidentificatie mee te geven) Als er in een verzoek groepen worden gerefereerd die niet bestaan worden ze genegeerd. Dit is dus geen fout. Reden: Tussen het ophalen van de structuur en het ophalen van groepsgerelateerde gegevens 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. 5.2 Implementatie aanroepen (requests) 5.2.1 Ophalen structuur Deze is identiek aan de aanroep voor een volledig set van leerlinggegevens (par. 4.2) en kent alleen een ander omringend element: <Structuur>. Bijvoorbeeld: