○ API calls - Courses
These API calls make it possible to:
- get information about existing templates and courses
- create new courses or update existing courses
- set an external ID for an existing course
- set permissions for instructors
- link learners and instructors
- link learner groups and instructors
- delete courses
- copy templates
Context
aNewSpring has templates that contain a design for the learning journey. This design consists of blocks that all have their own set of activities. Administrators can make an instance of the template by creating a course. A template can have multiple courses.
You can subscribe learners to a course, they can then do the activities.
You can also link one instructor group and one observer group to the course. These groups contain (one or more) users with the instructor or observer role. Observers can only view statistics. Instructors can have multiple permissions.
For most activity types, you can select which instructor is allowed to assess this activity (for example: open questions or a hand-in assignment)
There can also be a link between instructors and learners or learner groups in the context of a course. This way, the instructor can only see the linked learners e.g. in the statistics of the course.
Support articles:
- The platform structure
- Which activities can I use in a template?
- Subscribe learners
- Add an instructor to a course
- Course settings - Tab: Instructors
- Course settings - Tab: Activities
- Course settings - Tab: Managing instructor learner
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.
- A Learner group is called a StudentGroup
- An Instructor is called a Teacher.
- An Observer is called a Mentor.
- An Activity is sometimes called a CoursePart.
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 /getTemplates
Use this to get all published templates that have an external ID. Archived templates are excluded.
GET /getCourses/{templateID}
or GET /getCourses?templateUID={templateUID}
Use this to get all courses of a specific template. You will need to use the external ID (templateID) or UID (templateUID) of the template.
GET /getCourseStructure/{ID}
or GET /getCourseStructure?UID={UID}
Use this to view the structure of a specific template or course. You will need to use the external ID (ID) or UID of the template or course.
GET /courseExists/{ID}
or GET /courseExists?UID={UID}
Use this to check if a specific course already exists. You will need to use the external ID (ID) or UID of the template or course.
GET /getCourse/{ID}
or GET /getCourse?UID={UID}
Use this to get the details of a specific course. You will need to use the external ID (ID) or UID of the template or course.
GET /getStudentSubscriptions/{courseID}
or GET /getStudentSubscriptions?courseUID={courseUID}
Use this to get all learners that are subscribed to a specific course. You will need to use the external ID (courseID) or UID (courseUID) of the course.
GET /getStudentTeachers/{userID}/{courseID}
or GET /getStudentTeachers?userUID={userUID}&courseUID={courseUID}
Use this to get all instructors of a specific learner in a specific course. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user (learner) and the course.
GET /getStudentGroupTeachers/{courseID}/{groupID}
or GET /getStudentGroupTeachers?courseUID={courseUID}&groupID={groupID}
Use this to get all instructors of a specific learner group in a specific course. You will need to use the external ID or UID of the course (courseID/courseUID) and the external ID of the group (groupID).
GET /getTeacherStudents/{userID}/{courseID}
or GET /getTeacherStudents?userUID={userUID}&courseUID={courseUID}
Use this to get all learners of a specific instructor in a specific course. You will need to use the external IDs (userID/courseID) or UIDs (userUID/courseUID) of the user (instructor) and the course.
POST requests
POST /instantiate/{templateID}/{courseID}
or POST /instantiate?templateUID={templateUID}&courseID={courseID}
Use this to create a new course based on a specific template. You will need to use the external ID (templateID) or UID (templateUID) of the template and the new course will get the external ID that you specify as courseID.
POST /initializeCourseId/{UID}/{ID}
Use this to set an external ID for an existing course that does not have an external ID yet. You will need to use the UID of the existing course and a new unique external ID for this course.
POST /updateCourse/{ID}
or POST /updateCourse?UID={UID}
Use this to change the properties of an existing course. Also use this API call if you want to link an instructor and/or observer group.
You will need to use the external ID (ID) or UID of the template or course and optionally the external ID(s) of the instructor and/or observer group.
POST /setCoursePermissions/{courseID}/{teacherID}
or POST /setCoursePermissions?courseUID={courseUID}&teacherUID={teacherUID}
Use this to set (or unset) the instructor rights for this course. By default, all permissions are enabled. If that's the case, you should send the parameter unset with value true to disable the permissions that the instructor shouldn't have.
The values that you can place in the permission parameter are:
- CourseSettings: Instructor can edit the settings of the course.
- EditCalendar: Instructor can add calendar items.
- EditTeacherStudents: Instructor can create and instruct a specific group of learners.
- ReceiveStudentMessage: Instructor can send and receive messages from learners.
- ReceiveCoursePartNotification: Instructor receives statistics mail, a copy of the course notifications for learners and notifications from discussions and completed selected activities.
- AssessorPossible: Instructor can assess open questions, hand-in assignments and 360° feedback. You can further specify which activities instructors are allowed to assess with POST /setActivityPermissions.
You can send the permissions in as an array by repeating the same parameter with different values.
You will need to use the external IDs (courseID/teacherID) or UIDs (courseUID/teacherUID) of the course and the user (instructor).
POST /setCoursePermissionsForTeacherGroup/{groupID}
or POST /setCoursePermissionsForTeacherGroup?groupID={groupID}
This does the same as POST /setCoursePermissions, but for every instructor of a specific instructor group, for all relevant courses at once.
POST /setActivityPermissions/{courseID}/{activityID}/{teacherID}
or POST /setActivityPermissions?courseUID={courseUID}&activityID={activityID}&teacherUID={teacherUID}
Use this to set (or unset) if an instructor can assess a specific activity. This only works if an instructor also has the coursePermission AssessorPossible which you can set with POST /setCoursePermissions.
You will need to send the value Assess in the permission parameter.
You will need to use the external IDs (courseID/teacherID) or UIDs (courseUID/teacherUID) of the course and the user (instructor) and the external ID (activityID) of the activity.
POST /addTeacherStudents/{courseID}/{teacherID}
or POST /addTeacherStudents?courseUID={courseUID}&teacherUID={teacherUID}
Use this to link learners to a specific instructor. The instructor can only see learners that they are linked to. You will need to use the external IDs (courseID/teacherID) or UIDs (courseUID/teacherUID) of the course and the user (instructor). All users (learners) that you want to link to the instructor can be sent as an array in the parameter student with external IDs or as an array in the parameter studentUID with UIDs, by repeating the same parameter with different values.
POST /addStudentGroupTeachers/{courseID}/{studentGroupID}
or POST /addStudentGroupTeachers?courseUID={courseUID}&studentGroupID={studentGroupID}
Use this to link instructors to a specific learner group. The instructor can only see learners that they are linked to via a group. You will need to use the external ID or UID of the course (courseID/courseUID) and the external ID of the group (studentGroupID). All users (instructors) that you want to link to the learner group can be sent as an array in the parameter teacherID with external IDs or as an array in the parameter teacherUID with UIDs, by repeating the same parameter with different values.
POST /setTeacherStudents/{teacherID}
or POST /setTeacherStudents?teacherUID={teacherUID}
Use this to link learners to a specific instructor. The instructor can only see learners that they are linked to. You will need to use the external ID (teacherID) or UID (teacherUID) of the instructor. All users (learners) that you want to link to the instructor can be sent as an array in the parameter studentID with external IDs or as an array in the parameter studentUID with UIDs, by repeating the same parameter with different values. Based on this call, learners will automatically be linked to the instructor for all applicable courses. A course is applicable if the learners are linked to it and the instructor is linked via an instructor group. Learners that are excluded from this call will be unlinked from the instructor.
POST /setStudentGroupTeachers/{studentGroupID}
or POST /setStudentGroupTeachers?studentGroupID={studentGroupID}
Use this to link instructors to a specific learner group. The instructor can only see learners that they are linked to via a group. You will need to use the external ID of the group (studentGroupID). All users (instructors) that you want to link to the learner group can be sent as an array in the parameter teacherID with external IDs or as an array in the parameter teacherUID with UIDs, by repeating the same parameter with different values. Based on this call, instructors will automatically be linked to the learner group for all applicable courses. A course is applicable if the learner group is linked to it and the instructor is linked via an instructor group. Instructors that are excluded from this call will be unlinked.
POST /deleteTeacherStudents/{courseID}/{teacherID}
or POST /deleteTeacherStudents?courseUID={courseUID}&teacherUID={teacherUID}
This works the same as /addTeacherStudents/, but will instead unlink the learners from the specific instructor.
POST /deleteStudentGroupTeachers/{courseID}/{studentGroupID}
or POST /deleteStudentGroupTeachers?courseUID={courseUID}&studentGroupID={studentGroupID}
This works the same as /addStudentGroupTeachers/, but will instead unlink the instructors from the specific learner group.
POST /deleteCourse/{courseID}
or POST /deleteCourse?courseUID={courseUID}
Use this to remove the course. You can only do this if there are no active learners any more, unless you add the parameter force with value true. This cannot be undone. You will need to use the external ID (courseID) or UID (courseUID) of the course.
POST /deleteTemplate/{templateID}
or POST /deleteTemplate?templateUID={templateUID}
Use this to remove the template. You can only do this if the template has no courses and is not linked to any bundles. The template also needs to be unpublished, unless you add the parameter force with value true. This cannot be undone. You will need to use the external ID (templateID) or UID (templateUID) of the template.
POST /copyTemplate/{templateID}/{ID}
or POST /copyTemplate?templateUID={templateUID}&ID={ID}
Use this to create a copy of a template.
Templates are linked to one or more content libraries. Multiple templates can share the same content libraries. You can specify if the new template needs to use the same content libraries or if you also want to copy these by setting copyContent to true or false.
Set publish to true if you want to be able to instantiate new courses from the copied template. If you set publish to false, a user with the role designer will need to publish the template manually after finishing to make changes to it.
You will need to use the external ID (templateID) or UID (templateUID) of the template and you also need to specify the new external ID for the copy in the parameter ID.