WootsSync

Versie 20241101b

Abstract

WootsSync synchroniseert programma’s in Woots met Magister. Het maakt programma’s aan of werkt deze bij, door hieraan de juiste docenten, klassen en legroepen te koppelen. Magister is een veelgebruikt schooladministratiesysteem voor het voortgezet onderwijs in Nederland. Woots is een digitaal toetsplatform en toetsbibliotheek.

WootsSync bevat schoolspecifieke logica. Het is zaak om deze aan te passen naar eigen wens of behoefte.

Vereisten

Dit script vereist:

• Windows PowerShell 5, PowerShell 7 of hoger.

• Woots PowerShell module

• Gegevens uit Magister; deze worden opgehaald door het ImportMagister script uit TeamSync.

Installatie

• Download alle bestanden uit de WootsSync repository en plaats ze in een map naar keuze.

• Maak een API-token aan: log in als beheerder, kies avatar→instellingen→API-token en klik op "Generate new token". Noteer School_id en token.

• Schrijf de gewenste instellingen in WootsSync.ini . Maak eventueel de gewenste mappen en zet de vereiste invoerbestanden klaar.

Gebruik

WootsSync bestaat uit 3 scripts die achtereenvolgens worden uitgevoerd.

• Import-Magister.ps1 haalt gegevens op uit Magister.

• WootsSync-ReadPhase.ps1 bepaalt Woots-programma’s.

• WootsSync-WritePhase.ps1 werkt in Woots de programma’s bij.

Documentatie

Import-Magister

Het script Import-Magister.ps1 maakt verbinding met Magister Webservices en haalt leerlingen, docenten en vakken op. Zie de documentatie op TeamSync GitHub repository.

Het script genereert de volgende bestanden:

• magister_leerlingen.clixml

• magister_docenten.clixml

• magister_vak.clixml

Deze bestanden moeten worden klaargezet in de WootsSync-importmap en worden ingelezen door WritePhase.

WootsSync-ReadPhase

Het script WootsSync-ReadPhase.ps1 leest de bestanden aangemaakt door Import-Magister en bouwt een lijst met programma’s op. Het genereert een Woots-programma voor elke unieke combinatie van leerjaar, studie en vak en koppelt de klassen en docenten hieraan. Het doet dit als volgt.

1. Het telt alle leerlingen af, en

   1. voor elke leerling loopt alle lesgroepen af. Het splitst de naam van de lesgroep. Het bepaalt afdeling en vakcode op basis van schoolspecifieke logica. Het zoekt de vakomschrijving op voor elke vakcode. Het bouwt nu een programmanaam op door combineren van afdeling en vakomschrijving. Het voegt de lesgroep van de leerling toe aan het programma.

   2. indien onderbouw (leerjaar =< 3), loopt alle vakken af. Voor elke combinatie van afdeling en vak voegt de klas van de leerling toe aan het respectievelijke programma. Het maakt het programma aan, indien deze nog niet bestaat.

2. Het telt alle docenten af,

   1. telt alle groepvakken af. Voor elk groepvak, bepaalt afdeling en vak en voegt de docent toe aan het respectievelijke programma, indien deze bestaat.

   2. telt alle klasvakken af en telt alle docentvakken af. Het bepaalt afdeling en voegt voor elke combinatie van afdeling en vak de docent toe aan het respectievelijke programma, indien deze bestaat.

WootsSync-ReadPhase maakt gebruik van een of meer filters in bestanden in de datamap. Zie onder voor uitleg.

WootsSync-ReadPhase genereert de volgende bestanden in de datamap:

• WootsSync.clixml bevat een lijst met programma’s in XML,

• WootsSync.csv bevat een lijst met programma’s in CSV,

• WootsSync.txt bevat een lijst met programmanamen.

Het resultaat kan worden beoordeeld in deze bestanden. Indien alles in orde is, ga door met WootsSync-WritePhase.ps1 om de programma’s aan te maken in Woots.

WootsSync-WritePhase

Het script WootsSync-WritePhase.ps1 maakt verbinding met de Woots API, leest WootsSync.clixml, loopt alle programma’s af en werkt de programma’s in Woots bij door de verschillen naar Woots te schrijven.

• indien het programma niet bestaat in Woots en het zou volgens het lijst wel moeten bestaan, dan wordt het aangemaakt.

• indien een groep (klas of lesgroep) niet gekoppeld is aan het programma en het zou volgend de lijst wel lid gekoppeld moeten zijn, dan wordt de groep gekoppeld.

• indien een groep (klas of lesgroep) wel gekoppeld is aan het programma en het zou volgend de lijst niet lid gekoppeld moeten zijn, dan wordt de groep afgekoppeld.

• indien een docent niet lid is van het programma, dan wordt de docent gekoppeld.

(AANPASSEN) Docentcodes worden aangevuld met '@jpthijsse.nl' om een geldig e-mail te genereren. De betreffende docent wordt met dit e-mail in Woots opgezocht.

