In GoBright View it's possible to retrieve information from various scheduling/timetable tools like Zermelo and Untis. This information can be used to display schedule changes on signage displays within a building. The changes can be filtered according to your needs.
| Zermelo | Untis | |
| Filter classes | V | V |
| Filter teachers | V | V |
| Filter subjects | V | V |
| Display cancelled appointments | V | V |
| Display changed teacher | V | V |
| Display changed location | V | V |
| Display changed time | V | V |
| Display changed subject | V | V |
| Display only changes made today | V | V |
| Display entire schedule for today* | X | X |
* The widgets are built to only show changes in a schedule. Showing the entire schedule would cause an overload of information on the signage display.
Configuring schedule provider
There are a few requirements that need to be set up first. Please continue following the steps for your situation.
Zermelo configuration
Requirements
- The name of the organization within Zermelo
- A Zermelo admin account
- An API token
- One or more codes of the location(s)
- The Zermelo Widget
Create the API token
Summary of the Zermelo article
The first thing we require is the name of the organization within Zermelo. This is the same name within the URL you use to login to Zermelo:
https://[Schoolname].zportal.nl
Login to Zermelo with an admin account and note down the Schoolname within the URL, we'll be needing that later. Follow these steps within Zermelo to create a new API token:
Step 1 Add the user
The external client has to be added to the portal as a user.
1. Go to Beheer > Gebruikers
2. Select at Filter: "Geen filter"
3. Click on the button <Toevoegen>
4. Fill in the "Gebruikerscode" the name of the user
5. Delete the check on "Mag de gebruikers inloggen"
6. Add the check on "Toevoegen als werknemer"
6. Click on the button <Toevoegen>
Step 2 Add user to the "Roosterproject"
The user that was just created has to be added to the "Roosterproject".
1. Go to Personeel>Overzicht>Tabblad Contracten
2. Select the right "roosterproject"
S. Click on the butoon <Toevoegen>
4. Type in the user at the Gebruikerscode
5. Click on the button <Volgende>
6. Change the "functiecategore" to OOP
7. Click on the button <Klaar>
More projects in one portal?
Maybe there are more "roosterprojecten" for the current school year in the portal. That means for the user with multiple "roosterprojecten" more contracts need to be assigned to this user.
Step 3: Configuring the rights
Now it is time to give the user the rights. Important is to not give the user more rights than it's necessary!
Warning: An external party gets the right to do reading and writing. If not configured correctly, please doublecheck the rights that are being configured for this user.
1. Go to Beheer > Schoolfuncties > tabblad Toekeningen schoolfuncties (details)
2. Select the "roosterproject"
3. Select the user
4. Click on the button <Toevoegen>
5. Select the right you want to add
6. Select the level "Project"
7. Select the rights (lezen/bewerken)
8. Click on the button <Toevoegen>
Rights for narrowcasting
External parties that will show the "roosterwijzgingen" will need the following rights to show the information on the screens:
- Lezen: Roosters en afspraken (project)
- Lezen: Afwezigheden (project)
Step 4: Creating the API token
Now the user has been added and has been given the rights for reading the "roosterwijzigingen". Now you have to create the API token. This token will be used for the external party.
1. Go to Beheer > Admin-paneel>tabblad API tokens
2. Click on the button <Toevoegen>
3. Select the user
4. Select the expire date
5. Add a comment to make it easier to find it back
6. Click on the button <Opslaan>
7. Click on the button <OK>
You can create the token for a maximum amount of 5 years. You can also choose to create a new token every year. Make sure to note this data in your agenda.
Note down the API token.
Get the code from the location(s)
The Zermelo widget will only show information from one specific location. It's possible to add multiple widgets with different locations, but for each location, a code is required. This code can be found underneath locations within Zermelo or by following the steps below:
- https://[Schoolname].zportal.nl/static/swagger/
- Copy the created API token to the access_token field on the top right
- Press the reload button
- Scroll down to branches, select it and press the try it out button
- When done correctly there should be a list with all the names of locations and their codes displayed below:
{ "response": { "status": 200, "message": "", "details": "", "eventId": 0, "startRow": 0, "endRow": 4, "totalRows": 4, "data": [ { "code": "a", "name": "Apeldoorn", "somCode": "01rl00" }, { "code": "u", "name": "Uddel", "somCode": "01rl02" }
Note down the field next to code, this is the information we'll need within the widget.
Only items (appointments) that have a "changed" state are being displayed in the widget. If you copy an item in Zermelo it can be marked as an 'original' appointment, without "changed" state and thus won't show in the widget.
Requirements
- The export from Untis (a GPU014.txt file)
- A OneDrive or FTP location to publish the GPU014.txt file (this location must be accessible by the GoBright Portal and View device(s))
- The Untis Widget
Please be aware that for units to work with OneDrive the permissions that will be required are (Application instead of Delegate) in Azure:
Application Files.Read.All
Application User.Read.All
OneDrive
To set up OneDrive and the Graph API, please be aware that for units to work with OneDrive the permissions that will be required are (Application instead of Delegate) in Azure:
Application Files.Read.All
Application User.Read.All
GoBright View Widget Configuration
Now head over to GoBright View to complete the following steps.
- Place the Widget in a template or slide.
- Fill in the API Token, School name, School year (the beginning year of the current school year - for ex. 2024 for this school year) and location code in the Zermelo widget. This should display all the changes based on the current location.
- Define the timetable / lesson times
- Set the filter parameters to your need (optional)
- Place the Widget in a template or slide
-
Choose the source (OneDrive or URL)
-
OneDrive:
Fill in the Client ID, Client Secret, Tenant ID, User Email, Folder Name (file location) and File Name - URL
Fill in the entire URL to the GPU014.txt file
-
OneDrive:
- Define the timetable / lesson times (see below)
- Set the filter parameters to your need (optional) (see below)
Widget parameters
Timetable
To show only the current changes we'll need to add in the times that the lessons take place. The time here represents the end time of the lessons. These times are mandatory for the widget to function correctly.
Filter options
There are three fields that allow filtering options class, rooms, and teachers. Filters can be used to include and/or exclude. To use these, an item can be entered to filter on that specific item. For example, if V5E is entered within the class_include field it will only show schedule informatio for class V5E. It is possible to use multiple items (seperated by a pipe: '|') or to use more advanced filtering options. This is done using regex.
Some examples:
| Filter | Used in | Explanation |
| a4b1|a4b2|a4b3 | classes_include | Shows only classes ‘a4b1’, ‘a4b2’ or ‘a4b3’ |
| aula | locations_exclude | Hides aula |
| pp|tvdg | teachers_exclude | Hides pp and tvdg |
| INV | subject_exclude | Hides all subjects containing 'INV' |
In most cases these examples will suffice.
More advanced filtering
When more advanced filtering is needed it is good to know that all this is based on regular expressions (regex). Please be careful as it is easy to hide all results. Then the widget will show a "there are no changes" message.
Try to keep filters as simple as possible. Do not use an exclusion regex within a include field or vice versa to prevent 'double negatives'.
Regex
^ = Starts with characters after this sign
$ = Ends with characters before this sign
| = Separation character between each item
(?!) = Everything which is not equal to these characters
| ^r2 | Filter on rooms that starts with ‘r2’ (this is case sensitive) |
| ^r2|^r3 | Filter on rooms that starts with ‘r2’ or ‘r3’ |
| 4A$ | Filter on classes that ends with ‘4A’ |
| (?!a4b1) | Filter on everything except class 'a4b1' |
| (?!a4b1)|(?!a4b2)|(?!a4b3) | Filter on everything except classes ‘a4b1’, ‘a4b2’ or ‘a4b3’ |
| ^(?!a4b) | Filter on everything except classes that starts with ‘a4b’ |
| 4\. | Filter on everything containing "4." (the back slash is key) |
Other options
There are a couple of other options that are used to:
- sort the information by specific types or dates
- change the order of the columns
- show or hide previous schedule data (for example: classroom1 > classroom2)
- show data from the current day and/or the next day
- apply styling