> ## 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.

# Google Calendar sync

> Connect Google Calendar to TimeTracker for two-way sync of planned blocks. What syncs each way, who pushes a shared block, and how to disconnect.

Google Calendar sync keeps your **planned blocks** and your Google Calendar in
step, both ways.

Go to **Settings → Integrations**.

<Info>
  Calendar sync needs the **Calendar** app, which requires the **Resource Planner**
  app. It is a **Pro** feature. See [Apps and modules](/concepts/apps-and-modules).
</Info>

## What it does

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

| Direction                | What moves                                  |
| ------------------------ | ------------------------------------------- |
| **TimeTracker → Google** | Blocks you created appear as Google events  |
| **Google → TimeTracker** | Your Google events appear as planned blocks |

You connect **your own** calendar. Each person in the workspace connects
separately, and a connection only ever touches that person's calendar.

## Connecting

<Steps>
  <Step title="Open Settings → Integrations">
    You need the `block.manage` capability. Without it the card reads *"You need
    block-management permission to connect a calendar."*
  </Step>

  <Step title="Click Connect Google Calendar">
    You are taken to Google to sign in.
  </Step>

  <Step title="Approve access">
    Google asks you to grant TimeTracker access to your calendar, plus your email
    and basic profile.
  </Step>

  <Step title="Come back">
    You land on the integrations page with a toast – **"Google Calendar
    connected."**
  </Step>
</Steps>

If something goes wrong you see *"Couldn't connect Google Calendar. Please try
again."* Nothing is saved when a connection fails part way.

## The connected card

Once connected the card shows:

| Part                     | What it is                                                  |
| ------------------------ | ----------------------------------------------------------- |
| **Connected**            | A green dot and the word Connected                          |
| **as `<email>`**         | Which Google account is linked                              |
| **Last synced**          | The date and time of the last run, or **"Not synced yet."** |
| **Last error**           | Appended only when the last run failed                      |
| **Imported event color** | The colour imported Google events get in the Planner        |
| **Sync now**             | Runs a sync immediately. Reads **Syncing…** while it works. |
| **Disconnect**           | Removes the connection                                      |

## What syncs each way

### Google → TimeTracker

| Google             | Becomes                      |
| ------------------ | ---------------------------- |
| Event title        | Block title                  |
| Event description  | Block notes                  |
| Start and end time | Block start and end          |
| Google Meet link   | The block's meeting link     |
| Attendee responses | Who has accepted or declined |

| Not imported                   | Why                                           |
| ------------------------------ | --------------------------------------------- |
| **All-day events**             | A planned block needs a start and an end time |
| Events with no valid time span | Nothing usable to plan                        |

Cancelling an event in Google deletes the matching block in TimeTracker.

### TimeTracker → Google

Only blocks **you created in TimeTracker** are pushed. A block that came from
Google is never pushed back, so nothing loops.

| Block         | Becomes                                                 |
| ------------- | ------------------------------------------------------- |
| Title         | Event title, or `Planned block` when the title is empty |
| Notes         | Event description                                       |
| Start and end | Event start and end                                     |
| Participants  | Google guests                                           |
| Meeting link  | A Google Meet conference                                |

<Note>
  A block with **no participants** is created in Google without emailing anyone. A
  block with participants sends Google's normal invitations. So a focus block never
  spams your team.
</Note>

## Only the organiser pushes a shared block

This is the rule that keeps a team block from being duplicated.

A block with several people has one **organiser** – the person who created it.
Only the organiser's connection pushes it to Google.

| Person                                      | What they see                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------ |
| **The organiser**                           | The block in TimeTracker, and the event on their Google Calendar         |
| **A participant with Google connected**     | The block in TimeTracker, and Google's own invitation from the organiser |
| **A participant with no Google connection** | The block in TimeTracker, and nothing in Google                          |

One Google event exists, owned by the organiser. Everyone else is a guest on it,
exactly as they would be for any meeting.

<Warning>
  Declining the Google invitation does **not** delete the block. A guest's response
  is read back as an RSVP only – it can never remove the organiser's block or
  anyone else's.
</Warning>

## When sync runs

| Trigger                | Timing                                     |
| ---------------------- | ------------------------------------------ |
| Automatic              | Every **15 minutes**                       |
| After you edit a block | About **5 seconds** after you stop editing |
| **Sync now**           | Immediately                                |

The 5-second wait is deliberate. Drag a block, resize it and rename it, and all
three changes go to Google as one update rather than three.

A full sync reads **30 days back and 90 days forward**. After that it only picks
up what changed.

## When two sides disagree

The most recent change wins. If you move a block in TimeTracker and someone moves
the same event in Google, whichever happened last is kept.

## Example

Priya Raman runs Northwind Studio's delivery and lives in Google Calendar.

