Magister

Import - Magister

Inleiding

De koppeling Magister Import haalt de groepen en de studenten (leerlingen) van een school uit Magister op en legt ze vast in de basisdata van Xedule Roosteren. Doel is dat de klassen, de lesgroepen en de leerlingen met hun groepslidmaatschappen niet met de hand in Xedule hoeven te worden ingevoerd, zodat het rooster altijd uitgaat van de leerlingadministratie.

De import werkt per organisatorische eenheid en per schooljaar. Welke school in Magister bij de eenheid hoort, wordt bepaald door het BRIN-nummer met vestigingscode (BRIN6) in de referentie van de organisatorische eenheid. Xedule haalt de gegevens op uit twee Magister-diensten: de leerlinggegevens (de UWLR smalle set voor het voortgezet onderwijs) met de groepen, de samengestelde groepen en de leerlingen, en de gebruikersgegevens (SCIM) met het leerlingnummer, het e-mailadres en de gebruikersnaam.

Afbeelding 1 – Van Magister, via de tabbladen Groepen en Studenten, naar de basisdata van Xedule.

De koppeling kent één richting: gegevens gaan van Magister naar Xedule. Er wordt niets naar Magister teruggeschreven. Een import schrijft ook niet direct weg: Xedule toont eerst een vergelijking en voert pas door wanneer de gebruiker daarvoor kiest (zie “De drie doorvoerknoppen”). Docenten, vakken en inschrijvingen worden niet via deze koppeling geïmporteerd.

Het activeren van de koppeling en het vastleggen van de referentie gebeuren door Xedule Support. Het geven van toestemming in Magister, het controleren van de opgehaalde gegevens en het doorvoeren ervan zijn de verantwoordelijkheid van de functioneel beheerder van de school.

Randvoorwaarden en functionele eisen

Technische randvoorwaarden

Aan de onderstaande voorwaarden moet zijn voldaan voordat de import gegevens oplevert.

• In de Privacymanager van Magister heeft de school Xedule toestemming gegeven voor beide producten: de UWLR smalle set en de SCIM-gebruikersgegevens. Ontbreekt een van beide, dan levert de import geen gegevens op.
• De school is in Magister bekend onder de BRIN6 die in de referentie van de organisatorische eenheid staat (zie “Referentie van de organisatorische eenheid”).
• De gebruiker heeft in Xedule de rechten voor de Magister-import (zie “Rechten”).
• Magister levert bij elke import de volledige set van het schooljaar. Er wordt niet alleen naar wijzigingen gekeken.

Functionele eisen aan de inrichting van Magister

• Elke leerling heeft in Magister een stamgroep die ook als groep in de leerlinggegevens van die school voorkomt.
• Leerlingen hebben een actief, niet verlopen en niet geblokkeerd leerlingaccount met een leerlingnummer, precies één primair e-mailadres en een gebruikersnaam. Alleen dan worden de code, het e-mailadres en de gebruikersnaam van de student gevuld (zie “Leerlingnummer, e-mailadres en gebruikersnaam”).
• Groepen hebben binnen één school een unieke sleutel. Komt dezelfde groep dubbel voor, dan telt alleen de eerste.

Functionele eisen aan de inrichting van Xedule

• De referentie van de organisatorische eenheid bevat de BRIN6 van de school (zie “Referentie van de organisatorische eenheid”).
• Er is een jaartijdvak voor het schooljaar dat u importeert. Het schooljaar volgt uit het beginjaar van het gekozen tijdvak: begint het tijdvak in 2025, dan wordt schooljaar 2025-2026 opgehaald.
• De groepen worden geïmporteerd vóór de studenten. Een lidmaatschap kan alleen worden vastgelegd als de groep al in Xedule staat (zie “Handmatig importeren en de volgorde”).
• Bestaande Xedule-groepen en -studenten die u met Magister wilt verbinden, hebben dezelfde referentie als in Magister, of dezelfde code (zie “Type en koppeling van de groep” en “Leerlingnummer, e-mailadres en gebruikersnaam”).

De configuratie

De Magister-import heeft geen eigen configuratiepagina onder Beheer/Configuratie. De verbinding met Magister wordt centraal door Xedule beheerd; per school zijn alleen de referentie van de organisatorische eenheid en de rechten van belang. Wat er per gegevensgroep wordt opgehaald, staat in de hoofdstukken “Groepen” en “Studenten”.

