Inleiding

In deze beschrijving staan de handelingen die je in Zermelo en Somtoday moet doen om de automatische roosterwebservice-koppeling succesvol in gebruik te nemen.

De roosterkoppeling kun je gebruiken voor lessen, toetsen en activiteiten en vergaderingen.

Afvinklijstje

Dit moet je hebben gedaan om de koppeling succesvol in gebruik te nemen:

▢ Zermelo en Somtoday vestiging structuur controleren
▢ Zermelo en Somtoday vakafkortingen zijn gelijk aan elkaar
▢ Zermelo en Somtoday docentafkortingen zijn gelijk aan elkaar
▢ Somtoday feauture voor Zermelo aangevraagd bij de servicedesk
▢ Feature ingericht
▢ Somtoday rolrechten ingesteld voor Zermelo
▢ Somtoday medewerker aangemaakt voor Zermelo
▢ Zermelo medewerker/verzorger/leerling synchroniseren met Somtoday
▢ Zermelo rechtenstructuur instellen
▢ In Zermelo onderwijssoorten van Somtoday overnemen
▢ Stam- en lesgroepen exporteren uit Zermelo
▢ Stam- en lesgroepen importen in Somtoday
▢ Afspraaktypes goed instellen in Somtoday
▢ Eventueel huidige ingelezen rooster verwijderen uit Somtoday
▢ Roosterimport starten
▢ Logbestanden controleren en fouten oplossen
▢ Roosterimport automatiseren

Algemene voorbereiding

Vestigingen in Zermelo en Somtoday

Als je gebruik wil maken van de automatische roosterkoppeling Zermelo webservice, is het noodzakelijk dat de structuren van Zermelo en Somtoday op elkaar aansluiten. Heb je in Somtoday meerdere vestigingen waarvan je het rooster apart inleest, dan is het noodzakelijk dat voor deze vestiging ook het rooster in een apart Zermelo-vestiging staat. Het is niet mogelijk om binnen één Zermelo-vestiging twee verschillende Somtoday vestigingen van een rooster te voorzien.

Projecten in Zermelo bij Multi-brin omgevingen

Verder dienen er, indien Somtoday een multi-brin omgeving is, meerdere projecten te zijn aangemaakt in Zermelo. Ieder project bedient zijn eigen vestiging.

Medewerkers synchronisatie

Daarnaast worden altijd alle medewerkers gesynchroniseerd vanuit Somtoday naar Zermelo. Iedere medewerker moet daarom aan het juiste project te zijn gekoppeld, anders worden ze automatisch in Zermelo gearchiveerd.

Douanebladen en vakafkortingen

Verder zijn de douanebladen in Zermelo niet van toepassing in de export naar Somtoday. Dat betekent dat vakafkortingen en docentafkortingen exact gelijk moeten zijn in beide applicaties.

Zorg er ook voor dat de vakafkortingen in Zermelo gelijk zijn aan die in Somtoday.

Voorbereidingen Somtoday

Feature activeren in Somtoday

Om gebruik te kunnen maken van de automatische koppeling, moet de feature Zermelo koppeling worden aangezet in Somtoday door de Servicedesk. Meer informatie over features activeren vindt u hier.

Zermelo portaal koppelen

Stel de koppeling met het Zermelo-portal in onder Beheer > Instelling > Features > Zermelo koppeling.

Je kunt meerdere Zermelo-portals invoeren d.m.v. de juiste portal naam en Zermeloi api-token.
Het api-token vindt je in stap 3 van deze Zermelo-handleiding

Door middel van een vinkje kun je in Somtoday een Zermelo omgeving actief of niet actief maken.
Zermelo-omgevingen kun je ook verwijderen, tenzij ze al gebruikt zijn. Is dat het geval, dan is bij het portal een grijze achtergrond zichtbaar en mist het icoon waarmee je de omgeving kunt verwijderen.

Bij de kopieslag van productie naar test staat de instelling van de Zermelo-koppeling op productie ook op test. Met als gevolg dat test Somtoday verbonden is met productie Zermelo. Dit kun je uiteraard aanpassen door de API-token van de testomgeving van Zermelo in de testomgeving van Somtoday te plakken.

Zermelo live-koppeling (KWT lessen)

Volg eerst de Zermelo inricht instructie over het inrichten van het Zermelo-portaal. Zet daarna deze koppeling in Somtoday aan. Als de rechten in Zermelo niet juist zijn ingesteld en de live koppeling wordt toch aangezet zien de leerlingen maar 1 afspraak staan in de ELO.

