○ API calls - Templates en uitvoeringen
Deze API calls maken het mogelijk om:
- gegevens over bestaande templates en uitvoeringen op te halen
- nieuwe uitvoeringen aan te maken of bestaande te updaten
- een externe ID instellen voor een bestaande uitvoering
- rechten voor begeleiders in te stellen
- deelnemers en begeleiders te koppelen
- deelnemersgroepen en begeleiders te koppelen
- uitvoeringen te verwijderen
- templates te kopiëren
Context
In aNewSpring heb je templates die bestaan uit een ontwerp voor het leerpad. Dit ontwerp bestaat uit blokken die alle een eigen set activiteiten hebben. Beheerders kunnen een uitvoering maken van de template. Een template kan meerdere uitvoeringen hebben.
Je kunt deelnemers inschrijven voor een uitvoering en zij kunnen dan de activiteiten doen.
Je kunt ook één begeleidersgroep en één observatorgroep aan de uitvoering koppelen. Deze groepen bevatten (een of meer) gebruikers met de rol van begeleider of observator. Observators kunnen alleen statistieken bekijken. Begeleiders hebben meer rechten.
Bij de meeste types activiteiten, kun je selecteren welke begeleiders de activiteit mogen beoordelen (bijvoorbeeld: open vragen of een inleveropdracht)
Binnen een uitvoering zijn begeleiders aan deelnemers of aan deelnemersgroepen gekoppeld. Op deze manier kunnen begeleiders alleen de gekoppelde deelnemers zien in bijvoorbeeld de statistieken van de cursus.
Supportartikelen:
- De structuur van aNewSpring
- Welke activiteiten kan ik gebruiken in een template?
- Op welke manier kan ik deelnemers inschrijven in een uitvoering?
- Begeleider toevoegen aan een uitvoering
- Uitvoering instellingen - Tab: Begeleiders
- Uitvoering instellingen - Tab: Activiteiten
- Uitvoering instellingen - Tab: Begeleider en deelnemer koppelen
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 uitvoering is een course.
- Een activiteit wordt soms een coursePart genoemd.
- Een deelnemer is een student.
- Een begeleider is een teacher.
- Een observator is een mentor.
- Een subomgeving is een reseller, niet te verwarren met de reseller-rol.
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 /getTemplates
Hiermee kun je een lijst ophalen van alle gepubliceerde templates die een extern ID hebben. Gearchiveerde templates worden niet meegenomen.
GET /getCourses/{templateID}
of GET /getCourses?templateUID={templateUID}
Hiermee kun je alle uitvoeringen van een specifieke template ophalen. Je moet hiervoor de externe ID (templateID) of UID (templateUID) van de template gebruiken.
GET /getCourseStructure/{ID}
of GET /getCourseStructure?UID={UID}
Hiermee kun je de structuur van een specifieke template of uitvoering ophalen. Je moet heirvoor de externe ID (ID) of UID van de template of uitvoering gebruiken.
GET /courseExists/{ID}
of GET /courseExists?UID={UID}
Hiermee kun je nagaan of een specifieke uitvoering al bestaat. Je moet hiervoor de externe ID (ID) of UID van de uitvoering of template gebruiken.
GET /getCourse/{ID}
of GET /getCourse?UID={UID}
Hiermee kun je gegevens ophalen van een specifieke uitvoering. Je moet hiervoor de externe ID (ID) of UID van de uitvoering of template gebruiken.
GET /getStudentSubscriptions/{courseID}
of GET /getStudentSubscriptions?courseUID={courseUID}
Hiermee kun je een lijst ophalen van alle deelnemers die zijn ingeschreven voor een specifieke uitvoering. Je moet hiervoor de externe ID (courseID) of UID (courseUID) van de uitvoering gebruiken.
GET /getStudentTeachers/{userID}/{courseID}
of GET /getStudentTeachers?userUID={userUID}&courseUID={courseUID}
Hiermee kun je een lijst ophalen van alle begeleiders van een specifieke deelnemer van een specifieke uitvoering. Je moet hiervoor de externe ID's (userID/courseID)of UID's (userUID/courseUID) van de gebruiker (deelnemer) en de uitvoering gebruiken.
GET /getStudentGroupTeachers/{courseID}/{groupID}
of GET /getStudentGroupTeachers?courseUID={courseUID}&groupID={groupID}
Hiermee kun je een lijst ophalen van alle begeleiders van een specifieke deelnemersgroep van een specifieke uitvoering. Je moet hiervoor de externe ID of UID van de uitvoering (courseID/courseUID) gebruiken en de externe ID van de groep (groupID).
GET /getTeacherStudents/{userID}/{courseID}
of GET /getTeacherStudents?userUID={userUID}&courseUID={courseUID}
Hiermee kun je een lijst ophalen van alle deelnemers van een specifieke begeleider van een specifieke uitvoering. Je moet hiervoor de externe ID's (userID/courseID) of UID (userUID/courseUID) van de gebruiker (begeleider) en de uitvoering gebruiken.
POST requests
POST /instantiate/{templateID}/{courseID}
of POST /instantiate?templateUID={templateUID}&courseID={courseID}
Hiermee kun je een nieuwe uitvoering aanmaken aan de hand van een specifieke template. Je moet hiervoor de externe ID (templateID) of UID (templateUID) van de template gebruiken en de nieuwe uitvoering krijgt het externe ID dat je aangeeft als courseID.
POST /initializeCourseId/{UID}/{ID}
Hiermee kun je een externe ID instellen voor een uitvoering die nog geen externe ID heeft. Je zult hiervoor de UID van de bestaande uitvoering moeten gebruiken en de nieuwe unieke externe ID die je wilt toekennen.
POST /updateCourse/{ID}
of POST /updateCourse?UID={UID}
Hiermee kun je eigenschappen van een bestaande uitvoering wijzigen. Gebruik deze API call ook als je een begeleiders- en/of observatorgroep wilt koppelen.
Je moet hiervoor de externe ID (ID) of UID van de uitvoering of template gebruiken en optioneel ook de externe ID('s) van de begeleider en/of observatorgroep.
POST /setCoursePermissions/{courseID}/{teacherID}
of POST /setCoursePermissions?courseUID={courseUID}&teacherUID={teacherUID}
Hiermee kun je begeleidersrechten toekennen (of ontnemen) voor een specifieke uitvoering. Standaard staan alle rechten ingeschakeld. Als dat het geval is, zou je de parameter unset met als waarde true kunnen meesturen om de rechten die een begeleider niet moet hebben te ontnemen.
Deze waardes zijn toegestaan in de permission parameter:
- CourseSettings: Begeleider kan de instellingen van de uitvoering aanpassen.
- EditCalendar: Begeleider kan agendapunten toevoegen.
- EditTeacherStudents: Begeleider kan een specifieke groep deelnemers aanmaken en begeleiden.
- ReceiveStudentMessage: Begeleider kan berichten ontvangen van en versturen aan deelnemers.
- ReceiveCoursePartNotification: Begeleider ontvangt statistiekenmail, een kopie van cursusnotificaties aan deelnemers en notificaties van discussies en afgeronde geselecteerde activiteiten.
- AssessorPossible: Begeleider kan open vragen, inleveropdrachten en 360° feedback activiteiten beoordelen. Je kunt verder specificeren welke activiteiten begeleiders mogen beoordelen met POST /setActivityPermissions.
Je kunt de rechten meesturen als array door de parameter meerdere keren te herhalen met verschillende waardes in één API call.
Je moet hiervoor de externe ID's (courseID/teacherID) of UID's (courseUID/teacherUID) van de uitvoering en de gebruiker (deelnemer) gebruiken.
POST /setCoursePermissionsForTeacherGroup/{groupID}
of POST /setCoursePermissionsForTeacherGroup?groupID={groupID}
Dit doet hetzelfde als POST /setCoursePermissions, maar voor elke begeleider van een specifieke begeleidersgroep voor alle relevante uitvoeringen in één keer.
POST /setActivityPermissions/{courseID}/{activityID}/{teacherID}
of POST /setActivityPermissions?courseUID={courseUID}&activityID={activityID}&teacherUID={teacherUID}
Hiermee kun je aanzetten (of uitzetten) dat een begeleider een specifieke activiteit mag beoordelen. Dit werkt alleen als de begeleider ook de coursePermission AssessorPossible heeft, die je kunt instellen met POST /setCoursePermissions.
Als permission parameter moet je hiervoor de waarde Assess meesturen.
Je moet hiervoor de externe ID's (courseID/teacherID) of UID's (courseUID/teacherUID) van de uitvoering en de gebruiker (begeleider) en de externe ID (activityID) van de activiteit gebruiken.
POST /addTeacherStudents/{courseID}/{teacherID}
of POST /addTeacherStudents?courseUID={courseUID}&teacherUID={teacherUID}
Hiermee kun je deelnemers aan een specifieke begeleider koppelen. De begeleider kan alleen deelnemers zien waar die aan gelinkt is. Je moet hiervoor de externe ID's (courseID/teacherID) of UID's (courseUID/teacherUID) van de uitvoering en de gebruiker (begeleider) gebruiken. Alle gebruikers (deelnemers) die je aan de begeleider wilt koppelen, kun je versturen als array in de parameter student met externe ID's of in de parameter studentUID met UID's, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call.
POST /addStudentGroupTeachers/{courseID}/{studentGroupID}
of POST /addStudentGroupTeachers?courseUID={courseUID}&studentGroupID={studentGroupID}
Hiermee kun je begeleiders aan een specifieke deelnemersgroep koppelen.
De begeleider kan alleen deelnemers zien waar die aan gelinkt is via een groep. Je moet hiervoor de externe ID of UID van de uitvoering (courseID/courseUID) gebruiken en de externe ID van de groep (studentGroupID). Alle gebruikers (begeleiders) die je aan de deelnemersgroep wilt koppelen, kun je versturen als array in de parameter teacherID met externe ID's of in de parameter teacherUID met UID's, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call.
POST /setTeacherStudents/{teacherID}
of POST /setTeacherStudents?teacherUID={teacherUID}
Hiermee kun je instellen welke deelnemers aan een specifieke begeleider moeten zijn gekoppeld. De begeleider kan alleen deelnemers zien waar die aan gelinkt is. Je moet hiervoor de externe ID (teacherID) of UID (teacherUID) van de begeleider gebruiken. Alle gebruikers (deelnemers) die je aan de begeleider wilt koppelen, kun je versturen als array in de parameter studentID met externe ID's of in de parameter studentUID met UID's, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call. Op basis van deze call, zullen deelnemers automatisch aan de begeleider worden gekoppeld voor alle uitvoeringen die van toepassing zijn. Een uitvoering is van toepassing als de deelnemers eraan zijn gekoppeld en als de begeleider is gekoppeld via een begeleidersgroep. Deelnemers die niet worden meegestuurd in deze call, worden ontkoppeld van de begeleider.
POST /setStudentGroupTeachers/{studentGroupID}
of POST /setStudentGroupTeachers?studentGroupID={studentGroupID}
Hiermee kun je instellen welke begeleiders aan een specifieke deelnemersgroep moeten zijn gekoppeld. De begeleider kan alleen deelnemers zien waar die aan gelinkt is via een groep. Je moet hiervoor de externe ID van de groep (studentGroupID) gebruiken. Alle gebruikers (begeleiders) die je aan de deelnemersgroep wilt koppelen, kun je versturen als array in de parameter teacherID met externe ID's of in de parameter teacherUID met UID's, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call. Op basis van deze call, zullen begeleiders automatisch aan de deelnemersgroep worden gekoppeld voor alle uitvoeringen die van toepassing zijn. Een uitvoering is van toepassing als de deelnemersgroep eraan is gekoppeld en als de begeleider is gekoppeld via een begeleidersgroep. Begeleiders die niet worden meegestuurd in deze call, worden ontkoppeld.
POST /deleteTeacherStudents/{courseID}/{teacherID}
of POST /deleteTeacherStudents?courseUID={courseUID}&teacherUID={teacherUID}
Dit werkt hetzelfde als /addTeacherStudents/, maar zal de deelnemers ontkoppelen van de specifieke begeleider.
POST /deleteStudentGroupTeachers/{courseID}/{studentGroupID}
of POST /deleteStudentGroupTeachers?courseUID={courseUID}&studentGroupID={studentGroupID}
Dit werkt hetzelfde als /addStudentGroupTeachers/, maar zal de begeleiders ontkoppelen van de specifieke deelnemersgroep.
POST /deleteCourse/{courseID}
of POST /deleteCourse?courseUID={courseUID}
Hiermee kun je de uitvoering verwijderen. Dit is alleen mogelijk als er geen actieve deelnemers meer zijn, behalve als je de parameter force met als waarde true meestuurt. Dit kan niet ongedaan worden gemaakt. Je moet hiervoor de externe ID (courseID) of UID (courseUID) van de uitvoering gebruiken.
POST /deleteTemplate/{templateID}
of POST /deleteTemplate?templateUID={templateUID}
Hiermee kun je de template verwijderen. Dit is alleen mogelijk als de template geen uitvoeringen heeft en niet aan bundels is gekoppeld. De template moet ook niet gepubliceerd zijn, behalve als je de parameter force met als waarde true meestuurt. Dit kan niet ongedaan worden gemaakt. Je moet hiervoor de externe ID (templateID) of UID (templateUID) van de template gebruiken.
POST /copyTemplate/{templateID}/{ID}
of POST /copyTemplate?templateUID={templateUID}&ID={ID}
Hiermee kun je een kopie maken van de template.
Templates zijn gekoppeld aan een of meer contentbibliotheken. Meerdere templates kunnen dezelfde contentbibliotheek gebruiken. Je kunt aangeven of de nieuwe template dezelfde contentbibliotheken moet blijven gebruiken of dat je hier ook een kopie van wilt maken door copyContent als true of false in te stellen.
Geef publish als waarde true mee om ook uitvoeringen aan te kunnen maken aan de hand van de gekopieerde template. Als je publish als waarde false meegeeft, zal een gebruiker met de rol van ontwerper de template handmatig moeten publiceren na het doen van eventuele aanpassingen.
Je moet hiervoor de externe ID (templateID) of UID (templateUID) van de template gebruiken en je moet ook aangeven wat de externe ID van de kopie moet worden in de parameter ID.