Referentie van de organisatorische eenheid

Veld	Waarde / voorbeeld	Toelichting
Referentie van de organisatorische eenheid	00XX01 of 00XX01,00XX02	De BRIN6 van de school: het BRIN-nummer van vier tekens met de vestigingscode van twee tekens. Hoort de eenheid bij meer vestigingen, dan staan de BRIN6-codes gescheiden door een komma, zonder spaties. Elke code moet precies zes tekens hebben; een BRIN-nummer van vier tekens of een code met een spatie levert geen gegevens op. De referentie wordt door Xedule Support vastgelegd.

Met de BRIN6 zoekt Xedule bij Magister de school die die vestiging heeft. Bij meer BRIN6-codes worden de gegevens van alle vestigingen samen in één vergelijking getoond.

Rechten

Het menu Import > Magister en de tabbladen Groepen en Studenten zijn alleen zichtbaar voor gebruikers met de bijbehorende actierechten (Magister, Magister Groepen en Magister Studenten). Zonder die rechten kan er ook niet worden doorgevoerd.

Het ophalen van de gegevens

Bij elke verversing doorloopt Xedule per organisatorische eenheid dezelfde stappen. Eerst wordt de school bij Magister opgezocht aan de hand van de BRIN6. Daarna worden de leerlinggegevens van het schooljaar opgehaald: de groepen, de samengestelde groepen en de leerlingen met hun groepen. Voor het tabblad Studenten worden daarnaast de gebruikersgegevens van de school opgehaald: alleen actieve, niet verlopen en niet geblokkeerde accounts van het type leerling, in porties van tweehonderd.

Afbeelding 2 – De stappen bij het ophalen van de gegevens.

• Het schooljaar wordt meegegeven in de vorm 2025-2026.
• De leerlinggegevens worden altijd volledig opgehaald, nooit alleen de wijzigingen sinds de vorige keer.
• De opgehaalde gegevens gelden voor het hele schooljaar: groepen, studenten en lidmaatschappen krijgen in Xedule het jaartijdvak als periode. Data uit Magister, zoals een begin- of einddatum van een plaatsing, worden niet overgenomen.

Groepen

Bron: de groepen en de samengestelde groepen uit de leerlinggegevens (UWLR smalle set) van elke BRIN6. Een groep in Magister wordt in Xedule een klas, een samengestelde groep een lesgroep.

Extern veld (exacte benaming)	Betekenis	Xedule-bestemming	Verwerking / filter
groep.key samengestelde_groep.key	Unieke sleutel van de groep in Magister.	Referentie	Sleutel voor de koppeling (zie “Type en koppeling van de groep”). Komt dezelfde sleutel binnen één school dubbel voor, dan telt de eerste.
groep.naam samengestelde_groep.naam	Naam van de groep.	Code en naam	Code en naam krijgen dezelfde waarde.
groep.omschrijving samengestelde_groep.omschrijving	Omschrijving van de groep.	Opmerking	Wordt overgenomen wanneer de groep nieuw in Xedule wordt toegevoegd. Maakt geen deel uit van de vergelijking; bij een bestaande groep wordt een gewijzigde omschrijving daardoor niet bijgewerkt.
groep / samengestelde_groep	Soort groep in Magister.	Type	groep wordt klas, samengestelde_groep wordt lesgroep.
—	Magister levert geen aantal studenten.	Aantal studenten	Blijft leeg bij een nieuwe groep. Bij bijwerken wordt een aantal dat in Xedule bij een gekoppelde groep is ingevuld, leeggemaakt.
jaargroep, mutatiedatum	Leerjaar en datum van de laatste wijziging.	—	Wordt niet gebruikt.

De periode en de beschikbaarheid van de groep zijn het jaartijdvak van het schooljaar. De vergelijking toont per groep de code, de naam, het type, het aantal studenten en de referentie. Alleen deze velden worden bij bijwerken overschreven; de opmerking, de periode en de beschikbaarheid van een bestaande groep blijven zoals ze in Xedule staan.

Type en koppeling van de groep

