Voor het genereren van de juiste gegevens voor School Data Sync moeten de identiteiten van docenten en leerlingen in Magister worden gepaard (gekoppeld, "match") aan de overeenkomstige identiteiten van alle gebruikers in Microsoft 365 en Teams, dus in Azure Active Directory (AAD). In de uitvoer die TeamSync genereert, wijst ID naar de unieke identiteit van een medewerker of gebruiker in AAD. De ID kan een suffix bevatten, maar dat hoeft niet. Indien nodig wordt door School Data Sync aan dit veld de suffix toegevoegd om te refereren aan een unieke gebruiker in AAD.

Voor leerlingen kan makkelijker het Magister email gebruikt om de unieke ID te bepalen. Voor medewerkers is dit lastiger omdat in Magister geen e-mailadres is opgeslagen op een manier die TeamSync kan uitlezen.

De volgende methoden van koppeling worden ondersteund voor medewerkers:

• ID ← Magister:code

• ID ← Magister:loginaccount

• ID ← CSV[EmployeeId_Prefix + Magister:stamnr]

De volgende methoden van koppeling worden ondersteund voor leerlingen:

• ID ← Magister:email

• ID ← Magister:loginaccount

In het configuratiebestand moet één koppelmethode voor leerlingen en één koppelmethode voor medewerkers worden gedefinieerd.

TeamSync vanaf versie 20201127 ondersteunt niet meer het opzoeken van de UserPrincipalName in active Directory (via INI-parameters useemail, ADsearchscope, ADserver). Het alternatief hiervoor is om een CSV-opzoektabel te gebruiken. Je kunt deze CSV-tabel aanmaken met behulp van een script die de informatie leest uit Active Directory of uit een andere bron. Een voorbeeld van een script die de CSV-tabel vult met informatie uit Entra ID met behulp van Microsoft Graph PowerShell SDK vind je in Ophalen-EntraMedewerkerUPN-voorbeeld.ps1. Dit script genereert een CSV met een kolom UserPrincipalName en een kolom EmployeeId.

De gewenste koppelmethode wordt aangeduid met één van de volgende variabelen.

• medewerker_id=loginaccount : Koppel Id aan Magister loginaccount. Id bevat geen domeinsuffix. SDS vult Id aan met een domeinsuffix.

• medewerker_id=code : Koppel Id aan Magister code. Id bevat geen domeinsuffix. School Data Sync (SDS) vult Id aan met een domeinsuffix.

• medewerker_id=csv_upn : Koppel Id aan UserPrincipalName van de gebruiker in een extern CSV-bestand waarvan employeeId overeenkomt met EmployeeId_prefix + Magister-stamnummer. Zie sectie Medewerker-UPN-CSV voor een beschrijving van dit bestand. Id bevat de domeinsuffix.

• leerling_id=loginaccount : koppel Id aan Magister loginaccount. Id bevat geen domeinsuffix. SDS vult Id aan met een domeinsuffix.

• leerling_id=email : Koppel ID aan Magister email. Id bevat een domeinsuffix. De leerlingen worden uniek geidentificeerd met het "email" veld in de Magister leerlingkaart. Het is de verantwoordelijkheid van de school om ervoor te zorgen dat het email-veld van leerlingen is ingevuld met de overeenkomstige userPrincipalName van de leerling in Azure AD / Microsoft 365.

Dit bestand heet bij verstek Import-Magister.ini voor het importscript of Export-SchoolDataSync.ps1 voor het exportscript en staat in dezelfde map als het script. Het bevat configuratievariabelen die de werking van TeamSync beinvloeden. Een andere bestandsnaam kan worden aangegeven door middel van de Parameter Inifile. Configuratievariabelen worden behandeld in hoofdstuk Configuratie.

In deze map worden Filters geplaatst ten behoeve van het importscript.

Het importscript plaatst hier tijdelijke bestanden, die slechts dienen om de goede werking te controleren van de Magister webservice en instellingen en filters van TeamSync,

Het importscript plaatst in deze map een aantal bestanden met uit Magister opgehaalde gegevens over leerlingen, docenten en vakken. Het exportscript heeft deze bestanden nodig om in te lezen en bewerkt ze verder.

• magister_leer.clixml

• magister_docent.clixml

• magister_vak.clixml

Bestanden met de extensie ".clixml" zijn bestanden in een XML-formaat die door PowerShell kunnen worden weergegeven met het volgende commando:

