# Evalytics api
# Overzicht
Overzicht van alle onderdelen binnen evalytics
Overzicht
| Onderdeel | Afhankelijkheid van / relatie met onderdelen | **Toelichting** | API |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| Faculteiten en opleidingen | |
Faculteiten en opleidingen zijn van toepassing indien er binnen de organisatie per faculteit/opleiding onderscheid gemaakt moet worden tussen onder andere rollen, rechten en resultaten.
Beheer via API brengt complexiteit met zich mee ten aanzien van onderhoud en toegang tot historie van evaluaties en is daarom niet aan te raden.
| Ja |
| Concept gebruikers | |
Een conceptgebruiker is een gebruiker die nog geen rol of rechten heeft binnen Evalytics. Instellingen maken gebruik van conceptgebruikers als zij alle medewerkers alvast in Evalytics willen plaatsen zonder dat daar een functionele rol aan gekoppeld is. Op het moment dat het nodig is, kunnen deze gebruikers omgezet worden naar een reguliere gebruiker met de bijbehorende rol binnen de benodigde organisatieonderdelen.
Een concept gebruiker (draft user) staat altijd op het hoogste organisatieniveau en heeft geen rol in het systeem.
| Ja |
| Gebruikers |
Faculteiten en opleidingen
| De relatie met faculteiten en opleidingen is van belang om gebruikers rechten te geven binnen specifieke faculteiten en opleidingen. | Ja |
| Docenten |
Faculteiten en opleidingen
Gebruikers
|
Docenten zijn van toepassing indien er docent evaluaties aangemaakt moeten worden en/of docenten toegang moeten hebben tot de resultaten van cursussen.
Wanneer een docent wordt aangemaakt zal deze gekoppeld worden aan de gebruiker met hetzelfde e-mailadres. Als er nog geen gebruiker bestaat met dit e-mailadres zal een nieuwe gebruikt aangemaakt worden.
De relatie met faculteiten en opleidingen is van belang om gebruikers rechten te geven binnen specifieke faculteiten en opleidingen.
| Ja |
| Werkvormen |
Faculteiten en opleidingen
| Faculteiten en opleidingen | |
| Groepen |
Faculteiten en opleidingen
|
Groepen bevatten de e-mailadressen van studentgroepen.
De relatie met faculteiten en opleidingen om de groepen te kunnen koppelen aan de cursussen en evaluaties binnen specifieke faculteiten en opleidingen.
| Ja |
| Vragensets |
Faculteiten en opleidingen (opt)
|
Vragensets bevatten een aantal vragen.
Vragensets kunnen op instellingsniveau aangemaakt worden en zijn dan beschikbaar op lagere niveaus. Op lagere niveaus kunnen ook vragensets aangemaakt worden.
De relatie met faculteiten/opleidingen is afhankelijk van of er gebruik wordt gemaakt van faculteiten en opleidingen.
| Nee |
| Cursussen |
Faculteiten en opleidingen
Werkvormen (opt)
Docenten (opt)
Cursuscoordinator (opt)
Vragensets (opt)
Groepen (opt)
|
De relatie met faculteiten en opleidingen is van belang om gebruikers rechten te geven tot functies en resultaten binnen specifieke faculteiten en opleidingen.
De relatie met werkvormen is van belang om te kunnen evalueren per werkvorm.
De relatie met docenten is onder andere van belang om docenten via Evalytics toegang te geven tot resultaten van de cursus en is benodigd om evaluaties waarin ook docenten worden geëvalueerd aan te maken via de evaluatiekalender.
De relatie met vragensets is eveneens van belang om evaluaties aan te maken via de evaluatiekalender.
De relatie met de cursus coördinator is van belang vanwege een mogelijke rol in de evaluatiecyclus, toegang tot de cursus resultaten en optioneel toegang tot resultaten van collega-docenten.
| Ja |
| Workflow |
Faculteiten en opleidingen
Gebruikers
Docenten
| Workflows zijn nodig voor bepaling van de evaluatiecyclus van evaluaties die aangemaakt worden op basis van de evaluatiekalender. | *Ja\** |
| Evaluaties |
Faculteiten en opleidingen
Gebruikers
Werkvormen (opt)
Docenten (opt)
Cursuscoördinator (opt)
Vragen/Vragensets
|
Afhankelijk van de samenstelling en type van de evaluatie wordt er in evaluaties onder andere gebruik gemaakt van werkvormen, docenten, gebruikers en cursuscoördinatoren.
De relatie met faculteiten en opleidingen is van belang voor het onderscheid in evaluaties en resultaten binnen specifieke faculteiten en opleidingen. En om gebruikers rechten te geven tot evaluaties binnen specifieke faculteiten en opleidingen.
| Ja |
| Evaluatiekalender |
Faculteiten en opleidingen
Cursussen
Evaluatie templates
Werkvormen (opt)
Groepen (opt)
Vragensets
|
De relatie met faculteiten en opleidingen is van belang voor het onderscheid in evaluaties en resultaten binnen specifieke faculteiten en opleidingen, en om gebruikers rechten te geven tot evaluaties binnen specifieke faculteiten en opleidingen.
De relatie met groepen is van belang voor evaluaties op uitnodiging.
De relatie met werkvormen is nodig indien de wens bestaat om per werkvorm te evalueren.
Evaluatie templates en vragensets zijn noodzakelijk voor de evaluatiekalender.
De evaluatiekalender kan alleen gebruikt worden voor cursus- en toetsevaluaties.
| Ja |
| |
| - |
*\*: Kunnen via de API beheerd worden. Dit echt echter niet wenselijk of noodzakelijk*
# Authenticatie
## Api key aanmaken
Authenticatie loopt door middel van een API key. Als functioneel beheerder is het mogelijk om API keys aan te maken. Je kunt API keys verschillende rechten en restricties op organisaties geven.
De API key kan je vervolgens meegeven als header parameter en is verplicht bij alle API calls.
## Meesturen van een organisation (verplicht)
Als je gebruik wilt maken van de API is het verplicht om een organisation mee te geven. Evalytics weet dan welke items teruggestuurd moeten worden of onder welke organisatie een item geplaatst of bijgewerkt moet worden. Dit kan zowel een extern id als het interne id van de organisation zijn (zie hoofdstuk Algemene query parameters)
## Api voorbeeld
`GET` `https://api-portal.evalytics.xyz/groups`
Hieronder zie je een voorbeeld van een call die je kan aanroepen om een lijst met groepen op te halen
#### Query Parameters
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------- |
| organisation | string | Id van de organisation (kan ook een externalId zijn) |
#### Headers
| Name | Type | Description |
| ------- | ------ | ------------- |
| api-key | string | Api key token |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-02-22T20:35:30.186Z",
"resultSet": {
"count": 1,
"limit": 30
}
},
"results": [
{
"organisation": 1,
"topOrganisation": 1,
"deleted": false,
"createdBy": "123",
"modifiedBy": null,
"externalId": null,
"archived": false,
"name": "Groep studenten",
"description": "Studenten",
"id": 1772,
"createdAt": "2020-12-21T16:17:55.000Z",
"updatedAt": "2020-12-21T16:17:55.000Z"
}
]
}
```
{% endtab %}
{% endtabs %}
# Foutmeldingen
Wanneer je een call hebt gedaan die is gefaald, dan krijg je over het algemeen een van twee type errors.
### **400 - Bad Request**
Een user errors. Deze foutmelding betekent over het algemeen dat er ongeldige data in de call staat. De response van de call geeft aan wat er onjuist is. Deze errors kan de ontwikkelaar vaak zelf oplossen.
### 500 - Server Error
Een error in het systeem. Deze foutmelding betekent dat er iets verkeerd gaat in het systeem. Dit betekent dat de user dit vaak niet zelf kan oplossen en contact zal moeten opnemen met Evalytics.
### Tracking id
Bij iedere API call geven wij als response header een tracking-id mee.. Mocht je een foutmelding krijgen, dan is het handig om het tracking-id aan ons door te sturen. Zo kunnen wij eenvoudiger achterhalen wat er is misgegaan.
**Voorbeeld**
`tracking-id: 61b9b5c5-8bf9-4eea-8a37-f07495c20d2e`
# Algemene query parameters
### Extern id
Evalytics ondersteunt de mogelijkheid om gebruik te maken van een extern id. Als in uw eigen systeem een docent een id heeft, dan kun je dat meesturen als externalId. Bij ons wordt er nog altijd gebruik gemaakt van een interne id, maar hierdoor kun je wel op onderdelen zoeken of aanpassingen doen met het externe id. Dit werkt alleen voor modellen waarbij een externalId bij het aanmaken is meegegeven.
De onderdelen die dit nu ondersteunen zijn: Concept gebruikers, Docenten, Cursussen en Groepen.
**Organisation**
Als je gebruik maakt van de API is het meesturen van een organisation verplicht. Zo weet Evalytics in welke organisatie (opleiding of faculteit) je wilt aanspreken
| query parameter | Omschrijving |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| organisationExternalId | Als je zoekt naar objecten binnen een organisatie zal de organisationId die je meestuurt gecheckt worden op externalId in plaats van het interne id van Evalytics |
| external | Bij het updaten of ophalen van een enkel item zal er gezocht worden op het externe id in plaats van het interne id van Evalytics |
| organisation **(verplicht)** | Als je gebruik maakt van de API is het verplicht om een organisation mee te geven. Dit kan extern id zijn of het id van Evalytics. Bij het aanmaken, bewerken, ophalen van items is het nodig om een organisation mee te geven, zodat Evalytics weet waar deze geplaatst moet worden. |
## Voorbeeld
`GET` `https://api-portal.evalytics.nl/group/{id}`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------- |
| id | string | intern/extern id van de group |
#### Query Parameters
| Name | Type | Description |
| ------------------------ | ------- | ----------------------------------- |
| organisationIsExternalId | boolean | organisation param is een extern id |
| external | boolean | Zoek op extern id |
| organisation | string | intern/extern id van de organisatie |
{% tabs %}
{% tab title="200 " %}
```
{
"participants": [
{
"deleted": false,
"createdBy": "1",
"modifiedBy": null,
"name": "",
"email": "voorbeeld@evalytics.nl",
"externalId": null,
"id": 12345,
"createdAt": "2021-01-14T11:10:17.000Z",
"updatedAt": "2021-01-14T11:10:17.000Z",
"group": 10
}
],
"organisation": 2,
"topOrganisation": 1,
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"externalId": null,
"archived": false,
"name": "Voorbeeld",
"description": "Voorbeeld omschrijving",
"id": 10,
"createdAt": "2021-01-14T11:10:17.000Z",
"updatedAt": "2021-01-14T11:10:17.000Z"
}
```
{% endtab %}
{% endtabs %}
# Paginering
Wanneer je een lijst ophaalt, kun je in de query een limiet en een skip toevoegen in de vorm\
\&limit=30\&skip=0
**Limit** geeft aan hoeveel resultaten je opvraagt. Bij 0 zullen alle resultaten worden opgehaald.\
**Skip** geeft aan hoeveel resultaten je wilt overslaan. Bij 0 zal niks worden overgeslagen.
De ordening van de resultaten is deterministisch. Dus als er 60 resultaten zijn en je gebruikt een limit van 5 zul en skip van 0 zul je altijd dezelfde 5 resultaten krijgen.
Wanneer je in dit geval een limit van 5 zou gebruiken en een skip van 3, zul je de laatste 2 resultaten van de vorige lijst krijgen.
**Voorbeeld**:
* limit: 0, skip: 0 geeft a,b,c,d,e,f,g
* limit: 5, skip: 0 geeft a,b,c,d,e
* limit: 5, skip: 3 geeft d,e
## Voorbeeld
`GET` `https://api-portal.evalytics.nl/group`
#### Query Parameters
| Name | Type | Description |
| ----- | ------- | ----------------------------------------- |
| limit | integer | Aantal resultaten opvragen (standaard 30) |
| skip | integer | Resultaten overslaan (standaard 0) |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-02-08T20:35:30.186Z",
"resultSet": {
"count": 2,
"limit": 30
}
},
"results": [
{
"organisation": 2,
"topOrganisation": 1,
"deleted": false,
"createdBy": "1",
"modifiedBy": null,
"externalId": null,
"archived": false,
"name": "Voorbeeld 1",
"description": "Studenten",
"id": 1,
"createdAt": "2020-12-21T16:17:55.000Z",
"updatedAt": "2020-12-21T16:17:55.000Z"
},
{
"organisation": 2,
"topOrganisation": 1,
"deleted": false,
"createdBy": "1",
"modifiedBy": null,
"externalId": null,
"archived": false,
"name": "Voorbeeld 2",
"description": "",
"id": 2,
"createdAt": "2020-10-23T15:25:07.000Z",
"updatedAt": "2021-01-14T11:10:35.000Z"
}
]
}
```
{% endtab %}
{% endtabs %}
\
# Metadata
**Bij het ophalen van objecten zullen de volgende velden ten alle tijde aanwezig zijn. De metadata zijn niet aan de response voorbeelden toegevoegd.**
| Naam | Omschrijving | type / Voorbeeld |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| createdAt | Timestamp wanneer het item is aangemaakt. | string (2020-12-21T16:17:55.000Z) |
| updatedAt | Timestamp wanneer het item voor het laatst is aangepast. | string (2020-12-21T18:17:55.000Z) |
| createdBy | Het userId van de gebruiker die het item heeft aangemaakt. | string |
| modifiedBy | Het userId van de gebruiker die het item het voor het laatst gewijzigd. | string |
| organisation | De organisatie (id) waar het item bij hoort. | int |
| topOrganisation | De hoofdorganisatie waar het item bij hoort. | int |
| archived | Het is mogelijk om objecten (met uitzondering van gebruikers en organisaties) te archiveren. Ze worden dan niet meer standaard getoond in de lijsten, maar kunnen nog wel opgehaald (vaak door de archived query parameter mee te geven). | boolean (default false) |
| deleted | Objecten worden ge-'soft delete' en kunnen niet meer opgehaald of bewerkt worden. Het is mogelijk om verwijderde items ongedaan te maken. | boolean (default false) |
# Faculteiten/opleidingen
Faculteiten en opleidingen (organisaties) zijn nodig voor een goede koppeling, indien deze niet aanwezig zijn kunnen cursussen en docenten niet worden toegevoegd omdat deze altijd gekoppeld zijn aan een organisatie.
Bij Evalytics maken we gebruik van een boomstructuur. Dit betekent dat organisaties onder elkaar gekoppeld zijn.
{% hint style="info" %}
Organisaties ondersteunen nog geen id naar externalId conversie zoals staat beschreven in het hoofdstuk ‘Algemene Query Parameters’
{% endhint %}
## Organisatie ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/organisation`
Organisaties kunnen worden gevonden op basis van naam, code, id of externId. De zoekresultaten tonen altijd het interne id van de opleiding. Dit id heb je nodig wanneer je een object binnen een organisatie wilt zoeken of toevoegen. Om alle opleidingen te zien, moet de gebruiker/api-key wel gekoppeld zijn aan alle opleidingen.
#### Query Parameters
| Name | Type | Description |
| ---------- | ------- | --------------------------------------------------------------- |
| q | string | Zoek naar een organisatie |
| parent | integer | Zoek naar child organisaties die aan de 'parent' gekoppeld zijn |
| code | string | Zoek op organisatie code |
| type | string | Zoek op type (faculty / department) |
| externalId | string | Zoek op extern id |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-03-25T20:32:13.118Z",
"resultSet": {
"count": 2,
"limit": 30
}
},
"results": [
{
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"parent": 1,
"topOrganisation": 1,
"name": "Faculteit A",
"code": "FA",
"type": "faculty",
"availableModules": null,
"modules": null,
"externalId": null,
"id": 2,
"createdAt": "2020-04-12T19:12:42.000Z",
"updatedAt": "2020-04-12T19:12:42.000Z"
},
{
"deleted": false,
"createdBy": "3",
"modifiedBy": "3",
"parent": 2,
"topOrganisation": 1,
"name": "Opleiding B",
"code": "ob",
"type": "department",
"availableModules": null,
"modules": null,
"externalId": "Example",
"id": 3,
"createdAt": "2020-04-12T19:12:58.000Z",
"updatedAt": "2021-01-14T11:07:02.000Z"
}
]
}
```
{% endtab %}
{% endtabs %}
## Organisatie ophalen (item)
`GET` `https://api-portal.evalytics.nl/organisation/:id`
Je kunt een enkele organisatie ophalen door het id van de organisatie mee te geven. De onderliggende organisaties (children) worden ook meegestuurd in de response.
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | --------------------- |
| id | integer | id van de organisatie |
{% tabs %}
{% tab title="200 " %}
```
{
"notificationSettings": [],
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"parent": 1,
"topOrganisation": 418,
"name": "Faculteit A",
"code": "FA",
"type": "faculty",
"availableModules": null,
"modules": null,
"externalId": "example",
"id": 2,
"createdAt": "2020-04-12T19:12:58.000Z",
"updatedAt": "2021-01-14T11:07:02.000Z",
"hasChildren": true,
"children": [
{
"deleted": false,
"createdBy": "3",
"modifiedBy": "3",
"parent": 2,
"topOrganisation": 1,
"name": "Opleiding B",
"code": "ob",
"type": "department",
"availableModules": null,
"modules": null,
"externalId": "Example",
"id": 3,
"createdAt": "2020-04-12T19:12:58.000Z",
"updatedAt": "2021-01-14T11:07:02.000Z"
}
]
}
```
{% endtab %}
{% endtabs %}
## Organisatieboom ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/getOrganisationTree`
Haalt een lijst op met alle opleidingen die aan de hoofdorganisatie gekoppeld zijn. Bij de **GET /organisations** krijg je alleen een lijst terug met de opleidingen waar de gebruiker/api-key aan gekoppeld is. Bij dit endpoint hoeft de gebruiker/api-key niet gekoppeld te zijn aan alle organisaties.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------- |
| q | string | Zoek op organisatie |
{% tabs %}
{% tab title="200 " %}
```
[
{
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"parent": 123,
"topOrganisation": 123,
"name": "Example 1",
"code": null,
"type": "department",
"availableModules": null,
"modules": null,
"externalId": null,
"importLock": false,
"id": 124,
"createdAt": "2020-12-03T10:58:46.000Z",
"updatedAt": "2020-12-03T10:58:46.000Z"
},
{
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"parent": 123,
"topOrganisation": 123,
"name": "Example 2",
"code": null,
"type": "department",
"availableModules": null,
"modules": null,
"externalId": null,
"importLock": false,
"id": 125,
"createdAt": "2020-12-03T10:58:46.000Z",
"updatedAt": "2020-12-03T10:58:46.000Z"
}
]
```
{% endtab %}
{% endtabs %}
# Concept gebruikers
Concept gebruikers worden via het koppelvlak aangemaakt in Evalytics en opgeslagen als ‘draft users’ Een draft user is in feite een template-user, hier staat enkel de basisinformatie in die benodigd is om er een gebruiker of docent van te maken. Een draft user staat altijd op het hoogste organisatieniveau en heeft geen rol in het systeem
### Overzichtstabel termen
| Naam | Typ | Verplicht bij aanmaken | Omschrijving |
| -------------- | -------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| title | string | Nee | Titel van de gebruiker (Bijv: Dhr., Mevr.) |
| firstName | string | Ja | Voornaam van de gebruiker |
| lastName | string | Ja | Achternaam van de gebruiker |
| prefix | string | Nee | Tussenvoegsel |
| code | string | Ja | Code van de gebruiker |
| email | string (email) | Ja | E-mailadres van de gebruiker. Deze moet uniek zijn |
| externalId | string | Nee | Het externe id van de concept gebruiker |
| altId | string | Nee | Een alternatief id. Deze wordt alleen gebruikt als hiervoor een afspraak is gemaakt en is niet nodig om mee te sturen. |
| teacherOptions | object | Nee |
Je kunt teacherOptions meegeven die worden gebruikt als je een conceptgebruiker omzet naar een docent:
isWorkingStudent: Als de docent een werkstudent/student assistent is
isGuestTeacher: Als de docent een gast docent is
Werkstudenten/gast docenten hebben minder rechten dan een echte docent en kunnen bijvoorbeeld minder resultaten inzien.
|
## Concept gebruiker ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/draftUser`
Haal de conceptgebruikers op. Normaal gesproken worden alle concept gebruikers opgehaald die nog **niet** zijn omgezet naar docenten. Je kunt forTopicType=2 (2= type docent) mee geven aan de url om alle concept gebruikers op te halen die **wel** zijn omgezet.
#### Query Parameters
| Name | Type | Description |
| --------------- | ------- | --------------------------------------------------------------------------------------------------- |
| convertedToUser | boolean | Haal alle concept gebruikers op die gekoppeld zijn aan een gebruiker |
| q | string | Zoeken naar conceptgebruikers (Voornaam, Achternaam, code, email, externalId |
| forTopicType | integer | Door topicType=2 mee te geven worden alle concept gebruikers opgehaald die zijn omgezet naar docent |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-02-25T09:51:20.547Z",
"resultSet": {
"count": 1
}
},
"results": [
{
"id": 1,
"title": "Dhr.",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"code": "EU",
"email": "example@evalytics.nl"
"organisation": 100,
"topOrganisation": 100,
"externalId": "ABC",
"altId": "",
"user": null
}
]
}
```
{% endtab %}
{% endtabs %}
## Conceptgebruikers ophalen (item)
`GET` `https://api-portal.evalytics.nl/draftUser/:id`
Een gebruiker kan gevonden worden op basis van het interne of externe id. Hierbij geeft onze API de interne id en organisatie id terug.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------------------------- |
| id | string | Intern id of externalId van de conceptgebruiker |
{% tabs %}
{% tab title="200 " %}
```
{
"id": 1,
"title": "Dhr",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"code": "EU",
"email": "example@evalytics.nl"
"organisation": 100,
"topOrganisation": 100,
"externalId": "ABC",
"altId": "",
"user": null
}
```
{% endtab %}
{% endtabs %}
## Maak een conceptgebruiker aan
`POST` `https://api-portal.evalytics.nl/drafUser`
Maak een conceptgebruiker aan
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| | string | |
{% tabs %}
{% tab title="200 " %}
```
{
"id": 1,
"title": "Dhr.",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"code": "EU",
"email": "example@evalytics.nl"
"organisation": 100,
"topOrganisation": 100,
"externalId": "ABC",
"altId": "",
"user": null
}
```
{% endtab %}
{% endtabs %}
```
{
"title": "(string)",
"firstName":"(string - required)",
"lastName":"(string - required)",
"prefix":"(string)",
"code":"(string - required)",
"email": (string - required),
"altId": (string),
"externalId": (string),
"teacherOptions": {
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
}
}
```
{% hint style="info" %}
Conceptgebruikers worden altijd op het hoogste niveau aangemaakt. Meestal is dit de school waar de faculteiten en opleidingen aan gekoppeld zijn. Je kunt ze bij alle onderliggende opleidingen/faculteiten ophalen.
{% endhint %}
## Conceptgebruiker bijwerken
`POST` `https://api-portal.evalytics.nl/draftUser/:id`
Indien het gewenst is dat de update van de gebruiker propageert met het systeem (naar de gekoppelde docenten en cursussen), dan kan je dat aangeven met de optie propagate=true.\
\
**Voorbeeld**: Er vindt een naamswijziging plaats van Emma de Vries naar Emma de Vries - janssen. De naam wordt gewijzigd bij de volgende onderdelen:\
\- Concept gebruiker\
\- Gebruiker\
\- De docent\
\- Alle cursussen waar de docent aan gekoppeld is.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------- |
| id | string | Intern id of extern id van de conceptgebruiker |
#### Query Parameters
| Name | Type | Description |
| --------- | ------- | ---------------------------------------------------------------- |
| propagate | boolean | Voer update door bij gekoppelde gebruiker, docent en cursussen. |
{% tabs %}
{% tab title="200 " %}
```
{
"id": 1,
"title": "Dhr.",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"code": "EU",
"email": "example_updated@evalytics.nl"
"organisation": 100,
"topOrganisation": 100,
"externalId": "ABC",
"altId": "",
"user": null
}
```
{% endtab %}
{% endtabs %}
```
{
"title": "(string)",
"firstName":"(string)",
"lastName":"(string)",
"prefix":"(string)",
"code":"(string)",
"email": (string),
"altId": (string),
"externalId": (string),
"teacherOptions": {
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
}
}
```
## Conceptgebruiker omzetten naar docent
`POST` `https://api-portal.evalytics.nl/draftUser/:id/toTeacher`
Als je een concept gebruiker wilt gebruiken als docent, zal deze eerst omgezet moet worden. Er wordt een docent aangemaakt op de organisatie waar je de call op aanroept, dus niet altijd de hoofdorganisatie zoals concept gebruikers. Bij het aanmaken van een docent zal er ook direct een gebruiker aangemaakt worden. De gebruiker krijgt daarnaast ook de rol docent binnen de opleiding.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------------------------ |
| id | string | intern of extern id van de gebruiker |
{% tabs %}
{% tab title="200 Als response krijg je de docent terug die is aangemaakt." %}
```
{
"type": 2,
"organisation": 3,
"topOrganisation": 2,
"user": 3,
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"externalId": "exampleExternalId",
"archived": false,
"parent": null,
"name": "Pascal Examp;e",
"description": null,
"data": {
"title": "Dhr.",
"firstName": "Pascal",
"lastName": "Example",
"prefix": "",
"code": "ee",
"emailAddress": "example@evalytics.nl"
},
"id": 4
}
```
{% endtab %}
{% endtabs %}
## Concept gebruiker verwijderen
`DELETE` `https://api-portal.evalytics.nl/draftUser/:id`
Een gebruiker kan worden verwijderd door middel van een delete. De delete kan op basis van het eerder meegegeven extern id. Indien het gewenst is dat de delete van de gebruiker propageert in het systeem (naar gekoppelde docenten/cursussen) dan dient dit aangegeven te worden met de optie “propagate = true”. Let hierbij wel op dat de docent dan bij alle opleidingen wordt verwijderd, inclusief gerelateerde cursussen en de gebruiker. Mocht het nodig zijn dat een docent wordt verwijderd bij een specifieke opleiding dan dient dit uitgevoerd te worden via de docent API. Tevens wordt een lopende evaluatie niet aangepast (de functie propageert niet naar lopende evaluaties).
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------------------------------- |
| id | string | intern of extern id van de concept gebruiker |
#### Query Parameters
| Name | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------------ |
| undo | boolean | Maak actie ongedaan. Dit is niet mogelijk als je gebruik maakt van propagate |
| propagate | string | Propageren naar onderliggende gebruiker, docenten en cursussen. Kan niet ongedaan gemaakt worden |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Als je tegelijk gebruik maakt van propagate (true) en undo (true), krijg je een 400 - bad request terug van de api .**
{% endhint %}
## Anonymize draft user
`POST` `https://api-portal.evalytics.nl/draftUser/:id/anonymize`
Anonymize a draft user and the linked user/teacher(s). The draft user, user and teacher will be anonymized. This means all personal data will be removed from the (draft)user and teacher(s). Linked evaluations results will not be removed.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------------------------------- |
| id | string | The external or internal id of the draftUser |
#### Query Parameters
| Name | Type | Description |
| ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| forAllOrganisations | boolean |
- false (default): Anonymize only for the current organisation. The teacher will be anonymized from the current organisation. The (draft)user will only be anonymized when it is not linked to other organisations. - true: The teacher and (draft)user will be anonymized for all organisations.
|
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
When anonymizing the draft user, you can re-use the externalId, because it is not linked to a draftUser anymore.
{% endhint %}
## Block (draft) user
`POST` `https://api-portal.evalytics.nl/draftUser/:id/block`
Block a user linked to the draftUser. When a user is blocked:\
\- The user is not able to login\
\- The user will not receive notifications in the period that the user is blocked\
\- The linked organisations and roles will not be removed
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------- |
| id | string | Internal or external id |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | --------------------- |
| undo | boolean | Undo the block action |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
# Gebruikers
### Overzichttabel termen
| Naam | Type | Verplicht bij aanmaken | Omschrijving |
| ----------------------------------- | -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Ja | Naam van de gebruiker |
| title | string | Nee | Titel van de gebruiker. Bijv. Mevr. of Dhr. |
| firstName | string | Nee | Voornaam van de gebruiker |
| prefix | string | Nee | Tussenvoegsel |
| lastName | string | Nee | Achternaam van de gebruiker |
| email | string (email) | Ja | E-mailadres van de gebruiker. Hier logt de gebruiker mee in |
| roles | array | Ja | Je kunt rollen aan de gebruiker toevoegen. Per organisatie kan een rol verschillen. Als voorbeeld: Een gebruiker kan docent zijn bij opleiding A en functioneel kwaliteitsmanager bij een andere faculteit |
| organisations / linkedOrganisations | array | n.v.t. | Naast rollen wordt er ook een lijst met organisaties meegegeven bij het ophalen van gebruiker(s). Hierin staat welke organisaties gekoppeld zijn aan de gebruiker |
| additionalPermissionGroups | array | Nee | In Evalytics zijn er extra permissies mogelijk die je bij een gebruiker kan instellen. Zoals bijvoorbeeld: Evaluatiebeheer, cursusbeheer of docentbeheer. |
| noSurf | boolean | nee | Als de docent geen gebruik kan maken van saml, kan je noSurf meegeven. De gebruiker krijgt dan een inlog en wachtwoord. |
| lastActivationMail | timestamp | n.v.t. | Geeft aan wanneer er voor het laatst een activeringsmail is verstuurd |
| activated | boolean | n.v.t. | Geeft aan of een gebruiker geactiveerd is. De gebruiker krijgt, als je noSurf = true meegeeft, bij het aanmaken van een gebruiker een activerings e-mail. Na het activeren wordt activated op true gezet. |
| externalId | string | nee | Het externe id van de gebruiker |
### Gebruikers en docenten
Gebruikers en docenten zijn nauw met elkaar verbonden. Op het moment dat je een docent aanmaakt binnen de opleiding, zal er automatisch ook een gebruiker aangemaakt worden. Hetzelfde geldt voor concept gebruikers. Als je een concept gebruiker omzet naar docent, zal er automatisch ook een gebruiker aangemaakt worden. De gebruiker en docent zijn met elkaar gekoppeld.
## Gebruikers ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/user`
Hiermee kan je zoeken op gebruikers binnen de organisatie. Bij de gebruikers zullen ook de onderliggende rollen en organisaties toegevoegd worden aan de response
#### Query Parameters
| Name | Type | Description |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| includeChildOrganisations | boolean | Haal ook gebruikers op uit organisaties die onder de huidige organisatie staan |
| role | array | Filter de users op een bepaalde role. Je kunt hier de ids van de rolen meegeven waarop je wilt filteren |
| q | string | Zoeken binnen gebruikers op naam, code en e-mail |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
...
},
"results": [
{
"organisations": [
{
"parent": 100,
"topOrganisation": 100,
"name": "TestFaculteit",
"code": "tf",
"type": "faculty",
"availableModules": null,
"modules": null,
"externalId": "ABC",
"id": 1
}
],
"roles": [
{
"id": 123,
"user": 567,
"evaluator": null,
"role": 13,
"organisation": 100
}
],
"organisation": 100,
"topOrganisation": 100,
"name": "Example user",
"title": "",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"email": "example@evalytics.nl",
"altId": null,
"externalId": "ABC",
"activated": true,
"lastActivationMail": "2020-12-29T10:15:09.000Z",
"id": 567
}
}]
}
```
{% endtab %}
{% endtabs %}
## Gebruiker ophalen (item)
`GET` `https://api-portal.evalytics.nl/user/:id`
Haal een enkele gebruiker op. Organisaties en rollen waar de gebruiker aan gekoppeld is worden ook toegevoegd.
#### Path Parameters
| Name | Type | Description |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Intern id of extern id van de gebruiker |
| showPropagatedRoles | boolean | Indien het nieuwe gebruikersbeheer actief is: hiermee krijg je alle individuele rollen terug die uit `propagate` zijn voortgekomen |
{% tabs %}
{% tab title="200 " %}
```
{
"linkedOrganisations": [
{
"parent": 100,
"topOrganisation": 100,
"name": "TestFaculteit",
"code": "tf",
"type": "faculty",
"availableModules": null,
"modules": null,
"externalId": "ABC",
"id": 1
}
],
"roles": [
{
"id": 123,
"user": 567,
"evaluator": null,
"role": 13,
"organisation": 100
// Indien het nieuwe gebruikersbeheer actief is: geeft de status van de toegang aan. Kan enkel gebruikt worden i.c.m. `role` "3" (teacher)
"enabled": true
// Indien het nieuwe gebruikersbeheer actief is: voert de rol door op alle onderliggende organisaties. Kan gebruikt worden i.c.m. `role` anders dan "3" (teacher)
"propagate": false
// Indien het nieuwe gebruikersbeheer actief is: geeft aan of de rol voortkomt uit een andere rol waar `propagate: true`. Kan gebruikt worden i.c.m. `role` anders dan "3" (teacher).
"propagated": false
}
],
"organisation": 100,
"topOrganisation": 100,
"name": "Example user",
"title": "",
"firstName": "Example",
"prefix": "",
"lastName": "user",
"email": "example@evalytics.nl",
"altId": null,
"activated": true,
"lastActivationMail": "2020-12-29T10:15:09.000Z",
"id": 567
}
```
{% endtab %}
{% endtabs %}
## Gebruiker aanmaken
`POST` `https://api-portal.evalytics.nl/user`
Als je een gebruiker aanmaakt moet het e-mailadres uniek zijn. Het is niet mogelijk om meerdere gebruikers aan te maken met hetzelfde e-mailadres
{% tabs %}
{% tab title="200 " %}
```
{
"deleted": false,
"createdBy": "3",
"modifiedBy": "3",
"name": "pascal api docs",
"title": "",
"firstName": "Pascal",
"prefix": "",
"lastName": "api docs",
"email": "pascal+apidocs@evalytics.nl",
"altId": null,
"activated": false,
"lastActivationMail": "2021-02-25T10:21:39.000Z",
"organisation": 100,
"topOrganisation": 100,
"id": 123
}
```
{% endtab %}
{% endtabs %}
```
{
"name": (string - deprecated),
"title": "(string)",
"firstName": "(string - required when you do not use the name field)",
"prefix": "(string)",
"lastName": "(string - required when you do not use the name field)",
"email": (string - required),
"noSurf":(boolean),
"externalId: (string),
"additionalPermissionGroups":[
{
“organisation”: (integer),
“additionalPermissionGroup”: (integer)
// Indien het nieuwe gebruikersbeheer actief is: geeft aan of de rol gekoppeld is aan `role` "3" (teacher).
"isTeacher": (boolean)
}
],
“roles”: [
{
“organisation”: (integer - at least one role required),
“role”: (integer)
// Indien het nieuwe gebruikersbeheer actief is: geeft de status van de toegang aan. Kan enkel gebruikt worden i.c.m. `role` "3" (teacher)
"enabled": (boolean)
// Indien het nieuwe gebruikersbeheer actief is: voert de rol door op alle onderliggende organisaties. Kan gebruikt worden i.c.m. `role` anders dan "3" (teacher)
"propagate": (boolean)
}
]
}
```
## Gebruiker bijwerken
`POST` `https://api-portal.evalytics.nl/user/:id`
Het is mogelijk om een gebruiker bij te werken. Je kunt de gebruiker bijvoorbeeld extra rollen geven of de naam aanpassen. Het aanpassen van het e-mailadres is niet mogelijk.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------------------- |
| id | string | Intern id of extern id van de gebruiker |
{% tabs %}
{% tab title="200 " %}
```
{
"deleted": false,
"createdBy": "3",
"modifiedBy": "3",
"name": "pascal api docs updated name",
"title": "",
"firstName": "Pascal",
"prefix": "",
"lastName": "api docs updated name",
"email": "pascal+apidocs@evalytics.nl",
"altId": null,
"activated": false,
"lastActivationMail": "2021-02-25T10:21:39.000Z",
"organisation": 100,
"topOrganisation": 100,
"id": 123
}
```
{% endtab %}
{% endtabs %}
```
{
"externalId": (string),
"name": (string - deprecated),
"title": "(string)",
"firstName": "(string - required when you do not use the name field)",
"prefix": "(string)",
"lastName": "(string - required when you do not use the name field)",
"noSurf":(boolean),
"additionalPermissionGroups":[
{
“organisation”: (integer),
“additionalPermissionGroup”: (integer)
// Indien het nieuwe gebruikersbeheer actief is: geeft aan of de rol gekoppeld is aan `role` "3" (teacher).
"isTeacher": (boolean)
}
],
“roles”: [
{
“organisation”: (number),
“role”: (number)
// Indien het nieuwe gebruikersbeheer actief is: geeft de status van de toegang aan. Kan enkel gebruikt worden i.c.m. `role` "3" (teacher)
"enabled": true
// Indien het nieuwe gebruikersbeheer actief is: voert de rol door op alle onderliggende organisaties. Kan gebruikt worden i.c.m. `role` anders dan "3" (teacher)
"propagate": false
}
]
}
```
## Gebruiker verwijderen
`DELETE` `https://api-portal.evalytics.nl/user/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------------------- |
| id | string | Intern id of extern id van de gebruiker |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ------------------------------------ |
| undo | boolean | Maakt de verwijderingsactie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Als je een gebruiker verwijderd, kan de gebruiker daarna ook niet meer inloggen in het systeem
{% endhint %}
## Block user
`POST` `https://api-portal.evalytics.nl/user/:id/block`
Block a user in Evalytics. When a user is blocked:\
\- The user is not able to login\
\- The user will not receive notifications in the period the user is blocked\
\- The linked organisations and roles will not be removed
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------- |
| id | string | Internal or external id |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | --------------------- |
| undo | boolean | Undo the block action |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Upgrading to User Management 2.0
On 09-07-2025 a new update was released which introduced User Mangement 2.0. Most notably the feature to apply (propagate) roles and permissions to underlying organisations was introduced. To accomodate this change the API underwent a couple of slight changes, which is why 2.0 is opt-in for the next 3 months. The following changes have been made:
* Teacher-roles should no longer be added through the `/user` endpoints, since these are of no value when no teacher is created through `POST /teacher` . Instead, retrieve the user beforehand to find out where the teacher role is applicable and disable (or omit) it if necessary
* New attributes have been added to `POST /user` and `PUT /user` :
* `additionalPermissionGroups[].isTeacher` describes if the additional permissions should be linked to the teacher role, this is reflected on the frontend since teacher roles and permissions are now managed in a separate step in the user form
* `roles[].enabled` in case the role is the teacher-role. This marks a teacher role as enabled or disabled.
* `roles[].propagate` applies all roles and additional permissions to the organisation itself and all child organisations, including new child organisations which can be added later. Note that this applies all given roles for the organisation, you can not partially (e.g. one role for the parent org, another for the child). This also applies possible `additionalPermissionGroups` for the organisation. Note that this function can only be used by a user with the *administrator* role
* New attributes and a data flag have been added to `GET /user/:id` :
* The three attributes from above.
* `roles[].propagated` describes if a role is propagated from a parent organisation, which means the role is locked on this level
* A flag `showPropagatedRoles=false` can be given to `GET /user/:id` which removes possible propagated roles, only returning normal or propagating roles instead
* Note that you may receive more teacher roles than expected when retrieving a user: if a teacher role was previously removed but the teacher-object is still available, a role is added to the response with `enabled` set to `false`
* The `name` attribute has been deprecated. Instead, use at least `firstName` and `lastName`.
To migrate, in short:
* Do not add new teacher roles though the user endpoints
* When adding `additionalPermissionGroups` to a teacher role, ensure `isTeacher` is set to `true`
* Implement propagation logic, keep in mind that an administrator can use this functionality at any time on the Evalytics portal. For instance errors can be thrown when trying to add a role to an organisation where `propagated` is set to `true`
We want to make sure everyone is at the latest version before removing deprecated logic, so please contact us in case you encounter any issues during your migration!
# Docenten
#### **Docenten kunnen op drie manieren in het systeem terecht komen:**
* Een nieuwe docent kan worden toegevoegd via de topic-endpoints
* Een docent kan worden toegevoegd vanuit een draft user (concept gebruiker).
* Een docent kan worden toegevoegd vanuit een draft user tijdens het toevoegen van een cursus
De eerste optie resulteert in een docent die bij een specifieke opleiding hoort. De tweede en derde optie in principe ook, alleen blijft daar de koppeling naar de draft user behouden waardoor de gegevens altijd up-to-date kunnen worden gehouden door de draft user te updaten. Op die manier kan beheer van gebruikers plaatsvinden zoals omschreven in stap 1.
Een docent wordt altijd toegevoegd bij een specifieke opleiding, daarvoor is het ID van de opleiding nodig (niet het externe ID), zie stap 2.
**Docenten kunnen worden beheerd op basis van het externe ID en het interne ID.**
#### **De flow zal normaal gesproken als volgt lopen**
* Aanmaken van een ‘draft user’.
* Toevoegen van een ‘draft user’ aan een cursus. Hierbij wordt automatisch de docent (en gebruiker) aangemaakt bij de desbetreffende opleiding.
* Update of delete op een ‘draft user’ en deze past de bijbehorende docenten aan.
#### **Gebruikers en docenten**
Gebruikers en docenten zijn nauw met elkaar verbonden. Op het moment dat je een docent aanmaakt binnen de opleiding, zal er automatisch ook een gebruiker aangemaakt worden. Hetzelfde geldt voor concept gebruikers. Als je een concept gebruiker omzet naar docent, zal er automatisch ook een gebruiker aangemaakt worden. De gebruiker en docent zijn met elkaar gekoppeld.
### Overzichtstabel termen
| name | Type | Verplicht bij aanmaken | Omschrijving |
| ---------------- | -------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title | string | Nee | Titel van de docent (Bijv. Mevr. of Dhr.) |
| firstName | string | Ja | Voornaam van docent |
| lastName | string | Ja | Achternaam van docent |
| prefix | string | Nee | Tussenvoegsel van docent |
| code | string | Ja | Code van docent. Door instelling zelf in te geven |
| externalId | string | Nee | Het interne id van de instelling |
| emailAddress | string (email) | Ja | Het e-mailadres van de docent |
| isGuestTeacher | boolean | Nee | Geeft aan of de docent een gastdocent is |
| isWorkingStudent | boolean | Nee | Geeft aan of de docent een werkstudent is |
| noSurf | boolean | Nee | Kan de gebruiker niet inloggen via surfConext. Er wordt dan een activeringsmail gestuurd waarmee de gebruiker een wachtwoord kan instellen. |
| phoneNumber | integer | Nee | telefoonnummer van de docent |
| type | integer | Ja | Door dit op 2 te zetten geef je aan dat dit een docent is. |
| name | string | Ja | Gehele naam van de docent, dus **Voornaam tussenvoegsel achternaam** |
| importLock | boolean | Nee | Zorgt ervoor dat op de frontend de docent 'gelocked' wordt. Hierdoor kunnen docenten niet zomaar aangepast worden door gebruikers. Alleen een functioneel beheerder heeft de mogelijkheid om de docent aan te passen. |
| useDisabledEmail | boolean | Nee | Als je een docent wilt aanmaken zonder e-mail. Deze docent wordt niet gekoppeld aan een gebruiker en kan ook niet inloggen. |
## Docenten ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/teacher`
Zoeken op docenten.
#### Query Parameters
| Name | Type | Description |
| -------------------- | ------------ | ----------------------------------------------------- |
| archived | boolean | Filter op gearchiveerde docenten |
| q | string | Zoeken op docent (naam, code, externalId) |
| populateProfileImage | boolean | Populated the uploaded profile images of the teachers |
| status | string array | Filter on active, archived, deleted (default=active) |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
...
},
"results": [
{
"data": {
"title": "",
"firstName": "Example",
"lastName": "Teacher",
"prefix": "",
"code": "et",
"emailAddress": "teacher@evalytics.nl"
},
"name": "Example teacher",
"type": 2,
"organisation": 101,
"topOrganisation": 100,
"id": 123,
"user": 456
}
]
}
```
{% endtab %}
{% endtabs %}
## Docent ophalen (item)
`GET` `https://api-portal.evalytics.nl/teacher/:id`
Een enkele docent kan gevonden worden op basis van het interne of externe id. Hiermee geeft onze API het interne id en organisatie id terug.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------- |
| id | string | Intern of externalId van de docent |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"title": "",
"firstName": "Example",
"prefix": "",
"lastName": "Teacher",
"code": "et",
"emailAddress": "teacher@evalytics.nl"
},
"name": "Example teacher",
"type": 2,
"organisation": 101,
"topOrganisation": 100,
"id": 123,
"user": 456
}
```
{% endtab %}
{% endtabs %}
## Docent aanmaken
`POST` `https://api-portal.evalytics.nl/teacher`
Maakt een docent aan. Als er nog geen gebruiker bestaat bij het gegeven e-mailadres, zal er ook een gebruiker aangemaakt worden.
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | --------------------------------------------------------------------------------------- |
| useDisabledEmail | boolean | When set to true, the teacher will be created without an emailAddress (default = false) |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"title": "Dhr.",
"firstName": "Example",
"lastName": "Teacher",
"code": "et",
"emailAddress": "teacher@evalytics.nl"
},
"name": "Dhr. Example teacher",
"importLock": false,
"type": 2,
"organisation": 101,
"topOrganisation": 100,
"id": 123
}
```
{% endtab %}
{% endtabs %}
```
{
"noSurf":(boolean),
"data":{
"title": "(string)",
"firstName":"(string)",
"lastName":"(string)",
"prefix":"(string)",
"code":"(string - required)",
"emailAddress": (string - required),
"phoneNumber":(string),
"isGuestTeacher": (boolean),
"isWorkingStudent": (boolean),
"noSurf": (boolean)
},
"externalId": (string),
"name": (string - required),
"importLock": (boolean)
}
```
## Docent bijwerken
`POST` `https://api-portal.evalytics.nl/teacher/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------- |
| id | string | intern of externalId van de docent |
{% tabs %}
{% tab title="200 " %}
```
{
"data": {
"firstName": "Example",
"lastName": "Teacher",
"code": "et",
"emailAddress": "teacher@evalytics.nl"
},
"name": "Example teacher update",
"importLock": false,
"type": 2,
"organisation": 101,
"topOrganisation": 100,
"id": 123
}
```
{% endtab %}
{% endtabs %}
```
{
"noSurf":(boolean),
"data":{
"title": "(string)",
"firstName":"(string)",
"lastName":"(string)",
"prefix":"(string)",
"code":"(string - required)",
"emailAddress": (string - required),
"phoneNumber":(string),
"isGuestTeacher": (boolean),
"isWorkingStudent": (boolean),
"noSurf": (boolean)
},
"externalId": (string),
"name": (string - required),
"importLock": (boolean)
}
```
## Docent archiveren
`POST` `https://api-portal.evalytics.nl/topic/:id/archive`
Het is mogelijk om een docent te archiveren. Een docent die gearchiveerd is, wordt niet meer getoond als je zoekt naar een docent in alle schermen waar je een docent kunt selecteren
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------- |
| id | string | Intern of externalid van de docent |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ----------------------------------- |
| undo | boolean | Maakt de archiveringsactie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Docent verwijderen
`DELETE` `https://api-portal.evalytics.nl/topic/:id`
Een docent kan verwijderd worden via het topic endpoint. \
\
De gekoppelde gebruiker zal niet direct permanent verwijderd worden. En deze delete kan dus nog (voor een bepaalde tijd) terug gedraait met behulp van de undo parameter.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------------------------- |
| id | string | Intern id of externalid van de docent |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ------------------------------------ |
| undo | boolean | Maakt de verwijderingsactie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
# Cursussen
### Overzichtstabel termen
| Naam | Type | Verplicht | Omschrijving |
| ------------------- | ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Ja | Naam van de cursus. |
| description | string | Nee | Omschrijving van de cursus. |
| code | string | Ja | Code van de cursus. Door de instelling in te geven. Het is mogelijk om binnen evalytics een cursus verplicht uniek te laten zijn. (zie cursus aanmaken) |
| externalId | string | nee | Externe id van de cursus. |
| editions | object array | n.v.t. |
Bij het ophalen van een cursus zullen de onderliggende cursusedities als array meegestuurd worden.
Een cursuseditie is een “child” cursus van een andere reeds bestaande cursus. Van cursusedities kan typisch gebruik gemaakt worden als bij de instelling het interne id van een cursus (in een nieuw jaar) verandert, maar het toch wenselijk is dat resultaten “gegroepeerd” mee gegeven kunnen worden met eerdere edities in Evalytics.
|
| parent | object | Nee \* |
Door parent (id of externalId van de cursus) mee te sturen en edition: true, wordt de cursuseditie gekoppeld aan een cursus.
\* Let op: Verplicht als je een cursuseditie wilt maken. Geef je dit niet mee, dan wordt het een normale cursus
|
| edition | boolean | Nee \* |
Door parent (id of externalId van de cursus) mee te sturen en edition: true, wordt de cursuseditie gekoppeld aan een cursus.
\* Let op: Verplicht als je een cursuseditie wilt maken. Geef je dit niet mee, dan wordt het een normale cursus
|
| coordinators | Object array | Nee | Een lijst van gebruikers die als vak/cursuscoördinatoren voor de cursus worden ingesteld. Deze gebruikers zullen voor de cursus extra rechten krijgen. |
| grades | Object array | Nee | Een lijst met leerjaren en periodes. Je kunt dit als filter gebruiken op de resultaten pagina. |
| types | Object array | Nee |
Werkvormen die bij de cursus horen.
Als bij cursussen gebruik wordt gemaakt van werkvormen, dan kun je bij een evaluatie vragen stellen die over een enkele werkvorm gaan binnen de cursus.
De standaard beschikbare werkvormen lijst is uit te breiden. Zie hoofdstuk Werkvormen.
Aan werkvormen kun je docenten en vragenlijsten toevoegen
|
| labels | object array | Nee |
Labels kunnen gebruikt worden om te filteren in de resultaten en cursuslijst. Voorbeeld:
\[{name: (string)}]
|
| languages | array | Nee |
Welke talen wil je dat er ondersteund worden voor de evaluatie. Geef een array mee met 1 of meerdere talen. Dit kunnen zijn:
nl (Nederlands)
en (Engels)
Geef je niks mee dan is de default multi-language
Let op: Als je organisatie geforceerd op engels staat, is deze overbodig.
|
| groups | Object array | Nee | Groepen (van participanten) die aan de cursus gekoppeld zijn. Dit kunnen de klassen of studentgroepen zijn die de cursus volgen. |
| studyYear | string | Nee |
Studiejaar van de cursuseditie.
Dit wordt alleen gebruikt wanneer de cursus een cursuseditie is.
|
| questionSets | integer | Nee | Het is mogelijk om vragenlijsten aan werkvormen te koppelen. Bij het aanmaken van een evaluatie wordt de vragenlijst geselecteerd bij de desbetreffende werkvorm. |
| teachers | object array | Nee |
Het is mogelijk om docenten te koppelen aan een cursus of werkvormen.
Extra docent properties (De docent zal aangepast worden binnen de huidige organisatie):
isWorkingStudent: Maakt van de docent een werkstudent binnen de organisatie
isGuestTeacher: Maakt van de docent een gastdocent binnen de organisatie
|
| evaluationCalendars | Object array | Nee |
Het is mogelijk om evaluatiekalender item(s) mee te geven om aan deze cursus te koppelen. (Zie ook Hoofdstuk Evaluatiekalender)
|
| Type | integer | Nee |
Een cursus is in feite een topic met type 1. (type 2 is een docent)
|
| index | integer | Nee |
Bij het meesturen van types is het mogelijk om een volgorde te bepalen. Hier zullen de werkvormen op gesorteerd worden bij het aanmaken van de evaluatie. De volgorde is van laag naar hoog. Bijvoorbeeld:
Hoorcollege, index=0
Werkcollege, index=1
Practicum, index=2
Hoorcollege wordt dan als eerst weergegeven, daarna komt werkcollege en vervolgens practicum.
|
| importLock | boolean | Nee | Zorgt ervoor dat op de frontend de cursussen 'gelocked' worden. Hierdoor kunnen de cursussen niet zomaar aangepast worden door gebruikers. Alleen een functioneel beheerder heeft de mogelijkheid om de cursus aan te passen. |
| linkedOrganisations | array | Nee | Hiermee kan je een cursus koppelen aan andere organisaties. De resultaten van deze cursus worden gedeeld en zullen zichtbaar zijn in het resultaten overzicht van de andere organisatie(s). |
## Cursussen ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/subject`
Haalt een lijst met cursussen op.
#### Query Parameters
| Name | Type | Description |
| --------------------------- | ------- | ------------------------------------------------------------------------------------ |
| hasCalendar | boolean | Haal alleen cursussen op waar een of meerdere kalender(s) aan gekoppeld zijn |
| populateLinkedOrganisations | boolean | Voegt alle gekoppelde organisaties toe aan de cursussen |
| populateEditions | boolean | Voegt alle cursusedities toe die aan de cursus gekoppeld zijn |
| populateHasEditions | boolean | Voegt een extra property toe aan de cursussen die bepaald of de cursus edities heeft |
| q | string | Zoeken op cursus (naam, code, externalId) |
| status | string | Filter op active, archived, deleted (default = active) |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"edition": false,
"parent": null,
"language": [
"EN",
"NL"
],
"studyYear": "",
"description": "Dit is een cursus voorbeeld",
"externalId": "123",
"name": "Cursus voorbeeld",
"code": "CV",
"coordinators": [
{
"id": 1,
"user": 2,
"externalId": "ABC",
"name": "Pascal"
}
],
"groups": [
{
"id": 123,
"externalId": "test",
"name": "groepnaam"
}
],
"grades": [
{
"grade": "1",
"periods": [
1,
2,
3
]
}
],
"types": [
{
"index": 0,
"id": 1,
"type": "subject",
"questionList": 343,
"teachers": [
{
"id": 1,
"user": 2,
"externalId": "ABC",
"name": "Pascal"
}
]
},
{
"index": 1,
"id": 123,
"questionList": 342
}
],
"evaluationCalendar": [
{
"startDate": "2021-04-01",
"evaluationName": "Voorbeeld evaluatie",
"evaluationTemplate": "123",
"types": [
{
"id": 17,
"name": "Algemeen"
}
],
"groups": [
{
"externalId": "test",
"id": 123,
"name": "student A"
}
],
"labels": [
{
"name": "Kalender label 1"
},
{
"name": "Kalender label 2"
}
]
}
],
"labels": [
{
"name": "Cursus label 1"
}
],
"data": {
"code": "CV",
"edition": false
}
}
```
{% endtab %}
{% endtabs %}
## Cursus ophalen (item)
`GET` `https://api-portal.evalytics.nl/subject/:id`
Een enkele cursus kan gevonden worden op basis van het extern Id of het interne Id.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------------------- |
| id | string | Intern of externId van de cursus |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"edition": false,
"parent": null,
"language": [
"EN",
"NL"
],
"studyYear": null,
"description": "Dit is een cursus voorbeeld",
"externalId": "123",
"name": "Cursus voorbeeld",
"code": "CV",
"coordinators": [
{
"id": 1,
"user": 2,
"externalId": "ABC",
"name": "Pascal"
}
],
"groups": [
{
"id": 123,
"externalId": "test",
"name": "groepnaam"
}
],
"grades": [
{
"grade": "1",
"periods": [
1,
2,
3
]
}
],
"types": [
{
"index": 0,
"id": 1,
"type": "subject",
"questionSets": [
{
"id": 1,
"name": "Standaard"
},
{
"id": 2,
"name": "test"
}
],
"teachers": [
{
"id": 1,
"user": 2,
"externalId": "ABC",
"name": "Pascal"
}
]
},
{
"index": 1,
"topicType": 124
}
],
"evaluationCalendar": [
{
"startDate": "2021-04-01",
"evaluationName": "Voorbeeld evaluatie",
"evaluationTemplate": "123",
"types": [
{
"id": 17,
"name": "Algemeen"
}
],
"groups": [
{
"externalId": "test",
"id": 123,
"name": "student A"
}
],
"labels": [
{
"name": "Kalender label 1"
},
{
"name": "Kalender label 2"
}
]
}
],
"labels": [
{
"name": "Cursus label 1"
}
],
"linkedOrganisations": [{
"name": "Another organisation",
"code": "AO",
"externalId": "AO-ORG",
"id": 987
}],
"data": {
"code": "CV",
"edition": false
}
}
```
{% endtab %}
{% endtabs %}
## Cursus aanmaken (geen cursus editie)
`POST` `https://api-portal.evalytics.nl/subject`
Maakt een cursus aan
#### Query Parameters
| Name | Type | Description |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| useDefaultQuestionSets | boolean | Als je useDefaultQuestionSets=true meegeeft, zullen de vragensets die je aan de werkvorm(en) hebt gekoppeld, automatisch ook aan de cursus werkvorm(en) gekoppeld worden. |
| strictValidation | boolean | Zet strictValidation aan of uit (default = aan). Als je strictValidation uitzet, zal de cursus wel aangemaakt worden als een docent, werkvorm, groep of coordinator niet door de validatie heen komt. De niet correcte items worden dan niet toegevoegd aan de cursus en zullen als foutmelding in de response teruggegeven worden |
| convertDraftUserToTeacher | boolean | Als er geen docent gevonden kan worden op externalId, zoek dan in conceptgebruikers en zet deze direct om naar een docent. (default: false) |
| enforceUniqueCode | boolean |
Forceert unieke cursuscode. (default: false) Standaard zal een cursuscode niet uniek zijn. Het is mogelijk om dit te controleren bij het aanmaken van een cursus. Als de cursuscode al bestaat wordt er een foutmelding teruggestuurd.
|
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een cursus |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"organisation": 420,
"topOrganisation": 418,
"user": null,
"deleted": false,
"createdBy": "2203",
"modifiedBy": "2225",
"externalId": null,
"archived": false,
"parent": null,
"name": "Example",
"importLock": false,
"description": "Example description",
"data": {
"code": "Test"
},
"id": 4126,
"createdAt": "2021-01-21T12:37:42.000Z",
"updatedAt": "2021-04-06T15:40:42.000Z",
"labels": []
}
```
{% endtab %}
{% endtabs %}
```
{
"externalId": (string),
"languages": (array),
"description": (string),
"name": (string - verplicht),
"importLock": (boolean),
"data": {
"code": (string)
},
"coordinators": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"types": [{
"index": (int),
"id": (int - verplicht),
"type": (string, als alternatief voor id),
"questionSets": [
{
"id": (int)
},
{
"code": (string)
}
],
"teachers": [
{
"id": (int - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
},
{
"externalId": (string - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
}
]
}],
"grades": [{
"grade": (string)
"periods": (array)
}],
"linkedOrganisations": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"evaluationCalendars": [{
"startDate": (date string zoals "2021-02-09"),
"evaluationName": (string),
"workflow": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"types": [
{
"id": (int)
*"orderIndex": (int, update staat nog niet online,
laagste nummer => eerste block,
hoogste => laatste block
)
},
{
"externalId": (string)
}
]
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"labels": [
{
"name": (string)
}
]
}],
"labels": [
{
"name": (string)
}
]
}
```
{% hint style="info" %}
* Bij het meegeven van types kan je ook een type meegeven als in plaats van het interne id
* Bij types bepaald het veld 'index' de volgorde van de blokken bij het aanmaken van de evaluaties
* Als je in het voorbeeld, bijvoorbeeld bij coordinators, externalId en id ziet staan kan je een van deze meegeven.
* Het is niet mogelijk om meerdere items (werkvormen, groepen, coördinatoren) van hetzelfde id/type te koppelen, wij filteren deze items op uniekheid om dubbeling te voorkomen. Bij werkvormen controleren wij op dubbele docenten en vragensets
{% endhint %}
**Docenten en vragensets direct koppelen aan een cursus**
Wanneer een docent of vragenset niet bij een werkvorm moet horen, maar direct op een cursus, geef dan **id: 1** of **type: subject** mee bij een topic type. Voeg vervolgens de docenten/vragensets toe die je wilt koppelen. Als voorbeeld:
```
{
"externalId": (string),
"languages": (array),
"description": (string),
"name": (string - verplicht),
"importLock": (boolean),
"data": {
"code": (string)
},
"types": [{
"index": (int),
"id": (int),
"type": "subject",
"questionSets": [
{
"id": (int)
},
{
"code": (string)
}
],
"teachers": [
{
"id": (int - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
},
{
"externalId": (string - required),
}
]
}]
}
```
#### Voorbeeld response bij strictValidation=false
Als strictValidation uitstaat, geven wij de foutmeldingen terug in de response. In dit voorbeeld kon de groep niet gekoppeld worden, omdat deze niet gevonden kon worden. De cursus is wel aangemaakt.
```
{
"type": 1,
"organisation": 123,
"topOrganisation": 456,
"user": null,
"deleted": false,
"createdBy": "123",
"modifiedBy": "123",
"externalId": null,
"archived": false,
"parent": null,
"name": "Natuurkunde",
"description": "Natuurkunde",
"importLock": false,
"data": {
"code": "test"
},
"id": 1234,
"createdAt": "2021-06-25T08:37:53.000Z",
"updatedAt": "2021-06-29T09:56:20.000Z",
"validationErrors": [
{
"message": "The group with id '1234' could not be found",
"errorCode": "5d71f131-e1ee-47ce-8a8a-7785e9feae6e",
"object": {
"id": 78378437
}
}
],
"studyYear": null,
"languages": null,
"groups": [],
"coordinators": [],
"labels": []
}
```
## Cursus aanmaken (editie)
`POST` `https://api-portal.evalytics.nl/subject`
Het is mogelijk om cursussen op te splitsen in cursusedities. Je koppelt dan een cursuseditie aan een 'normale' cursus (zie voorbeeld hierboven). Er zijn wat verschillen in het aanmaken van een cursus editie en een cursus:\
\- Om een cursus editie aan te maken geef je **parent: {id: (int)}** of **parent: {externalId: (string)}** mee, samen met **edition: true** in het data veld. Het id van de parent is de cursus waar je de editie aan wilt koppelen\
\- Bij cursusedities is het mogelijk om het veld **studyYear** te gebruiken.
#### Path Parameters
| Name | Type | Description |
| ----------------- | ------- | ---------------------------------- |
| enforceUniqueCode | boolean | Verplicht dat code uniek moet zijn |
#### Query Parameters
| Name | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een cursus |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"organisation": 101,
"topOrganisation": 100,
"user": null,
"deleted": false,
"createdBy": "123",
"modifiedBy": "123",
"externalId": null,
"archived": false,
"parent": {
"id": 1,
"externalId: "abc"
},
"importLock": false,
"name": "Example",
"description": "Example description",
"data": {
"code": "Test",
"edition": true
},
"id": 1234,
"createdAt": "2021-01-21T12:37:42.000Z",
"updatedAt": "2021-04-06T15:40:42.000Z",
"labels": []
}
```
{% endtab %}
{% endtabs %}
```
{
"externalId": (string),
"languages": (array),
"description": (string),
"name": (string - verplicht),
"importLock": (boolean),
"parent": {
"id": (int),
"externalId": (string)
}
"data": {
"code": (string),
"edition": (boolean),
"studyYear": (string)
},
"coordinators": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"types": [{
"index": (int),
"id": (int - verplicht),
"type": (string, als alternatief voor id),
"questionSets": [
{
"id": (int)
},
{
"code": (string)
}
],
"teachers": [
{
"id": (int - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
},
{
"externalId": (string - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
}
]
}],
"grades": [{
"grade": (string)
"periods": (array)
}],
"linkedOrganisations": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"evaluationCalendars": [{
"startDate": (date string zoals "2021-02-09"),
"evaluationName": (string),
"workflow": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"types": [
{
"id": (int)
*"orderIndex": (int, update staat nog niet online,
laagste nummer => eerste block,
hoogste => laatste block
)
},
{
"externalId": (string)
}
]
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"labels": [
{
"name": (string)
}
]
}],
"labels": [
{
"name": (string)
}
]
}
```
{% hint style="info" %}
* Voor het toevoegen van types, groepen, coordinators: zie **cursus aanmaken (geen editie)**
* Bij parent kan je een **id** of **externalId** meegeven waarop de cursuseditie gekoppeld zal worden
{% endhint %}
## Cursus bijwerken
`PUT` `https://api-portal.evalytics.nl/subject/:id`
Een cursus bijwerken werkt op dezelfde manier als een cursus aanmaken.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------------------ |
| id | string | id of externalId van de cursus |
#### Query Parameters
| Name | Type | Description |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| useExternalIdForCalendar | boolean | Als je useExternalIdForCalendar=true meegeeft wordt een kalender geüpdate/aangemaakt op basis van externalId. |
| useDefaultQuestionSets | boolean | Als je useDefaultQuestionSets=true meegeeft, zullen de vragensets die je aan de werkvorm(en) heb gekoppeld, automatisch ook aan de cursus werkvorm(en) gekoppeld worden |
| strictValidation | boolean | Zet strictValidation aan of uit (default = aan). Als je strictValidation uitzet, zal de cursus wel aangemaakt worden als een docent, werkvorm, groep of coordinator niet door de validatie heen komt. De niet correcte items worden dan niet toegevoegd aan de cursus en zullen als foutmelding in de response teruggegeven worden. |
| enforceUniqueCode | boolean | Verplicht unieke cursuscode |
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een cursus |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"organisation": 101,
"topOrganisation": 100,
"user": null,
"deleted": false,
"createdBy": "123",
"modifiedBy": "123",
"externalId": null,
"archived": false,
"parent": {
"id": 1,
"externalId: "abc"
},
"name": "Example",
"description": "Example description",
"importLock": false,
"data": {
"code": "Test",
"edition": true
},
"id": 1234,
"createdAt": "2021-01-21T12:37:42.000Z",
"updatedAt": "2021-04-06T15:40:42.000Z",
"labels": []
}
```
{% endtab %}
{% endtabs %}
```
{
"externalId": (string),
"languages": (array),
"description": (string),
"name": (string - verplicht),
"importLock": (boolean),
"data": {
"code": (string)
},
"coordinators": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}],
"types": [{
"index": (int),
"id": (int - verplicht),
"type": (string, als alternatief voor id),
"questionSets": [{
"id": 1 (int)
}, {
"code": (string)
}],
"teachers": [{
"id": (int - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
},
{
"externalId": (string - required),
"isWorkingStudent": (boolean),
"isGuestTeacher": (boolean)
}]
}],
"linkedOrganisations": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"evaluationCalendars": [{
"startDate": (date string zoals "2021-02-09"),
"evaluationName": (string),
"workflow": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"types": [
{
"id": (int)
*"orderIndex":(int, update staat nog niet online,
laagste nummer => eerste block,
hoogste => laatste block
)
},
{
"externalId": (string)
}
]
"groups": [
{
"id": (int)
},
{
"externalId": (string)
}
],
"labels": [
{
"name": (string)
}
]
}]
}
```
{% hint style="info" %}
Als geen group, coordinators, types, linkedOrganisations meegeeft, zullen deze items niet overschreven worden. Mocht je toch willen dat de gegevens overschreven worden, geef dan een leeg array mee
{% endhint %}
## Cursus verwijderen
`DELETE` `https://api-portal.evalytics.nl/subject/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | ---------------------------------- |
| id | boolean | intern of externalId van de cursus |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ----------------------------------- |
| undo | boolean | Maak de verwijdering actie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Docent toevoegen aan een cursus (intern id)
`POST` `https://api-portal.evalytics.nl/subject/:id:/teacher`
Hiermee kan je een docent toevoegen aan een cursus. Als het gelukt is krijg je als response de cursus terug.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------- |
| id | string | Intern id van de cursus |
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"organisation": 101,
"topOrganisation": 100,
"user": null,
"deleted": false,
"createdBy": "123",
"modifiedBy": "123",
"externalId": null,
"archived": false,
"parent": {
"id": 1,
"externalId: "abc"
},
"name": "Example",
"description": "Example description",
"data": {
"code": "Test",
"edition": true
},
"id": 1234,
"createdAt": "2021-01-21T12:37:42.000Z",
"updatedAt": "2021-04-06T15:40:42.000Z",
"labels": []
}
```
{% endtab %}
{% endtabs %}
**Docent toevoegen op basis van intern id:**
```
{
"teacherId": (int)
}
```
{% hint style="info" %}
Als je gebruikt maakt van externe id: Zie onderdeel **Docent toevoegen aan een cursus (extern id)**
{% endhint %}
## Docent toevoegen aan een cursus (extern id)
`POST` `https://api-portal.evalytics.nl/subject/teacher/identifier/externalId`
Hiermee kan je een docent toevoegen aan een cursus doormiddel van het externe id
{% tabs %}
{% tab title="200 " %}
```
{
"type": 1,
"organisation": 101,
"topOrganisation": 100,
"user": null,
"deleted": false,
"createdBy": "123",
"modifiedBy": "123",
"externalId": null,
"archived": false,
"parent": {
"id": 1,
"externalId: "abc"
},
"name": "Example",
"description": "Example description",
"data": {
"code": "Test",
"edition": true
},
"id": 1234,
"createdAt": "2021-01-21T12:37:42.000Z",
"updatedAt": "2021-04-06T15:40:42.000Z",
"labels": []
}
```
{% endtab %}
{% endtabs %}
```
{
"identifier": {
"externalId": (string),
"teacher": {
"externalId": (string)
}
}
}
```
## Docent verwijderen van een cursus (intern id)
`DELETE` `https://api-portal.evalytics.nl/subject/:subjectId/teacher/teacherId`
Het is mogelijk om een docent te verwijderen van een cursus. Geef hiervoor het interne cursus id en de docent id mee. Je zal een 200 OK response terugkrijgen als het gelukt is.
#### Path Parameters
| Name | Type | Description |
| --------- | ------- | -------------------- |
| teacherId | integer | Het id van de docent |
| subjectId | integer | Het id van de cursus |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Docent verwijderen van de cursus (extern id)
`DELETE` `https://api-portal.evalytics.nl/subject/teacher/identifier/externalId`
Hiermee kan je een docent verwijderen van een cursus door middel van het externe id
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"identifier": {
"externalId": (string),
"teacher": {
"externalId": (string)
}
}
}
```
## Werkvorm toevoegen aan een cursus
`POST` `https://api-portal.evalytics.nl/subjects/:id/topicType`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------- |
| id | string | Id of extern id van de cursus |
#### Query Parameters
| Name | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een cursus |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"id": (int - required when no type is given),
"type": (string - required when no id is given)
"index": (int),
"teachers": [{
"id": (int)
}, {
"externalId": (string)
}],
"index": (int)
}
```
## Werkvorm verwijderen van een cursus
`DELETE` `https://api-portal.evalytics.nl/subject/:id/topicType`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------- |
| id | string | Id of extern id van de cursus |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"id": (int)
}
OR
{
"type": (string)
}
```
## Gekoppelde organisaties van cursus (resultaten) ophalen
`GET` `https://api-portal.evalytics.nl/subject/:id/linkedOrganisations`
Het is mogelijk om cursus resultaten te delen met andere organisaties. Met dit endpoint kan je een lijst ophalen met alle gedeelde organisaties voor de desbetreffende cursus.
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | ------------------------------ |
| id | integer | Id of externalId van de cursus |
{% tabs %}
{% tab title="200 " %}
```
[
{
"id": 632,
"name": "Example 1",
"code": "e1",
"type": "department",
"externalId": "ABC"
},
{
"id": 633,
"name": "Example 2",
"code": "e2",
"type": "department",
"externalId": null
}
]
```
{% endtab %}
{% endtabs %}
## Organisatie(s) koppelen aan cursus
`POST` `https://api-portal.evalytics.nl/subject/:id/linkedOrganisations`
Met dit endpoint kun je een cursus koppelen aan een andere organisatie. Hierdoor worden resultaten van deze cursus gedeeld met de organisatie(s) die je opgeeft. De resultaten van deze cursus zijn zichtbaar in het resultaten overzicht van de organisatie waarmee je de resultaten deelt.
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | ---------------- |
| id | integer | Id van de cursus |
#### Query Parameters
| Name | Type | Description |
| --------- | ------- | ---------------------------------------------------------------------------------- |
| overwrite | boolean | Overschrijf eventueel al gekoppelde opleidingen die aan deze cursus gekoppeld zijn |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"id": (number)
"organisationArray": [
{
"id": (int)
}, {
"externalId": (string)
}
]
}
```
# Generic topics
### Overview terms
Name
Type
Required
Description
Name
string
Yes
Name of the generic topic
Description
string
No
Description of the generic topic
Code
string
No
Code of the generic topic
externalId
string
No
Probably needed when using the API with externalIds
blocks
Array object
No
You can pass a block object to the generic topic. This block will be used when creating an evaluation from a calendar.
block->topicType
String
Yes (in a block object)
The block type (you can manage generic topic blocks on top organisation)
block->questionSets
Array object
No
Array of questionSet ids. You can use id or code of the questionSet [{id: number, code: string}]
block->index
integer
No
Order of the blocks
labels
Array object
No
Add labels to the generic topic
labels->name
string
Yes (in a label object)
name of the label
## Get a list of generic topics
`GET` `https://api-portal.evalytics.nl/genericTopic`
#### Query Parameters
| Name | Type | Description |
| -------------- | ------------ | ----------------------------------------------------------- |
| q | String | Search for a specific generic topic |
| archived | boolean | Filter generic topics on archived (default=null) |
| populateBlocks | boolean | Populate blocks object (default = false) |
| populateLabels | boolean | Populate labels (default = false) |
| skip | number | Total items to be skipped for pagination (default=0) |
| limit | number | Limit the total items returned from the api (default=30) |
| status | string array | Filter list on active, archived, deleted (default = active) |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"metadata": {
"timestamp": "2023-01-11T10:00:37.605Z",
"resultSet": {
"count": 1,
"limit": 30,
"skip": 0
}
},
"results": [
{
"id": 1,
"name": "Example topic",
"description": "",
"externalId": "",
"code": "",
"organisation": 4,
"topOrganisation": 3,
"updatedAt": null,
"modifiedBy": null,
"createdAt": "2023-01-03T16:08:45.000Z",
"createdBy": 1,
"deleted": false,
"archived": false,
"labels": [{
"name": "Example label"
}]
}
]
}
```
{% endtab %}
{% endtabs %}
## Get a generic topic
`GET` `https://api-portal.evalytics.nl/genericTopic/:id`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------------------------------ |
| id\* | number | Id or externalId of the genericTopic |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"id": 1,
"name": "Example topic",
"description": "",
"externalId": "",
"code": "",
"organisation": 4,
"topOrganisation": 3,
"updatedAt": null,
"modifiedBy": null,
"createdAt": "2023-01-03T16:08:45.000Z",
"createdBy": 1,
"deleted": false,
"archived": false,
"labels": [{
"name": "Example label"
}]
}
```
{% endtab %}
{% endtabs %}
## Creates a generic topic
`POST` `https://api-portal.evalytics.nl/genericTopic`
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"id": 1,
"name": "Example topic",
"description": "",
"externalId": "",
"code": "",
"organisation": 4,
"topOrganisation": 3,
"updatedAt": null,
"modifiedBy": null,
"createdAt": "2023-01-03T16:08:45.000Z",
"createdBy": 1,
"deleted": false,
"archived": false,
"labels": [{
"name": "Example label"
}]
}
```
{% endtab %}
{% endtabs %}
```json
{
"name": (string - required),
"description": (string),
"code": (string),
"externalId": (string),
"blocks": [{
"name": (string - required),
"topicType": {
"id": (integer - required or use type),
"type": (string - required or use id)
} - (required),
"index": (integer),
"questionSets": [{
"id": (integer - required or use code),
"code": (string - required or use id)
}] - (optional)
}]- (optional),
"labels": [{
"name": (string - required)
}] - (optional)
}
```
## Update a generic topic
`PUT` `https://api-portal.evalytics.nl/genericTopic/:id`
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"id": 1,
"name": "Example topic updated",
"description": "",
"externalId": "",
"code": "",
"organisation": 4,
"topOrganisation": 3,
"updatedAt": null,
"modifiedBy": null,
"createdAt": "2023-01-03T16:08:45.000Z",
"createdBy": 1,
"deleted": false,
"archived": false,
"labels": [{
"name": "Example label"
}]
}
```
{% endtab %}
{% endtabs %}
```json
{
"name": (string - required),
"description": (string),
"code": (string),
"externalId": (string),
"blocks": [{
"topicType": {
"id": (integer - required or use type),
"type": (string - required or use id)
}
"index": (integer),
"questionSets": [{
"id": (integer - required or use code),
"code": (string - required or use id)
}] - (optional)
}]- (optional),
"labels": [{
"name": (string - required)
}] - (optional)
}
```
## Archive a generic topic
`POST` `https://api-portal.evalytics.nl/genericTopic/:id/archive`
#### Path Parameters
| Name | Type | Description |
| ---------------------------------- | ------ | ------------------------------------ |
| \* | number | id or externalId of the genericTopic |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ------------------------- |
| undo | boolean | Undo the archiving action |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
## Delete a generic topic
`DELETE` `https://api-portal.evalytics.nl/genericTopic/:id`
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------------------------------ |
| id\* | number | id or externalId of the genericTopic |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ------------------------- |
| undo | boolean | Undo the archiving action |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
# Groepen
Groepen bevatten de gegevens (minimaal e-mailadres) van de studenten/respondenten bij evaluaties op uitnodiging. Vinden er alleen evaluaties live in de klas plaats, dan zijn groepen niet van toepassing.
### **Overzichtstabel termen**
| Naam | Type | Verplicht | Omschrijving |
| --------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| name | string | Ja | Eigen naam (identificatie) voor de studentengroep |
| description | string | Nee | Omschrijving van de cursus |
| externalId | string | Nee | Dit kan een id van de groep in het eigen systeem zijn. Zie het onderdeel over externalId voor meer informatie. Dit veld is wel verplicht als je gebruik maakt van externalId voor groepen |
| participants | array | Nee |
Een lijst met participanten die aan de groep toegevoegd kunnen worden. Geef per participant een e-mailadres mee en optioneel een naam of externalId. Let op: Op het portaal is het wel verplicht om deelnemers toe te voegen
Het is ook mogelijk om participanten te labelen. Deze labels kunnen eind gebruikers vervolgens gebruiken om resultaten te filteren. Wijzigingen in labels bij deelnemers worden alleen toegepast op nieuwe evaluaties. Oude resultaten blijven ongewijzigd.
|
| organisation | int | n.v.t. | **De organisatie waar de groep aan gekoppeld is** |
| topOrganisation | int | n.v.t. | **Geeft aan wat de hoofdorganisatie is waar de groep aan gekoppeld is** |
| id | int | Ja*\** | *Alleen nodig bij updaten* |
| importLock | boolean | Nee | Zorgt ervoor dat op de frontend de groepen 'gelocked' worden. Hierdoor kunnen de groepen niet zomaar aangepast worden door gebruikers. Alleen een functioneel beheerder heeft de mogelijkheid om de groep aan te passen. |
| integrations | array | Nee | Nodig als er gebruik wordt gemaakt van de LTI integratie |
## Groepen ophalen (Lijst)
`GET` `https://api-portal.evalytics.nl/group`
Haalt een lijst op met groepen die aan de organisatie zijn gekoppeld
#### Query Parameters
| Name | Type | Description |
| -------- | ------------ | ------------------------------------------------------- |
| archived | boolean | Filteren op gearchiveerde of niet gearchiveerde groepen |
| q | string | Zoeken binnen groepen (naam, omschrijving, externalId) |
| status | string array | Filter op active, archived, deleted (default = active) |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-02-08T20:35:30.186Z",
"resultSet": {
"count": 4,
"limit": 30
}
},
"results": [
{
"organisation": 101,
"topOrganisation": 100,
"deleted": false,
"createdBy": "2144",
"modifiedBy": null,
"externalId": "group1",
"archived": false,
"name": "Groep studenten",
"description": "Studenten",
"id": 1233,
"createdAt": "2020-12-21T16:17:55.000Z",
"updatedAt": "2020-12-21T16:17:55.000Z",
"totalParticipants": 10
},
{
"organisation": 101,
"topOrganisation": 100,
"deleted": false,
"createdBy": "1234",
"modifiedBy": null,
"externalId": "group2",
"archived": false,
"name": "groep 2",
"description": "Example groep 2",
"id": 1234,
"createdAt": "2021-02-08T20:35:11.000Z",
"updatedAt": "2021-02-08T20:35:11.000Z",
"totalParticipants": 5
}
]
}
```
{% endtab %}
{% endtabs %}
## Groep ophalen (item)
`GET` `https://api-portal.evalytics.nl/group/:id`
Hiermee kan je een enkele groep ophalen. De lijst met deelnemers wordt ook meegestuurd in de response
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------- |
| id | string | Interne of externalId van de groep |
{% tabs %}
{% tab title="200 " %}
```
{
"participants": [
{
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"name": "",
"email": "example@evalytics.nl",
"externalId": null,
"id": 12345,
"createdAt": "2021-01-14T11:10:17.000Z",
"updatedAt": "2021-01-14T11:10:17.000Z",
"group": 1234
}
],
"organisation": 101,
"topOrganisation": 100,
"deleted": false,
"createdBy": "3",
"modifiedBy": null,
"externalId": null,
"archived": false,
"name": "New group",
"description": "Groep met studenten",
"id": 1234,
"createdAt": "2021-01-14T11:10:17.000Z",
"updatedAt": "2021-01-14T11:10:17.000Z"
}
```
{% endtab %}
{% endtabs %}
## Groep aanmaken
`POST` `https://api-portal.evalytics.nl/group`
Maak een groep aan. Het meesturen van participants is niet verplicht.
{% tabs %}
{% tab title="200 " %}
```
{
"name": "Groep voorbeeld",
"description": "Groep voorbeeld omschrijving",
"externalId": "abcd",
"createdBy": "123",
"organisation": 101,
"topOrganisation": 100,
"deleted": false,
"archived": false,
"createdAt": "2021-04-08T11:10:21.000Z",
"updatedAt": "2021-04-08T11:10:21.000Z",
"id": 1234,
"modifiedBy": null,
"importLock": false
}
```
{% endtab %}
{% endtabs %}
```json
{
"name": (string - verplicht),
"description": (string),
"externalId": (string)
"participants": [
{
"externalId": (string),
"name": (string),
"email": (string - email - verplicht),
"labels": [{
"name": (string - verplicht)
}],
"integrations": [{
"type": "sisIntegrationId",
"id": (string)
}]
}
],
"importLock": (boolean)
}
```
## Groep bijwerken
`POST` `https://api-portal.evalytics.nl/group/:id`
Bijwerken van een groep
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------- |
| id | string | Interne of externalId van de groep |
#### Query parameters
| Name | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------- |
| updateEvaluations | boolean | Past de deelnemers direct aan in evaluaties waar deze groep aan gekoppeld is |
{% tabs %}
{% tab title="200 " %}
```
{
"name": "Groep voorbeeld",
"description": "Groep voorbeeld omschrijving",
"externalId": "abcd",
"createdBy": "123",
"organisation": 101,
"topOrganisation": 100,
"deleted": false,
"archived": false,
"createdAt": "2021-04-08T11:10:21.000Z",
"updatedAt": "2021-04-08T11:10:21.000Z",
"id": 1234,
"modifiedBy": null,
"importLock": false
}
```
{% endtab %}
{% endtabs %}
```json
{
"name": (string - verplicht),
"description": (string),
"externalId": (string)
"participants": [
{
"externalId": (string),
"name": (string),
"email": (string - email - verplicht),
"labels": [{
"name": (string - verplicht)
}],
"integrations": [{
"type": "sisIntegrationId",
"id": (string)
}]
}
],
"importLock": (boolean)
}
```
## Groep verwijderen
`DELETE` `https://api-portal.evalytics.nl/group/:id`
Verwijderen van een groep. Door undo=true mee te geven kan je de actie ongedaan maken
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------- |
| id | string | Id of externalId van de groep |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | --------------------------------------------------------------- |
| undo | boolean | Door undo=true mee te geven maak je de verwijder actie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Groep archiveren
`POST` `https://api-portal.evalytics.nl/group/:id/archive`
Groep archiveren
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------- |
| id | string | Id of externalId van de groep |
#### Query Parameters
| Name | Type | Description |
| ---- | ------ | ---------------------------------------------------------- |
| undo | string | Door undo=true mee te geve maak je de archivering ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Deelnemer toevoegen aan groep
`POST` `https://api-portal.evalytics.nl/group/:id/participant`
Voeg een nieuwe deelnemer toe aan een groep. Indien de deelnemer al bestaat, krijg je geen foutmelding maar een 200 OK terug. Kan beheerd worden op basis van extern id.
Met participantUpdateType=email|externalId kan je de check of een deelnemer al bestaat op externalId of op email (default) uitvoeren. Als een deelnemer al bestaat worden de andere gegevens (name, labels, ...) overschreven.
Het is niet mogelijk om meerdere deelnemers met hetzelfde e-mail toe te voegen.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ------------------------------------- |
| id\* | string | Interne id of externalId van de groep |
| participantUpdateType | string | externalId of email (default = email) |
{% tabs %}
{% tab title="200 " %}
```
{
"deleted": false,
"createdBy": "1",
"modifiedBy": null,
"name": "pascal",
"email": "example@evalytics.nl",
"externalId": "exampleExternalId",
"group": 123,
"id": 456,
"createdAt": "2021-03-02T08:54:25.000Z",
"updatedAt": "2021-03-02T08:54:36.000Z"
}
```
{% endtab %}
{% endtabs %}
```json
{
"name": (string),
"email": (string - verplicht),
"externalId": (string),
"labels": [{
"name": (string)
}],
"integrations": [{
"type": "sisIntegrationId",
"id": (string)
}]
}
```
## Deelnemer toevoegen aan groep (identifier)
`POST` `https://api-portal.evalytics.nl/group/participant/identifier/externalId`
Voeg een deelnemer toe aan een groep met als identifier het externalId\
TODO: Meer typen zijn mogelijk
{% tabs %}
{% tab title="200 " %}
```
{
"deleted": false,
"createdBy": "123",
"modifiedBy": null,
"name": "example",
"email": "example+example@evalytics.nl",
"externalId": "exampleExternalId",
"group": 1234,
"id": 123456,
"createdAt": "2021-03-02T08:54:25.000Z",
"updatedAt": "2021-03-02T08:54:36.000Z"
}
```
{% endtab %}
{% endtabs %}
```
{
"identifier": {
"externalId": (string - verplicht - externalId van de groep)
},
"data": {
"name": (string),
"email": (string - verplicht),
"externalId": (string - verplicht - externalId van de deelnemer),
"labels": [{
"name": (string)
}]
}
}
```
## Deelnemer verwijderen van groep
`DELETE` `https://api-portal.evalytics.nl/group/:id/participant/:participantId`
Verwijderd een deelnemer uit een groep. Als het gelukt is krijg je een 200 OK terug
#### Path Parameters
| Name | Type | Description |
| ------------- | ------ | ----------------------------------------- |
| participantId | string | Interne id of externalId van de deelnemer |
| id | string | Interne id of externalId van de groep |
{% tabs %}
{% tab title="200 " %}
```
{
"removed": {
"id": "92294",
"group": "7397"
}
}
```
{% endtab %}
{% endtabs %}
## Deelnemer verwijderen van groep (identifier)
`DELETE` `https://api-portal.evalytics.nl/group/participant/identifier/externalId`
Verwijderd een deelnemer van een groep op basis van identifier. \
TODO: meerdere identifiers zijn mogelijk
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"identifier": {
"externalId": (string - verplicht - externalId van de groep),
"participant": {
"externalId": (string - verplicht - externalId van de deelnemer)
}
}
}
```
## Deelnemers in bulk importeren
`POST` `https://api-portal.evalytics.nl/group/bulkImportParticipants`
Hiermee is het mogelijk om in bulk deelnemers toe te voegen aan groepen doormiddel van een CSV import. Als de groupId een externalId is, voeg dan external=true toe.
#### Path Parameters
| Name | Type | Description |
| -------- | ------- | ----------------------------------------- |
| external | boolean | De groupId in het bestand is een externId |
#### Headers
| Name | Type | Description |
| ------------ | ------ | ------------------- |
| Content-Type | string | multipart/form-data |
#### Request Body
| Name | Type | Description |
| ---- | ------ | --------------- |
| file | object | Het CSV bestand |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% file src="/files/-MdXYqcLcD-5rSlvaD1H" %}
Import example
{% endfile %}
{% hint style="info" %}
* Bestaande deelnemers in de import worden eventueel bijgewerkt
{% endhint %}
## Deelnemer in groep bijwerken
`PUT` `https://api-portal.evalytics.nl/group/:id/participant`
Update een deelnemer in een groep. Als identifier kan je **email** of **externalId** gebruiken.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ---------------- |
| id\* | String | id of externalId |
{% tabs %}
{% tab title="200: OK " %}
```json
[
{
"id": 1,
"email": "dev@evalytics.nl",
"integrations": [
{
"type": "sisIntegrationId",
"id": "1234"
}
],
"name": "Dev student"
}
]
```
{% endtab %}
{% endtabs %}
# Evaluation calendar
De evaluatiekalender is een mechanisme waarmee de creatie van evaluaties gepland kan worden. Items in de evaluatiekalender zijn altijd gekoppeld aan een cursus en aan een workflow (voorheen: evaluatietemplate). De workflow bepaalt de cyclus (bijvoorbeeld welke stappen de evaluatie doorloopt). De evaluatiekalender bepaalt voor welke cursus er op welk moment een evaluatie uitgevoerd moet worden. Evalytics maakt vlak voor aanvang van de evaluatiecyclus automatisch een evaluatie aan.
### Overzichtstabel termen
| Naam | Type | Verplicht | Omschrijving |
| ------------------------ | -------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| topic | object | Ja (of geef genericTopic object mee) | Het externalId of interne id van de cursus waaraan de evaluatiekalender gekoppeld moet worden. |
| externalId | string | Nee | Externe id van de evaluatiekalender |
| startDate | string | Nee |
Startdatum moet in de toekomst liggen en geeft aan wanneer de evaluatie aangemaakt moet worden. Het meegeven van een startdatum is niet verplicht.
Als voorbeeld: "2021-04-01".
|
| evaluation | int | n.v.t. | Het id van de evaluatie die is aangemaakt door dit kalender item. Als er nog geen evaluatie is aangemaakt is dit *null*. |
| evaluationName | string | Ja | Naam van de evaluatie die aangemaakt gaat worden. |
| workflow | object | Ja | De workflow die gekoppeld gaat worden aan de kalender. |
| types | Object array | Nee |
Werkvormen die gekoppeld moeten worden aan de evaluatiekalender.
Je kunt de gekoppelde docenten nog wijzigen door een nieuw teacher array mee geven. Als je niks meegeeft, worden de standaard docenten die aan de werkvormen gekoppeld zijn gebruikt. De volgorde van de werkvormen wordt bepaald door de volgorde die je hebt ingesteld bij de cursus.
|
| Groups | Object array | Nee | Groepen die gebruikt worden bij het maken van de evaluatie. Wanneer de evaluatie op uitnodiging is zullen de studenten uit deze groepen worden uitgenodigd. |
| Labels | Object array | Nee | De labels die in de evaluatie gezet zullen worden. Labels kunnen worden gebruikt om evaluaties te filteren. |
| Checked | Object | n.v.t. | Geeft aan of de evaluatie gecontroleerd is en door wie/wanneer. Het is in te stellen dat de evaluatie pas gestart wordt wanneer deze gecontroleerd is. |
| creationStartDate | unix timestamp | nvt | Geeft aan wanneer de evaluatie aangemaakt zal gaan worden |
| importLock | boolean | Nee | Zorgt ervoor dat op de frontend de evaluatie kalender items 'gelocked' worden. Hierdoor kunnen de evaluatie kalender items niet zomaar aangepast worden door gebruikers. Alleen een functioneel beheerder heeft de mogelijkheid ze aan te passen. |
| shouldNotUpdateStartDate | boolean | nvt | Als gebruiker is het mogelijk om een startdatum van een kalender item vast te zetten. Als deze waarde op true is moet de koppeling zorgen dat er geen nieuwe startdatum wordt meegegeven bij het updaten van de evaluatiekalender. |
| genericTopic | Object | Ja \* (of geef topic object mee) | Een kalender kan ook gekoppeld worden aan geen onderwerp (genericTopic) in plaas van aan een cursus/docent/toets |
| creationStatus | string | Nee | Kan zijn: "active", "canceled", "paused" |
## Evaluatiekalender items ophalen (Lijst)
`GET` `https://api-portal.evalytics.nl/evaluationCalendar`
Haal een lijst op met evaluatiekalender items die gekoppeld zijn aan de organisatie. Standaard geven wij basis informatie terug. Met bepaalde populate opties zal deze info ook meegestuurd worden.
#### Query Parameters
| Name | Type | Description |
| ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| topic | string | Filter op een (array van) topic id(s) die gebruikt worden in de evaluatie kalender. |
| calendarStatus | string | Filtert op de kalender status van de kalendar items. Kan of 'planned' zijn voor kalender items die nog geen evaluatie hebben aangemaakt of 'completed' voor kalender items die wel al een evaluatie hebben aangemaakt |
| workflow | string | Filter op een (array van) workflow id(s) die gebruikt worden in de evaluatie kalender. |
| afterDate | string | Laat alleen kalenders van wie de evaluatie na deze datum begint. (voorbeeld: 2023-12-02 03:00:00) |
| archived | boolean | Filter op gearchiveerde kalender items |
| q | string | Zoeken op naam |
| populateTopic | boolean | Cursus naam en code koppelen aan de kalender items |
| populateWithChecked | boolean | Gecontroleerd status koppelen aan de kalender items |
| populateWithTypes | boolean | Werkvormen koppelen aan de kalender items |
| populateWithLabels | boolean | Labels koppelen aan de kalender items |
| populateWithGroups | boolean | Groepen koppelen aan de kalender items |
| status | string array | active, deleted, archived |
| genericTopic | number array | Filter op een (array van) genericTopic id(s) die gebruikt worden in de evaluatie kalender. |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
...
},
"results": [
{
"types": [
{
"id": 1,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"teachers": [
{
"name": "Example Teacher",
"id": 4144,
"externalId": "Teacher External Id 7"
}
]
}
],
"groups": [
{
"id": 1800,
"name": "Example Group",
"externalId": null
}
],
"archived": 0,
"checked": [],
"labels": [
{
"name": "label1",
"id": 717
},
{
"name": "label2",
"id": 718
}
],
"deleted": 0,
"createdBy": "3",
"modifiedBy": "3",
"id": 114,
"topic": {
"id": 4327,
"name": "Example Subject"
},
"externalId": "External Id Calendar 56",
"startDate": "2025-12-02T02:00:00.000Z",
"creationStartDate": 1615413600,
"evaluation": null,
"evaluationName": "Example Calendar Evaluation",
"shouldNotUpdateStartDate": false,
"workflow": {
"id": 42,
"name": "Example Workflow",
"externalId": "",
"topicType": 1,
"extraOptions": {},
"visibility": "code",
"evaluationDays": 30
},
"importLock": 1,
"organisation": 688,
"topOrganisation": 418,
"createdAt": "2021-05-10 15:25:00",
"updatedAt": "2021-05-10 15:25:00",
"topicCode": "ExampleSub"
}
]
}
```
{% endtab %}
{% endtabs %}
## Evaluatiekalender ophalen (item)
`GET` `https://api-portal.evalytics.nl/evaluationCalendar/:id`
Haalt een enkele evaluatiekalender item op
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------------- |
| id | string | Interne id van de evaluatiekalender |
{% tabs %}
{% tab title="200 " %}
```
{
"types": [
{
"id": 1,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"teachers": [
{
"name": "Example Teacher",
"id": 4144,
"externalId": "Example External Id 6"
}
]
}
],
"groups": [
{
"id": 1800,
"name": "Example Group",
"externalId": null
}
],
"archived": 0,
"checked": [],
"labels": [
{
"name": "label1",
"id": 717
},
{
"name": "label2",
"id": 718
}
],
"deleted": 0,
"importLock": 1,
"createdBy": "3",
"modifiedBy": "3",
"id": 114,
"topic": {
"id": 4327,
"name": "Example Subject",
"externalId": null
},
"externalId": "Calendar External Id 6",
"startDate": "2025-12-02T02:00:00.000Z",
"creationStartDate": 1615413600,
"evaluation": null,
"evaluationName": "Calendar Example Evaluation",
"shouldNotUpdateStartDate": false,
"workflow": {
"id": 42,
"name": "Example Workflow",
"externalId": "Workflow External Id 5",
"topicType": 1,
"extraOptions": {},
"evaluationDays": 30,
"visibility": "invitation"
},
"organisation": 688,
"topOrganisation": 418,
"createdAt": "2021-05-10 15:25:00",
"updatedAt": "2021-05-10 15:25:00"
}
```
{% endtab %}
{% endtabs %}
## Evaluatiekalender aanmaken
`POST` `https://api-portal.evalytics.nl/evaluationCalendar`
Maak een kalender item aan.
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| strictValidation | boolean | Als je strictValidation op false zet, zal er minder streng gecontroleerd worden op het aanmaken van een evaluationCalendar. Docenten, groepen, werkvormen die niet bestaan, zullen eruit gefilterd worden (Default = true) |
{% tabs %}
{% tab title="200 " %}
```
{
"types": [
{
"id": 1,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"teachers": [
{
"name": "Example Teacher",
"id": 4144,
"externalId": "ExampleExternalTeacher4"
}
]
}
],
"groups": [
{
"id": 1800,
"name": "Example Group",
"externalId": null
}
],
"archived": 0,
"checked": [],
"labels": [
{
"name": "label1",
"id": 717
},
{
"name": "label2",
"id": 718
}
],
"deleted": 0,
"createdBy": "3",
"modifiedBy": "3",
"id": 114,
"topic": {
"id": 4327,
"name": "Example Subject",
"externalId": null
},
"externalId": "buiten23",
"startDate": "2025-12-02T02:00:00.000Z",
"evaluation": null,
"evaluationName": "ExampleCalendarEvaluation",
"workflow": {
"id": 42,
"name": "Example Workflow",
"externalId": "",
"topicType": 1,
"extraOptions": {}
},
"organisation": 688,
"topOrganisation": 418,
"createdAt": "2021-05-10 15:25:00",
"updatedAt": "2021-05-10 15:25:00"
}
```
{% endtab %}
{% endtabs %}
```json
{
"topic": {
"id": (int - verplicht als je geen externalId gebruikt),
"externalId": (string - verplicht als je geen id gebruikt),
"name": (**deprecated** - string - verplicht indien je gebruik maakt van willekeurig onderwerp)
"integrations": [
{
"id": (string),
"type": ("canvasId" of "canvasSisId")
}
]
} - (required - of gebruik genericTopic),
"genericTopic": {
"id": (number - required of gebruik externalId),
"externalId": (string - required of gebruik id)
} (required of gebruik topic)
"externalId": (string)
"startDate": (date string - Voorbeeld: "2021-01-01"),
"evaluationName": (string),
"importLock": (boolean),
"workflow": {
"id": (int - verplicht of externalId),
"externalId": (string - verplicht of id)
},
"types": [{
"id": (int - verplicht als je geen type gebruikt),
"type": (string - verplicht als je geen id gebruikt),
"index": (int)
"teachers": [
"id": (int - verplicht of gebruik externalId),
"externalId": (string - verplicht of gebruik id)
]
}],
"groups": [
"id": (int - verplicht of gebruik externalId),
"externalId": (string - verplicht of gebruik id)
],
"labels": [{
"name": (string)
}]
}
```
{% hint style="warning" %}
**\*\*deprecated\*\*** - Voorheen kon je een willekeurig onderwerp aanmaken door een name op te geven bij een topic. Hiervoor kan je nu genericTopic gebruiken.
{% endhint %}
## Evaluatiekalender bijwerken
`PUT` `https://api-portal.evalytics.nl/evaluationCalendar/:id`
Werk een kalender item bij. Het is niet mogelijk om een evaluatiekalender bij te werken op het moment dat de evaluatie al geweest is.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------- |
| id | string | id van de evaluatiekalender |
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| strictValidation | boolean | Als je strictValidation op false zet, zal er minder streng gecontroleerd worden op het aanmaken van een evaluationCalendar. Docenten, groepen, werkvormen die niet bestaan zullen eruit gefilterd worden bij het aanmaken. (default = true) |
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een evaluatie kalender |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```json
{
"topic": {
"id": (int - verplicht als je geen externalId gebruikt),
"externalId": (string - verplicht als je geen id gebruikt),
"name": (**deprecated** - string - verplicht indien evaluatie kalender op willekeurig onderwerp, id en externalId zijn dan niet nodig)
"integrations": [
{
"id": (string),
"type": ("canvasId" of "canvasSisId")
}
]
},
"genericTopic": {
"id": (number - required of gebruik externalId),
"externalId": (string - required of gebruik id)
}
"startDate": (date string - Voorbeeld: "2021-01-01"),
"importLock": (boolean),
"evaluationName": (string),
"workflow": {
"id": (int - verplicht of externalId),
"externalId": (string - verplicht of id)
},
"types": [{
"id": (int - verplicht als je geen type gebruikt),
"type": (string - verplicht als je geen id gebruikt),
"index": (int)
"teachers": [
"id": (int - verplicht of gebruik externalId),
"externalId": (string - verplicht of gebruik id)
]
}],
"groups": [{
"id": (int - verplicht of gebruik externalId),
"externalId": (string - verplicht of gebruik id)
}],
"labels": [{
"name": (string)
}]
}
```
{% hint style="warning" %}
**\*\*deprecated\*\*** - Voorheen kon je een willekeurig onderwerp aanmaken door een name op te geven bij een topic. Hiervoor kan je nu genericTopic gebruiken.
{% endhint %}
## Evaluatiekalender controleren
`POST` `https://api-portal.evalytics.nl/evaluationCalendar/:id/setChecked`
Zet een kalender item op gecontroleerd
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------- |
| id | string | Id van de evaluatiekalender |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ---------------------------- |
| undo | boolean | Maak de check actie ongedaan |
{% tabs %}
{% tab title="200 " %}
```
[{
"date": "2025-12-02 03:00:00",
"userId": 2,
"name": "voorbeeld gebruiker"
}]
```
{% endtab %}
{% endtabs %}
## Update the startDate of the evaluation calendar
`POST` `https://api-portal.evalytics.nl/evaluationCalendar/:id/startDate`
Update the startDate of the evaluationCalendar. Make sure the startDate is at least one day in the future or an error will be returned.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------------------------------- |
| id | string | ExternalId or internal id of the evaluationCalendar |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
```
{
"startDate": "2021-06-01"
}
```
## Evaluatiekalender archiveren
`POST` `https://api-portal.evalytics.nl/evaluationCalendar/:id/archive`
Archiveer een kalender item. Als response krijg je een lege 200 OK terug
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------- |
| id | string | Id van de evaluatiekalender |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ---------------------------- |
| undo | boolean | Maak de archivering ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Evaluatiekalender verwijderen
`DELETE` `https://api-portal.evalytics.nl/evaluationCalendar/:id`
Verwijder een evaluatiekalender item. Er zal geen evaluatie aangemaakt worden als de evaluatiekalender item is verwijderd.
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------- |
| id | string | Id van de evaluatiekalender |
#### Query Parameters
| Name | Type | Description |
| ---- | ------- | ----------------------------- |
| undo | boolean | Maak de verwijdering ongedaan |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
## Werkvorm toevoegen aan een evaluatiekalender
`POST` `https://api-portal.evalytics.nl/evaluationCalendar/:id/topicType`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------------------------------------- |
| id | string | Id of extern id van de evaluatie kalender |
#### Query Parameters
| Name | Type | Description |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| strictValidation | boolean | Als je strictValidation op false set (default=true), zal er minder streng gevalideerd worden. Docenten die niet bestaan worden er uitgefilterd, maar de werkvorm wordt nog steeds aangemaakt. |
| overwrite | boolean | Geef overwrite=false mee om te zorgen dat werkvormen en docenten niet overschreven worden bij het updaten van een evaluatie kalender |
{% tabs %}
{% tab title="200 " %}
```
{
"types": [
{
"id": 1,
"type": "lecture",
"nameNl": "Hoorcollege",
"nameEn": "Lecture",
"teachers": [
{
"name": "Example Teacher",
"id": 4144,
"externalId": "ExampleExternalTeacher4"
}
]
}
],
"groups": [
{
"id": 1800,
"name": "Example Group",
"externalId": null
}
],
"archived": 0,
"checked": [],
"labels": [
{
"name": "label1",
"id": 717
},
{
"name": "label2",
"id": 718
}
],
"deleted": 0,
"createdBy": "3",
"modifiedBy": "3",
"id": 114,
"topic": {
"id": 4327,
"name": "Example Subject",
"externalId": null
},
"externalId": "buiten23",
"startDate": "2025-12-02T02:00:00.000Z",
"evaluation": null,
"evaluationName": "ExampleCalendarEvaluation",
"workflow": {
"id": 42,
"name": "Example Workflow",
"externalId": "",
"topicType": 1,
"extraOptions": {}
},
"organisation": 688,
"topOrganisation": 418,
"createdAt": "2021-05-10 15:25:00",
"updatedAt": "2021-05-10 15:25:00"
}
```
{% endtab %}
{% endtabs %}
```
{
"index": (int),
"id": (int - verplicht),
"type": (string, als alternatief voor id),
"questionSets": [{
"id": 1 (int)
}, {
"code": (string)
}],
"teachers": [{
"id": (int)
},
{
"externalId": (string)
}]
}
```
## Werkvorm verwijderen van een evaluatiekalender
`DELETE` `https://api-portal.evalytics.nl/evaluationCalendar/:id/topicType`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| id | string | |
{% tabs %}
{% tab title="200 " %}
```
{
"types": [],
"groups": [
{
"id": 1800,
"name": "Example Group",
"externalId": null
}
],
"archived": 0,
"checked": [],
"labels": [
{
"name": "label1",
"id": 717
},
{
"name": "label2",
"id": 718
}
],
"deleted": 0,
"createdBy": "3",
"modifiedBy": "3",
"id": 114,
"topic": {
"id": 4327,
"name": "Example Subject",
"externalId": null
},
"externalId": "buiten23",
"startDate": "2025-12-02T02:00:00.000Z",
"evaluation": null,
"evaluationName": "ExampleCalendarEvaluation",
"workflow": {
"id": 42,
"name": "Example Workflow",
"externalId": "",
"topicType": 1,
"extraOptions": {}
},
"organisation": 688,
"topOrganisation": 418,
"createdAt": "2021-05-10 15:25:00",
"updatedAt": "2021-05-10 15:25:00"
}
```
{% endtab %}
{% endtabs %}
```
{
"id": (int - verplicht),
"type": (string, als alternatief voor id)
}
```
## Sets the creation status of the calendar
`POST` `https://api-portal.evalytics.nl/evaluationCalendar/:id/setCreationStatus`
You are able to change the creation status of the calendar when the evaluation has not been created yet, The available status options are:\
**- active:** The default status - when a calendar is active, it will create an evaluation on the creationDate\
\- **paused**: Mark a calendar as paused. It will not create an evaluation on the creation date.\
**- canceled:** Mark a calendar as canceled. It will not create an evaluation on the creation date.
You should always be able to set a paused/canceled calendar back to active. The evaluation will be created on the creation date. Please note: When the calendar has already been expired. When the creationDate has passed, but the evaluation endDate has not been passed, the calendar will be created immediately.\
\
You can also pass a remark why a calendar has been paused/canceled.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | -------------------------------- |
| id\* | string | id or externalId of the calendar |
```
{
"creationStatus": "paused|canceled|active (required)",
"creationStatusRemark": "string (optional)"
}
```
# Evaluation
## Add participant(s) to an evaluation
`POST` `https://api-portal.evalytics.nl/evaluation/:id/addParticipants`
Add a new participant to an evaluation. You can only add participants when the evaluation has not yet been finished. You can also provide a groupId, so the group will also be linked to the invitationUser.
#### Path Parameters
| Name | Type | Description |
| ---------------------------------- | ------ | ----------------------------------------- |
| \* | String | Internal or external id of the evaluation |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"newInvited": [
"deleted": false,
"createdBy": "123",
"modifiedBy": null,
"evaluator": 123,
"evaluation": 456,
"groupName": "Some group",
"groupId": 1000,
"id": 1,
"createdAt": "2021-11-08T12:00:00.000Z",
"updatedAt": null,
"email": "example@evalytics.nl",
"name": "Example Student"
],
"alreadyInvited": [{
"deleted": false,
"createdBy": "123",
"modifiedBy": null,
"evaluator": 122,
"evaluation": 456,
"groupName": "Some group",
"groupId": 1000,
"id": 2,
"createdAt": "2021-11-08T12:00:00.000Z",
"updatedAt": null,
"email": "dev@evalytics.nl",
"name": "Dev Student"
}]
}
```
{% endtab %}
{% tab title="400: Bad Request When one of the groups could not be linked to the invited participant" %}
```json
{
"userMessage": "The evaluation could not be found",
"errorCode": "22531c1b-cf00-4e25-ad7c-ebca49a51614"
}
```
```json
{
"userMessage": "The evaluation visibility is not set to invitation",
"errorCode": "fe635a42-bff9-4234-9985-1b94a88656ae"
}
```
```json
{
"userMessage": "The evaluation has already been finished",
"errorCode": "4988f6c0-df89-4200-9e27-e0025d0bd68a"
}
```
```json
{
"userMessage": "One or multiple invitationUsers could not be found in the given group",
"errorCode": "4e26d890-5dc8-41f9-ad61-41b053f9a043",
"context": [
{
"email": "example@evalytics",
"name": "Example",
"group": {
"externalId": "nonExistingGroup"
}
}
],
"status": 400
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
We will ignore participants that are already added to the evaluation (**alreadyInvited** in the API response)
{% endhint %}
{% hint style="info" %}
You cannot add participants to an evaluation that is finished
{% endhint %}
#### Example post data
```
{
"participants": [{
"email": (string - required),
"name": (string - not required),
"group": (optional) {
"externalId": (string)
}, {
"id": (int)
},
"labels": [{
"name": (string)
}]
}]
}
```
## Removes one or multiple participants from the evaluation
`DELETE` `https://api-portal.evalytics.nl/evaluation/:id/participants`
Remove participants from the evaluation. Please note you can only remove participants when the evaluation has not yet been finished. The invitation url will no longer work, when the student is already invited for the evaluation.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | ----------------------------------------- |
| id\* | String | Internal or external id of the evaluation |
{% tabs %}
{% tab title="200: OK Returns the total deleted evaluators" %}
```
{
"totalDeletedEvaluators": number
}
```
{% endtab %}
{% tab title="400: Bad Request " %}
**Validation error**
```
{
"userMessage": "Error in parameters",
"context": [
"\"participants\" is required"
],
"errorCode": "7d0a889a-1ce5-4eb1-9ce7-cb89b994656b",
"status": 400
}
```
**Visibility is not set to invitation**
{
"userMessage": "The evaluation visibility is not set to invitation",
"errorCode": "380be142-e6aa-4daa-aa81-a406759a9531",
"status": 400
}
**The evaluation has already been finished**
```
{
"userMessage": "The evaluation has already been finished",
"errorCode": "e6b371eb-8e14-43bb-8805-81318925d950",
"status": 400
}
```
{% endtab %}
{% endtabs %}
**Example post data**
```
{
"participants": [{
"email": (string - required)
}]
}
```
{% hint style="info" %}
You cannot remove participants when the evaluation has been finished
{% endhint %}
{% hint style="info" %}
Already emailed participants can no longer use the invitation url, because they are no longer invited for the evaluation
{% endhint %}
# Topic types
When setting up evaluations, organisations have the option to setup questions within the evaluation for each topic type to the students/respondents. This is an existing functionality. Examples of topic types include lecture or seminar. Questions from a single question set can be set for each instructional format, or a separate question set per topic type.
Topic types can only be created in the highest (top) organisation and are then available to all lower-level organisations. The lower-level organisations can also make them (in)visible.
### Terms
| Name | Type | Required | Description |
| ------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| nameNl | string | Yes | Name of the topic type in Dutch |
| nameEn | string | Yes | Name of the topic type in English |
| type | string | Yes | A recognisable naming of the topic type in English. For example: exercise, theoryLesson. Can be used as an externalId. |
| enabled | boolean | n.a. | Indicates whether the topic type is available when creating a new course. Results and old courses remain unchanged. They are still visible there. |
| parent | int | no | Topic types can be linked to a parent. You can filter these with parent, and when retrieving item(s), it will return whether a topic type is linked to another topic type. The available parentId's are 1 (subject) or 7 (exam). |
## Get a list of topic types
`GET` `https://api-portal.evalytics.nl/topicType`
#### Path Parameters
| Name | Type | Description |
| ------ | ------- | ------------------- |
| parent | integer | Filter on parent id |
#### Query Parameters
| Name | Type | Description |
| -------------------- | ------- | -------------------------------------------------------- |
| showInvisible | boolean | Show the topic types, made invisible by the organisation |
| populateQuestionSets | boolean | populate the linked questionSets (default = false) |
| evalyticsTopics | boolean | Include the default evalytics topicTypes |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-04-14T10:21:15.347Z",
"resultSet": {
"count": 32,
"limit": 0,
"skip": 0
}
},
"results": [
{
"deleted": 0,
"createdBy": "bootstrap",
"modifiedBy": null,
"parent": 1,
"type": "minor",
"nameNl": "Minor",
"nameEn": "Minor",
"organisation": 1,
"topOrganisation": 1,
"id": 3,
"createdAt": "2018-09-11T18:11:43.000Z",
"updatedAt": "2018-09-11T18:11:43.000Z"
},
{
"deleted": 0,
"createdBy": "bootstrap",
"modifiedBy": null,
"parent": 1,
"type": "project",
"nameNl": "Project",
"nameEn": "Project",
"organisation": 1,
"topOrganisation": 1,
"id": 4,
"createdAt": "2018-09-11T18:11:43.000Z",
"updatedAt": "2018-09-11T18:11:43.000Z"
}
]
}
```
{% endtab %}
{% endtabs %}
## Get topic type
`GET` `https://api-portal.evalytics.nl/topicType/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | -------------------- |
| id | integer | Id of the topic type |
{% tabs %}
{% tab title="200 " %}
```
{
"deleted": 0,
"createdBy": "bootstrap",
"modifiedBy": null,
"parent": 1,
"type": "minor",
"nameNl": "Minor",
"nameEn": "Minor",
"organisation": 1,
"topOrganisation": 1,
"id": 3,
"createdAt": "2018-09-11T18:11:43.000Z",
"updatedAt": "2018-09-11T18:11:43.000Z",
"disabled": false,
"resultIndex": null,
"questionSets": [
{
"id": 1,
"name": "Standaard"
}
]
}
```
{% endtab %}
{% endtabs %}
## Add topic type
`POST` `https://api-portal.evalytics.nl/topicType`
{% tabs %}
{% tab title="200 " %}
```
{
"organisation": 100,
"topOrganisation": 100,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"id": 1,
"name": "Subject",
"enabled": true,
"resultIndex": null,
"parent": null,
"questionSets": [{
"id": 123,
"name": "Standaard"
}]
}
```
{% endtab %}
{% endtabs %}
```json
{
"type": (string - required),
"nameNl": (string - required),
"nameEn": (string - required),
"questionSets": [{
"id": (int)
}],
"parent": (int)
}
```
{% hint style="info" %}
Parent: Can be 1 (subject - default) or 7 (exam)
{% endhint %}
## Add questionSets to topic type
`POST` `https://api-portal.evalytics.nl/topicType/:id/updateQuestionSet`
#### Path Parameters
| Name | Type | Description |
| ---- | ------- | -------------------- |
| id | integer | Id of the topic type |
{% tabs %}
{% tab title="200 " %}
```
{
"organisation": 100,
"topOrganisation": 100,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"id": 1,
"name": "Subject",
"enabled": true,
"questionSets": [{
"id": 123,
"name": "Standaard"
}]
}
```
{% endtab %}
{% endtabs %}
```json
{
"questionSets": [{
"id": (int)
}]
}
```
## Make a topic type invisible for a specific organisation.
`POST` `https://api-portal.evalytics.nl/topicType/:id/updateDisabled`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | -------------------- |
| id | number | Id of the topic type |
{% tabs %}
{% tab title="200 " %}
```
{
"organisation": 100,
"topOrganisation": 100,
"type": "subject",
"nameNl": "Cursus",
"nameEn": "Subject",
"id": 1,
"name": "Subject",
"enabled": true,
"questionSets": [{
"id": 123,
"name": "Standaard"
}]
}
```
{% endtab %}
{% endtabs %}
```json
{
"setDisabled": (boolean - required)
}
```
# Vragensets
## Overzichtstabel termen
| | |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code | De code van de vragenset |
| description | Omschrijving van de vragenset |
| name | Naam van de vragenset |
| questions | Een lijst met vragen die aan de vragensets gekoppeld zijn |
| status | De huidige status van de vragenset. ongoing = actief, draft = concept |
| lockedBy | De huidige vragenset is **gelocked** door de aangegeven gebruiker. Het is dan niet meer mogelijk om de vragenset te bewerken door andere gebruikers. |
| organisationObject | De organisatie die de eigenaar is van de vragenset |
| evaluationCount | Het totaal aantal evaluaties wat gekoppeld is aan de vragenset, ongeacht de huidige organisatie/opleiding |
| evaluationCountCurrentOrg | Het totaal aantal evaluaties wat gekoppeld is aan de vragenset binnen de huidige organisatie/opleiding |
| createdByObject | De gebruiker die de vragenset heeft aangemaakt |
| questionCount | Het totaal aantal vragen binnen een vragenset |
| routing | Het is mogelijk om routering toe te passen voor een vragenset. Bij een bepaald antwoord op een vraag kan je dan extra vragen stellen of vragen overslaan. Als een vragenset routering gebruikt staat hierbinnen de routering gedefinieerd. |
## Vragensets ophalen (lijst)
`GET` `https://api-portal.evalytics.nl/questionSet`
#### Query Parameters
| Name | Type | Description |
| ---------------------- | ------- | --------------------------------------------------------------------------------------------- |
| q | string | Zoek op vragensets (naam, omschrijving, code) |
| questionTypes | array | Filter op vraag type (1=cursus, 2=docent, 7=toets) |
| countLinkedEvaluations | boolean | Voegt aan alle vragensets het totaal aantal evaluaties toe die gebruik maken van de vragenset |
| countQuestions | boolean | Voegt aan alle vragensets het totaal aantal vragen toe |
| hasRouting | boolean | Filter op vragensets met vraag routering |
{% tabs %}
{% tab title="200 " %}
```
{
"metadata": {
"timestamp": "2021-06-22T11:21:11.409Z",
"resultSet": {
"count": 1
}
},
"results": [
{
"deleted": 0,
"createdBy": "bootstrap",
"modifiedBy": null,
"archived": 0,
"status": "ongoing",
"code": "XAMHUBXF",
"name": "Verdieping 'Toets'",
"description": "Deze verdiepende toetsvragen kunnen aanvullende context bieden op de toetsvragen gesteld in de standaard vragenset.",
"isPreselection": 0,
"routing": null,
"lockedBy": null,
"organisation": 418,
"topOrganisation": 418,
"id": 376,
"createdAt": "2020-04-12T19:12:43.000Z",
"updatedAt": "2020-04-12T19:12:43.000Z",
"createdByObject": {
"id": "3",
"name": "Evalytics"
},
"organisationObject": {
"id": 123,
"name": "Example school"
},
"questionCount": 2,
"evaluationCount": 0,
"evaluationCountCurrentOrg": 0
}
]
}
```
{% endtab %}
{% endtabs %}
## Vragenset ophalen (item)
`GET` `https://api-portal.evalytics.nl/questionSet/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | --------------------------- |
| id | string | Interne id van de vragenset |
#### Query Parameters
| Name | Type | Description |
| ------------------------ | ------- | ----------------------------------------- |
| populateWithLockedByUser | boolean | Voegt toe wie de vragenset gelocked heeft |
{% tabs %}
{% tab title="200 " %}
```
{
"lockedBy": null,
"organisation": 418,
"topOrganisation": 418,
"deleted": false,
"createdBy": "bootstrap",
"modifiedBy": null,
"archived": false,
"status": "ongoing",
"code": "XAMHUBXF",
"name": "Verdieping 'Toets'",
"description": "Deze verdiepende toetsvragen kunnen aanvullende context bieden op de toetsvragen gesteld in de standaard vragenset.",
"isPreselection": false,
"routing": null,
"id": 376,
"createdAt": "2020-04-12T19:12:43.000Z",
"updatedAt": "2020-04-12T19:12:43.000Z",
"questions": []
}
```
{% endtab %}
{% endtabs %}
# Results
Evalytics uses a couple of generic result-endpoints with which all results can be retrieved (assuming the user has permission to a specific result). By setting the context, a combination of `type`, `id`, `comparisonType` and optionally a `comparisonId`, the desired results can be retrieved.
## Averages
`GET` `https://api-portal.evalytics.nl/result/averages`
Returns a list of total averages within the given context (e.g. an evaluation).
#### Query Parameters
| Name | Type | Description |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | array |
Determines which results the API will return.
Possible values: totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage
|
| type | string |
Context in which results are being searched.
Possible values:organisation, evaluation, teacher, subject
|
| id | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id. |
| comparisonType | string |
Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.
Possible values: organisation, evaluation, teacher, subject
|
| comparisonId | integer | Use in combination with `comparisonType` to retrieve results within the sub context. |
| startDate | string | Uses the format `YYYY-MM-DD` |
| endDate | string | Uses the format `YYYY-MM-DD` |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available. |
{% tabs %}
{% tab title="200 " %}
```scheme
{
"name": string,
"averages": [
{
"type": string,
"average": number
}
]
}
```
{% endtab %}
{% endtabs %}
## Average history
`GET` `https://api-portal.evalytics.nl/result/averageHistory`
Returns a list of averages per quarter, per type, within the given context. Note that this only works if the context supports history, i.e. not for evaluations.
#### Query Parameters
| Name | Type | Description |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | string |
Determines which results the API will return.
Possible values: totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage
|
| type | string |
Context in which results are being searched.
Possible values:organisation, subject, teacher
|
| id | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id. |
| comparisonType | string |
Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.
Possible values: organisation, teacher, subject
|
| comparisonId | integer | Use in combination with `comparisonType` to retrieve results within the sub context. |
| startDate | string | Uses the format `YYYY-MM-DD` |
| endDate | string | Uses the format `YYYY-MM-DD` |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available. |
{% tabs %}
{% tab title="200 " %}
```scheme
[
{
"type": string,
"history": [
{
"average": number,
"quarter": integer,
"year": integer
}
]
}
]
```
{% endtab %}
{% endtabs %}
## List
`GET` `https://api-portal.evalytics.nl/result/list`
Returns a list of items with their average results for the given context (e.g. a list of evaluations for an organisation).
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | array |
Determines which results the API will return.
Possible values: totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage
|
| type\* | string |
Context in which results are being searched.
Possible values:organisation, evaluation, teacher, subject
|
| id | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id. |
| comparisonType\* | string |
Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.
Possible values: organisation, evaluation, teacher, subject
|
| comparisonId | integer | Use in combination with `comparisonType` to retrieve results within the sub context. |
| startDate | string | Uses the format `YYYY-MM-DD` |
| endDate | string | Uses the format `YYYY-MM-DD` |
| searchQuery | string | |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available. |
| skip | integer | Defaults to `0` |
| limit | integer | Defaults to `30` |
| orderBy | string |
Possible values: name ASC, name DESC, totalAverage ASC, totalAverage DESC, subjectAverage ASC, subjectAverage DESC, teacherAverage ASC, teacherAverage DESC, examAverage ASC, examAverage DESC, enddate ASC, enddate DESC
|
{% tabs %}
{% tab title="200 Note that the response can have minor differences depending on the context. E.g. if the context is a teacher, only a teacherAverage will be present." %}
```scheme
{
"metadata": {
"resultSet": {
"count": integer,
"limit": integer,
"skip": integer
}
},
"results": [
{
"id": integer,
"name": string,
"code": string,
"evaluations": integer,
"totalAverage": number,
"teacherPersonalAverage": number,
"examAverage": number,
"teacherAverage": number,
"subjectAverage": number,
"response": integer,
"expectedResponse": integer
}
]
}
```
{% endtab %}
{% endtabs %}
## Questions
`GET` `https://api-portal.evalytics.nl/result/questions`
Returns a list of questions with their average results for the given context (e.g. a list of questions for a specific evaluation).
#### Query Parameters
| Name | Type | Description |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element | array |
Determines which results the API will return.
Possible values: subjectQuestions, teacherQuestions, examQuestions, genericQuestions
|
| type\* | string |
Context in which results are being searched.
Possible values:organisation, evaluation, teacher, subject
|
| id | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id. |
| comparisonType | string |
Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.
Possible values: organisation, evaluation, teacher, subject
|
| comparisonId | integer | Use in combination with `comparisonType` to retrieve results within the sub context. |
| startDate | string | Uses the format `YYYY-MM-DD` |
| endDate | string | Uses the format `YYYY-MM-DD` |
| includedInAverage | boolean | By default all question results are retrieved. By setting this to `true`, only questions that count towards global averages will be returned. |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available. |
| orderBy | string |
Possible values: question ASC, question DESC
|
{% tabs %}
{% tab title="200 " %}
```scheme
{
"questionGroups": [
{
"name": string,
"questions": [
{
"typeId": integer,
"hash": string,
"code": string
"type": integer,
"topicType": integer,
"questionType": integer,
"isIncludedInAverage": boolean,
"response": integer,
"scale": {
"name": string,
"scale": object,
"input": string
},
"question": string,
"average": number,
"deviation": number
}
]
}
],
"hasLabels": boolean
}
```
{% endtab %}
{% endtabs %}
## Question
`GET` `https://api-portal.evalytics.nl/result/question/:hash`
Returns a single question with it's average result and result distribution for the given context (e.g. a single topic question).
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------- |
| hash | string | The question's hash |
#### Query Parameters
| Name | Type | Description |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string |
Context in which results are being searched.
Possible values:organisation, evaluation, teacher, subject
|
| id | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id. |
| comparisonType | string |
Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.
Possible values: organisation, evaluation, teacher, subject
|
| comparisonId | integer | Use in combination with `comparisonType` to retrieve results within the sub context. |
| startDate | string | Uses the format `YYYY-MM-DD` |
| endDate | string | Uses the format `YYYY-MM-DD` |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available. |
{% tabs %}
{% tab title="200 " %}
```scheme
{
"typeId": integer,
"hash": string,
"code": string,
"type": integer,
"topicType": integer,
"response": integer,
"scale": {
"name": string,
"scale": object,
"input": string
},
"question": string,
"scoreDistribution": object,
"average": number,
"deviation": number,
"averageIndex": integer,
"explanations": array
}
```
{% endtab %}
{% endtabs %}
# Periodic export
Export raw data periodically, e.g. for use with other analysis tools.
## Enable the periodic data export feature
`POST` `https://api-portal.evalytics/dataexport/enable`
Be sure to save the private key in a safe place, you must be able to provide it when downloading exported files.
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"enabled": boolean,
"privateKey": string
}
```
{% endtab %}
{% endtabs %}
## Download a single periodically exported file
`GET` `https://api-portal.evalytics.nl/dataexport/download`
#### Query Parameters
| Name | Type | Description |
| -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file\* | String |
|
| privateKey\* | String | The private key (encryption key) that was created when the periodic export feature was enabled |
| parseJsonDataTypes | Boolean | Ensures the data types in the JSON files are conform the data model |
{% tabs %}
{% tab title="200: OK Returns the file as an attachment" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
## Download all periodically exported files as a zip
`GET` `https://api-portal.evalytics.nl/dataexport/downloadAll`
#### Query Parameters
| Name | Type | Description |
| -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| fileType\* | String |
Possible values:
csv, json
|
| privateKey\* | String | The private key (encryption key) that was created when the periodic export feature was enabled |
| parseJsonDataTypes | Boolean | Ensures the data types in the JSON files are conform the data model |
{% tabs %}
{% tab title="200: OK Returns the zip-file as an attachment" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
## Disable the periodic data export feature
`POST` `https://api-portal.evalytics.nl/dataexport/disable`
#### Query Parameters
| Name | Type | Description |
| -------------- | ------- | ----------------------------------------------------------------- |
| deleteSettings | Boolean | Removes previously exported files and invalidates the private key |
{% tabs %}
{% tab title="200: OK " %}
```javascript
{
"enabled": boolean
}
```
{% endtab %}
{% endtabs %}
## Data model
{% file src="/files/p3bnSg8buUljJYyGTVxj" %}
The SVG in full size
{% endfile %}
{% file src="/files/AQqC8X7Rs8PiupneORPb" %}
For use with
{% endfile %}
# Automatic report generation
Set a webhook to automatically receive generated reports after an evaluation has ended.
### Webhook settings page
On the webhook settings page you can configure the webhook. These settings include:
* A field where you can configure the webhook
* A method to configure the report settings. This will mirror the report download window.
* A field where you set the api user. To use this function you need to set an api user that has permissions over the entire organisation (on all suborganisations) and is at least functional admin. You have to use this api user to retrieve all the generated reports. For more info an api users see [Authenticatie](/algemeen/authenticatie#api-key-aanmaken).
* A field where you can set the moment when report should be created. This can be set to
* **End evaluation period**: This is when the evaluation closes for the students.
* **End feedback period**: After the users have filled in their feedback.
* **Start results period**: After the "result are available" notifications have been sent.
* Please note: When this field is set to **feedback period end** or **start results period,** for any evaluations without these periods no reports will be generated.
### Webhook callback
```json
{
"reportId": (number),
"nameReport": (string),
"fileType": ("pdf" | "doc" | "xlsx" | "spss" | "zip"),
"evaluation": {
"id": (number),
"externalId": (string),
"name": (string),
"type": ("subject" | "exam" | "teacher" | "generic"),
"topic": {
"id": (number),
"name": (string),
"code": (string),
"externalId": (string)
}
}
}
```
When the `externalId` is turned off, the `externalId` fields will be set to `null`.
### Downloading the report
When the webhook callback has been received the report is ready to be downloaded. This can be done by calling the following API call.
## Fetch a report from the webhook
`GET` `https://api-portal.evalytics.nl/storedReport/:id/downloadApi`
The file type can be parsed from the Content-Disposition and Content-Type fields in the response header.
#### Path Parameters
| Name | Type | Description |
| ------------------------------------ | ------ | -------------------------------------------------------------------------- |
| id\* | number | This should be the reportId that has been received in the webhook callback |
{% tabs %}
{% tab title="200: OK The response will contain the file data" %}
{% endtab %}
{% tab title="400: Bad Request The report cannot be found or accessed" %}
{% endtab %}
{% endtabs %}
### Roles
The `downloadApi` call can only be called by api key users who have been granted the role of atleast functional admin for the entire organisation.
### Report expiration
After the report has been created, it will be available for 3 days. After which it will be deleted and will no longer be available.
# API Changelog
## 2024-03-07
* Topic types can now be linked to the exam type
## 2023-09-06
* Added **DELETE evaluation/:id/participants** endpoint
## 2023-05-31
* Added: **calendar/:id/setCreationstatus** endpoint
* Added: New status filter to teachers, subjects, groups, generic topic and calendar list endpoints.
## 2023-04-06
* Added: Automatic report generation
## 2023-01-27
## Changed
* Removed name/description from genericTopic->blocks
* Added topicType to genericTopic->blocks
## 2023-01-11
### Added
* Generic topic api
### Changed
* The way you can add a generic Topic to a calendar has been changed.
## 2022-10-26
### Added
* You can now update a participant in a group with the **PUT /group/:id/participant** api call
* **participantUpdateType** param to the **POST /group/:id/participant** api call
* **integrations field** to the **group** api calls
* You can now create a teacher without an emailaddress
### Fixed
* When creating/updating subjects, we now check for duplicate items. It should not be possible to add multiple groups, coordinators, questionSets, topic types of the same id.
## 2022-08-25
### Added
* You can now add **labels** to a participant in the /evaluation/:id/addParticipants api call
## 2022-07-14
### Added
* **tracking-id** header explanation to error page
## 2022-02-24
### Added
* **shouldNotUpdateStartDate** field to the evaluationCalendar.
## 2022-02-10
### Fixed
* Integration in evaluationCalendar create/update api calls were added on the wrong place.
## 2022-01-27
### Added
* Added title field to teachers, draftUsers and users
* Added title, firstName, prefix, lastName to field to users
## 2022-01-19
### Added
* Flag to subject/calendar update calls to set overwrite=false. When set to false, topicTypes and teachers will not be removed when submitting new ones.
## 2021-12-16
### Added
* Option to label group participants
## 2021-11-08
### Added
* Endpoint to add new participants to an evaluation
## 2021-10-25
### Added
* **isWorkingStudent** and **isGuestTeacher** properties to the subject create/update api calls
## 2021-10-01
### Added
* useExternalIdForCalendar flag to the **PUT /topic/:id** endPoint
* externalId support for the user endpoints
## 2021-09-13
### Added
* Added `integrations` attribute to evaluationCalendar, currently for use with Canvas course announcements.
## 2021-09-09
### Added
* Documentation for `/result` endpoints. Main functions have been covered, more intricate things like label filtering will be documented at a later time.
## 2021-09-02
### Added
* /draftUser/:id/block endpoint to be able to block a user linked to the draftUser.
* /user/:id/block endpoint to be able to block a user.
* A blocked user is not able to login
* A blocked user will not receive notifications in the period the user is blocked
* The linked roles and organisations will not be removed
## 2021-08-20
### Added
* It is now possible to add `teacherOptions` to a draftUser. These teacherOptions will also be saved by the teacher when you convert the draftUser to a teacher. You can add the following teacherOptions:
* isWorkingStudent (boolean)
* isGuestTeacher (boolean).
##
### Added
* **hasCalendar** flag to the subject list to be able to only retrieve a list of subjects, linked to at least one calendar item
## 2021-08-16
### Added
* Endpoint to anonymize draftUser and it's linked user/teacher(s)
## 2021-08-11
### **Added**
* added missing query parameters for list users: `includeChildOrganisations` and `role`
## 2021-08-01
### **Added**
* add/delete a topicType from an evaluationCalendar
## 2021-07-29
### Fixed
* Some minor text changes on the subject page
## 2021-07-15
### Added
* **totalParticipants** field to the group list response
* Missing fields for the calendar item/list response **(itemLock, workflow\.visibility)**
## 2021-07-07
### Added
* Added: Documentation for adding **linkedOrganisations** when creating/updating subjects.
* Added: Documentation for populating linkedOrganisations to the subject list
* Fixed: Some minor text changes on the subject page
## 2021-07-05
### Added
* GET /subject/:id/getOrganisationTree. Get a list of all organisations linked to the current topOrganisation.
* GET /subject/:id/linkedOrganisations. A list of linked organisations of the subject. When a subject is linked to an organisation, the organisation can view the results of that subject.
* POST /subject/:id/linkedOrganisations. Link a subject to one or more organisations. The organisations linked to the subject can view the results of that subject.
* It is now possible to add an **importLock** to groups, subjects, teachers and evaluation calendar items. When the importLock is set **true**, the item will be locked on the Evalytics portal. Users (quality managers, coordinators, ..) will not able to modify the items. Only functional admins are able to edit them.
* **convertedToUser** flag to the GET /draftUsers api endpoint to filter all draftUsers, converted to user.
## 2021-07-01
### Added
* POST /group/bulkImportParticipants. Bulk import with a CSV file
## 2021-06-30
### Added
* Documentation for strictValidation mode when creating/updating a subject or evaluationCalendar
## 2021-06-22
### Added
* API documentation to get a list of questionSets or a single questionSet
## 2021-06-09
### Added
* API documentation to add a single topicType to a subject
* API documentation to delete a single topicType from a subject
## 2021-06-02
### Added
* Example to updateStartDate of the evaluationCalendar (POST /evaluationCalendar/:id/updateStartDate)
* EvaluationCalender **GET** list and **GET** item will now also return the creationStartDate. This is the date (in unix timestamp) the calendar is going to create the evaluation.
.
## 2021-05-14
### Added
* First version of the api documentation
