# Connect Zermelo

Lumicast can pull a school's timetable straight from Zermelo and show it on your displays. This guide walks a Zermelo Portal administrator through granting Lumicast access and creating the authorization code you paste into Lumicast.

::: info Partner rights
Zermelo has replaced the old "API token" integration with **partner rights**: instead of sharing a token, the school creates a *partner* for Lumicast, grants it access to specific endpoints and fields, and generates a one-time authorization code. The older "Zermelo (legacy)" connection in Lumicast keeps working for existing setups, but new connections use the partner flow described here. To move a legacy connection over, open its menu under **Data sources** and choose **Migrate**: your data sources and apps keep working.
:::

## 1. Create the partner

In the Zermelo Portal, go to **Beheer › Partners** and open the **Partners** tab. Click **Toevoegen**.

![Partners overview in the Zermelo Portal](/img/articles/how-to/zermelo/01-partners-overview.png)

Fill in the partner details:

- **Naam** — `Lumicast`
- **Contactpersoon school** — your own details
- **Emailadres partner** — `team@lumicast.com`
- **Projecten** — select the schedule projects (roosterprojecten) whose timetable you want to show. Pick every school year / location you want to show.

![Add a partner and select the schedule projects](/img/articles/how-to/zermelo/02-add-partner.png)

Click **OK**.

## 2. Grant access to the appointments endpoint

Open the **Toegang** tab and click **Toevoegen**.

![Access tab listing endpoint permissions](/img/articles/how-to/zermelo/03-access-tab.png)

- Set **Partner** to `Lumicast`.
- Set **Endpoint** to **appointments (Afspraakversies)**.
- Under **Veldtoegang**, set **every field to Lezen** (read). This is the simplest reliable setup — the schedule app uses most of these fields, and it handles the few it can't get (they aren't offered to partners) gracefully.

![Granting read access to the appointments fields](/img/articles/how-to/zermelo/04-endpoint-access.png)

::: warning Read access is required
If a field has **no** read access, Lumicast doesn't request it, and if *zero* fields are granted the connection can't be created. At a minimum these fields must be set to **Lezen**, or the schedule won't show correctly:

`id`, `appointmentInstance`, `start`, `end`, `lastModified`, `type`, `valid`, `cancelled`, `changeDescription`, `subjects`, `teachers`, `groups`, `locations`, `groupChanged`, `locationChanged`, `teacherChanged`, `timeChanged`

Granting all fields means you don't have to come back here when the app starts using more of them.
:::

- Under **Extra filters**, leave the **fields** and **schoolInSchoolYear** filters allowed (required, on by default). The `start` and `end` fields are filterable by default; Lumicast uses that to fetch only the schedule around the current day.

Click **Toevoegen** (or **Bijwerken** when you edit an existing grant).

## 3. Create an API token

Open the **API-tokens** tab and click **Toevoegen**.

![API tokens tab](/img/articles/how-to/zermelo/05-api-tokens-tab.png)

- **Gebruiker** — select the `Lumicast` partner.
- **Maximaal geldig** — set an expiry date. Pick a date far in the future so the connection keeps working (for example several years ahead).
- **Opmerking** — optional, for example `Lumicast narrowcasting`.

![Add a token for the partner](/img/articles/how-to/zermelo/06-add-token.png)

Click **Toevoegen**.

## 4. Copy the authorization code

The Portal shows a **one-time authorization code**. It is shown **only once** and must be used **within 30 days**.

![One-time authorization code dialog](/img/articles/how-to/zermelo/07-authcode.png)

Copy this code — you need it in the next step.

## 5. Add the connection in Lumicast

1. In Lumicast, go to **Data sources** and click **Create data source**.
2. Under **Connected services**, open **Zermelo** and choose **Zermelo schedule**.
3. Under **Select connection**, choose **New connection** and fill in:
   - **Base URL** — your portal address including `https://`, for example `https://yourschool.zportal.nl`
   - **Authorization code** — the code from step 4

   Click **Save**. Lumicast exchanges the code for an access token and names the connection after your school.
4. Pick the **School year** (roosterproject) you want to show and click **Save**.

## Troubleshooting

- **The connection can't be created** — the code is single-use and valid for 30 days. Create a new token (step 3) and try again with the new code. Also check that the partner has read access to at least one `appointments` field (step 2).
- **No schedule appears** — make sure the partner has **Lezen** access to the `appointments` endpoint (step 2) and that the right project is selected under **Projecten** (step 1).
- **Announcements** — the partner API doesn't provide announcements. They are only available through the older "Zermelo (legacy)" connection.