In deze map worden Filters geplaatst ten behoeve van het exportscript.

Het exportscript plaatst hier tijdelijke bestanden, die dienen om de goede werking te controleren van TeamSync, met name instelingen en filters.

Het exportscript maakt in deze map volgens de specificaties van School Data Sync de volgende bestanden aan.

• School.csv

• Section.csv

• Student.csv

• StudentEnrollment.csv

• Teacher.csv

• TeacherRoster.csv

Deze bestanden zijn bedoeld om te uploaden naar het gewenste synchronisatieprofiel in School Data Sync.

In deze map worden de naar SDS te uploaden gegevensbestanden voor alle scholen wordt verzameld. Elke keer dat Export-SchoolDataSync wordt uitgevoerd, wordt de uitvoer die afzonderlijk worden opgeslagen in de exportdatamap óók toegevoegd aan de bestanden in de ExportVerzamelmap. Deze functie is toegevoegd in TeamSync vanaf versie 20240222 en compenseert het gebrek aan "Single Subscription - Multi-Academy Trust Support" in de huidige School Data Sync v2. Het maakt het mogelijk dat TeamSync gegevens van verscheidene scholen samenvoegt om te kunnen uploaden naar School Data Sync v2.

Voor elk van de vereiste bestanden in de SDS CSV V1 specificatie, neemt TeamSync de volgende beslissing:

• Indien het bestand in de ExportVerzamelmap niet aanwezig is, dan creeert TeamSync een nieuw bestand en bewaart de gegevens daarin.

• Indien het bestand in de ExportVerzamelmap wel aanwezig is, dan voegt TeamSync de gegevens toe aan het bestaande bestand.

Indien de koppelmethode is ingesteld op een CSV-bestand (configuratieparameter "medewerker_id=csv_upn"), dan leest het importscript dit bestand uit de uit de importfiltermap. Het importscript gebruikt deze tabel om de medewerkers UserPrincipalName op te zoeken bij een stamnummer uit Magister.

De inhoud van dit bestand bestaat uit een kopregel en één of meer gegevensregels. De kopregel bevat "employeeId,UserPrincipalName". Voor elke medewerker in Magister is er een gegevensregel. De gegevensregels bevatten elk twee gegevensvelden, gescheiden door een komma. Het eerste gegevensveld bevat de employeeId van een medewerker. Het tweede gegevensveld bevat de overeenkomstige UserPrincipalName die de gebruiker in Entra ID uniek identificeert. De velden mogen omsloten zijn door dubbele aanhalingstekens, maar dat is niet verplicht.

Normaliter zul je deze tabel moeten ophalen uit Entra ID, met behulp van een script afgeleid van het voorbeeldbestand Ophalen-EntraMedewerkerUPN-voorbeeld.ps1. Let op: dit script slaat de medewerkergegevens op in de huidige map. Je zult het CSV-bestand zelf moeten kopieren naar de juiste importmap afhankelijk van de gebruikte configuratie voor het importscript.

In zowel de Importfiltermap als de Exportfiltermap kunnen één of meer bestanden worden geplaatst om filters toe te passen op de te verwerken gegevens. Hierbij wordt gebruikt gemaakt van zogenaamde 'regular expressions' oftewel regex-patronen. Met behulp van de regex-patronen kunnen krachtige selecties worden gemaakt die bepalen welke gegevens moeten worden verwerkt en welke niet. De filters kunnen worden toegepast om de hoeveelheid te verwerken gegevens te reduceren en slimme selecties te maken op welke gegevens resulteren in actieve klassenteams.

Er kan bij het ophalen van Magistergegevens door Import-Magister.ps1 worden gefilterd op:

• docent(id),

• klas,

• studie,

• locatie (overeenkomend met Administratieve_eenheid.Omschrijving in Magister).

Er kan bij het bepalen van klassenteams door Export-Magister.ps1 worden gefilterd op:

• docent(id),

• klas,

• studie,

• locatie (overeenkomend met Administratieve_eenheid.Omschrijving in Magister),

• teamnaam.

Er zijn twee typen filters te definieren:

• insluitende of inclusieve filters, en

• uitsluitende of exclusieve filters.

