Paul Wiegmans <p.wiegmans@svok.nl>
TeamSync is een universele oplossing voor het overbrengen van gegevens uit Magister naar School Data Sync ten behoeve van een geautomatiseerde aanmaak van Teams in een Microsoft 365 omgeving.
Deze oplossing maakt gebruik van Microsoft School Data Sync. School Data Sync is een oplossing die identiteiten vanuit een schooladministratiesysteem synchroniseert met Microsoft 365, en klassenteams maakt voor alle actieve klassen of lesgroepen.
Inspiratie hiervoor komt uit eerder werk genaamd 'v06-sds-files_FONSVITAE.ps1' door Wim den Ronde, Eric Redegeld, Joppe van Daalen.
Gebruikt jouw school Somtoday en zoek je een koppeling tussen Somtoday en School Data Sync ? Bezoek dan GitHub: DwayneSelsig/Somtoday2MicrosoftSchoolDataSync
TeamSync leest uit Magister lijsten met leerlingen, docenten, klassen, lesgroepen en vakken., TeamSync genereert hieruit lijsten waarin voor elk samenwerkingsverband bestaande uit lesgroep of combinatie van klas en vak, waarvan zowel leerlingen als docent(en) lid zijn, een actief team in de uitvoer terechtkomt. Deze lijsten vormen de basis voor een actieve synchronisatie van Microsoft School Data Sync. SDS maakt de juiste Microsoft 365 klassenteams aan, maakt de juiste docent teameigenaar en voegt de juiste leerlingen als leden toe.
De werking van TeamSync wordt weergegeven als volgt:
-
gegevens inladen
-
gegevens verwerken
-
gegevens opslaan
TeamSync bestaat uit twee scripts:
-
Import-Magister.ps1hierna genoemd het importscript, -
Export-SchoolDataSync.ps1hierna genoemd het exportscript.
Het importscript wordt eerst uitgevoerd om gegevens uit Magister op te halen. Gegevens worden tussentijds opgeslagen in een aantal tijdelijke bestanden. Daarna wordt het exportscript uitgevoerd om de bestanden te genereren voor School Data Sync. De uitvoer bestaat uit 6 CSV-bestanden die nodig zijn voor synchronisatie met een profiel in Microsoft School Data Sync.
Voor het ophalen van gegevens wordt gebruik gemaakt van de Magister SOAP/XML Webservice. Er is hiervoor een geldige gebruikersnaam en een wachtwoord vereist en permissies voor het uitvoeren van webqueries en dan specifiek de AD-functies. Er wordt gebruik gemaakt van de standaard Web API van Magister. Er zijn geen zogenaamde aangepaste lijsten of 'custom queries' nodig. Je kunt meer lezen hierover op Magister SOAP/XML webservice.
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.
|
Important
|
Hier wordt ervan uitgegaan dat alle gebruikersaccounts al in AAD aanwezig zijn en dus niet door School Data Sync actief worden aangemaakt. |
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.
Om TeamSync in te zetten is het volgende nodig.
-
Een computer, welk ip-adres is opgenomen in de lijst met ip-adressen die zijn toegestaan om te verbinden met Magister SOAP API, ook bekend als webqueries.
-
Windows PowerShell 5.1 of PowerShell 7.
-
Een configuratiebestand zoals bijvoorbeeld Import-Magister-voorbeeld.ini,
-
een configuratiebestand zoals bijvoorbeeld Export-SchoolDataSync-voorbeeld.ini,
-
Een URL naar de Magister webservice; een gebruikersnaam en een wachtwoord met toegangsrechten tot de AD-functies van de Magister SOAP API.
Doe het volgende:
-
Lees deze handleiding en configureer TeamSync naar wens.
-
Start Teamsync met het commando Teamsync.cmd.
-
Maak een scheduled task om TeamSync dagelijks uit te voeren.
-
Richt Microsoft School Data Sync in en creëer een synchronisatieprofiel voor de gewenste school.
-
Upload dagelijks de door TeamSync aangemaakte CSV-bestanden naar het synchronisatieprofiel om de Microsoft 365 klassenteams bijgewerkt te houden met de actuele leerlingen, docenten en lesgroepen.
Om TeamSync te gebruken, is het essentieel om de functie en structuur van enkele bestanden en mappen te gebruiken.
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:
Import-CliXML -Path $clixmlfile | Out-GridView -WaitIn 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
Alle leerlingen waarvan de studie eindigt op "VAVO" worden uitgesloten.
Het bestand ImportFilterMap\excl_studie.csv wordt aangemaakt en bevat:
VAVO$We willen de leerlingen van Mavo, Havo, Vwo en de brugklassen verwerken; alle leerlingen in een studie die begint met B,M,H of V moeten worden verwerkt.
Het bestand ImportFilterMap\incl_studie.csv wordt aangemaakt en bevat:
^M
^H
^V
^BVoorbeeld : we willen alleen 4 en 5 Havo en verwerken; alle leerlingen in de klas die begint met '4H' of '5H' moeten worden verwerkt.
Het bestand ImportFilterMap\incl_klas.csv bevat:
^5H
^4HVoorbeeld: we willen alleen docenten wiens id niet begint met '_' of eindigt op '*'.
Het bestand ImportFilterMap\excl_docent.csv bevat:
^_
\*$Voorbeeld: In het geval dat er 4 scholen gebruik maken van 1 Magisterinstantie, en alleen klassenteams voor Beroepsgericht zijn gewenst. Alle docenten, leerlingen en lesgroepen hebben Magister:Administratieve_eenheid.Omschrijving = "Beroepsgericht".
Het bestand ImportFiltermap\incl_locatie.csv of ExportFiltermap\incl_locatie.csv bevat:
BeroepsgerichtVoorbeeld: alleen teams met " EN " in de naam.
Het bestand Export-Filter\incl_teamnaam.csv bevat:
\sEN\sGotcha: het filter is niet hoofdlettergevoelig, dus filtert ook alle voorkomingen van " en ".
Het configuratiebestand definieert een aantal parameters (anders gezegd: configuratievariabelen), die nodig zijn voor de correct werking van TeamSync.
De parameters in het configuratiebestand worden gespecificeerd als een naam-waarde-paar en hebben de volgende vorm:
<naam>=<waarde>Aanhalingstekens zijn toegestaan maar niet nodig. Spaties in het waarde-deel zijn toegestaan. Commentaarregels zijn toegestaan, door de regel te beginnen met '#'.
|
Important
|
Backslashes worden opgevat als escape-karakters. Om backslashes in paden op te geven, escape deze met een extra backslash, bijvoorbeeld: Importfiltermap=Submap1\\Submap2\\Submap3. Je mag ze ook vervangen door een forward slash, bijvoorbeeld: 'Importfiltermap=Submap1/Submap2/Submap3'.
|
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. -
samenvoegen=waarde: bepaalt of uitvoer wordt toegevoegd aan de bestanden in de verzamelmap`
Deze verplichte parameter bevat een unieke identificatie van de school. Je kunt hiervoor het BRIN van de school gebruiken of een andere unieke aanduiding.
Deze verplichte parameter bevat de weergavenaam van de school.
Deze verplichte parameter bevat de gebruikersnaam voor toegang tot de Medius Webservice.
Deze verplichte parameter bevat het wachtwoord voor toegang tot de Medius Webservice.
Deze verplichte parameter bevat de URL voor toegang tot de Medius Webservice.
|
Important
|
De parameters MagisterUser, MagisterPassword en MagisterUrl zijn vereist om toegang te krijgen tot de Medius Webservices. De LAS-beheerder maakt een gebruiker aan in de Webservice gebruikerslijst in Magister. De gebruikersnaam en wachtwoord moeten worden gegeven in MagisterUser en MagisterPassword. Deze gebruiker heeft toegangsrechten nodig tot de ADfuncties in de Medius Webservices. De MagisterUrl is de URL waar de webservices worden aangeboden. Dit bestaat uit de schoolspecifieke URL voor Schoolwerkplek met daarachter de poort en het pad , welke meestal :8800/doc is. De produktieomgeving is benaderbaar op poort 8800, de testomgeving op poort 8801 en de beta omgeving op poort 8802. De hele URL ziet er uit als https://schooldomein.swp.nl:8800/doc.
|
Deze parameter is verplicht. Deze tekst wordt toegevoegd aan het begin van de ID van team. Dit wordt deel van de unieke ID die elk team uniek identificeert in Microsoft 365. Een nuttige prefix identificeert zowel de school als het schooljaar en is bijvoorbeeld "JPT 1920". Spaties in de naam worden omgezet in underscores ten behoeve van het bepalen van de ObjectID.
Deze tekst wordt toegevoegd aan het begin van de weergavenaam van elk team en wordt zichtbaar in de teamlijst van alle deelnemers.
Deze tekst wordt toegevoegd aan het eind van de weergavenaam van elk team en wordt zichtbaar in de teamlijst van alle deelnemers.
Dit specifieert de naam van de Importfiltermap, relatief ten opzichte van de locatie van het script. Bij verstek is de naam ImportFilter.
Dit specificeert de mapnaam van de Importkladmap relatief ten opzichte van de locatie van het script. Bij verstek is de naam ImportKlad.
Dit specificeert de mapnaam van de Importdatamap relatief ten opzichte van de locatie van het script. Bij verstek is de naam ImportData.
Dit specifieert de naam van de Exportfiltermap, relatief ten opzichte van de locatie van het script. Bij verstek is de naam ExportFilter.
Dit specificeert de mapnaam van de Exportkladmap relatief ten opzichte van de locatie van het script. Bij verstek is de naam ExportKlad.
Dit specificeert de mapnaam van de Exportdatamap relatief ten opzichte van de locatie van het script. Bij verstek is de naam ExportData.
Dit specificeert de mapnaam van de Exportverzamelmap relatief ten opzichte van de locatie van het script. Bij verstek is de naam ExportVerzameld.
Gebruik handhaafJPTMedewerkerCodeIsLogin=1. Bij verstek geldt handhaafJPTMedewerkerCodeIsLogin=0 . Deze instelling dient om uitsluitend medewerkers te verwerken waarbij Magister→Code gelijk is aan Magister→loginaccount.naam. Dit filter wordt in een speciaal geval voor JPT toegepast om dubbele identiteiten weg te filteren.
Deze parameter duidt aan hoe identiteiten van medewerkers in Azure AD worden gekoppeld aan Magister. Deze parameter is verplicht. Toegestane waarden zijn
code, loginaccount, ad_upn, csv_upn
. Zie Identiteiten koppelen .
Deze parameter duidt aan hoe identiteiten van leerlingen in Azure AD worden gekoppeld aan Magister. Deze parameter is verplicht. Toegestane waarden zijn
loginaccount, email
. Zie Identiteiten koppelen .
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.
Deze parameter is een schakelaar met de waarde 0 of 1 die bepaalt of de uitvoer moet worden toegevoegd aan de bestanden in de verzamelmap. Door dit de waarde 0 te geven, is het mogelijk om de uitvoer in het huidige profiel te beoordelen, alvorens deze te uploaden naar School Data Sync. Wanneer de uitvoer naar wens is, kan door dit waarde 1 te geven, de uitvoer worden samengevoegd met de bestanden in de verzamelmap om aan te bieden aan School Data Sync.
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 :
<scriptnaam> -Inifile <bestandsnaam>
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:
<scriptnaam> -Config <bestandsnaam>
Met het volgende CMD commandoscript kan het configuratiebestand 'Team-JPT.ini' worden gebruikt om script 1 en 2 uit te voeren, wanneer deze in dezelfde map als dit commandoscript staan.
@echo off
Powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0Import-Magister.ps1" -Inifile "Team-JPT.ini"
Powershell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0Export-SchoolDataSync.ps1" -IniFile "Team-JPT.ini"TeamSync is met name bedoeld om zonder interactie als geplande taak worden uitgevoerd.
Vanaf de PowerShell prompt gebruikmakend van verstekwaarden:
. .\Import-Magister.ps1
. .\Export-SchoolDataSync.ps1Vanaf PowerShell prompt met parameters:
. .\Import-Magister.ps1 -IniFile Magister.ini
. .\Export-SchoolDataSync.ps1 -IniFile School1.ini
. .\Export-SchoolDataSync.ps1 -IniFile School2.iniVanaf de CMD prompt of door middel van een batchbestand:
@PowerShell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0Import-Magister.ps1" -IniFile Magister.ini
@PowerShell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0Export-SchoolDataSync.ps1" -IniFile School1.ini
@PowerShell.exe -NoProfile -NoLogo -ExecutionPolicy Bypass -File "%~dp0Export-SchoolDataSync.ps1" -IniFile School2.iniDe 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.
Gedurende het testen is het meest handig als Import-Magister.ps1 gedurende een run zonder filters wordt uitgevoerd om alle gegevens op te halen uit Magister. Wanneer dit eenmaal is gebeurd, dan kan Export-SchoolDataSync.ps1 herhaaldelijk met één of meer filters worden uitgevoerd om te kijken wat het resultaat zou worden. Dit laatste script wordt veel sneller uitgevoerd, omdat het niet steeds opnieuw de gegevens uit Magister hoeft op te halen.
Een scenario van het soort 'Één Magister - twee scholen' kan er zo uitzien:
-
Het script
Import-Magister.ps1wordt uitgevoerd met een aangepast configuratiebestand, zonder filters, dat alle gegevens worden opgehaald uit Magister. Dit levert snelheidswinst op. De tussenresultaten worden opgeslagen in de Importdatamap. -
Het script
Export-SchoolDataSync.ps1wordt één keer uitgevoerd voor elke school met een voor één school specifiek configuratiebestand:-
Importdatamap, Exportfiltermap, Exportdatamap verwijzen naar een school-specifieke map
-
de schoolspecifieke Exportfiltermap bevat in het bestand
incl_locatie.csveen of meer school-specifieke regexpatronen die overeenkomen met de gewenste waarden voor het veld Administratieve_eenheid.Omschrijving in Magister. -
teamid_prefixenz. verschilt per school.
-
Met ingang van 'New School Data Sync' beschikbaar vanaf eind 2023, wordt de uitvoer van diverse TeamSync instanties samengevoegd in de verzamelmap om als één dataset te worden geupload naar School Data Sync.
Probeer je TeamSync uit, maar krijg je geen actieve teams? Waarschijnlijk haal je de Magistergegevens op in de zomervakantie. 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.
Voor elk team dat TeamSync samenstelt uit een lesgroep, plaatst het een vakomschrijving in de weergavenaam van het team. De vakomschrijving wordt bepaald door een vakcode te distilleren uit de lesgroepnaam. Het kijkt naar de tekens achter een punt of komma, met weglating van alle cijfers. De overblijvende tekenreeks wordt achtereenvolgens kleiner gemaakt totdat er een overeenkomstige vakcode gevonden wordt in de vakkentabel. De daarbij horende vakomschrijving wordt in de teamnaam geplaatst. Wanneer de vakcode niet eenduidig kan worden bepaald, kan het gebeuren dat een verkeerde vakomschrijving in de teamnaam geplaatst.
De makkelijkste manier om dit te verhelpen is om door te gaan met de implementatie van TeamSync en School Data Sync. Wanneer de teams met een verkeerde vakomschrijving in de weergavenaam zijn aangemaakt, wijzig de naam van de teams met de hand. Iedereen kan dit doen voor elk team waarvan iemand eigenaar is of een beheerder kan dit doen voor alle teams in de Teams Admin Center.
Een minder makkelijke workaround wanneer de teams nog niet zijn aangemaakt, is na uitvoeren van het importscript en vóór het uitvoeren van het exportscript om de vakkentabel magister_vak.clixml aan te passen, en een vakomschrijving te geven voor een afwijkende vakcode. Dit is dan alleen nodig voor de initiele synchronisatie van School Data Sync, en kies daarbij de instellingen "Section display names are synced only on first sync" . Wanneer de teams eenmaal zijn aangemaakt, wijzigt de naam niet meer.
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.
