Business case

Magister is een Learning Management System (LMS) uit Nederland dat studenten, hun ouders en leraren voorziet van informatie over hun roosters, huiswerk, cijfers, cursusinformatie, aanwezigheidsregistratie en meer. Het wordt gebruikt door meer dan 50% van de Nederlandse middelbare scholen, wat het een van de meest gebruikte applicaties in het onderwijs maakt. Het integreren van Workspace 365 met Magister vereenvoudigt de toegang tot informatie, zonder dat Magister zelf geopend hoeft te worden.

Configureer Magister

Vereisten

Om de Magister-integratie te gebruiken, moet je eerst de onderstaande stappen voltooien om een veilige verbinding tot stand te brengen en de informatie die we uit Magister moeten halen voor te bereiden om het rooster en de cijfers in Workspace 365 te kunnen presenteren.

Benodigde Workspace-abonnement: Adapt of Boost.
Het IP-bereik van Workspace 365 moet door Schoolmaster op de whitelist worden gezet.
Maak alle lijsten in Magister aan om rooster- en cijferinformatie te verkrijgen.
Maak een Magister-gebruikersaccount met "lees"-eigenschappen en toegang tot de lijsten.
Maak een nieuwe "Cijferkolomverzameling" genaamd "WS365".
- Opmerking: Dit moet aan het begin van elk schooljaar worden herhaald.

Whitelist Workspace 365 IP-bereik

Om ons in staat te stellen te communiceren met de juiste Magister-database, moet je Workspace 365 toegang geven tot je omgeving. Dit kan alleen worden bereikt door contact op te nemen met Schoolmaster en een verzoek in te dienen om ons IP-bereik (20.103.81.112/28) op de whitelist te zetten. Schoolmaster zal per e-mail reageren.

Klik rechtsboven op “Maak een ticket”.
Selecteer “Whitelisting IP-adressen”.
Geef de vereiste informatie en vul het formulier in.

In de tussentijd kun je doorgaan met de volgende stappen om je Magister-omgeving voor te bereiden op het ontvangen van een verbinding van Workspace 365.

Workspace 365 specifieke lijsten

Deze paragraaf beschrijft de lijsten (SQL-queries) in Magister, die moeten worden aangemaakt om de benodigde informatie uit Magister in Workspace 365 te krijgen. Een lijst bevat een SQL-query, die we kunnen definiëren, om de benodigde informatie uit de Magister-database te halen. Om de query in een lijst uit te voeren, gebruiken we een oproep naar de Medius Webservice.

We hebben de volgende lijsten gemaakt om gegevens van Magister naar Workspace 365 te halen:

WS365_GetLists
WS365_GetPerson_v1
WS365_GetSchedule_v1
WS365_GetLastGrades_v1

Om de Workspace 365-lijsten te downloaden, ga naar onze downloadpagina.

WS365_GetLists

Deze lijst retourneert de ID's en namen van de gedefinieerde WS365_* lijsten. Deze lijst kan worden gebruikt om alle door Workspace 365 gedefinieerde lijsten op te halen die in een specifieke Magister-omgeving zijn aangemaakt. Hierdoor kunnen we controleren of alle vereiste lijsten (en versies) correct en aangemaakt zijn in Magister.

Het geeft niet aan of je toegang hebt tot een lijst. Als een oproep naar een van deze lijsten mislukt, kan het zijn dat de Magister-beheerder de juiste gebruikersrechten niet heeft ingesteld om die lijst uit te voeren.

WS365_GetPerson_v1

Een lijst die de persoonsinformatie retourneert op basis van de UPN (Magister AD-naam).

Er zijn twee scenario's voor deze lijst, afhankelijk van je setup.