In Magister	In Xedule	Gebruik
Groep (stamgroep)	Klas	De vaste groep van de leerling; elke leerling heeft er één.
Samengestelde groep	Lesgroep	Een groep die is samengesteld uit leerlingen van verschillende stamgroepen, bijvoorbeeld voor een keuzevak.

Een groep uit Magister wordt gekoppeld aan de Xedule-groep met dezelfde referentie. Heeft de Xedule-groep geen referentie, dan wordt gekoppeld op de combinatie van code, periode en type. Een bestaande groep zonder referentie en met een andere code wordt dus niet herkend: de import biedt dan een nieuwe groep aan.

Studenten

Bron: de leerlingen uit de leerlinggegevens (UWLR smalle set) van elke BRIN6, aangevuld met de gebruikersgegevens (SCIM) van de school. Een leerling uit de leerlinggegevens wordt aan een gebruiker gekoppeld wanneer de sleutel van de leerling gelijk is aan het id van de gebruiker.

Extern veld (exacte benaming)	Betekenis	Xedule-bestemming	Verwerking / filter
leerling.key	Unieke sleutel van de leerling in Magister.	Referentie	Sleutel voor de koppeling (zie “Leerlingnummer, e-mailadres en gebruikersnaam”) en voor de koppeling met de gebruikersgegevens.
leerling.roepnaam	Roepnaam.	Voornaam	—
leerling.achternaam leerling.voorvoegsel	Achternaam en voorvoegsel.	Achternaam	Met voorvoegsel als "achternaam, voorvoegsel", bijvoorbeeld "Vries, de".
studentNumber (gebruikersgegevens)	Leerlingnummer.	Code	Zie “Leerlingnummer, e-mailadres en gebruikersnaam” voor de situatie zonder gebruikersgegevens.
emails, primair adres (gebruikersgegevens)	E-mailadres.	E-mail	Leeg zonder gebruikersgegevens.
userName (gebruikersgegevens)	Gebruikersnaam.	Gebruikersnaam (login)	Gebruikt voor het inloggen via Magister. Leeg zonder gebruikersgegevens.
leerling.groep.key	De stamgroep van de leerling.	Lidmaatschap van de klas	Zie “Lidmaatschappen van klassen en lesgroepen”.
leerling.samengestelde_groepen.key	De samengestelde groepen van de leerling.	Lidmaatschap van de lesgroepen	Zie “Lidmaatschappen van klassen en lesgroepen”.
eckid, jaargroep, mutatiedatum	Ketenidentificatie, leerjaar en wijzigingsdatum.	—	Wordt niet gebruikt.

De student studeert en is beschikbaar gedurende het hele jaartijdvak. Alle leerlingen die Magister voor het schooljaar levert, worden aangeboden; Xedule filtert zelf niet op een in- of uitschrijfdatum. Bij bijwerken wordt het studeren van een bestaande student binnen het schooljaar vervangen door het hele jaartijdvak; perioden buiten het schooljaar blijven staan.

Leerlingnummer, e-mailadres en gebruikersnaam

Het leerlingnummer, het e-mailadres en de gebruikersnaam komen uit de gebruikersgegevens. Wordt voor een leerling geen actief leerlingaccount gevonden, dan krijgt de student geen e-mailadres en geen gebruikersnaam, en wordt de code samengesteld uit de roepnaam, het voorvoegsel en de achternaam, direct achter elkaar en zonder spaties.

Leerling in Magister	Met leerlingaccount	Zonder leerlingaccount
Sanne de Vries, leerlingnummer 123456	Code 123456, e-mailadres en gebruikersnaam gevuld	Code SannedeVries, geen e-mailadres en geen gebruikersnaam
Tim Jansen, leerlingnummer 123457	Code 123457, e-mailadres en gebruikersnaam gevuld	Code TimJansen, geen e-mailadres en geen gebruikersnaam

Een student uit Magister wordt gekoppeld aan de Xedule-student met dezelfde referentie. Heeft de Xedule-student geen referentie, dan wordt gekoppeld op de code. Komt een leerlingaccount pas later beschikbaar, dan wijzigt bij de volgende import de code van de student van de samengestelde naam in het leerlingnummer; de koppeling blijft daarbij via de referentie behouden.

Lidmaatschappen van klassen en lesgroepen