De live koppeling met Zermelo gaat over het aanbieden en kiezen van vakkeuze lessen in Somtoday ELO die in Zermelo zijn gemaakt.

Zet deze optie per vestiging aan/uit als je het KWT keuzeproces van de leerling in Somtoday ELO wilt laten uitvoeren. Door de live-koppeling met Zermelo in te schakelen, door je vestiging te koppelen aan de Zermelo omgeving onder Zermelo Live koppeling, zorg je ervoor dat:

Somtoday ELO de gepubliceerde kwt lessen in het Zermelo portaal ophaalt en beschikbaar stelt aan de leerling
De leerling kiest dan in Somtoday ELO voor de kwt les uit Zermelo
De keuze wordt rechtstreeks naar Zermelo gestuurd en de leerling ziet zijn keuze direct in Somtoday ELO. De medewerker ziet dit na 15 minuten in Somtoday. Daarvoor moet je wel de taken hebben ingericht

Algemene instellingen

Leerling individueel roosteren

Deze optie maakt het mogelijk om leerlingen die in Zermelo uit een lesgroep afspraak zijn gehaald de afspraak in Somtoday ook niet te geven. Hiermee voorkom je dubbele afspraken. Wanneer deze optie gekozen wordt, kan alleen nog maar geïmporteerd worden op basis van 'groepen en individuele leerlingen'. Voor het roosteren is het vervolgens belangrijk dat altijd de lesgroep én de leerlingen die wel verwacht worden bij de les in Zermelo aan de afspraak gekoppeld worden. Hierdoor krijgen leerlingen uit de lesgroep die niet bij de les hoeven te zijn deze niet in hun rooster te zien, maar kunnen ze nog wel het huiswerk zien dat de lesgroep voor de afspraak heeft. Wel is het van belang om voordat het vinkje wordt aangezet de bestaande toekomstige afspraken te verwijderen.

Ouderavond: deze is beschreven in het artikel Ouderavondplanner

Zermelo synchroniseren met de Somtoday leerlingen/verzorgers/medewerkers

Zermelo kan iedere nacht de leerlingen, verzorgers en medewerkers ophalen uit Somtoday en deze als gebruiker aanmaken in Zermelo. Somtoday is vanwege de bekostiging leidend bij een school en daarom is hier altijd de actuele stand van leerlingen en verzorgers beschikbaar. Het is daarom verstandig deze synchronisatie in te richten.

Medewerker en rolrechten aanmaken

Maar een nieuwe rol aan voor de rechten op de webservices
Ga naar Beheer > Instellingen > Rollen en Rechten, en voeg een nieuwe rol ‘Zermelo webservices’ toe. Zet de onderstaande vinkjes aan:

Voeg een nieuwe medewerker toe in Somtoday met de naam ‘Zermelo webservices’. Deze medewerker moet toegang krijgen tot alle vestigingen waar Zermelo wordt gebruikt en koppel deze aan de nieuwe aangemaakte rol.

Het gebruikersnaam en wachtwoord van deze medewerker heb je nodig om in te voeren in Zermelo.

Voorbereiden in Zermelo

In Zermelo medew/verz/leerl synchroniseren met Somtoday

In Zermelo kan je nu via een webservice de gegevens van medewerkers, verzorgers en leerlingen iedere nacht actualiseren met Somtoday. De aangemaakte gebruikers moet je wel zelf aan een project koppelen.

Ook leerlingen met een voorlopige plaatsing gaan met de synchronisatie mee naar Zermelo. Als een leerling in Somtoday al een stamgroep heeft dan wordt deze leerling in Zermelo in de juiste stamklas en afdeling geplaatst. Heeft de leerling nog geen stamklas dan komt de leerling onder "instroom" terecht en kan de school de leerling daarna zelf plaatsen.

Vul in dit scherm de juiste wsdl, gebruikersnaam en het wachtwoord in.

De WSDL voor Somtoday is https://oop.somtoday.nl/services/umService?wsdl
Klik op de tab Systeemtaken in Zermelo.
Selecteer de regel en klik op Uitvoeren. Dit levert op het tabblad Logs een melding op dat dit alleen ‘s nachts kan. Dit bewijst dat de koppeling werkt. (Het handmatig uitvoeren van deze taak kan alleen ‘s nachts tussen 23:00 - 07:00 uur.)

Zermelo rol-rechten voor Somtoday-gebruiker

De gebruiker Somtoday in Zermelo moet een rol hebben met daarbij behorende instellingen. Alhoewel rolrechten niet meer van toepassing zijn in Zermelo, geldt dit niet voor de automatische koppeling.