Microsoft Entra ID als leidende identiteitsprovider.
De GetPerson-lijst kijkt standaard naar de kolom sis_gebr.adnaam in Magister. Dit wordt alleen automatisch ingevuld als je gebruikersgegevens van Microsoft Entra ID (voorheen Azure AD) naar Magister synchroniseert, waardoor Microsoft Entra ID de leidende identiteitsprovider wordt. Je kunt de lijsten in Magister instellen met onze standaardlijsten.
Magister als leidende identiteitsprovider.
Als Magister de leidende identiteitsprovider is (wat betekent dat er geen synchronisatie is van Microsoft Entra ID naar Magister), moet je een aanpassing maken om te voorkomen dat de Magister-tegel de foutmelding "items cannot be retrieved" geeft.

Open de GetPerson-lijst.
Ga naar de regel WHERE sis_gebr.adnaam = @upn
Vervang sis_gebr.adnaam door sis_gebr.email
Het e-mailadres van de gebruikers moet overeenkomen met hun UPN in Workspace.
- Je kunt vooraf verifiëren of je sis_gebr.adnaam kunt gebruiken door een query uit te voeren in Decibel.

WS365_GetSchedule_v1

Retourneert de geplande items van een persoon (student of leraar) binnen een bepaalde periode.

WS365_GetLastGrades_v1

Haalt de lijst op met de tien meest recente cijfers van een student. De geretourneerde lijst is gesorteerd om het meest recent toegekende cijfer bovenaan te tonen. Cijfers kunnen een weegfactor bevatten als er een is toegewezen.

Lijsten installeren in Magister

De door Workspace 365 gedefinieerde lijsten moeten in Magister worden geïnstalleerd. Beheerders van Magister zouden moeten weten hoe dit moet. Hieronder een korte instructie over hoe dit te doen.

Nieuwe (lege) lijsten toevoegen

Open Magister Desktop.
Ga naar "Beheer".
Ga naar "WebServices".
Selecteer "Lijsten".
Voeg een nieuwe lijst toe (rode '+' knop).
Annuleer de "Kolomkiezer" dialoog.
Vul de naam van de lijst in (bijv. WS365_GetLists_v1) in het bewerkingsvak "Naam".
Druk op de groene vinkknop.
Herhaal bovenstaande stappen voor alle lijsten die je moet maken.

SQL-queries toevoegen of bijwerken voor Workspace 365 lijsten

Open Magister Desktop.
Klik op het Magister-pictogram linksboven.
Selecteer “Onderhoud”.
Selecteer "Decibel".
Voer het wachtwoord in.
Het Magister Decibel Dashboard verschijnt na ongeveer 20 seconden. Selecteer "Systeem" vanuit de linker boomweergave.
Selecteer "ddlijsten".
Scrol in het rechteronderpaneel naar de lijst waaraan je de SQL-query wilt toevoegen.
Dubbelklik op het document-tekst-pictogram (in de tweede kolom "sSQL" van de tabel).
Een dialoogvenster "Memoinhoud van sSQL" verschijnt. Voeg (of vervang) de bestaande inhoud met de inhoud van de “WS365_XXXX_v1” SQL-bestanden.
Klik op "Sluiten".
Een bevestigingsdialoog verschijnt. Klik op de "Ja" knop om de wijzigingen op te slaan.
Herhaal bovenstaande stappen voor alle lijsten die je hebt gemaakt.

Lijstversies

De namen van de lijsten hebben een achtervoegsel met een versienummer (bijv. WS365_*_v1). Dit versienummer wordt verhoogd wanneer een nieuwe versie van een lijst niet compatibel is met de vorige versie. Bijvoorbeeld wanneer parameters worden gewijzigd, is een nieuwe versie van de lijst vereist. Wanneer er kleine wijzigingen in een lijst zijn (bijv. een extra veld wordt geretourneerd), is het niet nodig om het versienummer bij te werken.

Wanneer een nieuwe versie van een lijst beschikbaar is, kan deze naast de andere versie(s) worden geïnstalleerd. Een nieuwe versie van een lijst kan al worden geïnstalleerd voordat een nieuwe versie van Workspace 365 wordt gepubliceerd, zodat de Magister-omgeving van tevoren kan worden voorbereid.

