Zermelo koppelen

Lumicast kan het lesrooster van een school rechtstreeks uit Zermelo ophalen en op je displays tonen. Deze handleiding laat een beheerder van het Zermelo Portal zien hoe je Lumicast toegang geeft en de autorisatiecode aanmaakt die je in Lumicast plakt.

Partnerrechten

Zermelo heeft de oude "API-token"-koppeling vervangen door partnerrechten: in plaats van een token te delen maakt de school een partner aan voor Lumicast, geeft die toegang tot specifieke endpoints en velden, en genereert een eenmalige autorisatiecode. De oudere "Zermelo (legacy)"-koppeling in Lumicast blijft werken voor bestaande installaties, maar nieuwe koppelingen gebruiken de partnerflow die hier beschreven staat.

1. Maak de partner aan

Ga in het Zermelo Portal naar Beheer › Partners en open het tabblad Partners. Klik op Toevoegen.

Vul de partnergegevens in:

• Naam — Lumicast
• Contactpersoon school — je eigen gegevens
• Emailadres partner — [email protected]
• Projecten — selecteer de roosterprojecten waarvan je het rooster wilt tonen. Kies elk schooljaar / elke locatie die je wilt weergeven.

Klik op OK.

2. Geef toegang tot het appointments-endpoint

Open het tabblad Toegang en klik op Toevoegen.

• Zet Partner op Lumicast.
• Zet Endpoint op appointments (Afspraakversies).
• Zet onder Veldtoegang elk veld op Lezen. Dit is de eenvoudigste betrouwbare instelling — de rooster-app gebruikt de meeste van deze velden, en de paar velden die ze niet kan krijgen (die worden niet aan partners aangeboden) vangt ze netjes op.

Leestoegang is verplicht

Als een veld geen leestoegang heeft, vraagt Lumicast het niet op, en als er nul velden zijn toegekend kan de koppeling niet worden aangemaakt. Deze velden moeten minimaal op Lezen staan, anders wordt het rooster niet goed weergegeven:

id, appointmentInstance, start, end, lastModified, type, valid, cancelled, changeDescription, subjects, teachers, groups, locations

Door alle velden toe te kennen hoef je hier niet opnieuw langs zodra de app meer velden gaat gebruiken.

• Laat onder Extra filters de filters fields en schoolInSchoolYear toegestaan staan (verplicht, standaard aan). De velden start en end zijn standaard filterbaar; Lumicast gebruikt dat om alleen het rooster rond de huidige dag op te halen.

Klik op Toevoegen (of Bijwerken als je een bestaande toekenning aanpast).

3. Maak een API-token aan

Open het tabblad API-tokens en klik op Toevoegen.

• Gebruiker — selecteer de partner Lumicast.
• Maximaal geldig — stel een vervaldatum in. Kies een datum ver in de toekomst zodat de koppeling blijft werken (bijvoorbeeld enkele jaren vooruit).
• Opmerking — optioneel, bijvoorbeeld Lumicast narrowcasting.

Klik op Toevoegen.

4. Kopieer de autorisatiecode

Het Portal toont een eenmalige autorisatiecode. Deze wordt maar één keer getoond en moet binnen 30 dagen worden gebruikt.

Kopieer deze code — je hebt hem nodig in de volgende stap.

5. Voeg de koppeling toe in Lumicast

1. Maak in Lumicast een nieuwe databron Zermelo rooster aan.
2. Kies Zermelo wanneer om een koppeling wordt gevraagd en vul in:
   • Base URL — het adres van je portal, bijvoorbeeld https://jouwschool.zportal.nl
   • Authorization code — de code uit stap 4
3. Sla op. Lumicast wisselt de code in voor een access token en toont de gekoppelde school(en).
4. Kies het schooljaar (roosterproject) dat je wilt tonen.

Problemen oplossen

• "Authorization code is already used or expired" — de code is eenmalig en 30 dagen geldig. Maak een nieuw token aan (stap 3) en probeer het opnieuw met de nieuwe code.
• Er verschijnt geen rooster — controleer of de partner Lezen-toegang heeft op het appointments-endpoint (stap 2) en of het juiste project is geselecteerd onder Projecten (stap 1).
• Mededelingen — de partner-API geeft geen mededelingen door. Die zijn alleen beschikbaar via de oudere "Zermelo (legacy)"-koppeling.