Skip to end of metadata
Go to start of metadata


Definities

BegripBetekenis
lesEen afspraak. Om dit document makkelijker leesbaar te maken wordt overal "les" gebruikt, maar alles geldt ook voor toetsen en activiteiten.
keuzelesEen les of andere afspraak waar de betreffende leerling zich voor kan in/uitschrijven. Wat voor de ene leerling een reguliere les is kan voor de andere een keuzeles zijn.
reguliere lesEen les waar de betreffende leerling normaliter altijd naartoe moet. Het kan wel zijn dat de leerling incidenteel hier niet naartoe hoeft, bijvoorbeeld als er tegelijkertijd een activiteit plaatsvindt.
keuzeroosterEen rooster waar keuzelessen in voorkomen.
keuzemoment

Een tijdsinterval waarop een leerling iets mag kiezen. De mogelijke keuzes zullen in het overgrote deel van de gevallen ook betrekking hebben op dit moment. Het is echter wel belangrijk om te beseffen dat een genomen actie ook buiten dit interval invloed op het rooster en de keuzemogelijkheden kan hebben.

Let op: in Somtoday is een keuzemoment de les zelf. Het keuzemoment zoals Zermelo dat kent zou in Somtoday een keuzemomentcluster heten.

keuzemogelijkheidEén van de opties waaruit de leerling kan kiezen. Vaak zijn dit verschillende lessen die tijdens het keuzemoment worden aangeboden.
conflict/botsingEen probleem in het rooster waarbij een leerling op twee plekken tegelijk verwacht wordt, of twee dingen tegelijkertijd moet doen.
leerlingEen persoon die lessen volgt als deelnemer (dus niet als docent/begeleider/instructeur).
externe partijDe ELO (soms ook LAS) die het rooster aan haar gebruikers wil tonen.







Veel scholen gebruiken Zermelo voor het rooster en een externe partij als centraal systeem voor leerlingen/ouders/docenten (de ELO). Vroeger kon Zermelo een rooster opleveren met (ruimte voor) keuzelessen, en het inschrijven dan overlaten aan de ELO of een ander extern systeem. Door de toenemende individualisering van het onderwijs wordt dit echter steeds lastiger. Bij het maken van het rooster moet meer en meer rekening worden gehouden met de scholingsbehoefte, de keuzelessen staan niet meer in eenvoudige banden, en bij het aanpassen van het rooster moeten de roostermaker rekening houden met bestaande inschrijvingen. De afname van het leerlingaantal die sommige scholen zien vraagt ook om extra flexibiliteit.

Sinds afgelopen seizoen (schooljaar '19-'20) heeft Zermelo uitgebreide mogelijkheden om roosters op te leveren met keuzelessen en maatwerk. Leerlingen kunnen in de nieuwe Zermelo WebApp zien welke lessen ze moeten volgen en kunnen keuzes maken. Er leeft echter de sterke wens om geen aparte app te gebruiken maar om dit in de ELO te doen. Zermelo begrijpt dit volledig en wil dit mogelijk maken. Voor het onderwijs is het immers het beste als informatie zoals huiswerk en cijfers tegelijkertijd getoond wordt met het rooster, zodat de leerling weet waar deze aan toe is en de juiste keuzes kan maken.

Met dit doel heeft Zermelo een nieuwe API ontwikkeld die in dit document beschreven staat.

Een korte presentatie is te vinden op https://docs.google.com/presentation/d/1yOG-8dNukYH6U6ecNfimYYubS1IfZUg7U7L4EYsIep4/edit?usp=sharing

Scope van de nieuwe API

Het ontwerp van deze API heeft betrekking op het welke lessen een leerling volgt en de invloed die een leerling heeft op het rooster. Het is daarmee een aanvulling op de bestaande /appointments API.

Bestaande API (/appointments)Nieuwe API (/liveschedule)
  • Tijdstip en locatie van les.
  • Bij welk stuk onderwijs de les hoort.
  • Algemene (rooster) informatie over de les.

Daarnaast (voorlopig) ook:

  • Welke docent deze les geeft.
  • Daadwerkelijk ingeschreven leerlingen.
  • Het individuele meest actuele leerlingrooster
  • Acties die een leerling kan uitvoeren op het rooster, waaronder inschrijven

