Inleiding
Standaard worden gebruikersaccounts vanuit Somtoday aangemaakt, dit verschilt per soort gebruiker (medewerker, leerling en verzorgers). Per medewerker wordt bij het aanmaken van de gebruiker direct een account gegenereerd. Leerling- en verzorgeraccounts kun je vanuit Somtoday initieel of in bulk aanmaken. Op deze wijze wordt er altijd een bevestigingsmail naar de gebruiker gestuurd met hierin de benodigde gegevens, waaronder een random ‘moeilijk’ wachtwoord. Het versturen van de mail en/of random wachtwoord is niet altijd gewenst.
Het aanmaken van een leerling- of verzorgeraccount is ook via de webservices mogelijk. Op deze manier kun je accounts genereren zonder bevestigingsmail en met voorgedefinieerde wachtwoorden. Deze actie wordt éénmalig en handmatig uitgevoerd.
Er zijn ook verschillende externe partijen die met een specifieke koppeling naar Somtoday deze functionaliteit (en meer) aanbieden. Dit geautomatiseerd koppelen is minder foutgevoelig dan de werkwijze vanuit dit artikel. Deze tools kun je ook gebruiken voor password-synchronisaties.
Doel
Via de umService SOAP Webservice, met de juiste gegevens en software, éénmalig gebruikersaccounts aanmaken.
Advies
Wij adviseren om deze handelingen, voordat je deze uitvoert op de productieomgeving, altijd eerst uit te testen in de Somtoday testomgeving. Het uitgeven van gebruikersnamen voor leerlingen en verzorgers is namelijk vanuit de webservice een éénmalige actie.
Benodigdheden
Bij deze methode maken we gebruik van de Somtoday SOAP webservices. Voor toegang tot deze webservices moet in Somtoday een account met de juiste rechten worden aangemaakt. Om deze webservices aan te spreken, maken we gebruik van het programma SoapUI (https://www.soapui.org). We gebruiken hierbij de gratis versie.
Een CSV-bestand is opgebouwd uit leerlingnummer;gewenste gebruikersnaam;wachtwoord;e-mailadres. Met deze gegevens kun je een request opbouwen.
Toegang
Productieomgeving
De umService voor Somtoday in de productieomgeving is te benaderen via de URL
https://oop.somtoday.nl/services/umService?wsdl
Testomgeving
De umService voor Somtoday in de testomgeving is te benaderen via de URL
https://oop.test.somtoday.nl/services/umService?wsdl
Autorisatie en toegang
De school is verantwoordelijk voor het aan derden doorgeven van gegevens uit Somtoday en levert daarvoor zelf de benodigde accountgegevens aan. Creëer in Somtoday onder Rollen en rechten een rol met het recht wijzigen op de gewenste groepen in de Webservices User Management Service. Maak vervolgens een account aan en koppel deze aan de eerder aangemaakt rol. Gebruik dit account om het request naar de webservices te authentiseren.
Opvragen leerlingggegevens
Leerlinggegevens kunnen worden opgevraagd. Dit kan voor voorlopig (bijv. volgend schooljaar) en definitief geplaatste leerlingen.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mijnsom.nl">
<soapenv:Header/>
<soapenv:Body>
<ser:getDataLeerlingen>
<brinNr>11AA</brinNr>
<username>GEBRUIKERSNAAM</username>
<password>HETWACHTWOORD</password>
<schooljaar>2020/2021</schooljaar>
<vestigingAfkorting>DE-AFKORTING</vestigingAfkorting>
<leerlingnummer>137250</leerlingnummer>
</ser:getDataLeerlingen>
</soapenv:Body>
</soapenv:Envelope>
Door het schooljaar aan te passen kan je wisselen tussen het actuele of volgende schooljaar.
Voorwaarde:
- Let er op dat er een '/' moet worden gebruikt voor het schooljaar
- Een leerling moet op een vestiging zijn geplaatst
Aanmaken of wijzigen leerlingaccounts
De standaard methode vanuit Somtoday
In Somtoday kun je een account aanmaken via Leerlingen > [leerling selecteren] > Overig. Per leerling moet je een mailadres en een gebruikersnaam opgeven en met de knop Genereer wachtwoord ook een random wachtwoord genereren.
Via Beheer > Plaatsing > Leerlingen > Accounts aanmaken kun je voor een enkele leerling of voor een bepaalde selectie leerlingen een account aanmaken.
Via de User Management webservice umService
Met behulp van de webservice umService is het mogelijk om de leerlingaccounts voor Somtoday in te lezen.
Met behulp van de request writeDataLeerlingen vanuit de umService kun je dit proces automatiseren.
Op basis van het veld leerlingNummer kun je de overige gegevens invoeren:
- leerlingEmail
- leerlingGebruikersnaam
- leerlingWachtwoord
Bijzonderheden
Als een account eenmaal is aangemaakt, kun je vanuit de webservices de <leerlingGebruikersnaam. niet meer wijzigen. Dit kan alleen vanuit Somtoday.
Het wijzigen van het wachtwoord via <leerlingWachtwoord> is wel mogelijk via de webservices.
Voorbeeld request writeDataLeerlingen
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mijnsom.nl">
<soapenv:Header/>
<soapenv:Body>
<ser:writeDataLeerlingen>
<!--Optional:-->
<brinNr>11AA</brinNr>
<!--Optional:-->
<username>support</username>
<!--Optional:-->
<password>wAchtWoord</password>
<!--Zero or more repetitions:-->
<leerlingen><leerlingEmail>11111@school.nl</leerlingEmail><leerlingGebruikersnaam>11111</leerlingGebruikersnaam><leerlingNummer>11111</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
<leerlingen><leerlingEmail>22222@school.nl</leerlingEmail><leerlingGebruikersnaam>22222</leerlingGebruikersnaam><leerlingNummer>22222</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
<leerlingen><leerlingEmail>33333@school.nl</leerlingEmail><leerlingGebruikersnaam>33333</leerlingGebruikersnaam><leerlingNummer>33333</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
</ser:writeDataLeerlingen>
Aanmaken of wijzigen verzorgeraccounts
De standaard methode vanuit Somtoday
In Somtoday kun je een verzorgeraccount aanmaken via Leerlingen > [leerling selecteren] > Leerling > Overig. Per verzorger moet je een mailadres en een gebruikersnaam opgeven en met de knop Genereer wachtwoord ook een random wachtwoord genereren.
Via Beheer > Plaatsing > Verzorgers > Accounts aanmaken kun je een enkele verzorgeraccount of een bepaalde selectie verzorgersaccounts aanmaken. Een voorwaarde hierbij is dat een verzorger een mailadres heeft in Somtoday.
Via de User Management webservice umService
Met behulp van de webservice umService is het mogelijk om de verzorgeraccounts voor Somtoday in te lezen. Met behulp van de request writeDataVerzorgers vanuit de umService kun je dit proces automatiseren. Op basis van het verzorgerID kun je de overige gegevens invoeren:
- verzorgerEmail
- verzorgerGebruikersnaam
- verzorgerWachtwoord
Bijzonderheden
Als een account eenmaal is aangemaakt, kun je vanuit de webservices de <verzorgerGebruikersnaam> niet meer gewijzigd worden. Dit kan alleen gewijzigd worden vanuit Somtoday. Het wijzigen van het wachtwoord via <verzorgerWachtwoord> is wel mogelijk via de webservices.
Voorbeeld request writeDataVerzorgers
Een voorbeeld van het request writeDataVerzorgers:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mijnsom.nl">
<soapenv:Header/>
<soapenv:Body>
<ser:writeDataVerzorgers>
<!--Optional:-->
<brinNr>11AA</brinNr>
<!--Optional:-->
<username>support</username>
<!--Optional:-->
<password>wAchtWoord</password>
<!--Zero or more repetitions:-->
<verzorgers>
<!--Optional:-->
<verzorgerEmail>verzorger12345@voorbeeld.nl</verzorgerEmail>
<!--Optional:-->
<verzorgerGebruikersnaam>verzorger12345</verzorgerGebruikersnaam>
<!--Optional:-->
<verzorgerID>12345</verzorgerID>
<!--Optional:-->
<verzorgerOpenIdIdentifier></verzorgerOpenIdIdentifier>
<!--Optional:-->
<verzorgerWachtwoord>wachtwoord12345</verzorgerWachtwoord>
<verzorgerWachtwoordEncrypted></verzorgerWachtwoordEncrypted>
</verzorgers>
</ser:writeDataVerzorgers>
</soapenv:Body>
</soapenv:Envelope>
Voor het aanmaken van een account zijn de velden <verzorgerID>, <verzorgerGebruikersnaam>, <verzorgerWachtwoord> verplicht.
Alle andere velden zijn optioneel. Als in Somtoday nog geen mailadres ingevuld staat, adviseren wij om deze ook op te geven.
Voorbeeld writeDataVerzorgers
De response geeft met de onderstaande melding aan dat het request correct is opgebouwd en ontvangen.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:writeDataVerzorgersResponse xmlns:ns2="http://services.mijnsom.nl">
<return>Verzorgers update verwerkt voor: 1 call(s).</return>
</ns2:writeDataVerzorgersResponse>
</soap:Body>
</soap:Envelope>
Voorbeeld bulk request writeDataVerzorgers
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mijnsom.nl">
<soapenv:Header/>
<soapenv:Body>
<ser:writeDataLeerlingen>
<!--Optional:-->
<brinNr>11AA</brinNr>
<!--Optional:-->
<username>support</username>
<!--Optional:-->
<password>wAchtWoord</password>
<!--Zero or more repetitions:-->
<leerlingen><leerlingGebruikersnaam>11111</leerlingGebruikersnaam><leerlingNummer>11111</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
<leerlingen><leerlingGebruikersnaam>22222</leerlingGebruikersnaam><leerlingNummer>22222</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
<leerlingen><leerlingGebruikersnaam>33333</leerlingGebruikersnaam><leerlingNummer>33333</leerlingNummer><leerlingWachtwoord>ww12345</leerlingWachtwoord></leerlingen>
</ser:writeDataLeerlingen>
Wijzigen medewerkeraccounts
De standaard methode vanuit Somtoday
In Somtoday kun je bij een bestaande medewerker de gebruikersnaam, het mailadres en het wachtwoord wijzigen via Personeel > [medewerker selecteren] > Account > Genereer nieuw wachtwoord of Wijzigen.
Via de User Management writeDataMedewerkers
Met behulp van de webservice umService is het mogelijk om medewerkeraccounts voor Somtoday te wijzigen. Met behulp van de request writeDataMedewerkers vanuit de umService kun je dit proces automatiseren. Op basis van het medewerkerNummer kun je de overige gegevens invoeren:
- medewerkerEmail
- medewerkerGebruikersnaam
- medewerkerWachtwoord
Voorbeeld request writeDataMedewerkers
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mijnsom.nl">
<soapenv:Header/>
<soapenv:Body>
<ser:writeDataMedewerkers>
<!--Optional:-->
<brinNr>11AA</brinNr>
<!--Optional:-->
<username>support</username>
<!--Optional:-->
<password>wAchtWoord</password>
<!--Zero or more repetitions:-->
<medewerkers>
<!--Optional:-->
<medewerkerEmail>medewerker12345@voorbeeld.nl</medewerkerEmail>
<!--Optional:-->
<medewerkerGebruikersnaam>medewerker12345</medewerkerGebruikersnaam>
<!--Optional:-->
<medewerkerNummer>12345</medewerkerNummer>
<!--Optional:-->
<medewerkerOpenIdIdentifier></medewerkerOpenIdIdentifier>
<!--Optional:-->
<medewerkerWachtwoord>wachtwoord12345</medewerkerWachtwoord>
<medewerkerWachtwoordEncrypted></medewerkerWachtwoordEncrypted>
</medewerkers>
</ser:writeDataMedewerkers>
</soapenv:Body>
</soapenv:Envelope>
Voor het wijzigen van een account is het veld <medewerkerNummer> verplicht. Alle overige velden zijn optioneel.
Response writeDataMedewerkers
De response geeft met de onderstaande melding aan dat het request correct is opgebouwd en ontvangen.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:writeDataMedewerkersResponse xmlns:ns2="http://services.mijnsom.nl">
<return>Medewerker update verwerkt voor: 1 call(s).</return>
</ns2:writeDataMedewerkersResponse>
</soap:Body>
</soap:Envelope>
Uitbesteden / ondersteuning
Op de uitvoer van bovenstaande handelingen geven wij geen uitgebreidere ondersteuning dan in deze handleiding is beschreven.
Indien gewenst kunnen wij deze handelingen eenmalig voor je uitvoeren, dit op basis van de door jou aangeleverde gegevens.
Deze handelingen vallen niet onder de reguliere servicedesk-werkzaamheden en kunnen wij uitvoeren op basis van nacalculatie.
Voor verdere vragen hierover kun je contact opnemen met de Servicedesk via 0570-768 112 of via het aanmaken van een ticket via het 
in Somtoday.