Calendar sync¶
Calendar sync connects a staff member's Google Calendar to Diagonal. A connected calendar can receive events: Diagonal adds the person's events to it. It can also block availability: busy time in the calendar keeps people from booking the person. A calendar can do one or both. A person has one calendar that receives events.
Calendar sync works only for records of a Resource with the Schedulable capability, for example tutors or staff. Your Workspace must have calendar sync turned on.
Where you manage calendars¶
You manage calendars in two places. Both show the same sections, wording, and states.
- In System Admin, open a staff record. Below the record's fields, the Calendars section lists the person's calendars with their state, what each one is used for, and any problem. When a calendar needs attention, an alert at the top of the record says so. Select Manage calendars or Review calendars to change them.
- On a Page of your Workspace that shows your calendars, for example a My calendar page in a staff or tutor portal. Your organization decides where this page is.
The calendars page has two sections:
- Calendars: each calendar, the Google account it uses, who added it, its Receives events and Blocks availability switches, and its state.
- Your Google accounts: the Google accounts that you connected. You add calendars only through your own accounts.
Connect your own calendar¶
- Under Your Google accounts, select Connect Google account.
- Sign in to Google and allow Diagonal to see and edit your calendars. If you clear the calendar permission, Diagonal cannot connect.
- Google returns you to the page where you started. The page shows "… is connected." and opens the calendar list. A reconnect does not open it.
- Select Add calendar… if the list is not open. Under Use the calendar you add to, keep Receive events and Block availability on, or turn one off. Then select Add next to a calendar. Your own calendar is marked Suggested.
If you already have a calendar that receives events, Receive events starts off and the list names that calendar. Turn off Receives events on the other calendar first if you want to move your events.
If you cancel on Google's screen, the page shows "Google sign-in was cancelled." Nothing changes.
Complete the Google sign-in within 10 minutes. If it takes longer, Google shows "This Google sign-in expired or was already used. Go back to the page where you started and connect again."
You cannot connect from the page editor preview. The preview shows "Connect a calendar from the published page. The editor preview can't open Google sign-in." Open the published page to connect.
Only you can use the Google accounts that you connect. To stop using an account, select Disconnect… next to it. Calendars that use the account stop working until you connect it again.
When you disconnect an account, remove a calendar, or turn off Receives events, Diagonal asks what happens to the events it already added:
- Keep the events leaves them in Google Calendar. Diagonal stops changing them.
- Remove upcoming events deletes the upcoming events that Diagonal added. Past events stay.
When you remove the events of a disconnected account, the account shows Removing events… and each of its calendars shows the same state. The page updates by itself when Diagonal finishes.
Let an admin connect your calendar¶
A person with the Manage calendar connections permission can connect a calendar for you through their own Google account. They see only the calendars that you share with their Google account.
To share your calendar with an admin:
- In Google Calendar, open the settings of your calendar.
- Under Share with specific people or groups, add the admin's Google account.
- Choose Make changes to events.
- The admin opens your record, selects Manage calendars, and adds the calendar. They can also add it by email before they accept the share.
A calendar shared as See only free/busy (hide details) or See all event details can block your availability, but it cannot receive events.
Calendar states¶
Each calendar shows a state:
| State | Meaning |
|---|---|
| Active | Diagonal can use the calendar as you asked. |
| Waiting for write access | The calendar blocks availability, but Diagonal cannot add events to it yet. |
| Broken | Diagonal can no longer use the calendar. The message under it tells you what to do. |
| Checking… | Diagonal checks the calendar again after a reconnect. The page updates by itself. |
| Removing events… | Its Google account is disconnecting, and Diagonal is removing the events it added. |
Busy time¶
A calendar that blocks availability shows when Diagonal last read its busy time, for example "Busy time read 4 minutes ago". Diagonal reads it again soon after you change the calendar in Google, and at least every 30 minutes.
When Diagonal has not read the busy time for 6 hours, the calendar shows a warning, for example "Busy time is 7 hours old. Bookings may overlap it." Until then, Diagonal keeps blocking the busy time it read last. Check that the calendar is still shared and that its Google account does not need a reconnect.
Waiting for write access¶
A calendar that receives events needs the share Make changes to events or Make changes and manage sharing. When the share is lower, the calendar waits for write access and shows one of these messages.
For your own calendar, shared with you by someone else:
Can't add events: it's shared with you as 'See only free/busy (hide details)'. Ask its owner for 'Make changes to events', or choose your own calendar.
For a calendar that someone connected through another Google account:
Can't add events yet. Ask its owner to share it with {account} as 'Make changes to events'.
If Make changes to events is greyed out for an outside account, see Sharing outside your organization's domain.
Ask the owner of the calendar to change the share. Diagonal checks every hour and makes the calendar active when it can write to it. You can also turn off Receives events to keep the calendar for availability only.
Broken calendars¶
When one of your own Google accounts needs to reconnect, the page shows one notice at the top: "Reconnect {account}". Select Reconnect in it and sign in to the same Google account. Every calendar that uses the account works again. The calendars under the notice show Broken with no message of their own.
| Message | What to do |
|---|---|
| Reconnect {account} to resume. | Select Reconnect and sign in to the same Google account. |
| {owner} needs to reconnect {account}. Ask them, or connect your own calendar. | Ask the person who connected it to reconnect, or connect your own. |
| You disconnected {account}. Connect it again, or remove this calendar. | Connect the account again, or remove the calendar. |
| {owner} disconnected {account}. Ask them to connect it again, or connect your own calendar. | Ask the person who connected it, or connect your own. |
| {owner} is no longer active here. Remove this calendar and connect another. | Remove the calendar and connect another one. |
| {name} is archived. This calendar comes back when {name} is restored. | Restore the staff record. |
| Diagonal can't reach this calendar. It may be unshared or deleted. | Share the calendar again, then add it again. |
Diagonal emails you when one of your calendars breaks, stops receiving events, or needs a reconnect. The email lists each calendar that needs attention. When one of your Google accounts needs to reconnect, it names the account once with the calendars that it pauses. Select Review calendars to open the calendars page.
Sharing outside your organization's domain¶
Google Workspace admins can limit how people share calendars with accounts outside the organization. When this limit is on, Make changes to events is greyed out for an outside account. The calendar can only block availability.
To fix it, do one of these:
- Connect the calendar from your own Google account. Your own calendar is never limited.
- Ask your Google Workspace admin to allow external sharing with "Share all information, and outsiders can change calendars". In the Google Admin console, this setting is under Apps > Google Workspace > Calendar > Sharing settings > External sharing options for primary calendars.
For builders¶
An Eventable Resource on the series engine writes its Records to staff calendars with these settings. See Capabilities for the stored keys.
| Setting | Use |
|---|---|
| Write Events To Staff Calendars | Turn calendar sync on for the Resource. |
| Staff Member | The relation that names the staff member whose calendar gets the event, such as Tutor. It must point to a Resource with the Schedulable capability. |
| Event Title | The event title. Empty uses the Label Field, then the singular name of the Resource. |
| Event Description | The event description. Attendees see it. Empty uses the Description Template. |
| Room Field | A Select field whose option label is the event location when the Record has no Location. |
| Attendees | Email fields to invite, such as Student › Family › Parents › Email. |
| Status Field and Status Meanings | Which status values cancel an event or make it tentative. Other values confirm it. |
When you turn off Write Events To Staff Calendars and save, Diagonal asks what happens to the events it already added: Stop writing events keeps them, and Stop and remove events deletes the upcoming ones.
A Page can show the calendars of the signed-in person with Sdk.Components.CalendarConnections, or build its own layout with Sdk.hooks.useCalendarConnections. The component shows nothing to a guest, to a person who is not a Schedulable record, or while calendar sync is off. See the My calendar example in the Page Playground.