Somtoday

Inleiding

Somtoday is het leerlingadministratiesysteem waarin leerlingen, docenten en medewerkers hun rooster terugvinden. De koppeling tussen Xedule en Somtoday zorgt ervoor dat het rooster dat in Xedule is gemaakt in Somtoday zichtbaar wordt, en dat de groepen en leerlingen uit Somtoday in Xedule beschikbaar zijn om mee te plannen.

Randvoorwaarden en functionele eisen

Technische randvoorwaarden

• De module Somtoday is voor uw omgeving geactiveerd. Na activering moet de omgeving opnieuw worden geladen voordat de koppeling beschikbaar is.
• Voor de import van groepen en leerlingen gebruikt Xedule daarnaast de REST-koppeling Somtoday Connect (hoofdstuk “Import van groepen en leerlingen”). Xedule authenticeert zich daar met eigen clientgegevens.

Functionele inrichtingseisen in Xedule

• De groepen waaraan gepland wordt, komen uit Somtoday en houden hun Somtoday-sleutel als referentie. Groepen die alleen in Xedule bestaan, zijn in Somtoday niet te herleiden.

Inrichting aan de Somtoday-zijde

• In het privacydashboard van Somtoday is Xedule onder de aangeboden producten toegang gegeven; zonder die toestemming kan de koppeling geen gegevens uitwisselen.
• De referentie van de organisatorische eenheid in Xedule is voor de import bepalend. Die heeft een van twee vormen: een BRIN-nummer van zes tekens (twee cijfers, twee letters en twee cijfers, bijvoorbeeld 12AB00), of de instellingsnaam en de vestigingsnaam zoals ze in Somtoday staan, gescheiden door een liggend streepje (instellingsnaam_vestigingsnaam). Een andere schrijfwijze wordt niet geaccepteerd.

Import van groepen en leerlingen

Naast de roosterexport haalt Xedule groepen en leerlingen uit Somtoday op. Dat gebeurt via de REST-koppeling Somtoday Connect. U start een import handmatig via het tabblad Import, of u laat dit door een geplande taak doen. Bij het handmatig verversen kunt u kiezen hoe de gegevens worden verwerkt: toevoegen, toevoegen en bijwerken, of toevoegen, bijwerken en verwijderen; wat u wegfiltert, wordt niet verwerkt.

De volgorde is van belang: importeer eerst de groepen en daarna de leerlingen. Bestaat een groep nog niet in Xedule, dan kan het lidmaatschap van de leerling niet aan die groep worden gekoppeld.

De vaste volgorde van de import.

Xedule bepaalt zelf of het huidige of het volgende schooljaar wordt opgevraagd, op basis van het schooljaar waarvoor u importeert: vanaf ongeveer twee maanden voor de start van een schooljaar wordt het volgende schooljaar opgevraagd. Andere schooljaren ondersteunt Somtoday niet.

Om bij de gegevens te komen doorloopt Xedule vier stappen. Eerst wordt op adres /connect/instelling de instelling opgezocht op basis van de referentie van de organisatorische eenheid: bij een BRIN-nummer op de eerste vier tekens daarvan, anders op de instellingsnaam voor het liggend streepje. Vervolgens wordt met die instelling een token opgehaald op /oauth2/token. Daarna wordt op /connect/vestiging de vestiging opgezocht, op het volledige BRIN-nummer of op de vestigingsnaam achter het liggend streepje. Ten slotte worden de gegevens per vestiging opgehaald op /connect/vestiging/{vestiging}/stamgroep, /lesgroep en /leerling, in blokken van tweehonderd records tot er geen gegevens meer volgen. De volledige beschrijving van de velden per adres staat in de interactieve documentatie van Somtoday Connect.

Groepen

Klassen worden opgehaald op het adres /connect/vestiging/{vestiging}/stamgroep en lesgroepen op /connect/vestiging/{vestiging}/lesgroep. Beide leveren dezelfde velden; het adres bepaalt het groepstype in Xedule. Een geïmporteerde groep is beschikbaar in het schooljaar waarvoor u importeert.

Leerlingen

Leerlingen worden opgehaald op het adres /connect/vestiging/{vestiging}/leerling. Een geïmporteerde leerling is beschikbaar in het schooljaar waarvoor u importeert.

De drie doorvoerknoppen

Een import schrijft nooit rechtstreeks weg. Nadat de gegevens zijn opgehaald, toont Xedule een vergelijking: links de gegevens zoals het bronsysteem ze aanlevert, rechts dezelfde gegevens zoals ze op dat moment in Xedule staan. Pas wanneer u op een doorvoerknop drukt, verandert er iets in Xedule. Welke knop u kiest, bepaalt hoe ver dat doorvoeren gaat.

Elke import doorloopt dezelfde vier stappen; alleen de laatste stap wijzigt gegevens.

Er zijn drie knoppen. Ze werken in alle importkoppelingen op dezelfde manier en gaan altijd één kant op: van het bronsysteem naar Xedule. Via deze schermen wordt er nooit iets naar het bronsysteem teruggeschreven.