Het is nadrukkelijk de bedoeling de nieuwe API live te gebruiken. Er spelen twee aspecten mee waardoor Zermelo heeft gekozen om zich te richten op een live koppeling:

  1. Op het moment dat gegevens gewijzigd worden (bij inschrijven) is het belangrijk dat met de meest actuele gegevens gewerkt wordt.
  2. Synchronisatie kan veel tijd kosten, en is in de praktijk ingewikkeld en foutgevoelig.

Op het moment dat het externe systeem informatie wil koppelen aan een les (zoals huiswerk), dan moet de les natuurlijk wel in de database van het externe systeem staan. De lessen zelf kunnen voor dit doel worden ingelezen via /appointments.

Waarom Zermelo als beheerder van de inschrijfkaders en inschrijvingen?

Zermelo is verantwoordelijk voor de planning van de lessen (het rooster). Om dit optimaal te doen moet duidelijk zijn welke leerlingen welke lessen moeten en mogen volgen. Het is daarom belangrijk dat de inschrijfkaders bij Zermelo bekend zijn. Het gaat dan over het aantal lessen wat een leerling moet (kunnen) volgen, in welke volgorde dat moet etc. Op het moment dat de inschrijvingen door twee partijen beheerd zouden worden (één voor het rooster en één voor het daadwerkelijk inschrijven) moeten de kaders aan beide kanten volledig overeen komen, wat in de praktijk lastig is.

Waarom geen iFrame?

Je zou de volgende vraag kunnen stellen: Als het rooster in een ander systeem getoond moet worden, waarom kan dat dan niet met een iFrame (of vergelijkbare techniek), waarbij Zermelo de grafische weergave van het rooster volledig voor haar rekening neemt?

Zermelo vindt het essentieel dat informatie uit de ELO (huiswerk, cijfers, etc.) getoond worden bij een (keuze)les, zodat de leerling weet waar deze aan toe is en een weloverwogen keuze kan maken. De enige manier waarop Zermelo de weergave voor haar rekening zou kunnen nemen is als zij eerst deze gegevens uit de ELO zou inlezen. De route die de gegevens afleggen wordt dan wel erg gecompliceerd.

API ontwerp

Het ontwerp modelleert het probleem als volgt:

  1. Het externe systeem vraagt het rooster van een leerling of docent op (inclusief acties).
  2. Lessen waarbij niets te kiezen valt komen terug als de vertrouwde appointments.
  3. Een les waarvoor een leerling zich kan uitschrijven, of kan wisselen naar een andere les, bevat een lijst van acties. Bij deze actie staat aangegeven wat de les is waarheen je wisselt. Tevens is er (mits toegestaan) een actie waarbij de leerling zich uitschrijft.
  4. Een keuzemoment wordt gemodelleerd als een appointment van type "choice" waarbij als acties één van de lessen gekozen kan worden.
  5. Een conflict wordt gemodelleerd als een appointment van type "conflict" waarbij als acties (indien mogelijk) kan worden gekozen uit één van de verplichte of reeds gekozen lessen.
  6. De actie wordt uitgevoerd middels een HTTP POST naar een URL wat in de actie wordt meegegeven.
  7. Zermelo kan acties meegeven die niet genomen mogen worden. Het andere systeem kan de status van deze acties gebruiken om inzichtelijk te maken waarom iets niet kan.

Opvragen van roosters

De liverooster api ondersteunt het opvragen van twee type roosters, leelringroosters en docentroosters. Omdat er subtiele verschillen zitten in het aanroepen van de api, en de responses die de api teruggeeft hebben wij voor beide situaties een voorbeeld uitgewerkt.

Opvragen leerlingroosters

Voor het opvragen van de leerlingroosters verwijzen wij u naar de subpagina: Opvragen leerlingroosters.

Opvragen docentroosters

Voor het opvragen van de leerlingroosters verwijzen wij u naar de subpagina: Opvragen docentroosters.

Als extern systeem met één token roosters opvragen namens anderen

Als uw externe systeem normaal met één token de roosters van alle gebruikers opvraagt dan dient u hier rekening mee te houden met het gebruik van deze API. Omdat dit persoonlijke roosters zijn (en persoonlijke keuzes) moet er duidelijk worden aangegeven als welke gebruiker u het verzoek doet. Dat gaat via de X-Impersonate header. Een voorbeeld van zo'n verzoek voor een leerling met leerlingnummer 138531 is dus als volgt:

GET /api/v3/liveschedule?student=138531&week=202010&fields=appointmentInstance,start,end,startTimeSlotName,endTimeSlotName,subjects,groups,locations,teachers,cancelled,changeDescription,schedulerRemark,content,appointmentType,expectedStudentCount,expectedStudentCountOnline
Authorization: Bearer fgds74789gsf6gs6dfg6sdfg9s
X-Impersonate: 138531

...


Tonen van het rooster

Het tonen van een rooster kan op de volgende manier gebeuren:

  1. Een leerling gaat naar een pagina waar het rooster getoond moet worden.
  2. De externe partij doet via de API van Zermelo een verzoek om voor de betreffende week de appointments inclusief keuzemomenten op te vragen.
  3. De externe partij koppelt intern extra informatie aan de appointments. Dit is bijvoorbeeld het huiswerk.
  4. Het rooster wordt nu getoond. Voor keuzemomenten kan het aantal mogelijke acties getoond worden.
  5. Op het moment dat een leerling een les aanklikt met mogelijke acties toont de interface een knop om de lijst met acties te bekijken.
  6. Als het om een keuzemoment gaat waarop nog niets gekozen is (of de leerling klikt in de voorgaande stap op de knop) dan wordt de lijst met acties getoond.
  7. Op het moment dat leerling een van de acties kiest wordt er een POST gedaan op de Zermelo API.
    1. Is dit 2XX OK? Dan is de actie gelukt.
    2. Is dit 4XX? De actie is mislukt. In het veld "message" staat een (NL) tekst. Let op: we zijn aan het kijken of we de statusberichten zoals de API verder ook gebruikt hier voor kunnen inzetten. Dit verandert mogelijk nog.
    3. Andere status codes (zoals 3XX en 5XX) hebben de betekenis zoals in HTTP.
  8. Na elke gelukte of mislukte actie wordt het keuzerooster opnieuw opgehaald. Hierbij kan werkelijk alles veranderd zijn.

Bijzondere situaties

Hieronder staan een aantal bijzondere situaties omschreven.

Conflicten in het rooster

Zermelo heeft als doel om vooraf duidelijk te hebben waar alle betrokken personen verwacht worden. Het kan een enkele keer echter toch voorkomen dat in het rooster een persoon op twee plekken tegelijkertijd verwacht wordt. Dit is een roosterconflict. Een conflict kan optreden als er meerdere onafhankelijke roosters gecombineerd worden, door roosterwijzigingen waarbij verwacht wordt dat leerlingen het conflict zelf oplossen of door technische beperkingen die het onmogelijk maken het rooster op een andere manier te modelleren.

Een roosterconflict wordt in de API getoond als een object met type "conflict". De structuur van dit object is precies hetzelfde als een choice. Het verschil tussen een conflict en een choice is dat bij een conflict de leerling op dit moment (dubbel) ergens verwacht wordt, terwijl dit bij een choice niet zo is. Een choice waarbij niets te kiezen valt hoeft het externe systeem misschien niet eens te laten zien, terwijl dit bij een conflict wel moet gebeuren!

Bij onderstaande voorbeelden gaan we uit van een les NE die tegelijkertijd plaatsvindt met een les WI. De leerling wordt bij beide lessen verwacht. De actions bestaan in dit geval uit de handelingen die een gebruiker zou kunnen nemen om het conflict op te lossen. We onderscheiden 3 situaties.

1. Beide lessen zijn keuzelessen

De leerling kan in dit geval kiezen voor één van de lessen. Bijvoorbeeld door de actie met keuze voor het NE appointment uit te voeren. In dat geval gaat de leerling alleen naar NE en wordt uitgeschreven voor WI. De acties hebben een aparte status (3001) die aangeeft dat het aangegeven appointment reeds gekozen was.

2. Eén van de lessen is een keuzeles, de andere is verplicht

Naast twee lessen waar een leerling zich nog voor kan in/uitschrijven kan het ook zijn dat er een verplichte les botst met een keuzeles. In dat geval heeft de actie waarbij de leerling zou kiezen voor alleen de keuzeles de waarde allowed: false. Dit is dus geen actie die de leerling kan nemen. Wel mag de leerling kiezen om alleen de verplichte les te volgen. De leerling schrijft zich hierdoor uit voor de keuzeles en lost het conflict op.