<Steps>
  <Step title="She connects">
    **Settings → Integrations → Connect Google Calendar**.
  </Step>

  <Step title="Her meetings appear">
    Her client calls import as planned blocks, so the Planner shows her real
    capacity rather than a fictional empty week.
  </Step>

  <Step title="She plans work">
    She creates a 4-hour block for Sarah Lin and Jonas Bergman on Bluebird Coffee –
    Website Redesign.
  </Step>

  <Step title="Google gets one event">
    Priya is the organiser, so her connection pushes it. Sarah and Jonas get a
    normal Google invitation.
  </Step>

  <Step title="Jonas declines">
    His response shows on the block in TimeTracker. The block itself stays put.
  </Step>
</Steps>

## Options and settings

| Setting                  | What it does                                         |
| ------------------------ | ---------------------------------------------------- |
| **Imported event color** | The colour Google-imported blocks get in the Planner |
| **Sync now**             | Forces a sync without waiting                        |
| **Disconnect**           | Removes the link                                     |

## Disconnecting

Click **Disconnect**. You get *"Google Calendar disconnected. Imported blocks were
kept."*

| What happens                     | What does not                                                           |
| -------------------------------- | ----------------------------------------------------------------------- |
| Syncing stops in both directions | Imported blocks stay in TimeTracker – they become ordinary local blocks |
| The Google account is unlinked   | Events already created in Google stay in Google                         |

<Tip>
  Disconnect works even if an admin has turned the Calendar app off. Withdrawing
  access must never be blocked.
</Tip>

## Permissions

| Action                                    | Capability     | Roles                                 |
| ----------------------------------------- | -------------- | ------------------------------------- |
| Connect, sync, set the colour, disconnect | `block.manage` | Owner, Admin, Project Manager, Member |

This is a planner capability, not an admin one – the people who plan work are the
people who connect a calendar. See
[Roles and capabilities](/concepts/roles-and-capabilities).

## What happens if the app is turned off

Turning the **Calendar** app off under **Settings → Apps**: *"Syncing stops in
both directions. Events already in Google Calendar stay there, and connections
are kept."*

Turn it back on and sync resumes with the same connection.

## Common questions

<AccordionGroup>
  <Accordion title="Does everyone in the workspace share one calendar connection?">
    No. Each person connects their own Google account, and a connection only ever
    reads and writes that person's calendar.
  </Accordion>

  <Accordion title="Why did my all-day event not import?">
    All-day events are skipped. A planned block needs a real start and end time
    to sit in the Planner.
  </Accordion>

  <Accordion title="Why is a team block only on the organiser's Google Calendar?">
    It is on everyone's, through Google's own invitation. Only the organiser's
    connection creates the event; everyone else is a guest on it.
  </Accordion>

  <Accordion title="Will my team get emails when I plan a focus block?">
    No. A block with no participants is created in Google without notifying
    anyone. Only blocks with participants send invitations.
  </Accordion>

  <Accordion title="What happens to imported blocks when I disconnect?">
    They stay. They become ordinary local blocks that no longer sync.
  </Accordion>

  <Accordion title="I changed a block and Google has not updated.">
    Wait a few seconds – edits settle before syncing so a burst of changes goes
    as one update. Then use **Sync now**.
  </Accordion>

  <Accordion title="Does this sync my tracked time to Google?">
    No. It syncs **planned blocks**, which are what you intend to do. Tracked time
    is what actually happened. See
    [Planner vs tracked time](/planner/planner-vs-tracked-time).
  </Accordion>
</AccordionGroup>

## Troubleshooting

**The card shows a Last error.** The message names the problem. Click **Sync
now** to retry. If it mentions expired access, disconnect and connect again.

**Nothing has synced.** Check for **"Not synced yet."** on the card. Automatic
sync runs every 15 minutes, so a brand-new connection may not have run yet. Use
**Sync now**.

**I cannot see the Connect button.** You need `block.manage`. The card says so.
Ask an Owner or Admin.

**The whole page is missing.** The Calendar app is off, or your plan does not
include it. Check **Settings → Apps**.

**Blocks are duplicated.** Check who the organiser is. Only their connection
pushes to Google – a second event usually means someone recreated the block by
hand in Google rather than accepting the invitation.

## Related guides

<CardGroup cols={2}>
  <Card title="Integrations overview" icon="plug" href="/integrations/overview">
    Everything TimeTracker connects to.
  </Card>

  <Card title="Plan work blocks" icon="calendar" href="/planner/plan-work-blocks">
    Creating the blocks that sync.
  </Card>

  <Card title="Multi-person blocks" icon="users" href="/planner/multi-person-blocks">
    Organisers, participants and how they differ.
  </Card>

  <Card title="Planner vs tracked time" icon="clock" href="/planner/planner-vs-tracked-time">
    Planned is not the same as done.
  </Card>

  <Card title="Apps and modules" icon="toggle-on" href="/concepts/apps-and-modules">
    Turning the Calendar app on.
  </Card>

  <Card title="Plans and features" icon="tag" href="/concepts/plans-and-features">
    Calendar sync is a Pro feature.
  </Card>
</CardGroup>