> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timetracker.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Calendar

> Link your Google Calendar to TimeTracker, run a two-way sync with your planned blocks, set the colour of imported events, and disconnect when you are done.

**Settings → Calendar** is where you link your own Google Calendar to this
workspace. Once linked, your planned blocks and your Google events stay in step
in both directions.

The nav item is called **Calendar**. It sits in the **Integrations** group, and
the page itself is headed **Integrations** – "Connect external services to this
workspace."

<Info>
  The concept lives on [/integrations/google-calendar](/integrations/google-calendar).
  This page documents the screen.
</Info>

## Before you start

| Requirement  | Detail                                                                                          |
| ------------ | ----------------------------------------------------------------------------------------------- |
| App          | The **Calendar** app must be on                                                                 |
| Required app | Calendar needs the **Resource Planner** app – there is nothing to mirror without planned blocks |
| Plan         | Pro. The plan feature is `integrations`                                                         |
| Capability   | `block.manage` to connect, sync, recolour or disconnect                                         |

`block.manage` is held by Owner, Admin, Project Manager, Member and Contractor.
Finance and Client do not hold it.

If you open the page without `block.manage`, the card shows one line:
"You need block-management permission to connect a calendar."

## The connection is yours, not the workspace's

Each person links their own Google account, once per workspace. Sarah Lin linking
her calendar in Northwind Studio does not link Jonas Bergman's. He connects his
own, or he does not sync at all.

Turning the app on does not connect anyone. Every person connects for themselves.

## What is on the page

One card, **Google Calendar**, described as "Two-way sync between your Planner
blocks and your Google Calendar."

### Before you connect

A single button: **Connect Google Calendar**. That is the whole empty state.

### After you connect

| Item                 | What it shows                                                           |
| -------------------- | ----------------------------------------------------------------------- |
| Status               | A dot and the word **Connected**                                        |
| Account              | "as `you@example.com`" when Google returned your address                |
| Last sync            | "Last synced" with the date and time, or "Not synced yet."              |
| Last error           | Appended to the same line as "· Last error: …" when the last run failed |
| Imported event color | A colour picker for the colour imported Google events wear as blocks    |
| Sync now             | Runs a sync immediately. Reads "Syncing…" while a run is in progress    |
| Disconnect           | Unlinks the account                                                     |

There is no calendar picker on this page. Your main Google calendar is the one
that syncs.

## How to connect

<Steps>
  <Step title="Open the page">
    Go to **Settings → Calendar**.
  </Step>

  <Step title="Start the connection">
    Click **Connect Google Calendar**. You leave TimeTracker and land on Google's
    sign-in and consent screen.
  </Step>

  <Step title="Approve the access">
    Approve the calendar access Google asks for. Google sends you back to this
    page.
  </Step>

  <Step title="Check the result">
    A toast says "Google Calendar connected." and the card switches to the
    connected view. If something went wrong, the toast says "Couldn't connect
    Google Calendar. Please try again." and you can press **Connect Google
    Calendar** again.
  </Step>
</Steps>

## Which direction each thing moves

<Tabs>
  <Tab title="Google → TimeTracker">
    Timed events on your Google Calendar become blocks on your planner lane.

    * All-day events are skipped. Only timed events map to blocks.
    * Cancelling an event in Google deletes the matching block.
    * When an event and its block have both changed, the more recent change wins.
    * Imported blocks wear the colour you set in **Imported event color**.
  </Tab>

  <Tab title="TimeTracker → Google">
    Blocks you organise are created and updated as events on your calendar.

    * A block that came from Google is never pushed back to Google.
    * Only the block's **organizer** pushes it. Everyone else on the block is a
      guest.
    * A block that asked for a Google Meet gets one on the event.
  </Tab>
</Tabs>

## Blocks with more than one person

The card states this on screen:

> A block you plan with other people is created here as one event with them as
> guests, so it reaches their calendars too – and can carry a Google Meet link. A
> teammate who has not connected Google still gets the block in TimeTracker; they
> are not on the invite.

Only the organizer pushes the block. If Priya Raman plans a block with Sarah Lin
and Jonas Bergman, Priya's connection creates one Google event and invites both.
Sarah's own sync records only her RSVP on that event – it never creates a second
block and never overwrites Priya's title or times.

See [/planner/multi-person-blocks](/planner/multi-person-blocks).

## When syncing runs

| Trigger                     | Timing                                                              |
| --------------------------- | ------------------------------------------------------------------- |
| You change a block          | Within a few seconds                                                |
| Several fast edits in a row | Collapsed into one run, so you get one round trip, not one per edit |
| **Sync now**                | Straight away                                                       |
| Background                  | Every 15 minutes                                                    |