3. Beide lessen zijn verplicht

Als derde geval kan het zijn dat twee verplichte lessen botsen. In dat geval zijn beide acties (alleen WI en alleen NE) allowed: false.  Bij beide lessen wordt aangegeven dat de leerling verplicht naar de les moet en het niet mogelijk is om het conflict op te lossen door alleen voor die ene les te kiezen.

Bij Zermelo kiezen we ervoor om in de weekweergave alleen een indicatie van een conflict te tonen. De gebruiker moet op het conflict klikken om te kijken wat er aan de hand is.

Uitgevallen lessen

Bij Zermelo tonen we een uitgevallen les (cancelled: true) waar geen andere les overheen is geplaatst rood in het rooster. Als er wel een les (die wel doorgaat) overheen is gepland tonen we de niet-uitgevallen les, en in een niet-toegestane (allowed: false) actie is zichtbaar welke afspraak er eerder tegelijkertijd stond.

Blokuren

Het kan zijn dat een leerling voor twee opeenvolgende uren mag kiezen, en dat er de keuze is om één blokuur te volgen of twee losse lessen. Dit modelleren we als volgt:

  1. Beide lesuren van het blokuur zijn aparte keuzemomenten.
  2. Als de leerling zich inschrijft voor een les die maar één uur duurt dan is er niets aan de hand.
  3. Als de leerling zich inschrijft voor een les die hoort bij een blokuur dan gebeurt het volgende:
    1. De leerling wordt ook voor de andere les van het blokuur ingeschreven.
    2. De leerling wordt uitgeschreven voor lessen die conflicten zouden veroorzaken (een reeds gekozen les die valt tijdens het blokuur).

Dagvullende activiteiten

Het kan zijn dat er een dagvullende activiteit staat tegelijkertijd met een dag vol keuzemomenten van één lesuur. Deze situatie kan op dit moment nog niet vanuit Zermelo gepubliceerd worden, omdat de activiteiten bij publicatie ook gewoon op de lesuren staan. Op het moment dat de roostermaker dit wel als zodanig kan publiceren zorgt Zermelo ervoor dat dit op een overzichtelijke manier wordt aangeboden via de API. Dit zijn de mogelijkheden:

  1. één groot keuzemoment waarop de leerling wel/niet kiest voor de activiteit, wat na de keuze vanuit de API wordt aangeboden als keuzemomenten voor de verschillende lesuren (zie punt twee)
  2. direct als losse lesuren, waarbij de leerling op elk lesuur óók kan kiezen voor de dagvullende activiteit. Bij het kiezen voor de activiteit wordt de leerling voor alle lessen uitgeschreven en verschijnt de activiteit in het rooster (zie punt een

Statuscodes

Een uitgebreide uitleg over de statuscodes die bij een afsprakenlijst mee kan komen vindt u onder deze subpagina.

Caching voor performance en betrouwbaarheid

Als u aan de slag gaat met deze API is het voor de eerste proof-of-concept een stuk simpeler om dit buiten beschouwing te laten.

Het werken met caching kan nuttig zijn voor de beleving van gebruikers, performance en betrouwbaarheid. Het is dan ook aanbevolen om de gegevens uit de API te cachen. Wel moeten de volgende punten in acht worden genomen:

  1. Gegevens die 60 of minder seconden geleden opgehaald zijn mogen getoond worden als "live" gegevens.
  2. Gegevens moeten beschouwd worden als verouderd als deze meer dan 60 seconden geleden zijn opgehaald OF als er een actie op de API is gedaan die de gegevens aanpassen.
  3. Verouderde gegevens mogen getoond worden aan gebruikers maar hierbij moet duidelijk worden aangegeven dat deze verouderd zijn.
  4. Indien mogelijk moeten de verouderde gegevens automatisch op de achtergrond bijgewerkt worden. Na het bijwerken moeten deze dan automatisch aan de gebruiker worden getoond.

Bij Zermelo maken we in de nieuwe WebApp gebruik van deze architectuur (cache-first), en hier zijn we erg tevreden over. Het is voor gebruikers zelfs niet eens mogelijk om handmatig te verversen!

  • No labels