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.

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"
    }
  ]
}

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

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"
}

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)

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"
}

{
	"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)
	}]
}

**deprecated** - Voorheen kon je een willekeurig onderwerp aanmaken door een name op te geven bij een topic. Hiervoor kan je nu genericTopic gebruiken.

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

200

{
	"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)
	}]
}

**deprecated** - Voorheen kon je een willekeurig onderwerp aanmaken door een name op te geven bij een topic. Hiervoor kan je nu genericTopic gebruiken.

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

200

[{
  "date": "2025-12-02 03:00:00",
  "userId": 2,
  "name": "voorbeeld gebruiker"
}]

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

200

{
    "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

200

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

200

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

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"
}

{
    "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

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"
}

{
    "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)"
}