• De stamgroep van de leerling wordt een lidmaatschap van de klas met dezelfde referentie; de samengestelde groepen worden lidmaatschappen van de lesgroepen met dezelfde referentie.
• Elk lidmaatschap geldt voor het hele jaartijdvak. Bij bijwerken wordt de periode van een bestaand lidmaatschap binnen het schooljaar vervangen door het hele jaartijdvak.
• Een lidmaatschap dat alleen in Xedule staat, wordt bij bijwerken niet weggehaald. Alleen de knop toevoegen, bijwerken en verwijderen trekt zo’n lidmaatschap in voor het schooljaar.
• Een lidmaatschap kan alleen worden vastgelegd als de groep al in Xedule staat. Staat de klas of lesgroep niet in Xedule, dan wordt de student wel toegevoegd of bijgewerkt, maar alleen dat lidmaatschap overgeslagen. De studentenimport maakt de ontbrekende groep niet aan. Importeer daarom eerst de groepen (zie “Handmatig importeren en de volgorde”).
• Staat een samengestelde groep van een leerling niet in de geleverde groepen, dan wordt alleen dat lidmaatschap overgeslagen, met een melding (zie “Meldingen in het meldingenscherm”).

De vergelijking toont per student de code, de voornaam, de achternaam, het e-mailadres, de referentie, de gebruikersnaam, het studeren en de lidmaatschappen.

Import: doorvoeren, handmatig en via geplande taak

Handmatig importeren en de volgorde

De import staat in het menu Import > Magister, met de tabbladen Groepen en Studenten. Een tabblad toont eerst "Geen data. Druk op verversen om data op te halen."; met de knop verversen worden de gegevens opgehaald en naast de gegevens in Xedule gezet.

• Importeer eerst de Groepen en voer die door, en daarna de Studenten. De studentenimport maakt zelf geen groepen aan en legt alleen lidmaatschappen vast van groepen die al in Xedule staan. Xedule dwingt deze volgorde niet af.
• Na het doorvoeren verschijnt de melding "{naam van de import} gegevens doorgevoerd".

Geplande taken

Beide imports kunnen ook als geplande taak worden uitgevoerd, op het niveau van het jaar. Plan de taak voor de groepen vóór de taak voor de studenten. Meldingen van een geplande taak staan bij de uitvoering van die taak. Staat in MyXedule de instelling aan waarmee studenten na een geplande taak automatisch worden toegevoegd, dan worden de geïmporteerde studenten na een geplande studentenimport ook in MyXedule bijgewerkt.

De drie doorvoerknoppen

Een import schrijft nooit rechtstreeks weg. Nadat de gegevens zijn opgehaald, toont Xedule een vergelijking: links de gegevens zoals het bronsysteem ze aanlevert, rechts dezelfde gegevens zoals ze op dat moment in Xedule staan. Pas wanneer u op een doorvoerknop drukt, verandert er iets in Xedule. Welke knop u kiest, bepaalt hoe ver dat doorvoeren gaat.

Elke import doorloopt dezelfde vier stappen; alleen de laatste stap wijzigt gegevens.

Er zijn drie knoppen. Ze werken in alle importkoppelingen op dezelfde manier en gaan altijd één kant op: van het bronsysteem naar Xedule. Via deze schermen wordt er nooit iets naar het bronsysteem teruggeschreven.

Pictogram	Knop	Wat de knop doet	Wanneer u die kiest
	bijwerken	Werkt alleen de regels bij die zowel in het bronsysteem als in Xedule bestaan en waarvan een of meer waarden verschillen. Er wordt niets toegevoegd en niets verwijderd.	Als u alleen wijzigingen op bestaande gegevens wilt overnemen en bewust nog geen nieuwe objecten in Xedule wilt laten ontstaan.
	toevoegen en bijwerken	Doet hetzelfde als bijwerken en maakt daarnaast de regels aan die alleen in het bronsysteem voorkomen. Er wordt niets verwijderd.	De gebruikelijke keuze voor een reguliere import gedurende het jaar.
	toevoegen, bijwerken en verwijderen	Doet hetzelfde als toevoegen en bijwerken en trekt daarnaast de geldigheid in van de objecten die alleen nog in Xedule bestaan.	Alleen wanneer het bronsysteem voor deze gegevensgroep volledig leidend is en de aanlevering compleet is.