Bij insluitende filters worden alleen de gegevens die overeenkomen met de opgegeven regex-patronen verwerkt en de rest wordt weggegooid. Bij uitsluitende filters worden alle gegevens die niet overeenkomen met de opgegeven patronen verwerkt, terwijl de gegevens die wel overeenkomen niet worden verwerkt. Je kunt insluitende en uitsluitende filters combineren om te komen tot een nauwkeurige gedefinieerde verzameling klassenteams, die precies beantwoordt aan de behoefte.

De volgende filterbestanden kunnen worden gedefinieerd door het overeenkomstige bestand in de Importfiltermap en/of Exportfiltermap te definieren en deze te vullen met de gewenste regex-patronen.

• excl_docent.csv : dit bevat filters voor het uitsluitend filteren van docenten op Id.

• incl_docent.csv : filters voor het insluitend filteren van docenten op Id.

• excl_klas.csv : filters voor het uitsluitend filteren van leerlingen op klasnaam.

• incl_klas.csv : filters voor het insluitend filteren van leerlingen op klasnaam.

• excl_studie.csv : filters voor het uitsluitend filteren van leerlingen op studie.

• incl_studie.csv : filters voor het insluitend filteren van leerlingen op studie.

• incl_locatie.csv : filters voor het insluitend filteren van leerlingen op locatie oftewel Magister:Administratieve_eenheid.Omschrijving.

• incl_teamnaam.csv : (alleen in de ExportFiltermap t.b.v. Export-SchoolDataSync.ps1) filters voor het insluitend filteren van teams op (weergave)naam. t.b.v. Export-SchoolDataSync.ps1

• excl_teamnaam.csv : (alleen in de ExportFiltermap t.b.v. Export-SchoolDataSync.ps1) filters voor het uitsluitend filteren van teams op (weergave)naam.

Het gebruik van deze filterbestanden is optioneel. Als ze bestaan, worden ze ingelezen en gebruikt. Als ze niet bestaan, wordt er niet gefilterd. Indien gebruikt, dan bevat elk filterbestand één of meer regex-patronen, elk op een eigen regel, die worden toegepast voor het filteren van de relevante gegevens. Elke regex-patroon matcht een deel van de invoer. Wildcards zijn niet nodig. Alle tekens met een speciale betekenis voor de match-operator zijn hierbij toegelaten. Plaats geen lege regels in het filterbestand.

Speciale betekenis hebben:

• ^ matcht het begin van een zoekterm

• $ matcht het eind van een zoekterm

• '\' is een escape-teken voor tekens die een speciale betekenis voor regex hebben.

• '\s' is een aanduiding voor een spatie.

Voor een uitgebreidere uitleg over regular expressions of regex, zie Reguliere expressie - Wikipedia

De volgende parameters kunnen worden gedefinieerd in het configuratiebestand van het importscript.

• Importfiltermap=waarde : pad naar invoermap relatief t.o.v. scriptpad

• Importkladmap=waarde : pad naar kladmap relatief t.o.v. scriptpad

• Importdatamap=waarde : pad naar uitvoermap relatief t.o.v. scriptpad

• magisterUser=waarde : webservice-gebruikersnaam

• magisterPassword=waarde : webservice-wachtwoord

• magisterUrl=waarde : webservice-URL

• handhaafJPTMedewerkerCodeIsLogin=waarde : filtert dubbele identiteiten weg voor Code<>Login

• medewerker_id=waarde : koppelmethode voor medewerkers

• leerling_id=waarde : koppelmethode voor leerlingen

De volgende parameters kunnen worden gedefinieerd in het configuratiebestand van het exportscript.

• Importdatamap=waarde : pad naar importdatamap relatief t.o.v. scriptpad

• Exportfiltermap=waarde : pad naar exportfiltermap relatief t.o.v. scriptpad

• Exportkladmap=waarde : pad naar exportkladmap relatief t.o.v. scriptpad

• Exportdatamap=waarde : pad naar exportdatamap relatief t.o.v. scriptpad

• Exportverzamelmap=waarde : pad naar exportverzamelmap relatief t.o.v. scriptpad

• schoolid=waarde : unieke identificatie van de school

• schoolnaam=waarde : naam van de school in SDS

• teamid_prefix=waarde : prefix voor team-ids in SDS

• teamnaam_prefix=waarde : prefix voor teamnamen in SDS

• teamnaam_suffix=waarde : suffix voor teamnamen in SDS

• maakklassenteams=waarde : schakelaar voor aanmaken van een team voor iedere (stam)klas