Ga in Zermelo naar Beheer > Gebruikers > Rollen en voeg een rol Somtoday toe. Geef deze rol de rechten zoals op de afbeelding is aangegeven.

Ga naar de gebruiker Somtoday en geeft deze gebruiker de zojuist ingestelde rol Somtoday.

Als je deze stap overslaat, dan krijg je in Somtoday bij de import van het rooster de melding: Er is iets fout gegaan met de verbinding naar Zermelo. Probeer het later nog eens.

Onderwijssoort instellen

We raden aan om in Zermelo de onderwijssoort per afdeling in te vullen voordat je het exportbestand maakt. Je kunt de kolom LAS-onderwijssoort invullen bij de Exports > Lesgroepen en indelingen.
Tip: in het scherm Onderwijs > Afdelingen kun je de LAS-onderwijssoort bekijken. Deze kolom is standaard verborgen.

Onderwijssoorten van Somtoday overnemen in Zermelo

Ga in het portal van Zermelo naar Koppelingen > Exports. Kies de exportoptie Lesgroepen en indelingen onder het logo van Somtoday.

Selecteer een roosterproject.

Vul onder LAS-onderwijssoort per afdeling de onderwijssoort in zoals deze in Somtoday staat. In Somtoday vind je deze onder Groepen > Stamgroepen, kolom Onderwijssoort.

Stamgroepen exporteren uit Zermelo, importeren in Somtoday

De stamklassen uit Zermelo moet je exporteren naar Somtoday. Dit is een randvoorwaarde als je de roosters automatisch wil synchroniseren in Somtoday. De automatische roosterkoppeling heeft namelijk de ID's van de groepen uit Zermelo nodig, die je in Somtoday importeert met de stamgroepen.

Selecteer in Zermelo de afdelingen waarvoor je de stamgroepen wil exporteren. Klik op de knop Exporteren. Klik op Stamgroepen exporteren en klik op Opslaan om het bestand op te slaan als CSV.

Het bestand heeft de volgende opmaak:
Stamgroepnaam;leerjaar;onderwijssoort;mentor1;mentor2;externID

Je kunt dit bestand met stamklassen importeren in de Somtoday-omgeving onder Beheer > Import & Export > Imports > Stamgroepen. Geef vervolgens de vestiging en het schooljaar aan en voeg het bestand toe.

De Zermelo-key's worden alleen aan de stam/lesgroep gekoppeld als de Zermelokoppeling aan staat.

Controle ingelezen stamgroepen

Je kunt de Zermelo-ID’s inzichtelijk maken in Somtoday. Ga naar Groepen > Stamgroepen en klik op het tandwiel-icoon. Sleep uit de linker kolom het veld Sleutel voor Zermelo naar de rechter kolom. Onderzoek nu of iedere stamgroep een Zermelo-ID heeft.

Clustergroepen exporteren uit Zermelo, importeren in Somtoday

Je moet de cluster lesgroepen importeren in Somtoday vanuit Zermelo. Klassikale lesgroepen zijn in Zermelo niet aanwezig, deze maak je aan in Somtoday. Zie hieronder Klassikale lesgroepen aanmaken

Ga in het portal van Zermelo naar Koppelingen > Exports. Kies de exportoptie Lesgroepen en indelingen onder het logo van Somtoday.

Selecteer het roosterproject.

Selecteer de afdelingen waarvoor je de lesgroepen wil exporteren. Klik op Exporteren. Klik op Lesgroepen exporteren en klik op Opslaan om het bestand op te slaan als CSV.

Het bestand heeft de volgende opmaak:
lesgroepnaam;leerjaar;onderwijssoort;vakafkorting;stamgroep;docent,docent,docent;externID

Je moet dit bestand in Somtoday importeren onder Beheer > Import & Export > Imports > Lesgroepen. Geef de vestiging en het leerjaar aan en voeg het bestand toe.

Met deze import importeer je enkel de clusterlesgroepen vanuit Zermelo. Klassikale lesgroepen krijgen geen Zermelo-ID in Somtoday.

Let op
Als je dit in een lopend schooljaar uitvoert, dan worden de docenten die in Somtoday gekoppeld zijn aan de lesgroep losgekoppeld. In het exportbestand van Zermelo staan namelijk niet de docenten van de lesgroep. Dit heeft een behoorlijke impact voor de docent die op dat moment zijn groepen, studiewijzers en opgegeven huiswerk niet meer ziet.

Maak daarom uit Somtoday een export van de lesgroepen met de kolommen lesgroep, leerjaar, onderwijssoort, vak, docent-afkorting en zorg dat je de docent-afkortingen overneemt in het exportbestand van Zermelo. Pas dan kun je het lesgroepen-bestand inlezen in Somtoday.

