Zermelo koppelen

Lumicast kan het lesrooster van een school rechtstreeks uit Zermelo ophalen en op je schermen 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. Wil je een legacy-koppeling overzetten, open dan het menu van die koppeling onder Data koppelingen en kies Migreren: je databronnen en apps blijven gewoon werken.

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 tonen.

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, groupChanged, locationChanged, teacherChanged, timeChanged

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. Ga in Lumicast naar Data koppelingen en klik op Data koppeling aanmaken.

2. Open onder Verbonden diensten de groep Zermelo en kies Zermelo rooster.

3. Kies onder Selecteer verbinding de optie Nieuwe verbinding en vul in:

   • Basis-URL — het adres van je portal, inclusief https://, bijvoorbeeld https://jouwschool.zportal.nl
   • Autorisatiecode — de code uit stap 4

   Klik op Save. Lumicast wisselt de code in voor een toegangstoken en geeft de verbinding de naam van je school.

4. Kies het Schooljaar (roosterproject) dat je wilt tonen en klik op Opslaan.

Problemen oplossen

• De verbinding kan niet worden aangemaakt — de code is eenmalig en 30 dagen geldig. Maak een nieuw token aan (stap 3) en probeer het opnieuw met de nieuwe code. Controleer ook of de partner leestoegang heeft op minstens één veld van appointments (stap 2).
• 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 levert geen mededelingen. Die zijn alleen beschikbaar via de oudere "Zermelo (legacy)"-koppeling.