• bon_match_docentlesgroep_aan_leerlingklas=waarde : schakelaar voor matchen aan tweede deel van docent-groepvaknaam

• docenten_per_team_limiet=waarde : bepaalt limiet van het aantal docenten per tema.

Deze parameter is een schakelaar die uit staat met 0 of aan staat met de waarde 1. Wanneer 1 dan worden extra teams aangemaakt, waarvan de naam wordt opgebouwd uit het deel van de klasnaam na de punt in de docent-groepvakken, gevolgd door een vaknaam. Bij verstek is de waarde 0. Deze parameter zorgt ervoor dat het aantal actieve teams in de onderbouw van Bonhoeffercollege wordt verhoogd met teams voor docentgroepvakken voor lesgroepen met namen als "B.B2" en "M2.M2a", waarvan alleen het deel achter de punt wordt gebruikt om te kunnen koppelen aan leerlingklassen. Vanaf versie 20220718 heeft deze parameter geen functie meer.

Deze parameter bevat een getal dat wordt vergeleken met het aantal docenten in elke kandidaatteam. Indien het aantal docenten hoger is dan gegeven door deze parameter, dan wordt het team overgeslagen bij het identificeren van actieve teams. Wanneer deze parameter 0 is, dan wordt deze controle op het aantal docenten niet uitgevoerd. Bij verstek is de waarde 0.

Deze parameter heeft betekenis bij het opzoeken van de UserPrincipalName van een medewerker uit een CSV tabel. Het importscript zoekt een employeeid die gelijk is aan de employeeid_prefix + Magister-stamnummer. Indien gevonden, dan wordt de bijbehorende UserPrincipalName gebruikt als de unieke id van de docent in de uitvoer voor School Data Sync.

Voorbeeld: De employeeid_prefix bevat normaliter een waarde uniek voor een Magisterinstantie. In Stichting Voortgezet Onderwijs Kaagland worden alle medewerkers in Entra ID door een IAM applicatie gesynchroniseerd, waarbij het employeeId-veld wordt gevuld met een drielettercode voor de Magisterinstantie "JPT", "KEN" of "BON" gevolgd door het Magister-stamnummer. Het Importscript vindt de juiste UserPrincipalName terug door te zoeken naar de employeeid gelijk aan de employeeid_prefix "JPT" voor Jan Peter Thieme College, "KEN" voor Kaagland College en "BON" voor Bonifaciuscollege, gevolgd door het Magister-stamnummer.

Met de commandoregelparameter -Inifile wordt de naam van een alternatief Configuratie-bestand opgegeven. De naam is geinterpreteerd als relatief ten opzichte van de map waarin het script staat. Deze voorziening maakt het mogelijk om gegevens van verscheidene instanties van Magister gescheiden te verwerken.

Een voorbeeld :

waarbij <bestandsnaam> de naam is van een configuratiebestand. Deze parameter heeft de aliassen Inifilename,Inibestandsnaam,Config,Configfile en Configuratiebestand. Een alternatief configuratiebestand kan dus ook worden opgegeven met bijvoorbeeld:

Vanaf de PowerShell prompt gebruikmaken van verstekwaarden:

Vanaf PowerShell prompt met parameters:

Vanaf de CMD prompt of door middel van een batchbestand:

De twee scripts loggen alle schermuitvoer en foutmeldingen in een logbestand, met de naam "Import-Magister.log" respectievelijke "Export-SchoolDataSync.log" in de map "Log" in de map waar de scriptbestanden staan. Bestudeer deze logs om te onderzoeken welke foutmeldingen zijn gegenereerd, en op welke regel dat gebeurde.

De logbestanden worden geroteerd elke keer dat een script wordt uitgevoerd. Bij elke keer dat het importscript en exportscript worden uitgevoerd, worden de laatste 7 logbestanden hernoemd en een nieuw logbestand wordt aangemaakt. Het oudste logbestand wordt verwijderd. De naam van de bewaarde logbestanden zijn "Import-Magister.01.log" respectievelijk "Export-SchoolDataSync.01.log" en deze zijn opeenvolgend genummerd naarmate het logbestand ouder is. Er worden van elke script altijd ten hoogste 8 logbestanden bewaard.

TeamSync maakt een aantal bestanden aan, die inzicht geven in welke teams door School Data Sync aangemaakt zouden worden en welke gegevens worden verwerkt. Deze bestanden hebben een CSV-formaat (Comma Separated Values). Dit is een belangrijke hulp bij het bepalen van de juiste filters en instellingen.

