○ API calls - User groups
The API calls make it possible to
- check if user groups already exist
- check if users are already in a user group
- add new user groups or delete existing ones
- add users to user groups or remove them from the user groups
Context
aNewSpring has user groups of 3 different types, that are associated with 3 kinds of user roles:
- Learner groups
Learner groups are optional, because you can also link users with the role learner directly to courses. There could be a benefit in using learner groups with the API if an administrator of the learning environment wants to use learner groups when manually creating courses and not having to subscribe each learner. In a full integration, learner groups are usually not necessary, in that case you can use the API to create the courses and link the learners to it directly without a learner group. - Instructor groups
Instructor groups are the only way to link users with the role instructor to courses. - Observer groups
Observer groups are the only way to link users with the role observer to courses.
User groups use a tree structure in which a user group can be linked to a parent user group. If a user group doesn't have a parent, it will be at the top level of the tree structure. If you link a parent user group to a course, all the users in the sub groups of the parent group will also have access to the course with the permissions associated with the user group and role.
A user needs to have the learner, instructor or observer role to be able to be part of a learner, instructor or observer group respectively.
Support articles:
For historical reasons and to continue to support old API integrations, the terminology of the API and the front-end for administrators does not always match completely. In the API:
- A Learner is called a Student.
- An Instructor is called a Teacher.
- An Observer is called a Mentor.
API calls
You can view more information and an example of each API call in the API Documentation by clicking the titles below. However, all links go to the /apidocs page of a demo environment that you cannot use for your own testing purposes.
To test the API calls, you will need to change the first part of the URL to match the right learning environment.
GET requests
GET /groupExists/{groupID}
Use this to check if a specific user group already exists. You will need to use the external ID of the user group.
GET /getUserGroups/{userID}
or GET /getUserGroups?userUID={userUID}
Use this to get all groups that a user is part of. You will need to use the external ID (userID) or UID (userUID) of the user.
GET /groupUserExists/{groupID}/{userID}
or GET /groupUserExists?groupID={groupID}&userUID={userUID}
Use this to check if a specific user is already part of a specific user group. You will need to use the external ID of the user group and the external ID (userID) or UID (userUID) of the user.
GET /getGroupUsers/{groupID}
Use this to get all users of a specific user group. You will need to use the external ID of the user group.
POST requests
POST /addGroup/{groupID}
Use this to add a new user group. You will have to specify which type of user group in the type parameter. The options are:
- Student (to add a learner group)
- Teacher (to add an instructor group)
- Mentor (to add an observer group)
You can use the parent parameter if you want to add this user group inside an existing user group.
The user group will get the external ID that you specify as groupID. If you want to specify a parent user group, you will need to use the external ID of this user group.
POST /updateGroup/{groupID}
Use this to change the name of the user group and/or to move this group into another group by changing its parent user group. You will need to use the external ID of the user group that you want to edit and (optionally) the external ID of the parent user group.
POST /addGroupUsers/{groupID}
Use this to add users to a specific user group.
Make sure that the users that you want to add to the user group have the role that corresponds to the group (learner (student), instructor (teacher) or observer (mentor))
By default, if the user group is a learner or instructor group, learners and instructors will be linked for the courses that the group gives access to. If you set addToTeacherStudents to false, learners and instructors will not be linked to.
You will need to use the external ID of the user group and external IDs of the users, which can be sent as an array in the parameter user, by repeating the same parameter with different values. Instead of the external IDs of the users, you can also use the UIDs of the users as an array in the parameter userUID.
POST /deleteGroupUsers/{groupID}
Use this to remove users from a specific user group. You will need to use the external ID of the user group and external IDs of the users, which can be sent as an array in the parameter user, by repeating the same parameter with different values. Instead of the external IDs of the users, you can also use the UIDs of the users as an array in the parameter userUID.
POST /deleteGroup/{groupID}
Use this to remove a specific user group. By default, you can only remove the group if it has no users, by setting the parameter force to true, it will also remove the group if it still has users. This cannot be undone. You will need to use the external ID of the user group.