En importeer eerst het bestand op de testomgeving van Somtoday, voordat je het in productie uitvoert.

Controle ingelezen clusterlesgroepen

Je kunt de Zermelo-ID’s inzichtelijk maken in Somtoday. Ga naar Groepen > Lesgroepen, filter op type cluster. Klik nu op het tandwiel-icoon. Sleep uit de linker kolom het veld Sleutel voor Zermelo naar de rechter kolom. Onderzoek nu of iedere clusterlesgroep een Zermelo-ID heeft.

Klassikale lesgroepen aanmaken

Maak nu de klassikale lesgroepen aan (als deze er nog niet zijn). Ga naar Groepen > knop Klassikale lesgroep toevoegen. Filter eventueel op een ander leerjaar. Selecteer de vakken waarvoor je de klassikale lesgroepen wil aanmaken en klik daarna op de knop Volgende om de stamgroepen te selecteren en om de klassikale lesgroepen te genereren.

Basisrooster moet aanwezig zijn

Het rooster wordt in een ‘basisrooster’ (niet meer dan een opslagplek in Somtoday) ingelezen.

Maak minimaal één nieuw basisrooster aan voor:

Zermelo 2021-2022

Dit kun je doen via Beheer > Onderwijs > Basisroosters > Basisrooster toevoegen.

Afspraaktypen en presentieregistratie

Maak drie afspraaktypen aan. Dit kun je doen via Beheer > Afwezigheid > Afspraaktypen. Met een afspraaktype bepaal je of standaard presentieregistratie afgedwongen wordt.

Je moet minimaal een apart afspraaktype hebben:

Les: categorie = rooster; activiteit = optioneel
Toets: categorie toets (Dit zorgt ervoor dat in de ELO toetsen herkenbaar zijn); activiteit = optioneel
Activiteit: categorie = rooster; activiteit = optioneel
Meeting: categorie = rooster; activiteit = optioneel

Zet activiteit op optioneel. Voor toetsen en activiteiten moet je zelf bepalen of je de presentieregistratie wil bijhouden. Zo niet, maak dan een apart afspraaktype zonder dit vinkje.

Duidelijke omschrijvingen en herkenning van Zermelo toetsen

Somtoday neemt altijd de omschrijving uit Zermelo over in de Somtoday-afspraakomschrijving. Hiermee kun je de leerling nog beter informeren. Dit geldt voor Zermelo lessen, activiteiten en toetsen.

Somtoday neemt het Zermelo vak over bij de Zermelo activiteiten en toetsen. Dit wordt in de titel van de Somtoday afspraak geplaatst. Zermelo activiteiten en toetsen kunnen een vak bevatten, maar dat hoeft niet. Als in de Zermelo toetsen en activiteiten het vak ontbreekt, wordt in Somtoday geen vak getoond.

Voor de Zermelo toetsen wordt de categorie van de afspraaktype Toets getoond.
Voorbeeld: <lokaal><Somtoday afspraaktype> <Zermelo vak> <docentafkorting>.
De reden om dit afspraaktype in de titel op te nemen is om voor de leerling duidelijk te maken dat er in hun rooster een Zermelo-toets is gepland. Het onderscheid tussen Zermelo lessen en activiteiten ten opzichte van de Zermelo toetsen wordt daarmee duidelijk.

Ons advies

De opdracht aan jou als roostermaker/applicatiebeheerder is om de Somtoday afspraaktypen die hiervoor zijn beschreven aan te houden.

Voorkom dubbele roosters bij de automatische koppeling

Voordat je een rooster via de webservice gaat inlezen, moet je ervoor zorgen dat er in de week dat je dit gaat inlezen geen ander rooster aanwezig is die met een CSV- of txt-bestand is ingelezen. Is dit wel het geval, dan worden de afspraken uit de webservicekoppeling en het importbestand naast elkaar geplaatst in de agenda.

Je kunt een ingelezen rooster verwijderen onder Beheer > Onderwijs > Basisroosters > [basisrooster selecteren] > klik door op afspraken inzien > filter op wat je wil verwijderen en verwijder deze afspraken.

Het rooster inlezen

Nu staat alles klaar om het rooster, toetsen of activiteiten uit Zermelo in te lezen in Somtoday via de roosterwebservicekoppeling.
Ga naar Beheer > Import & Export > Imports > Rooster Zermelo Webservice.

Links staan de gegevens die nodig zijn voor de koppeling met Zermelo en rechts hoe ze in Somtoday moeten worden verwerkt. Na afloop verschijnt er hieronder een log van de import.