Pictogram	Knop	Wat de knop doet	Wanneer u die kiest
	bijwerken	Werkt alleen de regels bij die zowel in het bronsysteem als in Xedule bestaan en waarvan een of meer waarden verschillen. Er wordt niets toegevoegd en niets verwijderd.	Als u alleen wijzigingen op bestaande gegevens wilt overnemen en bewust nog geen nieuwe objecten in Xedule wilt laten ontstaan.
	toevoegen en bijwerken	Doet hetzelfde als bijwerken en maakt daarnaast de regels aan die alleen in het bronsysteem voorkomen. Er wordt niets verwijderd.	De gebruikelijke keuze voor een reguliere import gedurende het jaar.
	toevoegen, bijwerken en verwijderen	Doet hetzelfde als toevoegen en bijwerken en trekt daarnaast de geldigheid in van de objecten die alleen nog in Xedule bestaan.	Alleen wanneer het bronsysteem voor deze gegevensgroep volledig leidend is en de aanlevering compleet is.

Er is geen knop waarmee u uitsluitend toevoegt: bij elke knop die toevoegt, worden bestaande regels ook bijgewerkt.

Het resultaat van elke knop, per soort verschil tussen beide kanten.

Welke velden worden overgenomen

Bij een bijwerking worden niet alle velden overschreven, maar alleen de velden die daadwerkelijk verschillen; regels die in het geheel niet verschillen worden overgeslagen. Welke velden worden vergeleken, ligt per gegevensgroep vast: dat zijn precies de velden die in de vergelijking naast elkaar worden getoond. Velden die niet in de vergelijking voorkomen, worden door een import dus nooit overschreven.

Wat verwijderen precies doet

Verwijderen is geen harde verwijdering. Xedule trekt de geldigheid van het object in voor het tijdvak waarin u werkt; het object zelf en zijn historie blijven bestaan. In de praktijk betekent dat bijvoorbeeld dat een medewerker voor dat tijdvak uit dienst wordt gezet, een student in dat tijdvak niet meer studeert, een faciliteit in dat tijdvak niet meer geldig is, of dat een relatie tussen twee objecten voor dat tijdvak vervalt. Een groep is de uitzondering: valt de periode van de groep volledig binnen het tijdvak, dan wordt de groep zelf opgeruimd.

• Alleen gegevens die per tijdvak geldig zijn, kunnen op deze manier worden ingetrokken. Gegevenssoorten zonder tijdvak worden door de verwijdervariant ongemoeid gelaten.
• De knop kijkt niet naar de herkomst van een object. Objecten die handmatig in Xedule zijn aangemaakt en die niet in de aanlevering voorkomen, worden dus ook ingetrokken — tenzij de koppeling ze via een vast filter buiten de vergelijking houdt.
• Er wordt niet gecontroleerd of het object elders nog in gebruik is. Een object dat nog in het rooster of de jaarplanning voorkomt, wordt evengoed ingetrokken.

Alleen bij deze variant vraagt Xedule vooraf om een bevestiging. Het doorvoeren zelf gebeurt in één handeling: gaat er iets mis, dan blijven de gegevens in Xedule zoals ze waren.

Hoe een regel links aan een regel rechts wordt gekoppeld

Of een regel als nieuw, als gewijzigd of als alleen in Xedule wordt gezien, hangt af van de manier waarop beide kanten aan elkaar worden gekoppeld. Xedule gebruikt daarvoor in de eerste plaats de referentie uit het bronsysteem die bij het Xedule-object is vastgelegd. Is die niet gevuld, dan valt de vergelijking terug op de natuurlijke sleutel van het object: bijvoorbeeld het personeelsnummer van een medewerker, de code van een student of leeractiviteit, of de combinatie van code, periode en type bij een groep. Hoofdletters spelen daarbij geen rol.

Dit verklaart de twee situaties die het vaakst tot onverwachte uitkomsten leiden. Wijzigt in het bronsysteem de sleutel van een object waarvan in Xedule nog geen referentie is vastgelegd, dan ziet Xedule dat als een nieuw object naast het bestaande. En heeft een handmatig aangemaakt Xedule-object dezelfde sleutel als een aangeleverd object, dan worden beide als één regel behandeld en wordt het handmatige object met de aangeleverde waarden bijgewerkt.

Waarop een knop wordt toegepast

Een knop werkt op alle regels van de gegevensgroep die op dat moment geopend is, en niet op een selectie; er is geen aanvinkmogelijkheid per regel. Wel kan de lijst worden gefilterd op het soort verschil — alles, alleen links, alleen rechts, in beide, of in beide maar ongelijk — en werkt de knop daarna alleen op de regels die het filter overlaat. Wordt de knop op het overzichtstabblad gebruikt, dan geldt de keuze voor alle gegevensgroepen van die import tegelijk.

Dezelfde keuze in een geplande taak

Wordt de import als geplande taak uitgevoerd, dan vervalt de vergelijkingsstap en ligt de keuze vooraf vast. Per gegevensgroep zijn dezelfde drie mogelijkheden in te stellen, aangevuld met de mogelijkheid die gegevensgroep over te slaan. Is er voor een taak niets ingericht, dan geldt de ruimste variant en wordt er dus ook verwijderd. Richt een geplande taak daarom altijd bewust in, en werk in de beginperiode handmatig tot de gegevensstroom stabiel is.

Foutafhandeling en meldingen

Meldingen zijn per import op te vragen in het paneel Resultaten. Meldingen die van Somtoday zelf komen, worden ongewijzigd doorgegeven met het niveau dat Somtoday meegeeft.