Business case
Magister is a Learning Management System (LMS) from the Netherlands which provides students, their parents and teachers with information on their schedules, homework, grades, course information, attendance registration and more.
It is used by over 50% of Dutch secondary education schools, which makes it one of the most used applications in the education space. Integrating Workspace 365 with Magister simplifies access to information, without having to open Magister at all.
Configure Magister
Requirements
To use the Magister integration, you first have to complete the steps below to establish a secure connection and prepare the information we need to extract from Magister in order to present the schedule and grades in Workspace 365.
Needed Workspace subscription: Adapt or Boost.
The Workspace 365 IP range needs to be whitelisted by Schoolmaster
Create all the lists in Magister to obtain schedule and grade information.
Create a Magister user account with “read” properties and access to the lists.
Create a new “Grade column collection” named “WS365”
Note: This needs to be repeated at the beginning of every school year.
Whitelist Workspace 365 IP-range
To allow us to communicate with the correct Magister database, you have to allow Workspace 365 to access your environment. This can only be achieved by contacting Schoolmaster and file a request to whitelist our IP-range (20.103.81.112/28). Schoolmaster will respond by email.
Click on “Maak een ticket” in the top right corner.
Select “Whitelisting IP-adressen”.
Provide the required information and complete the form.
In the meantime, you can continue with the next steps to prepare your Magister environment to receive a connection from Workspace 365.
Workspace 365 specific lists
This paragraph describes the Lists (SQL queries) in Magister, which must be created to get the required information from Magister into Workspace 365. A list contains a SQL query, which we can define, to retrieve the required information from the Magister database. To execute the query in a list, we use a call to the Medius Webservice.
We have created the following Lists to get data from Magister into Workspace 365:
WS365_GetLists
WS365_GetPerson_v1
WS365_GetSchedule_v1
WS365_GetLastGrades_v1
To download the Workspace 365 lists, go to our download page in your widget.
WS365_GetLists
This list returns the IDs and names of the defined WS365_* lists. This list can be used to get all the lists defined by Workspace 365, which are created in a specific Magister environment. This allows us to check if all required lists (and versions) are correct and created in Magister.
It does not say if you have access to the a list or not. If a call to one of these lists fails, it can be that the Magister administrator did not configure the correct user permission to execute that list.
WS365_GetPerson_v1
A list which returns the person information based on its UPN (Magister AD name).
There are two scenarios regarding this list, depending on your setup.
1. Microsoft Entra ID as leading identity provider.
The GetPerson list looks at the sis_gebr.adnaam column in Magister by default. This is only filled in automatically if you sync user data from Microsoft Entra ID (previously called Azure AD) to Magister, making Microsoft Entra ID the leading identity provider. You can set up the lists in Magister using our default lists.
2. Magister as leading identity provider.
If Magister is the leading identity provider (meaning there is no sync from Microsoft Entra ID to Magister), you need to make an adjustment to prevent that the Magister tile will return the error “items cannot be retrieved“
Open the GetPerson list.
Go to line WHERE sis_gebr.adnaam = @upn
Replace sis_gebr.adnaam with sis_gebr.email
The users' email must match with their UPN in Workspace.
You can verify beforehand if you can use sis_gebr.adnaam by running a query in Decibel.
WS365_GetSchedule_v1
Returns the scheduled items of a person (student or teacher) within a certain period.
WS365_GetLastGrades_v1
Gets the list of ten most recent grades of a student. The returned list is sorted to show the most recently assigned grade at the top. Grades can include a weighting factor if there is one assigned.
Installing lists in Magister
The lists defined by Workspace 365 must be installed in Magister. Administrators of Magister should know how to do this. Below a short instruction on how to do this.
Adding new (empty) lists
Open Magister Desktop.
Go to "Beheer".
Go to "WebServices".
Select "Lijsten"
Add new list (red '+' button).
Cancel the "Kolomkiezer" dialog.
Fill in name of the list (e.g. WS365_GetLists_v1) in the edit box "Naam".
Press the green checkmark button.
Repeat the above steps for all the lists you have to create.
Add or update SQL queries for Workspace 365 lists
Open Magister Desktop.
Click on the top left Magister icon.
Select “Onderhoud”.
Select "Decibel".
Enter the password.
The Magister Decibel Dashboard will appear after 20 seconds or so. From the left tree view, select "System".
Select "ddlijsten".
In the right bottom panel, scroll to the list you want to add the SQL query to.
Double-click the document-text-icon (in the second column “sSQL” of the table).
A dialog "Memoinhoud van sSQL" will appear. Add (or replace) the existing content with the content from the “WS365_XXXX_v1” SQL files.
Click on "Sluiten".
A confirmation dialog will appear. Click the "Ja" button to save the changes.
Repeat the above steps for all the lists you have created.
List versioning
The names of the lists are suffixed with a version number (e.g. WS365_*_v1). This version number will be increased when a new version of a list is not compatible with its previous version. For example, when parameters are changed, a new version of the list is required. When there are small changes in a list (e.g. an extra field is returned), it is not required to update version number.
When a new version of a list is available, it can be installed next to the other version(s). A new version of a list can already be installed before a new version of Workspace 365 is published, so the Magister environment can be prepared in advance.
It is advised to not delete old versions of a list immediately after a Workspace 365 update, so a rollback of a Workspace 365 version can be done easily. Old list versions can be removed within one or two weeks after the release. It is the responsibility of the Magister administrator to install and update the correct version of the lists and to remove old versions.
Medius Webservice user
Magister allows third-party applications to access information in Magister via their Medius Webservice. To access this webservice you need an account which in turn has access to specific lists. Please follow the steps below to create a new account and assign the appropriate lists.
Create Medius Webservice user account
Open Magister Desktop.
Go to "Beheer".
Go to "WebServices".
Select "Gebruikers".
Add new user (red '+' button).
Go to the tab “Algemeen”.
Provide a name (e.g. "WS365").
Select the checkmark to activate the account.
Click the “Wachtwoord” button to set a secure password.
Note: Special characters are not allowed (for example: ! % #)
Save the user account by clicking on the green “V” button.
Assign Services and lists to a user
Open Magister Desktop.
Go to "Beheer".
Go to "WebServices".
Go to "Gebruikers".
Select the Workspace user you have just created.
Edit the user (red 'pencil' button).
Go to tab “Services”.
Go to the subsection “Algemeen”.
Add a checkmark for “Algemeen.Login”.
Add a checkmark for “Algemeen.Logout”
Go to the subsection “(Data)”.
Add a checkmark for “Data.GetData”.
Go to tab “Lijsten”.
Scroll down to the lists you’ve created in step “Adding new (empty) lists”.
Add a checkmark for each of the lists.
Save the user account by clicking on the green “V” button.
Create a “Grade column collection”
To allow a school to take control over which grade types they would like to appear in our grades Magister live tile, we decided to use the grade column collection (cijferkolomverzameling) feature in Magister, as this allows customers to select which studies, courses and periods they want to include in the results. The integration is dependent on this, so it will only work if the below steps are completed.
Open the Magister administration console.
Navigate to the “Beheer” section.
Click on “Ontwerp” to start the report designer.
Navigate to the “cijferrapportage” section.
Click on “Cijferkolomverzameling”.
Click on the + icon in the top navigation menu to create a new collection.
Provide “WS365” as the name.
Note: The name should exactly match “WS365” (without quotes).
Provide “Workspace 365 Cijfers” as the description.
Make sure “Cijferkolomverzameling wordt gebruikt voor” is set to "Inlezen en afdrukken".
Select all roles that should have access to this collection.
Click on the green button with checkmark to save the collection.
Select the new “WS365” collection.
Select the “Kolommen” tab in the right overview.
Click on the red '+' icon again to start the grade column wizard.
Use the “Alle” button to select all studies directions and all associated courses.
In the next section, only select the grade types you want to display in the grades tile in Workspace 365. You can decide whether you want to show, for example, exam or advice grades or not.
Click "Next" and leave the “kolommen” overview as is.
In the “Cijferkolomverzameling” section, press the “Alle” button again, as all have to be included.
It can take a few minutes to include everything. Once the progress bar is complete, continue to the next step.
Click “Voltooien” to complete the wizard.
Save the grades collection and close the wizard.
Configure Magister integration in Workspace 365
Now, you may continue to publish the Magister app in your Workspace 365 environment. If all goes well, you should see the schedule and grades be populated in the Magister live tile.
Go to the App store (or click on "+ Add tiles").
Select the “Manage apps” tab at the top.
Click on “Add new app” to configure the Magister app. This is where you can also manage the app settings, such as “who has access” or who can make changes to the app (owners).
Click “Add” in the "Connection” section to create a new integration connection.
For the Server URL, you can use the port to determine the Magister environment.
Production = 8800.
Test = 8801.Provide the webservice username and password you’ve created in Magister earlier.
API version allows us to manage different versions of the Workspace 365 lists in Magister.
Click "Add" when you're done. It should look something like this:
When you're done configuring the app, click “Save”.
From the App store, you can now add the app to Workspace.
It is advised to publish the Magister app twice in two different Shared tile groups: one only accessible for teachers showing the schedule. And the other one only accessible for students showing both the schedule and grades.
Note: you can publish the Magister app in one Shared tile group, accessible for both students and teachers, in which users can switch between the tile's default view via a drop-down menu. However, grades are not relevant for teachers.
Because schedules, grades, etc., is seen as something personal, we recommend to push the Magister app the Personal space of students and teachers: under 'Default visibility to users in personal space', select 'Show group'.
Note: Students and teachers can always choose to hide the Shared tile group from their Personal space under 'Groups'.
Connect multiple Magister environments (production and test environment)
Perhaps you want to configure both a Magister production- and a test environment. This enables you to test new Magister configurations without disturbing production. Don’t forget to also create a new app, select the correct connection and name the app according to the environment you are connecting to.
To configure the integration connections:
Click on your profile button in the top right corner of you workspace.
Select “Settings”.
Navigate to the “Integrations” section.
Select “Magister connections”.
By clicking “+ New”, you can create as many connections as you like.