Er is geen knop waarmee u uitsluitend toevoegt: bij elke knop die toevoegt, worden bestaande regels ook bijgewerkt.

Het resultaat van elke knop, per soort verschil tussen beide kanten.

Welke velden worden overgenomen

Bij een bijwerking worden niet alle velden overschreven, maar alleen de velden die daadwerkelijk verschillen; regels die in het geheel niet verschillen worden overgeslagen. Welke velden worden vergeleken, ligt per gegevensgroep vast: dat zijn precies de velden die in de vergelijking naast elkaar worden getoond. Velden die niet in de vergelijking voorkomen, worden door een import dus nooit overschreven.

Wat verwijderen precies doet

Verwijderen is geen harde verwijdering. Xedule trekt de geldigheid van het object in voor het tijdvak waarin u werkt; het object zelf en zijn historie blijven bestaan. In de praktijk betekent dat bijvoorbeeld dat een medewerker voor dat tijdvak uit dienst wordt gezet, een student in dat tijdvak niet meer studeert, een faciliteit in dat tijdvak niet meer geldig is, of dat een relatie tussen twee objecten voor dat tijdvak vervalt. Een groep is de uitzondering: valt de periode van de groep volledig binnen het tijdvak, dan wordt de groep zelf opgeruimd.

• Alleen gegevens die per tijdvak geldig zijn, kunnen op deze manier worden ingetrokken. Gegevenssoorten zonder tijdvak worden door de verwijdervariant ongemoeid gelaten.
• De knop kijkt niet naar de herkomst van een object. Objecten die handmatig in Xedule zijn aangemaakt en die niet in de aanlevering voorkomen, worden dus ook ingetrokken — tenzij de koppeling ze via een vast filter buiten de vergelijking houdt.
• Er wordt niet gecontroleerd of het object elders nog in gebruik is. Een object dat nog in het rooster of de jaarplanning voorkomt, wordt evengoed ingetrokken.

Alleen bij deze variant vraagt Xedule vooraf om een bevestiging. Het doorvoeren zelf gebeurt in één handeling: gaat er iets mis, dan blijven de gegevens in Xedule zoals ze waren.

Let op bij Magister: deze import heeft geen vast filter. De vergelijking omvat alle groepen en alle studenten van het jaartijdvak, ook groepen en studenten die u zelf in Xedule hebt aangemaakt. Met toevoegen, bijwerken en verwijderen worden die dus ook ingetrokken.

Hoe een regel links aan een regel rechts wordt gekoppeld

Of een regel als nieuw, als gewijzigd of als alleen in Xedule wordt gezien, hangt af van de manier waarop beide kanten aan elkaar worden gekoppeld. Xedule gebruikt daarvoor in de eerste plaats de referentie uit het bronsysteem die bij het Xedule-object is vastgelegd. Is die niet gevuld, dan valt de vergelijking terug op de natuurlijke sleutel van het object: bijvoorbeeld het personeelsnummer van een medewerker, de code van een student of leeractiviteit, of de combinatie van code, periode en type bij een groep. Hoofdletters spelen daarbij geen rol.

Dit verklaart de twee situaties die het vaakst tot onverwachte uitkomsten leiden. Wijzigt in het bronsysteem de sleutel van een object waarvan in Xedule nog geen referentie is vastgelegd, dan ziet Xedule dat als een nieuw object naast het bestaande. En heeft een handmatig aangemaakt Xedule-object dezelfde sleutel als een aangeleverd object, dan worden beide als één regel behandeld en wordt het handmatige object met de aangeleverde waarden bijgewerkt.

Waarop een knop wordt toegepast

Een knop werkt op alle regels van de gegevensgroep die op dat moment geopend is, en niet op een selectie; er is geen aanvinkmogelijkheid per regel. Wel kan de lijst worden gefilterd op het soort verschil — alles, alleen links, alleen rechts, in beide, of in beide maar ongelijk — en werkt de knop daarna alleen op de regels die het filter overlaat. Wordt de knop op het overzichtstabblad gebruikt, dan geldt de keuze voor alle gegevensgroepen van die import tegelijk.

Dezelfde keuze in een geplande taak

