○ API calls - Inschrijvingen
Deze API calls maken het mogelijk om:
- na te gaan of een deelnemer is ingeschreven voor een uitvoering
- na te gaan voor welke uitvoeringen een deelnemer is ingeschreven
- resultaten van uitvoeringen op te halen, inclusief de scores op activiteiten (maar niet de gegeven antwoorden)
- deelnemers in te schrijven op een uitvoering
- deelnemers uit te schrijven van een uitvoering
Context
Gebruikers met de rol deelnemer kunnen een inschrijving hebben voor een uitvoering.
Een inschrijving kan zijn gekoppeld aan een subomgeving. Standaard is dit de subomgeving die hoort bij het domein in de URL die je gebruikt om de API aan te roepen.
Een inschrijving heeft een startdatum en verloopdatum.
De deelnemer kan de cursus niet zien voor de startdatum. Na de verloopdatum kan de deelnemer alleen de statistieken nog bekijken, maar geen activiteiten meer doen.
Een deelnemer die is ingeschreven voor een uitvoering, kan zijn gekoppeld aan begeleiders. Begeleiders kunnen alleen de deelnemers zien waaraan ze gekoppeld zijn.
Uitvoeringen bestaan uit activiteiten en een voorbeeld van zo'n activiteit is de externe activiteit. Andere soorten activiteiten krijgen scores doordat ze automatisch worden berekend of doordat een begeleider ze invoert. Bij externe activiteiten kun je een score registreren door middel van de API.
Supportartikelen:
- Op welke manier kan ik deelnemers inschrijven in een uitvoering?
- De structuur van aNewSpring
- Subomgevingen
- Uitvoering verlengen voor de deelnemer
- Uitvoering instellingen - Tab: Begeleider en deelnemer koppelen
- Welke activiteiten kan ik gebruiken in een template?
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 inschrijving is een subscription.
- Een deelnemer is een student.
- Een begeleider is een teacher.
- Een uitvoering is een course.
- Een activiteit is een part of coursePart.
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 /isSubscribed/{userID}/{courseID}
of GET /isSubscribed?userUID={userUID}&courseUID={courseUID}
Hiermee kun je kijken of een gebruiker (deelnemer) een inschrijving heeft voor een specifieke uitvoering. Je moet hiervoor de externe ID's (userID/courseID) of UID's (userUID/courseUID) van de gebruiker (deelnemer) en uitvoering gebruiken.
GET /getSubscriptions/{userID}
of GET /getSubscriptions?userUID={userUID}
Hiermee kun je alle inschrijvingen van een specifieke gebruiker (deelnemer) ophalen. Dit bevat ook informatie over de inschrijving.
Voorbeeld van JSON output:
{ "courses": [ { "active": true, "efficiency": 0.5, "expired": false, "finished": false, "id": "VOORBEELD-00001", "knowledgeIntake": 0.7, "name": "Voorbeeldcursus", "objectivesProgress": 0.625, "progress": "1/1", "reseller": "SUBOMG-001", "startDate": "2019-03-27", "startDateTime": "2019-03-27T14:23:11Z", "subscribeDate": "2019-03-27", "subscribeDateTime": "2019-03-27T11:08:44Z", "uid": "a62b0793-7682-11eb-b67e-06575dd7e8c5" } ] }
De betekenis:
- active: Actief. Deze staat standaard op false wanneer de deelnemer is ingeschreven. Op het moment dat de deelnemer met de cursus begint, komt deze op true te staan.
- efficiency: Efficiëntie. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. Dit heeft te maken met het aantal pogingen op MemoTrainbare vragen.
- expired: Verlopen. Deze heeft als waarde true als de inschrijving is verlopen.
- finished: Beëindigd. Deze heeft als waarde true als de inschrijving is verlopen of als de deelnemer handmatig is uitgeschreven voor de uitvoering.
- id: Dit is de externe ID van de uitvoering.
- knowledgeIntake: Kennisopname. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. De kennisopname is de voortgang van een deelnemer op het opslaan van alle MemoTrainbare vragen in het langetermijngeheugen.
- name: Naam. Dit is de naam van de uitvoering.
- objectivesProgress: Leerdoel voortgang. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. Dit is de voortgang van de deelnemer op de leerdoelen van de cursus (niet elke cursus heeft leerdoelen).
- progress: Voortgang. Bijv. 11/16. Dit betekent dat 11 van de 16 beschikbare activiteiten zijn afgerond. Activiteiten die niet beschikbaar zijn vanwege condities, worden niet meegerekend.
- reseller: Subomgeving. Dit is de externe ID van de subomgeving waar de uitvoering aan is gekoppeld. Deze is leeg als een subomgeving geen extern ID heeft.
- startDate: Startdatum. Dit is de startdatum van de inschrijving, de deelnemer kan de cursus niet voor deze datum zien. Dit is de startdatum op die de deelnemer de uitvoering is gestart, en niet de startdatum die in de houdbaarheidsinstellingen van de uitvoering kan worden ingesteld.
- startDateTime: Hetzelfde als startDate, inclusief de tijd in UTC.
- subscribeDate: Inschrijfdatum. Dit is de datum waarop de deelnemer was ingeschreven voor de cursus.
- subscribeDateTime: Hetzelfde als subscribeDate, inclusief de tijd in UTC.
- uid: De uid is een uniek ID dat automatisch wordt gegenereerd.
Je moet hiervoor de externe ID (userID) of UID (userUID) van de gebruiker (deelnemer) gebruiken.
Voor meer statistieken en resultaten van een inschrijving, is het vaak beter om webhooks te gebruiken, omdat deze resultaten direct naar je server worden gestuurd wanneer het beschikbaar is en je dus niet steeds API calls hoeft te doen voor alle gebruikers en uitvoeringen. Als je wel een reden hebt om hier de API voor te gebruiken, kan dat door middel van /getResults zoals hieronder beschreven.
GET /getResults/{userID}
of GET /getResults?userUID={userUID}
Hiermee kun je de resultaten ophalen van alle inschrijvingen van een specifieke gebruiker. Je moet hiervoor de externe ID (userID) of UID (userUID) van de gebruiker (deelnemer) gebruiken.
GET /getResults/{userID}/{courseID}
of GET /getResults?userUID={userUID}&courseUID={courseUID}
Hiermee kun je de resultaten van een specifieke inschrijving van een specifieke gebruiker ophalen. Je moet hiervoor de externe ID's (userID/courseID) of UID (userUID/courseUID) van de gebruiker en uitvoering gebruiken.
Voorbeeld van JSON output:
{ "active": true, "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "efficiency": 0.5, "expired": false, "finished": false, "grade": "67%", "gradeDate": "2020-02-13", "gradeDateTime": "2020-02-13T16:23:55Z", "id": "VOORBEELD-0001", "knowledgeIntake": 0.4, "lastTrainingCompletedDate": "2020-02-12", "lastTrainingCompletedDateTime": "2020-02-12T08:05:23Z", "name": "Voorbeeldcursus", "objectives": [ { "knowledgeIntake": 0.5, "name": "Voorbeeldleerdoel", "target": 0.8, "value": 0.3 } ], "objectivesProgress": 0.375, "parts": [ { "attempts": [ { "attemptNr": -1, "completeDate": "2020-02-12", "completeDateTime": "2020-02-12T14:20:21Z", "completed": true, "criteria": [ { "id": "VOORBEELDCRI-001", "maxScore": 100, "name": "Criterium 1", "score": 100 }, { "id": "VOORBEELDCRI-002", "maxScore": 100, "name": "Criterium 2", "score": 100 } ], "passed": true, "progress": null, "score": "100%", "startDate": "2020-02-12", "startDateTime": "2020-02-12T14:14:38Z", "terms": [] } ], "blockName": "Blok 1", "completeDate": "2020-02-12", "completeDateTime": "2020-02-12T14:20:21Z", "completed": true, "id": null, "name": "Voorbeeld inleveropdracht", "partId": 118, "passed": true, "score": "100%", "subType": "SkillAssignment", "type": "SkillAssignment", "uid": "8e28909d-ff9d-4813-9007-dc7c785c62b0" }, { "attempts": [ { "attemptNr": 1, ... }, { "attemptNr": 2, "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "criteria": [], "passed": true, "progress": "3/3", "score": "67%", "startDate": "2020-02-13", "startDateTime": "2020-02-13T16:20:31Z", "terms": [ { "maxScore": 1, "name": "Examenterm 1", "score": 1, "threshold": 0 }, { "maxScore": 1, "name": "Examenterm 2", "score": 1, "threshold": 0 }, { "maxScore": 1, "name": "Exaenterm 3", "score": 1, "threshold": 0 } ] } ], "blockName": "Blok 1", "completeDate": "2020-02-13", "completeDateTime": "2020-02-13T16:23:55Z", "completed": true, "id": null, "name": "Voorbeeldtoets", "partId": 223, "passed": true, "score": "67%", "subType": "Assessment", "type": "Assessment", "uid": "c94d938b-0084-4a97-a51c-61e23478c462" } ], "progress": "2/2", "reseller": "VOORBEELID", "startDate": "2020-02-05", "startDateTime": "2020-02-05T15:38:35Z", "subscribeDate": "2020-02-05", "subscribeDateTime": "2020-02-05T09:00:12Z", "uid": "a62b0793-7682-11eb-b67e-06575dd7e8c5" }
De betekenis:
- active: Actief. Deze staat standaard op false wanneer de deelnemer is ingeschreven. Op het moment dat de deelnemer met de cursus begint, komt deze op true te staan.
- completeDate: Afrondingsdatum. Dit is datum waarop de cursus was afgerond.
- completeDateTime: Hetzelfde als completeDate, inclusief de tijd in UTC.
- completed: Afgerond. Deze heeft als waarde true wanneer de cursus is afgerond.
- efficiency: Efficiëntie. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. Dit heeft te maken met het aantal pogingen op MemoTrainbare vragen.
- expired: Verlopen. Deze heeft als waarde true als de inschrijving is verlopen.
- finished: Beëindigd. Deze heeft als waarde true als de inschrijving is verlopen of als de deelnemer handmatig is uitgeschreven voor de uitvoering.
- grade: Score. Dit is de score op de activiteit die was geselecteerd bij de "Cursus eindcijfer baseren op" instelling van de template.
- gradeDate: Datum van score. Dit is de datum waarop de activiteit was afgerond die was geselecteerd bij de "Cursus eindcijfer basren op" instelling van de template.
- gradeDateTime: Hetzelfde als gradeDate, inclusief de tijd in UTC.
- id: Dit is de externe ID van de uitvoering.
- knowledgeIntake: Kennisopname. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. De kennisopname is de voortgang van een deelnemer op het opslaan van alle MemoTrainbare vragen in het langetermijngeheugen.
- lastTrainingCompletedDate: Datum laatste afgeronde MemoTraining. This is the date of the last MemoTraining that was completed.
- lastTrainingCompletedDateTime: Hetzelfde als lastTrainingCompletedDate, inclusief de tijd in UTC.
- name: Naam. Dit is de naam van de uitvoering.
- objectives: Leerdoelen. Dit zijn de leerdoelen. Als een uitvoering geen leerdoelen heeft, is dit een lege array.
- knowledgeIntake: Kennisopname. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. Dit is de kennisopname van de MemoTrainbare vragen van een specifiek leerdoel.
- name: Naam. Dit is de naam van het leerdoel.
- target: Doel. Dit is de doelwaarde van het leerdoel.
- value: Waarde. Dit is de huidige score van de deelnemer op het leerdoel.
- objectivesProgress: Leerdoel voortgang. Dit heeft een waarde tussen 0 en 1, 1 betekent 100%. Dit is de voortgang van de deelnemer op de leerdoelen van de cursus (niet elke cursus heeft leerdoelen).
- parts: Activiteiten. Dit zijn de activiteiten van de uitvoering.
- attempts: Pogingen. Dit zijn de pogingen op deze activiteit. Alleen Toets-activiteiten kunnen meerdere pogingen hebben.
- attemptNr: Pogingnummer. Als meerdere pogingen niet zijn toegestaan, is deze waarde -1. Bij toetsen die meerdere pogingen toestaan is de waarde het pogingnummer.
- completeDate: Afrondingsdatum. Dit is de datum waarop de poging is afgerond.
- completeDateTime: Hetzelfde als completeDate, inclusief de tijd in UTC.
- completed: Afgerond. Deze heeft als waarde true wanneer de poging is afgerond.
- criteria: Criteria kunnen van toepassing zijn op activiteiten die moeten worden beoordeeld als deze zo zijn ingesteld. In andere gevallen is dit een lege array.
- id: Dit is het ID van het criterium.
- maxScore: Dit is de maximum score van het criterium.
- name: Naam. Dit is de naam van het criterium.
- score: Dit is de score op het criterium.
- passed: Geslaagd. Deze heeft als waarde true als de poging is geslaagd.
- progress: Voortgang. Sommige activiteiten ondersteunen geen voortgang. In dat geval heeft dit de waarde null. Als de activiteit wel voortgang ondersteunt, is de waarde bijvoorbeeld "3/3". Dat betekent dat 3 van de 3 vragen en/of inhoudsdelen zijn afgerond in deze poging.
- score: Dit is de score op de poging.
- startDate: Startdatum. Dit is de startdatum van de poging.
- startDateTime: Hetzelfde als startDate, inclusief de tijd in UTC.
- terms: Examentermen. Dit zijn de resultaten per examenterm. Examentermen zijn alleen mogelijk bij Toets-activiteiten. Als er geen examentermen zijn, is dit een lege array.
- maxScore: Dit is de maximum score van de examenterm.
- name: Naam. Dit is de naam van de examenterm.
- score: Dit is de score op de examenterm.
- threshold: Drempel. Dit is de drempel van de examenterm.
- blockName: Bloknaam. Dit is de naam van het blok waarin de activiteit staat.
- completeDate: Afrondingsdatum. Dit is de datum waarop de activiteit is afgerond.
- completeDateTime: Hetzelfde als completeDate, inclusief de tijd in UTC.
- completed: Afgerond. Deze heeft als waarde true wanneer de activiteit is afgerond.
- id: Dit is de externe ID van de activiteit.
- name: Naam. Dit is de naam van de activiteit.
- partId: Activiteit ID. Dit is de interne ID van de activiteit, die soms zichtbaar is in de URL die deelnemers zien.
- passed: Geslaagd. Deze heeft als waarde true als de deelnemer is geslaagd voor de activiteit. Bij activiteiten die geen slagingsgrens (kunnen) hebben (zoals een Les), is deze waarde altijd false. Bij evaluatie-activiteiten is de waarde altijd null.
- score: Dit is de score op de activiteit. Bij evaluatie-activiteiten is de waarde altijd null.
- subType: Deze geeft aan welk type activiteit het is op een specifieker niveau dan type. Zie type voor meer informatie.
- type: Deze geeft aan welk type activiteit het is. De namen van de types/subtypes activiteiten komen niet overeen met de namen zoals je ze ziet in de interface van aNewSpring.
- Toets: type "Assessment", subtype "Assessment"
- Proefexamen: type "Assessment", subtype "RandomAssessment". Dit activiteittype is tegenwoordig samengevoegd met Toets.
- Nulmeting/instaptoets: type "Assessment", subtype "FingerPrintAssessment". Dit activiteittype is tegenwoordig samengevoegd met Toets.
- Opdracht: type "Assignment", subtype "Assignment"
- Certificaat: type "Certificate", subtype "Certificate"
- Vragenlijst: type "Evaluation", subtype "Inquiry"
- Assessment: type "Evaluation", subtype "Scan"
- 360° feedback: type "Evaluation", subtype "360-degrees"
- Externe activiteit: type "External", subtype "External"
- Webinar: type "External", subtype "Webinar"
- Externe activiteit met LTI: type "External", subtype "LTI-1p0" of "LTI-2p0"
- Les: type "Lesson", subtype "Lesson"
- Documentatie: type "Lesson", subtype "Documentation"
- SCORM: type "Scorm", subtype "Scorm"
- Inleveropdracht: type "SkillAssignment", subtype "SkillAssignment"
- Video-inleveropdracht: type "SkillAssignment", subtype "VideoSkillAssignment" - uid: De uid is een uniek ID dat automatisch wordt gegenereerd. De uid van een activiteit is alleen uniek op templateniveau. Dezelfde activiteit in verschillende uitvoeringen zal dezelfde uid hebben.
- attempts: Pogingen. Dit zijn de pogingen op deze activiteit. Alleen Toets-activiteiten kunnen meerdere pogingen hebben.
- progress: Voortgang. Bijv. 11/16. Dit betekent dat 11 van de 16 beschikbare activiteiten zijn afgerond. Activiteiten die niet beschikbaar zijn vanwege condities, worden niet meegerekend.
- reseller: Subomgeving. Dit is de externe ID van de subomgeving waar de uitvoering aan is gekoppeld. Deze is leeg als een subomgeving geen extern ID heeft.
- startDate: Startdatum. Dit is de startdatum van de inschrijving, de deelnemer kan de cursus niet voor deze datum zien. Dit is de startdatum op die de deelnemer de uitvoering is gestart, en niet de startdatum die in de houdbaarheidsinstellingen van de uitvoering kan worden ingesteld.
- startDateTime: Hetzelfde als startDate, inclusief de tijd in UTC.
- subscribeDate: Inschrijfdatum. Dit is de datum waarop de deelnemer was ingeschreven voor de cursus.
- subscribeDateTime: Hetzelfde als subscribeDate, inclusief de tijd in UTC.
- uid: De uid is een uniek ID dat automatisch wordt gegenereerd.
GET /getResults/{userID}/{courseID}/{activityID}
of GET /getResults?userUID={userUID}&courseUID={courseUID}&activityID={activityID}
Hiermee kun je de resultaten ophalen van een specifieke activiteit van een specifieke inschrijving van een specifieke gebruiker. Je moet hiervoor de externe ID's (userID/courseID) of UID's (userUID/courseUID) van de gebruiker en de uitvoering en de externe ID (activityID) van de activiteit gebruiken.
POST requests
POST /subscribe/{userID}/{courseID}
of POST /subscribe?userUID={userUID}&courseUID={courseUID}
Hiermee kun je een deelnemer inschrijven voor een specifieke uitvoering. Je moet hiervoor de externe ID's (userID/courseID) of UID's (userUID/courseUID) van de gebruiker (deelnemer) en uitvoering gebruiken.
POST /subscribeGroups/{courseID}
of POST /subscribe?courseUID={courseUID}
Hiermee kun je bestaande deelnemersgroepen inschrijven voor een specifieke uitvoering. Je moet hiervoor de externe ID of UID van de uitvoering gebruiken en de externe ID's van de groepen. De externe ID's van de groepen kun je als array meegeven in de paramter groupID, door deze parameter meerdere keren te herhalen met verschillende waardes in één API call.
POST /updateSubscription/{userID}/{courseID}
of POST /updateSubscriptions?userUID={userUID}&courseUID={courseUID}
Hiermee kun je de start- en verloopdatum van een specifieke inschrijving van een specifieke deelnemer aanpassen. Je kunt de inschrijving ook op verlopen (expired) zetten. Je moet hiervoor de externe ID's (userID/courseID) of UID's (userUID/courseUID) van de gebruiker (deelnemer) en uitvoering gebruiken.
POST /unsubscribe/{userID}/{courseID}
of POST /unsubscribe?userUID={userUID}&courseUID={courseUID}
Hiermee kun je een specifieke deelnemer uitschrijven uit 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.
POST /scoreExternalActivity/{userID}/{courseID}/{activityID}
of POST /scoreExternalActivity?userUID={userUID}&courseUID={courseUID}&activityID={activityID}
Hiermee kun je een score registreren voor een specifieke externe activiteit van een specifieke inschrijving van een specifieke gebruiker. Je moet hiervoor de externe ID's (userID/courseID) of UID's (userUID/courseUID) van de gebruiker en de uitvoering en de externe ID (activityID) van de activiteit gebruiken.