Let op! Wij gaan dit kalenderjaar de UMservice uitfaseren, omdat deze niet meer voldoet aan de privacystandaarden. Wil je hier meer over weten, lees dan dit artikel.

Inleiding

In Somtoday worden gegevens van leerlingen, medewerkers en verzorgers, alsmede gegevens met betrekking tot de inrichting van het onderwijs van de school vastgelegd. Veel van deze gegevens zijn uitgangspunt voor de inrichting en het beheer van het schoolnetwerk.

Doel

Het doel van deze User Management Service webservice (verder in dit document: umService) is het mogelijk maken om de gegevens die beschikbaar zijn in Somtoday te gebruiken in diverse netwerk-beheertools en in de beheertool gegenereerde accountgegevens terug te schrijven naar Somtoday. Het is goed om je ervan bewust te zijn dat je met deze service rechten verleend aan een derde partij om jouw data uit Somtoday te halen en deze te gebruiken. Het is daarom beter om een minimale set aan rechten weg te geven, in ieder geval nooit te veel. Welke vinkjes je bij Rollen en rechten per instantie moet autoriseren, kun je aan de betreffende koppelpartner vragen.

Uitgangspunten

Deze umService webservice kent tweerichtingsverkeer: er worden gegevens gelezen ten behoeve van de externe beheertool en er worden vanuit de externe beheertool accountgegevens geschreven in Somtoday.
Met deze umService webservice is het mogelijk een belangrijk deel van de geregistreerde gegevens en statussen uit Somtoday te exporteren. Deze webservice kan alleen accountgegevens in Somtoday importeren.

De umService webservice is op de testomgeving continu beschikbaar. Op de productieomgevingen van de scholen is er een tijdslot ingesteld van 7 tot 23 uur waarin de getDataLeerlingen niet beschikbaar is. Dit om extra belasting van de database door deze query’s te voorkomen.

Beschrijving

De umService webservice bestaat uit een aantal requests:

getDataLeerlingen
getDataMedewerkers
getDataVerzorgers
getInrichtingVestigingen
getInrichtingStamgroepen
getInrichtingLesgroepen
getInrichtingOpleidingen
getInrichtingOpleidingVakken
getInrichtingVakken
getDataVrijevelden
getDataDebiteuren

En uit drie 'write' opdrachten waarmee accountgegevens geschreven worden in Somtoday:

writeDataLeerlingen
writeDataVerzorgers
writeDataMedewerkers

Om het gebruik van de umService zo efficiënt mogelijk te laten verlopen, is er een opsplitsing van het type gebruiker gemaakt: getDataLeerlingen, getDataVerzorgers en getDataMedewerkers.

Binnen deze drie requests is een nog verdere verfijning mogelijk door te filteren op basis van de vestigingscode, indien van toepassing.

Toegang

WSDL

Productieomgeving
De umService webservice voor Somtoday in de productieomgeving is te benaderen via:
https://oop.somtoday.nl/services/umService?wsdl

Testomgeving
De umService webservice voor Somtoday in de testomgeving is te benaderen via:
https://oop.test.somtoday.nl/services/umService?wsdl

Rol

Voor het gebruik van deze webservice moet je in Somtoday onder Rollen en rechten een rol creëren met de benodigde rechten op de webservices User Management Service.

Je bent als school zelf verantwoordelijk voor het aan derden doorgeven van gegevens uit Somtoday en daarvoor lever je zelf de benodigde accountgegevens aan bij de derde partij.

De rechten op de umService zijn opgesplitst, zodat je een betreffende partij die je toegang geeft ook gerichte rechten kan toekennen op alleen de onderdelen die voor die partij noodzakelijk zijn.

Het BSN en het ECK-id is via een apart recht te autoriseren.

Account

Maak een personeelslid aan (met als naam de functie van de webservice) en koppel deze aan de eerder aangemaakt rol. Gebruik het account van dit personeelslid om het request naar de webservices te authentiseren.

Brinnummer

Het brinnummer wat je nodig hebt moet een brin4 of brin6 zijn van het default brinnummer van de Somtoday omgeving. Het default brinnummer vindt je via Beheer > Instelling > Algemeen

^ in bovenstaand voorbeeld is 05SS het default brinnummer. Je kan ook 05SS00 of 05SS02 gebruiken waarbij 00 of 02 het vestigingsvolgnummer is. Voor de op te halen dataset maakt het niet uit of je een brin4 of brin6 opgeeft. Het geeft altijd toegang tot alle data in de database.

Beperken van dataset

Als je bij het aangemaakte personeelslid de gekoppelde vestigingen beperkt, dan beperk je daarmee ook de uit te lezen dataset. Als je alle vestigingen koppelt aan het personeelslid, dan kan de webservice ook alle data van alle vestigingen uitlezen.

Dit regel je bij Personeel > kies personeelslid > Aanstelling, beperk of breid het aantal vestigingen uit.

Koppeling met Google / Azure / OIDC

Via de umService kun je de Externe gebruikersnamen inlezen in Somtoday via het veld RemoteIdentifier.

In dit veld vul je de gebruikersnaam in die is vastgelegd bij de Identity Provider van je school. Dit is meestal de gebruikersnaam waarmee de gebruiker inlogt op het portaal van de school.

Dit kun je doen bij de drie typen gebruikers:

Leerlingen
Verzorgers
Medewerkers

In het onderstaande afbeelding zie je het voor medewerkers.

In het veld Type kies je voor AZURE of GOOGLE of OIDC (dit moet in hoofdletters).

Voorbeelden

getDataLeerlingen
Voorbeeld request

Voorbeeld response

GetDataVerzorgers
Voorbeeld request

Voorbeeld response

De opbouw van de verzorgerLeerlingRelaties is verder als volgt:

BugerServiceNummer leerling, Onderwijsnummmer leerling, leerlingnummer, relatie type, Wettelijk, Factuur, Post, extern debiteurnummer.

Als er geen BSN bekend is, gebruik je het onderwijsnummer (deze wordt dan door DUO verstrekt). Wettelijk, factuur en post zijn kenmerken in Somtoday. Een school kan deze vrij gebruiken. Indien aangevinkt geeft dit de waarde ja, anders een nee.
Indien factuur ja is, wordt er een extern debiteurnummer meegegeven.
Indien de verzorger meerdere kinderen als leerlingen heeft, worden deze achter elkaar getoond met een dubbele punt (:) als scheidingsteken.

getDataMedewerkers

Voorbeeld request