Het is aan te raden om oude versies van een lijst niet direct na een update van Workspace 365 te verwijderen, zodat een rollback van een Workspace 365-versie eenvoudig kan worden uitgevoerd. Oude lijstversies kunnen een tot twee weken na de release worden verwijderd. Het is de verantwoordelijkheid van de Magister-beheerder om de juiste versie van de lijsten te installeren en bij te werken en oude versies te verwijderen.

Medius Webservice-gebruiker

Magister stelt applicaties van derden in staat om informatie in Magister te benaderen via hun Medius Webservice. Om toegang te krijgen tot deze webservice heb je een account nodig dat toegang heeft tot specifieke lijsten. Volg de onderstaande stappen om een nieuw account aan te maken en de juiste lijsten toe te wijzen.

Maak een Medius Webservice-gebruikersaccount aan

Open Magister Desktop.
Ga naar "Beheer".
Ga naar "WebServices".
Selecteer "Gebruikers".
Voeg een nieuwe gebruiker toe (rode '+' knop).
Ga naar het tabblad “Algemeen”.
1. Geef een naam (bijv. "WS365").
2. Selecteer het vinkje om het account te activeren.
3. Klik op de knop “Wachtwoord” om een veilig wachtwoord in te stellen.
  - Opmerking: Speciale tekens zijn niet toegestaan (bijvoorbeeld: ! % #).
Sla het gebruikersaccount op door op de groene “V” knop te klikken.

Services en lijsten toewijzen aan een gebruiker

Open Magister Desktop.
Ga naar "Beheer".
Ga naar "WebServices".
Ga naar "Gebruikers".
Selecteer de Workspace-gebruiker die je zojuist hebt aangemaakt.
Bewerk de gebruiker (rode 'potlood' knop).
Ga naar het tabblad “Services”.
1. Ga naar de subsectie “Algemeen”.
  - Voeg een vinkje toe voor “Algemeen.Login”.
  - Voeg een vinkje toe voor “Algemeen.Logout”.
2. Ga naar de subsectie “(Data)”.
  - Voeg een vinkje toe voor “Data.GetData”.
Ga naar het tabblad “Lijsten”.
1. Scrol naar beneden naar de lijsten die je hebt aangemaakt in de stap “Nieuwe (lege) lijsten toevoegen”.
  - Voeg een vinkje toe voor elk van de lijsten.
Sla het gebruikersaccount op door op de groene “V” knop te klikken.

Maak een “Cijferkolomverzameling” aan

Om een school controle te laten hebben over welke cijfer typen zij willen weergeven in onze cijfers Magister live tegel, hebben we besloten om gebruik te maken van de cijferkolomverzameling functie in Magister, omdat dit klanten in staat stelt te selecteren welke studies, cursussen en periodes ze willen opnemen in de resultaten. De integratie is afhankelijk van deze functie, dus het werkt alleen als de onderstaande stappen zijn voltooid.

Open de Magister-beheerconsole.
Navigeer naar de sectie “Beheer”.
Klik op “Ontwerp” om de rapportontwerper te starten.
Navigeer naar de sectie “cijferrapportage”.
Klik op “Cijferkolomverzameling”.
Klik op het + pictogram in het bovenste navigatiemenu om een nieuwe verzameling aan te maken.
Geef “WS365” op als naam.
- Opmerking: De naam moet exact overeenkomen met “WS365” (zonder aanhalingstekens).
Geef “Workspace 365 Cijfers” op als beschrijving.
Zorg ervoor dat “Cijferkolomverzameling wordt gebruikt voor” is ingesteld op "Inlezen en afdrukken".
Selecteer alle rollen die toegang moeten hebben tot deze verzameling.
Klik op de groene knop met vinkje om de verzameling op te slaan.
Selecteer de nieuwe “WS365” verzameling.
Selecteer het tabblad “Kolommen” in het rechteroverzicht.
Klik opnieuw op het rode '+' pictogram om de wizard voor cijferkolommen te starten.
Gebruik de “Alle” knop om alle studierichtingen en alle bijbehorende cursussen te selecteren.
Selecteer in het volgende gedeelte alleen de cijfer typen die je wilt weergeven in de cijfer tegel in Workspace 365. Je kunt beslissen of je bijvoorbeeld examencijfers of adviescijfers wilt weergeven of niet.
Klik op "Volgende" en laat het “kolommen” overzicht zoals het is.
Druk in de sectie “Cijferkolomverzameling” opnieuw op de knop “Alle”, omdat alles moet worden opgenomen.
Het kan een paar minuten duren om alles op te nemen. Zodra de voortgangsbalk voltooid is, ga je verder naar de volgende stap.
Klik op “Voltooien” om de wizard te voltooien.
Sla de cijfer verzameling op en sluit de wizard.

Configureer Magister-integratie in Workspace 365

Nu kun je de Magister-app publiceren in je Workspace 365-omgeving. Als alles goed gaat, zou je het rooster en de cijfers moeten zien verschijnen in de Magister live tegel.

Ga naar de App store (of klik op "+ Tegels toevoegen").
Selecteer het tabblad “Apps beheren” bovenaan.
Klik op “Nieuwe app toevoegen” om de Magister-app te configureren. Hier kun je ook de app-instellingen beheren, zoals “wie heeft toegang” of wie wijzigingen in de app kan aanbrengen (eigenaren).
Klik op “Toevoegen” in de sectie "Verbinding” om een nieuwe integratieverbinding aan te maken.
- Voor de Server-URL kun je de poort gebruiken om de Magister-omgeving te bepalen. Productie = 8800. Test = 8801.
- Geef de webservice-gebruikersnaam en het wachtwoord op die je eerder in Magister hebt aangemaakt.
- Met de API-versie kunnen we verschillende versies van de Workspace 365-lijsten in Magister beheren.
- Klik op "Toevoegen" wanneer je klaar bent. Het zou er ongeveer zo uit moeten zien:
Wanneer je klaar bent met het configureren van de app, klik op “Opslaan”.
Je kunt de app nu toevoegen vanuit de App store aan Workspace.
1. Het is aan te raden om de Magister-app twee keer te publiceren in twee verschillende gedeelde tegelgroepen: één die alleen toegankelijk is voor docenten en het rooster toont. En de andere die alleen toegankelijk is voor studenten en zowel het rooster als de cijfers toont.
  - Opmerking: je kunt de Magister-app publiceren in één gedeelde tegelgroep, toegankelijk voor zowel studenten als docenten, waarin gebruikers kunnen schakelen tussen de standaardweergave van de tegel via een dropdownmenu. Cijfers zijn echter niet relevant voor docenten.
2. Omdat roosters, cijfers, enz., als iets persoonlijks worden beschouwd, raden we aan om de Magister-app in de persoonlijke ruimte van studenten en docenten te plaatsen: selecteer onder 'Standaard zichtbaarheid voor gebruikers in persoonlijke ruimte' de optie 'Groep tonen'.
Opmerking: Studenten en docenten kunnen er altijd voor kiezen om de gedeelde tegelgroep uit hun persoonlijke ruimte te verbergen onder 'Groepen'.

Meerdere Magister-omgevingen verbinden (productie- en testomgeving)

Misschien wil je zowel een Magister productie- als een testomgeving configureren. Hiermee kun je nieuwe Magister-configuraties testen zonder de productieomgeving te verstoren. Vergeet niet om ook een nieuwe app te maken, de juiste verbinding te selecteren en de app te benoemen volgens de omgeving waarmee je verbinding maakt.

Om de integratieverbindingen te configureren:

Klik op je profielknop in de rechterbovenhoek van je werkruimte.
Selecteer “Instellingen”.
Navigeer naar de sectie “Integraties”.
Selecteer “Magister-verbindingen”.
Door op “+ Nieuw” te klikken, kun je zoveel verbindingen maken als je wilt.