Script Import-Magister genereert onder andere:

• leerling.csv : Een lijst met leerlingen zoals die uit Magister wordt gelezen.

• docent.csv : Een lijst met medewerkers zoals die uit Magister wordt gelezen.

Script Export-SchoolDataSync genereert onder andere:

• hteamactief_{teamid_prefix}.csv : Een lijst met alle teams die TeamSync als actief aanmerkt. Dit zijn de teams die in de uitvoer voor SDS voorkomen.

• hteam0doc_{teamid_prefix}.csv : Een lijst met Teams die als inactief zijn aangeduid omdat een docent hierin ontbreekt.

• hteam0ll_{teamid_prefix}.csv : Een lijst met Teams die als inactief zijn aangeduid omdat leerlingen hierin ontbreken.

Om te zien welke teams actief zouden worden gesynchroniseerd door Microsoft School Data Sync, open het bestand met de naam hteamactief_{teamid_prefix}.csv.

Probeer je TeamSync uit, maar krijg je geen actieve teams? Waarschijnlijk haal je de Magistergegevens op in de zomervakantie. Dat gaat niet werken en waarom wordt hieronder uitgelegd.

Om een lijst met actieve teams te genereren, moeten de gegevens in Magister aan een aantal strikte voorwaarden voldoen:

• Leerlingen en docenten moeten actief zijn, d.w.z. de inschrijfdatum moet in het verleden liggen, en de uitschrijfdatum in de toekomst of leeg.

• Leerlingen en docenten moeten een ingevulde locatie oftewel "Administratieve_eenheid.Omschrijving" hebben.

• Leerlingen moeten lid zijn van een klas.

• Er moet een docent zijn toegewezen aan elk vak (in de lessentabel van een leerling).

• De lesperiode, waarin elk vak wordt gegeven door de docent aan de klas, moet actief zijn, d.w.z. de huidige datum moet tussen begindatum en einddatum liggen.

Als aan de bovenstaande voorwaarden niet is voldaan, worden de verbanden tussen docenten, leerlingen (lesgroep) en vak niet als actief beschouwd en bevat de uitvoer geen actieve teams. Vanwege deze reden zal TeamSync in de zomervakantie geen nuttige uitvoer leveren.

Om ten volle gebruik te maken van dagelijks bijgewerkte Microsoft 365 klassenteams, is het aanbevolen om de door TeamSync aangemaakte CSV-bestanden dagelijks naar Microsoft School Data Sync te uploaden. Om dit op een betrouwbare manier te automatiseren raadt de auteur aanom gebruik te maken van Microsoft Power Automate en de SDS Flow Connector. Lees meer over de inrichting en vereisten op CSV File Sync Automation.

d.d. September 2023 is SDS in een overgangsfase. De oorspronkelijke School Data Sync heet nu School Data Sync (Classic) en de actuele versie heet "Microsoft School Data Sync". School Data Sync (Classic) blijft beschikbaar tot einde 2024. De nieuwe SDS wijkt in zoverre af van de oude School Data Sync dat het geen afzonderlijke synchronisatieprofielen ondersteunt. In de woorden van Microsoft heet het dat "Single Subscription - Multi-Academy Trust Support" vooralsnog ontbreekt. De consequentie hiervan is dat het gelijktijdig synchroniseren van verscheidene scholen naar School Data Sync alleen mogelijk is door de uitvoer van TeamSync voor verscheidene scholen samen te voegen in één bestandenverzameling voor School Data Sync. TeamSync ondersteunt dat nog niet, maar misschien gebeurt dat nog ooit in de toekomst, afhankelijk van de behoefte bij Stichting Voortgezet Onderwijs Kennemerland. Voor schooljaar 2023-2024 is dat in ieder geval nog niet het geval.

School Data Sync ondersteunt nieuwe uitgebreidere bestandsformaten. Mijn wereld bestaat uitsluitend uit leerlingen en docenten. TeamSync kan daarom nog prima uit de voeten met CSV v1 en blijft dat formaat handhaven zolang dat nog kan. Bovendien heeft TeamSync nog helemaal geen ondersteuning voor de synchronisatie van guardians (ouders). Heb jij dat nodig, voel je vrij om deze repo te forken en dit zelf te implementeren.