Deze API calls maken het mogelijk om:

  • na te gaan of een gebruikersgroep al bestaat
  • na te gaan of gebruikers al in een gebruikersgroep zitten
  • nieuwe gebruikersgroepen toe te voegen of bestaande te verwijderen
  • gebruikers aan gebruikersgroepen toe te voegen of ze eruit te halen

Context

aNewSpring heeft 3 soorten gebruikersgroepen, die een verband hebben met 3 verschillende rollen:

  • Deelnemersgroepen
    Deelnemersgroepen zijn optioneel, omdat je gebruikers met de rol deelnemer ook direct aan uitvoeringen kunt koppelen. Het beheren van gebruikersgroepen door middel van de API kan voordelen hebben als een beheerder in de leeromgeving handmatig uitvoeringen wil aanmaken voor bestaande deelnemersgroepen in plaats van deelnemers een voor een in te schrijven. In een volledige integratie zijn deelnemersgroepen gewoonlijk niet nodig, omdat je via de API uitvoeringen kunt aanmaken en deelnemers daaraan kunt koppelen zonder deelnemersgroep.
  • Begeleidersgroepen
    Begeleidersgroepen zijn de enige manier om gebruikers met de rol begeleider aan uitvoeringen te koppelen.
  • Mentorgroepen
    Mentorgroepen zijn de enige manier om gebruikers met de rol mentor aan uitvoeringen te koppelen.

Gebruikersgroepen bestaan in een boomstructuur waarin een gebruikersgroep gekoppeld kan worden aan een parent groep. Als een gebruikersgroep geen parent heeft, dan bestaat die groep op het hoogste niveau in de boomstructuur. Als je een parent-groep aan een uitvoering koppelt, krijgen alle gebruikers in subgroepen van de parent-groep ook toegang tot de uitvoering met de rechten die bij de gebruikersgroep en rol horen.

Een gebruiker heeft de rol deelnemer, begeleider of mentor nodig om respectievelijk aan een deelnemersgroep, begeleidersgroep of mentorgroep te kunnen worden toegevoegd.

Supportartikelen:

  • Deelnemersgroepen aanmaken
  • Begeleiders- en mentorgroepen aanmaken

Om historische redenen en om oude API-integraties te blijven ondersteunen, komt de terminologie van de API en de front-end voor beheerders niet altijd helemaal overeen. Daarnaast is de terminologie van de API gebaseerd op de Engelstalige versie van aNewSpring.

  • Een deelnemer is een student.
  • Een begeleider is een teacher.

API calls

Je kunt meer informatie vinden over elke API call in de API Documentation door op de titels hieronder te klikken. Alle links verwijzen echter naar de /apidocs pagina van een demo-omgeving die je niet kunt gebruiken om zelf te testen.
Om de API calls te testen, zul je het eerste deel van de URL moeten aanpassen naar de URL van je eigen leeromgeving.

GET requests

GET /groupExists/{groupID}
Hiermee kun je nagaan of een specifieke gebruikersgroep al bestaat. Je moet hiervoor de externe ID van de gebruikersgroep gebruiken.

GET /groupUserExists/{groupID}/{userID}
Hiermee kun je nagaan of een specifiek gebruiker al in een specifieke gebruikersgroep zit. Je moet hiervoor de externe ID's van de gebruikersgroep en de gebruiker gebruiken.

GET /getGroupUsers/{groupID}
Hiermee kun je alle gebruikers van een specifieke gebruikersgroep ophalen. Je moet hiervoor de externe ID van de gebruikersgroep gebruiken.

POST requests

POST /addGroup/{groupID}
Hiermee kun je een nieuwe gebruikersgroep toevoegen. Je zult moeten aangeven om wat voor type gebruikersgroep het gaat d.m.v. de parameter type. De opties zijn:

  • Student (om een deelnemersgroep toe te voegen)
  • Teacher (om een begeleidersgroep toe te voegen)
  • Mentor (om een mentorgroep toe te voegen.)

Je kunt de parameter parent gebruiken als je de groep binnen een bestaande groep wilt plaatsen.
De gebruikersgroep krijgt het externe ID dat je aangeeft als groupID. Als je een parent-groep wilt aangeven, moet je daarvoor de externe ID van de gebruikersgroep gebruiken.

POST /updateGroup/{groupID}
Hiermee kun je de naam van de gebruikersgroep aanpassen en/of deze groep verplaatsen door de parent-groep te veranderen. Je moet hiervoor de externe ID van de gebruikersgroep die je wilt aanpassen gebruiken en (optioneel) de externe ID van de parent-groep.

POST /addGroupUsers/{groupID}
Hiermee kun je gebruikers aan een specifieke gebruikersgroep toevoegen.

Let op dat gebruikers de rol moeten hebben die bij de gebruikersgroep hoort als je ze wilt kunnen toevoegen.

Bij deelnemers- of begeleidersgroepen worden deelnemers en begeleiders standaard aan elkaar gekoppeld voor de uitvoeringen waar de groep toegang toe geeft. Als je addToTeacherStudents de waarde false meegeeft, zullen deelnemers en begeleiders niet aan elkaar worden gekoppeld.

Je moet hiervoor de externe ID van de gebruikersgroep en de externe ID's van de gebruikers gebruiken. De externe ID's van de gebruikers kun je als array meegeven in de parameter user, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call.

POST /deleteGroupUsers/{groupID}
Hiermee kun je gebruikers uit een specifieke gebruikersgroep halen.
Je moet hiervoor de externe ID van de gebruikersgroep en de externe ID' s van de gebruikers gebruiken. De externe ID's van de gebruikers kun je als array meegeven in de parameter user, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call.

POST /deleteGroup/{groupID}
Hiermee kun je een specifieke gebruikersgroep verwijderen. Standaard werkt dit alleen als de groep geen gebruikers (meer) heeft. Als je de parameter force de waarde true meegeeft, zal de groep ook worden verwijderd als die nog wel gebruikers heeft. Dit kan niet ongedaan worden gemaakt. Je moet hiervoor de externe ID van de gebruikersgroep gebruiken.