Filters

De volgende filters kunnen worden gedefinieerd om de door ReadPhase aangemaakte lijst programma’s te beinvloeden.

Studie uitsluiten

Om specifieke studies uit te sluiten van verwerken, maak het bestand Datamap\WSExcludeStudie.txt aan en zet daarin één of meer beschrijvingen van uit te sluiten studies in de vorm van een regular expression, elk op een eigen regel.

Vak uitsluiten

Om specifieke vakken uit te sluiten van verwerking, maak het bestand Datamap\WSExcludeVakcode.txt aan en zet daarin één of meer vakcodes van uit te sluiten vakken in de vorm van een regular expression elk op een eigen regel.

Voorbeeld: ^lo$ filtert alle vakcodes gelijk aan 'lo' Voorbeeld: ^me filtert alle vakcodes beginnend met 'me' Voorbeeld: pws filtert alle vakcodes waarin 'pws' voorkomt

Klassikale vakken

Indien het bestand ''Datamap\WSKlassikaleVakken.txt'' aanwezig is, dan wordt een lijst met vakcodes voor klassikale vakken ingelezen. Normaliter worden alleen onderbouwklassen gekoppeld aan programma’s, maar voor de vakcodes in deze lijst worden klassen gekoppeld aan programma’s in alle leerjaren.

WootsSync.ini

Het configuratiebestand bevat parameters voor zowel WootsSync-ReadPhase als WootsSync-WritePhase in een tekstbestand met de naam 'WootsSync.ini'. De naam en locatie van het configuratiebestand is WootsSync.ini in dezelfde map als WootsSync-ReadPhase en WootsSync-WritePhase. Om een ander bestand te kiezen, geeft de naam en locatie van WootsSync.Ini op de commandoregel van WootsSync-ReadPhase.ps1 en WootsSync-WritePhase.ps1 met de parameter -Inifilename <bestandsnaam>. Het configuratiebestand is een bestand dat in een teksteditor is bewerken en bestaat uit een reeks van naam-waarde-paren. Voor een voorbeeld, zie WootsSync-voorbeeld.ini

De volgende waarden zijn verplicht en mogen niet worden weggelaten: schooldatamap, importmap, tempmap, hostname, school_id, token, wootsinstantie.

school is een naam die de school aanduidt in ReadPhase ten behoeve van het kiezen van de juiste logica voor het bepalen van lesgroep- en klasnamen.

datamap, importmap en tempmap beduiden de naam van een map, relatief ten opzichte van de locatie van de script WootsSync-ReadPhase en WootsSync-WritePhase.

importmap geeft de naam van de map waarin gegevensbestanden worden opgeslagen voor de communicatie tussen Import-Magister en ReadPhase. Kopieer hierin de uitvoer van

datamap geeft de naam van de map waarin gegevensbestanden wordt opgeslagen voor de communicatie tussen ReadPhase en WritePhase, alsmedede filters voor ReadPhase.

tempmap geeft de naam van de map waarin ReadPhase een aantal controlebestanden opslaat.

wootsinstantie is een vrij te kiezen naam die de Woots-instantie aanduidt in WritePhase voor gebruik in logs en cache-bestandsnamen.

hostname is de hostname van de API eindpunt.

school_id is het identificatienummer van de school, te vinden onder instellingen, API-token.

token is het token dat toegang geeft tot de API, te beheren onder instellingen, API-token.

magistersyncleerjaar bevat een komma-gescheiden lijst van de leerjaren waarvoor WootsSync programma’s aanmaakt. Voor het beste resultaat is het aanbevolen dat WootsSync uitsluitend programma’s aanmaakt voor leerjaren die worden gesynchroniseerd met Magister, zoals ingesteld in Woots→Instellingen→Magister.

whatif is een schakelaar die bepaalt of Write-Phase wijzigingen in Woots aanbrengt ten behoeve van testen en debuggen. 0 betekent: schrijf wijzigingen, 1 betekent: doe alsof, schrijf geen wijzigingen.

do_remove_instructors is een schakelaar, 0 betekent: laat staan, 1 betekent: verwijder docenten uit programma’s indien ze niet meer voorkomen in de door ReadPhase aangemaakte lijst.

gridview is een schakelaar: 1 betekent: ReadPhase toont interactief het resultaat in een GridView-venster. Het programma is dan niet meer geschikt om uit te voeren als geplande taak zonder toezicht (unattended).

onbekendvak_overslaan is een schakelaar. 1 betekent dat ReadPhase vakken in de uitvoer overslaat, die niet konden worden gekoppeld aan een bekende vakomschrijving.

Extra’s

Known issues

WootsSync is niet in staat om docenten aan programma’s toe te kennen als ze in Woots een beheerdersrol hebben.

To Do

• toevoegen docenten die ook beheerder zijn.