# 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                                  | <p>Startdatum moet in de toekomst liggen en geeft aan wanneer de evaluatie aangemaakt moet worden. Het meegeven van een startdatum is niet verplicht.<br><br>Als voorbeeld: "2021-04-01".</p>                                                                                                                                                                           |
| 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                                  | <p>Werkvormen die gekoppeld moeten worden aan de evaluatiekalender. <br><br>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.</p> |
| 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)

<mark style="color:blue;">`GET`</mark> `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)

<mark style="color:blue;">`GET`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:orange;">`PUT`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:red;">`DELETE`</mark> `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

<mark style="color:green;">`POST`</mark> `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

<mark style="color:red;">`DELETE`</mark> `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

<mark style="color:green;">`POST`</mark> `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:\
\&#xNAN;**- 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.\
\&#xNAN;**- 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<mark style="color:red;">\*</mark> | string | id or externalId of the calendar |

```
{
    "creationStatus": "paused|canceled|active (required)",
    "creationStatusRemark": "string (optional)"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.evalytics.nl/onderdelen/evaluatiekalender.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.