# Connect a calendar

> Connect Google Calendar, Microsoft Outlook (busy time only), Nextcloud, iCloud or another CalDAV calendar so busy time is checked when you plan and planned sessions are added to it.

## Goal

Link one of your calendars to Coaching Toolkit for exactly two things: **busy lookup** (a warning when you plan a session over busy time) and **event push** (each planned session is added to the calendar, moved when rescheduled, removed when cancelled). Coaching Toolkit never reads what your events are, only when you are busy. A Microsoft Outlook connection does busy lookup only.

If you only want to see your sessions in a calendar app, the [calendar feed](https://coaching-toolkit.com/docs/sessions/plan-and-log) needs no password at all; use that instead.

## Prerequisites

- **Google Calendar**: a Google account. You sign in with Google and allow two things only: seeing when you are busy, and adding events to calendars you own. No password is stored; Coaching Toolkit keeps Google's access token, encrypted, until you disconnect.
- **Microsoft Outlook**: a Microsoft 365 **work or school** account. You sign in with Microsoft and allow one thing: reading your free/busy time. Personal Outlook.com, Hotmail and Live accounts cannot be connected (Microsoft does not offer free/busy for them); use the calendar feed there. Coaching Toolkit keeps Microsoft's access token, encrypted, until you disconnect.
- **CalDAV**: Nextcloud, iCloud, or any server that speaks CalDAV over https, and an **app password** for it, not your main password. Coaching Toolkit keeps it encrypted until you disconnect.
- A connection belongs to the Coach who created it.

Calendly connections are planned and not available yet.

## Google Calendar

**Settings**, **Calendar**, **Connect a calendar**, **Google**, then **Connect Google Calendar**. Google asks you to sign in and to allow Coaching Toolkit to see your free/busy time and to add events to calendars you own. Leave both ticked: with either one missing, nothing is connected and the app says so. Afterwards you land back on the Calendar page in Settings.

- Busy time is read from your **primary** Google calendar, as free/busy only. Google never tells Coaching Toolkit what an event is.
- Sessions are added to your primary calendar. The connection shows the Google account's email and "Primary calendar".
- Connecting the same Google account again (for example after you removed access in your Google account) replaces the old access; connecting another Google account adds a second connection.

The link Google gives is valid for 15 minutes and works once. Only the Coach who started the connection can finish it. If Google is declined, the link expired or was already used, or another Coach started it, the app says so and nothing is connected; start again.

## Microsoft Outlook: busy time only

**Settings**, **Calendar**, **Connect a calendar**, **Microsoft**, then **Connect Microsoft Outlook**. Microsoft asks you to pick your work or school account and to allow Coaching Toolkit to read your calendar's free/busy time (the permission Microsoft calls "Read user calendars" at its basic level, plus your sign-in and email). Afterwards you land back on the Calendar page in Settings.

What it does:

- Busy time is read from your default Outlook calendar, as free/busy only. Events marked **Busy**, **Tentative** or **Away** (out of office) count as busy; **Free** and **Working elsewhere** do not. Coaching Toolkit never keeps what an event is.
- The connection shows the Microsoft account's email and "Busy time only".

What it does not do:

- **Sessions are not added to Outlook.** Writing events would need Microsoft's full read and write permission on every calendar, which Coaching Toolkit does not ask for. To see your sessions in Outlook, subscribe to the [calendar feed](https://coaching-toolkit.com/docs/sessions/plan-and-log) in Outlook (Add calendar, Subscribe from web).
- The push switch is not shown: adding sessions is not available for a Microsoft connection.

The Microsoft link works like Google's: valid for 15 minutes, once, and only for the Coach who started it. Trying a personal Microsoft account fails.

## CalDAV: get the server address and an app password

**Nextcloud**

1. Your server address is your Nextcloud address followed by `/remote.php/dav`, for example `https://cloud.example.com/remote.php/dav`.
2. In Nextcloud, open **Settings**, **Security**, and create an app password.
3. Your username is your Nextcloud username.

**iCloud**

1. The server address is `https://caldav.icloud.com`.
2. Sign in at account.apple.com, open **Sign-In and Security**, **App-Specific Passwords**, and create one.
3. Your username is your Apple Account email address.

**Another CalDAV server**: use the CalDAV address your provider gives you, and an app password if it offers one.

## CalDAV: connect in the app

**Settings**, **Calendar**, **Connect a calendar**, **CalDAV**. Pick the preset (Nextcloud, iCloud or Other CalDAV server), fill in the server address, username and app password, give the connection a name, and submit. The server is checked straight away. Then pick the calendar new sessions go to.

## CalDAV: what the form asks for

| Field | Meaning |
| --- | --- |
| Server address | the https address above, up to 500 characters |
| Username | your calendar username |
| App password | the app password; never shown again |
| Name | your name for the connection, up to 80 characters, unique among your connections |

Once saved, the connection shows as Active with the calendars that take events; the first one is where sessions go. Sessions you already planned are added in the background. A Google connection shows the Google account's email and one calendar, "Primary calendar"; a Microsoft connection shows no calendars and is busy time only.

## Choose the calendar and the switches

On the connection in **Settings**, **Calendar**, pick the calendar new sessions go to (for Google there is one, Primary; for Microsoft there is none) and use the switches. **Busy lookup** turns the busy warning on or off; **Add sessions** turns adding sessions on or off (not available for Microsoft).

## What is pushed

| Session change | In your calendar |
| --- | --- |
| planned | a new event |
| rescheduled | the event moves |
| held | the event stays |
| cancelled or no-show | the event is removed |

The event is titled "Session with" and the client's first name, with the time, the place or meeting link, and nothing else about the client. A failed push never fails the session itself.

## Busy time

When you plan or reschedule, every active connection with busy lookup on is asked for busy time in that window. Busy time comes back as a Busy warning on the session (from, to and the connection's name), never as what the time is busy with, and never blocks the plan. Sessions Coaching Toolkit added to that calendar itself do not count as busy. On your public booking pages, busy time removes those slots.

## Connection states

- `Active`: used for busy lookup and push.
- `Failing`: the last attempt failed; the connection shows why (`unreachable`, `auth_failed`, `not_found`, `rejected` or `invalid_response`). Coaching Toolkit skips it and tries again every hour, then catches up on missed pushes once it works. For Google and Microsoft, `auth_failed` means the access was removed in the account, the password changed or the access expired: connect the calendar again. Google and Microsoft rate limits count as `unreachable` and clear by themselves.
- `Revoked`: disconnected; it no longer appears.

After fixing the cause (a new app password, a server back up, Google connected again), test it at once with **Test** on the connection in **Settings**, **Calendar**.

To disconnect, use **Disconnect** on the connection. The app password or the Google or Microsoft tokens and the calendar list are deleted (Google is also asked to revoke the access; Microsoft has no way for an app to do that, so remove Coaching Toolkit under your Microsoft account's app permissions if you want it gone there too); events already added stay in your calendar.

## Verify it worked

Open **Settings**, **Calendar**. The connection is listed as **Connected**, with the calendar sessions go to (a Microsoft connection shows **Busy time only**: plan a session over an Outlook event instead and look for the busy warning). Plan a test session and it appears in that calendar within a minute.

## Failure cases

| What you see | Why |
| --- | --- |
| Authentication failed | the server refused the username or app password |
| Server unreachable | the address is wrong, the server is down or not CalDAV, or it is a private address |
| Name already used | you already have a connection with this name |
| Calendar not found | the chosen calendar is not one of the connection's calendars |
| Provider not available | Calendly is not available yet; or this server has no Google or Microsoft connection set up |
| Push not supported | adding sessions was switched on for a Microsoft connection, which is busy time only |
| Connection not found | the connection is not yours, or was disconnected |