<Note>
  A full sync covers 30 days back and 90 days ahead. After that first pass, only
  what changed since the last run is pulled.
</Note>

## Changing the imported event colour

<Steps>
  <Step title="Open the colour picker">
    Next to **Imported event color**, click the swatch.
  </Step>

  <Step title="Pick a colour">
    Choose from the named colour palette. It saves as soon as you pick.
  </Step>
</Steps>

The change applies to future syncs **and** recolours the Google events you have
already imported, so you see it immediately.

## How to disconnect

<Steps>
  <Step title="Click Disconnect">
    On the connected card, click **Disconnect**.
  </Step>

  <Step title="Confirm what happened">
    A toast says "Google Calendar disconnected. Imported blocks were kept."
  </Step>
</Steps>

Disconnecting unlinks your Google account. Blocks that came in from Google stay
in your planner as ordinary local blocks. Events already on your Google Calendar
stay there too.

<Tip>
  You can disconnect even when the Calendar app is switched off. Withdrawing your
  own consent never depends on an admin turning something back on first.
</Tip>

## Errors and reconnecting

| What you see                                                 | What it means                             | What to do                                                   |
| ------------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------ |
| Toast: "Couldn't connect Google Calendar. Please try again." | The round trip to Google did not complete | Press **Connect Google Calendar** again                      |
| "· Last error: …" on the card                                | The most recent sync run failed           | Read the message, then press **Sync now**                    |
| Toast: "Couldn't disconnect. Please try again."              | The unlink did not save                   | Try again                                                    |
| Toast: "Couldn't start the sync."                            | The sync request was refused              | Confirm you still hold `block.manage` and that the app is on |

To reconnect after a problem, press **Connect Google Calendar** again and go
through Google's consent screen. There is no separate "reconnect" button.

## App off vs not on your plan

These are two different states, and they look different.

| State                         | What happens                                                                                                                                                                                    |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Calendar app switched off** | The **Calendar** nav item disappears. Syncing stops in both directions. Events already in Google Calendar stay there, and connections are kept. Opening the URL shows "Calendar is turned off". |
| **Not on your plan (Free)**   | The item stays in the sidebar. The page shows a blurred shape with an upgrade card: "Upgrade to Pro to unlock Integrations."                                                                    |

Because Calendar requires the **Resource Planner** app, switching the Planner off
takes Calendar with it. See [/settings/apps](/settings/apps).

## Common questions

<AccordionGroup>
  <Accordion title="Does connecting my calendar share it with the workspace?">
    No. The connection is yours. Other people see your planned blocks under the
    planner's normal visibility rules, not your Google Calendar.
  </Accordion>

  <Accordion title="Can I choose which Google calendar to sync?">
    No. There is no calendar picker on this page. Your main Google calendar is
    used.
  </Accordion>

  <Accordion title="Why did my all-day event not become a block?">
    All-day events are skipped on purpose. Only timed events map to time blocks.
  </Accordion>

  <Accordion title="I am on a block with two other people, but nothing reached my Google Calendar.">
    Only the organizer pushes a block to Google, and they invite the others as
    guests. If you did not receive the invite, check that the organizer has
    connected their own calendar and that your email address on the block matches
    the one Google knows.
  </Accordion>

  <Accordion title="Daniel in Finance cannot see the Connect button.">
    Connecting needs `block.manage`, which the Finance role does not hold. See
    [/concepts/roles-and-capabilities](/concepts/roles-and-capabilities).
  </Accordion>
</AccordionGroup>

## Related guides

<CardGroup cols={2}>
  <Card title="Google Calendar" icon="calendar" href="/integrations/google-calendar">
    How the two-way sync behaves day to day.
  </Card>

  <Card title="Resource Planner" icon="calendar-days" href="/planner/overview">
    Planned blocks – the thing that gets mirrored.
  </Card>

  <Card title="Multi-person blocks" icon="users" href="/planner/multi-person-blocks">
    Organizers, guests and who pushes the event.
  </Card>

  <Card title="Apps" icon="toggle-on" href="/settings/apps">
    Switching Calendar on or off, and its Planner requirement.
  </Card>

  <Card title="Plans and features" icon="star" href="/concepts/plans-and-features">
    Why Integrations is a Pro feature.
  </Card>

  <Card title="All settings" icon="gear" href="/settings/overview">
    Every settings page and who can open it.
  </Card>
</CardGroup>