Het importeren van toetsen en activiteiten gaat op basis van unieke leerlingen en niet op basis van lesgroepen/klassen.

Bij het importeren van het rooster moet je een keuze maken voor een gegevensset

Groepen
Leerlingen
Groepen en Leerlingen

De keuze hangt er vanaf hoe Zermelo is ingericht. Heb je alleen groepen in Zermelo en is deze indeling gelijk aan Somtoday, dan kies je voor groepen. Heb je alleen leerlingen in Zermelo, dan kies je voor leerlingen (leerlinguniek rooster).

Heb je in Zermelo ‘gastleerlingen’ bij een lesgroep, dan kies je voor groepen en individuele leerlingen.

Door controle op KWT aan te zetten is het mogelijk om leerlingen die in Zermelo het kenmerk [Optioneel] hebben meegekregen te importeren. Hierdoor kunnen deze optionele leerlingen zich via de ELO inschrijven voor de afspraak. In dit geval is er maximaal 1 keuze mogelijk. Indien de leerling niet meer uitgenodigd is maar zich al wel had ingeschreven wordt de inschrijving verwijderd. Hiermee volgen we Zermelo.

Bij afspraaktype Meeting kan er geen participanttype gekozen worden

Logbestand controleren

Controleer altijd de inhoud van het logbestand. Hierin staan belangrijke aanwijzingen, zoals:

Docent niet bekend
Onbekende groep

Automatische roosterkoppeling activeren

Om het importeren van lesroosters uit Zermelo in Somtoday nog makkelijker te maken, kun je het importeren automatisch laten verlopen. In het kort betekent dat, dat de roostermaker in Somtoday een 'geplande taak' kan instellen die Somtoday automatisch ieder kwartier uitvoert.

Je kunt geplande taken instellen voor de periodieke import van roostergegevens vanuit de Zermelo webservice. In principe gebeurt de verwerking elk kwartier. Bij geconstateerde fouten wordt de import-taak gedeactiveerd en stuurt Somtoday een mail om daarover te waarschuwen; de geplande taak wordt dan bevroren tot deze in Somtoday weer wordt aangezet nadat het probleem is opgelost.

Onderaan de import-pagina kun je geplande taken inzien of toevoegen. Als je op Geplande taken toevoegen klikt, worden de gegevens overgenomen uit het (vorige) importscherm. Belangrijk verschil ten opzichte van de import-pagina is dat de datumvelden ontbreken en er een omschrijving-veld en optioneel medewerker-veld bijgekomen zijn.

De overzichtpagina toont een tabel met alle geplande taken (en een aantal details per taak) en biedt per taak de optie om te wijzigen, (de)activeren of verwijderen.

Mogelijke foutmeldingen en oplossingen

Er is een fout opgetreden bij het uitvoeren van achtergrondtaak ZermeloRoosterImportJob:null

De oorzaak kan twee redenen hebben:

Reden 1

Er is een samenvoeging van twee databases uitgevoerd, waarna in Somtoday twee (inactieve) docenten dezelfde afkorting hebben.
Oplossing: filter op alle personeelsleden die ooit in dienst zijn geweest, exporteer deze naar excel en zoek dan in excel uit welke personeels-afkortingen meerdere keren voorkomen. Maak de afkortingen uniek in Somtoday. Daarna is het probleem verholpen.

Reden 2

Deze melding houdt in dat er meerdere lesgroepen aan een Zermelo-ID zijn gekoppeld. Somtoday weet dan niet voor welke lesgroep de afspraak is. Dit kun je als volgt oplossen:
Als eerste moet je alle Zermelo-ID's uit Somtoday weghalen door een export te maken van de stam- en lesgroepen en deze gelijk weer te importeren.

Beheer > Import & Export > Export > Stamgroepen, gevolgd door
Beheer > Import & Export > Import > Stamgroepen
Beheer > Import & Export > Export > Lesgroepen, gevolgd door
Beheer > Import & Export > Import > Lesgroepen

Hierna moet je de juiste Zermelo ID's weer toevoegen aan Somtoday door in Zermelo een export te maken van alle stamgroepen en lesgroepen en deze te importeren in Somtoday.

Beheer > Import & Export > Import > Stamgroepen en Beheer > Import & Export > Import > Lesgroepen

Er is een fout opgetreden bij het uitvoeren van achtergrondtaak ZermeloRoosterImportJob: could not execute statement.

De oorzaak hiervan is dat Somtoday een afspraak zonder titel probeert op te slaan.

De titel wordt gegenereerd door de volgende vier gegevens samen te voegen:

locatie
activiteit
lesgroepen
medewerkers