Wordt de import als geplande taak uitgevoerd, dan vervalt de vergelijkingsstap en ligt de keuze vooraf vast. Per gegevensgroep zijn dezelfde drie mogelijkheden in te stellen, aangevuld met de mogelijkheid die gegevensgroep over te slaan. Is er voor een taak niets ingericht, dan geldt de ruimste variant en wordt er dus ook verwijderd. Richt een geplande taak daarom altijd bewust in, en werk in de beginperiode handmatig tot de gegevensstroom stabiel is.

Foutafhandeling en meldingen

Als het ophalen niet lukt

Mislukt het ophalen, dan blijft het tabblad na verversen op "Geen data. Druk op verversen om data op te halen." staan; een toelichting verschijnt niet. Alleen als de verbinding met de server zelf mislukt, verschijnt "er is een fout opgetreden". De oorzaak wordt vastgelegd in de technische logging. Loop bij een leeg tabblad de onderstaande situaties na en neem, als die niet de oorzaak zijn, contact op met Xedule Support.

Situatie	Geldt voor	Wat te doen
De referentie van de organisatorische eenheid is leeg, bevat een code die niet precies zes tekens heeft, of bevat een spatie.	Groepen en Studenten	Laat de referentie door Xedule Support corrigeren (zie “Referentie van de organisatorische eenheid”).
Magister kent de BRIN6 niet, of de school heeft in de Privacymanager geen toestemming gegeven voor de UWLR smalle set en de SCIM-gebruikersgegevens.	Groepen en Studenten	Controleer de BRIN6 en laat beide producten in de Privacymanager activeren (zie “Technische randvoorwaarden”).
Magister levert voor het schooljaar geen leerlinggegevens.	Groepen en Studenten	Controleer of het schooljaar in Magister is ingericht en of het gekozen tijdvak in het juiste schooljaar valt.
Er is in Xedule geen jaartijdvak voor het schooljaar.	Groepen en Studenten	Richt het jaartijdvak in (zie “Functionele eisen aan de inrichting van Xedule”).
De stamgroep van een leerling komt niet voor in de groepen van die school.	Studenten	Controleer de stamgroep van de leerling in Magister.
Een leerlingaccount heeft meer dan één primair e-mailadres, of geen e-mailadres.	Studenten	Corrigeer het e-mailadres van het account in Magister.

Gegevens die zonder melding worden overgeslagen

Situatie	Gevolg
Geen actief leerlingaccount voor een leerling	De code wordt samengesteld uit de naam; e-mailadres en gebruikersnaam blijven leeg (zie “Leerlingnummer, e-mailadres en gebruikersnaam”).
Dezelfde groep komt binnen één school dubbel voor	Alleen de eerste groep wordt aangeboden.
Een leerling zonder stamgroep	Er wordt geen lidmaatschap van een klas vastgelegd.
Een gewijzigde omschrijving van een bestaande groep	De omschrijving wordt niet bijgewerkt (zie “Groepen”).
Een lidmaatschap van een groep die nog niet in Xedule staat (handmatige import)	Het lidmaatschap wordt niet vastgelegd; de student zelf wel. Importeer eerst de groepen en daarna opnieuw de studenten (zie “Handmatig importeren en de volgorde”). Bij een geplande taak verschijnt hiervan wel een melding (zie “Meldingen in het meldingenscherm”).

Meldingen in het meldingenscherm

Bij een handmatige import staan meldingen op het tabblad meldingen; bij een geplande taak staan ze bij de uitvoering van de taak. De melding staat zoals ze in het scherm verschijnt.

Melding	Wanneer / oorzaak	Oplossing
Student {studentcode} is geplaatst in de samengestelde groep met ID {key}. Deze groep ontbreekt in de geïmporteerde groepen.	De leerling is in Magister geplaatst in een samengestelde groep die niet in de geleverde groepen van die school staat. Alleen dit lidmaatschap wordt overgeslagen.	Controleer de samengestelde groep in Magister en importeer daarna opnieuw.
Kan Groep '{groepsnaam}' niet vinden	Alleen bij een geplande taak Studenten. Een lidmaatschap verwijst naar een klas of lesgroep die niet in Xedule staat. Alleen dit lidmaatschap wordt overgeslagen; de student wordt wel verwerkt.	Importeer eerst de groepen en voer daarna de studentenimport opnieuw uit.