Google Calendar

Overview

This page is for whoever runs the install. Google Calendar sync needs one OAuth client in Google Cloud and four environment variables. Once they are set, every user can connect their own Google account, and each schedule's owner decides which calendar the schedule syncs with and in which direction. Nothing is configured per schedule on the server.

The OAuth client you create here is used in three places:

• Calendar sync, the subject of this page: a schedule and one Google calendar kept in step, in one direction or both
• Import from Google Calendar: a one-time, read-only copy of the events a schedule's owner picks on the import page. See One-time import
• Log in with Google: the button appears on the log in page as soon as GOOGLE_CLIENT_ID is set, so register its redirect URIs too, in step 3

Where It Lives in the App

Open full size

Open full size

Prerequisites

• A Google Cloud Console project
• Google Calendar API enabled on that project
• OAuth 2.0 credentials of type "Web application"
• The Laravel scheduler cron, which drives the inbound poll and the channel renewals
• For near-real-time inbound sync, the app reachable at a public HTTPS URL on a domain you have verified with Google (Google will not create a change channel that points at a private address, a plain-HTTP address or an unverified domain)

Setup Instructions

1. Google Cloud Console Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Go to "APIs & Services" > "Library"
4. Search for "Google Calendar API"
5. Click on it and press "Enable"

2. OAuth Consent Screen and Scopes

Configure the consent screen and add the scopes Event Schedule requests. Anything missing here shows up later as a failed sync rather than a failed sign-in.

• https://www.googleapis.com/auth/calendar.events to create, update and delete events
• https://www.googleapis.com/auth/calendar.readonly to list calendars and read events for inbound sync and for the import page
• openid, email and profile to identify the connecting account

A connection started on the import page asks for read access only: calendar.readonly and the three identity scopes. Every other connection asks for all five.

While the project is in testing mode, add each account that will connect a calendar as a test user. Event Schedule always requests offline access and forces the consent prompt, so a refresh token is issued on every connect.

3. OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth 2.0 Client IDs"
3. Choose "Web application" as the application type
4. Add the authorized redirect URI that calendar sync and the import page both use: https://yourdomain.com/google-calendar/callback for production, or http://localhost:8000/google-calendar/callback for development
5. Add the three redirect URIs of the Google sign-in buttons, on the same host: /auth/google/callback, /auth/google/connect/callback and /auth/google/set-password/callback
6. Save the credentials and note down the Client ID and Client Secret

4. Environment Configuration

Add the following environment variables to your .env file. .env.example carries the same four, commented out, in its "Google Calendar sync (optional)" block:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://yourdomain.com/google-calendar/callback
GOOGLE_WEBHOOK_SECRET=a_long_random_string

If you cache your configuration, run php artisan config:cache after editing .env, or the new values will not be picked up.

Variable Reference

5. Scheduler Cron

Inbound polling and channel renewal run through the Laravel scheduler, so the standard cron entry from Installation has to be in place:

* * * * * php artisan schedule:run

Features

How Sync Works

Sync Direction

Each schedule picks one of four options under Sync Direction. Saving the schedule is what applies the choice and sets up the change channel. Only the schedule's owner sees the controls, and only while their own Google account is connected. To start reading from Google the owner has to choose a calendar: the account's main calendar is never read by default, and a save that starts reading without one is refused with "Choose the calendar to read events from."

Event Information Synced

A Google Calendar entry created by Event Schedule carries:

• The event name, as the Google event title
• The event description. If the schedule has a Calendar Description Template set under Integrations → Calendar text and feeds, the rendered template is sent instead (see the available variables). On an update with no template and an empty description, no description is sent, so notes you typed on the Google copy survive
• Start and end times in the schedule's timezone. The end is the start plus the event duration, and two hours when the event has no stored duration
• Location, taken from the venue's best available address. Events with no venue are sent without a location
• Google visibility: public for normal events, private for unlisted ones

What Is Not Sent

• Everything else about the event. Only the fields above leave Event Schedule: images, ticket types, prices and attendees stay here
• Drafts. A Draft or Internal event is never pushed by a save, so an event first appears on the calendar when you publish it
• Recurrence. Event Schedule does not send a recurrence rule, so a recurring event becomes a single Google entry on the series start date rather than a repeating series. Use the schedule's iCal feed or the .ics download when you need every date of a series in a calendar app

Events That Arrive From Google

What the owner sees is described once, in the schedule guide: new entries arrive as drafts unless Publish new events automatically is on, they wait under Events from your calendar, and some entries are never read in at all (What stays off your page). In Google's terms, an entry is skipped when its visibility is private or confidential, when the calendar's owner declined it, or when it is not an ordinary event (out of office, focus time, working location). An entry that shows meeting details or an email thread is held as a draft even with automatic publishing on.

Inbound sync expands Google's recurring events first, so each occurrence arrives as its own event. Events brought in this way:

• Are added to the schedule as its own events, and use the schedule's slug pattern and default category
• Take their name, description, start time and duration from the Google entry. The description is converted from HTML to Markdown
• Convert the Google location into a venue, reusing one of your existing venues when the name or address matches and creating one when nothing matches. An event that already has a venue keeps it. A meeting link, a dial-in number or a provider's name ("Microsoft Teams Meeting") is never made into a venue
• Are matched to an existing event by name and start time when there is no stored mapping yet, so an event you pushed out does not come back as a duplicate
• Never overwrite an appointment booking. An event created by a booking is owned by Event Schedule: inbound sync does not rewrite its name, description or time, so moving the Google copy will not move a customer's booking

Real-Time Sync and Polling Fallback

• Saving a schedule with an inbound direction creates a Google change channel that posts to the webhook endpoint, so calendar edits show up within moments. If the channel cannot be created the save still succeeds, the failure is logged, and inbound changes fall back to the poll
• The 15-minute google:sync command polls for changes as a fallback, and is the main path on installs with no public URL. It uses the schedule owner's connected account
• The daily google:refresh-webhooks command replaces channels that are within three days of expiring
• Inbound sync is incremental: Event Schedule stores Google's sync cursor, so each run fetches only what changed. If Google rejects the stored cursor, which happens after a long gap or a calendar switch, one full sync runs to rebuild it
• The first full sync covers a window from 30 days ago to 365 days ahead
• Each schedule that reads from Google also gets one more full read of that window, so entries read in before the private-entry rules existed are judged by them too. It only re-judges: it takes an entry off the page or puts back one it took off, and never rewrites what the owner edited here. Only the scheduled google:sync runs it (a webhook or Sync Events never does), at most ten schedules per run, and a read too big for one run carries on in the next
• Inbound work is serialized per schedule, so the webhook and the poll cannot import the same event twice

When an Event Is Deleted in the Connected Calendar

Schedules that read from Google also choose When an event is deleted in the connected calendar: Keep it here (the default), Mark as cancelled, or Delete it here. The three choices, and what is never deleted, are described in the schedule guide. It is one setting shared with Outlook, shown in the Google row while the owner's Google Calendar is connected and the direction reads from Google.

Two things an operator should know. Only a real deletion in Google triggers it, and only through the incremental sync, so the schedule needs one completed inbound sync first. And marking an event cancelled this way notifies nobody: the notice to ticket buyers goes out only from Cancel event in the event editor.

Calendar Sync on an Event

Once a schedule has a calendar selected and a direction that includes To Google Calendar, the Listing tab of a saved event ends with Calendar sync. Its Synced and Not synced states, Sync Now and Remove are described in the event guide. Sync Now is not offered, and the server refuses it, for a Draft, Internal or cancelled event.

For an operator, one detail matters: the status is the schedule owner's copy, while Sync Now and Remove act with the Google account of whoever is signed in, so they are the owner's buttons to use.

Personal Calendar Sync for Members

A team member who is not the schedule owner sees a Sync to My Calendar block in the schedule's Google Calendar row. Choosing one of their own calendars mirrors the schedule's events into it, in addition to whatever the owner has configured, and the member gets the same create, update and delete operations even when the owner has left the schedule on No Sync. Turning it back off removes the copies the member received.

• The member needs their own connected Google account, with a connection that may write (see read-only connections)
• The block has its own Save button, separate from the schedule form
• Turning it on does not backfill: events already on the schedule reach the member's calendar the next time they are edited
• This is a Google-only feature, since the Outlook and CalDAV integrations sync the owner's calendar only
• Adding team members beyond the owner is an Enterprise feature on the hosted service, and a selfhosted install resolves to Enterprise

Read-Only Connections

A Google connection made from the import page asks Google for read access only. It can import, and it can sync From Google Calendar, but it cannot add or change anything on a Google calendar. While the owner's connection is read-only:

• In the Google Calendar row, To Google Calendar and Bidirectional Sync are switched off under a notice that reads "This connection can only read your Google Calendar." Allow at Google in that notice runs the full consent and comes back to the row
• Nothing is pushed on save, and Sync Now, Sync Events with an outbound direction and turning on Sync to My Calendar are refused with the same notice
• A schedule saved in that state stores Bidirectional Sync as From Google Calendar, and To Google Calendar as No Sync

Connections made before Event Schedule began recording what Google granted count as full connections.

One-Time Import From Google Calendar

The import page has its own Google Calendar source, for events that live in a calendar that is not public. It is separate from sync: the schedule's owner connects with read access, picks one calendar, and chooses which of its upcoming events to copy. Nothing is written to Google, and events added to that calendar later do not arrive by themselves.

The source appears for a schedule's owner once GOOGLE_CLIENT_ID is set, and it uses the same OAuth client and redirect URI as sync, so there is nothing more to configure. The walkthrough for owners is Importing from Google Calendar.

Usage

Step by Step

Steps 1 and 2 turn sync on. The rest are for events that existed before it was on, for a change of calendar, and for team members.

1. Connect Google Calendar

   1. Open Settings in the sidebar and choose the Integrations tab
   2. In Google Settings, under Google Calendar, click Connect Google Calendar
   3. Approve the request on Google's consent screen. You come back to the same section, which now reads Google Calendar Connected

   The Google Account line above it is the separate sign-in connection. Connecting there does not connect a calendar, and you can use either one without the other. Connecting is half of it: nothing syncs until a schedule is told to.

2. Choose a Calendar and Sync Direction

   1. Open the schedule, click Edit Schedule, choose the Integrations tab and open the Google Calendar row
   2. Pick the calendar to sync with under Select Google Calendar. A calendar made after the page opened appears after Refresh list. Choosing the account's main calendar shows a warning, because a main calendar usually holds meetings and appointments: make a calendar just for public events in Google Calendar and choose that one
   3. Choose a Sync Direction: To Google Calendar, From Google Calendar, Bidirectional Sync or No Sync
   4. With From Google Calendar or Bidirectional Sync selected, decide on Publish new events automatically. Off (the default), new events wait as drafts for you to review; on, they go onto the public page as they arrive, with a warning that says so
   5. With the same two directions, choose When an event is deleted in the connected calendar: Keep it here, Mark as cancelled, or Delete it here. Keep it here is the default
   6. Click Save

   Saving is what applies the selection and sets up the change channel. When it starts reading from Google, the Schedule tab says that the calendar's events will arrive within 15 minutes. It does not push the events you already have: use step 3, 4 or 5 for those. Only the schedule's owner sees these controls. An owner who has not connected yet sees a Connect Google Calendar button in the row instead, which goes straight to Google and brings them back to this row.

3. Sync a Single Event

   Open the event's form and choose the Listing tab; Calendar sync is at its end. On the Google Calendar line, click Sync Now, or Remove to take the copy back off the calendar. It appears once the schedule has a calendar selected and pushes to Google. Sync Now is for an event guests can see: publish a Draft or Internal event first.

4. Sync the Whole Schedule

   Open the schedule, click Actions and choose Sync Events, then confirm. The entry is listed for the schedule's owner once their Google account is connected and the schedule has a calendar selected.

   • It runs the schedule's saved sync direction now. A schedule left on No Sync is pushed to Google instead, and To Google Calendar is then saved as its direction
   • A push only creates events that are missing from the calendar; it does not rewrite copies that are already there
   • An inbound direction also imports from the calendar, exactly as the scheduled poll would

5. Resync Everything to Google

   Use this after switching Google accounts or target calendars.

   1. Save the schedule with the new calendar selected. The resync pushes to the saved calendar, and the button stays disabled while the dropdown differs from it
   2. In the schedule's Google Calendar row, click Resync to Google Calendar and confirm
   • Only the schedule owner sees this button, and the request is refused unless the direction includes To Google Calendar
   • Events already sitting on the saved calendar are left alone. An event whose copy is on a different calendar has that old copy deleted and a fresh one created, so switching calendars does not leave duplicates behind
   • It only ever pushes to Google and never imports, and it only covers published events
   • The resync works through the schedule ten events at a time, each batch queuing the next. With QUEUE_CONNECTION=database, the scheduler's minutely queue worker carries it to the end, which can take a few minutes on a large schedule. On the shipped sync setting the batches run one after another once the page has responded, in the same PHP process, so a very large schedule is better served by database. Clicking it again is safe: it only redoes work still outstanding

6. Mirror a Schedule into Your Own Calendar

   1. As a team member who does not own the schedule, connect your own Google Calendar first (step 1)
   2. Open the schedule's Edit Schedule → Integrations → Google Calendar row and find Sync to My Calendar
   3. Pick one of your calendars under Select Your Calendar and click Save. That block saves on its own, so you do not need to save the schedule

   Choosing No Sync there and saving removes the events again.

Automatic Sync

Once a schedule pushes to Google, publishing, editing, cancelling and deleting an event change its Google copy with no extra step, and Draft and Internal events are never pushed. The event guide's Calendar Sync section says what is copied when. Members with personal calendar sync receive the same create, update and delete operations even when the owner has not turned on sync for the schedule.

An event the sync read in from Google is a copy of the owner's own entry, and the entry belongs to the owner's calendar, so it is treated differently: publishing it does not create a second entry in Google, and hiding it as a draft or cancelling it never deletes the owner's original. Deleting it deletes the original only when it is published and the schedule's direction sends events to Google (Bidirectional Sync, or To Google Calendar); with From Google Calendar the original stays. A team member's own copy, from Sync to My Calendar, is removed as usual.

For Developers: Sync Helpers on the Event Model

Outbound sync and status checks go through the Event model:

// Push to every schedule that syncs to Google, plus members with personal sync
$event->syncToGoogleCalendar('create'); // or 'update', 'delete'

// Is there a Google copy for a given schedule?
$event->isSyncedToGoogleCalendarForRole($role->id);
$event->isSyncedToGoogleCalendarForSubdomain($subdomain);

// 'not_connected', 'not_synced' or 'synced'
$event->getGoogleCalendarSyncStatus($user, $role->id);

For Developers: How the Work Is Dispatched

The mapping between an event and its Google copy lives in the calendar_syncs table, one row per user, event and schedule, together with the calendar the copy was created on.

• SyncEventToGoogleCalendar performs one create, update or delete. Saving an event runs it inline, so the calendar is up to date by the time the save finishes and a queue worker is not required
• ForceResyncGoogleCalendar backs the Resync to Google Calendar button and is queued. It handles ten events per run and dispatches a follow-up while any remain, so a large schedule finishes across several runs instead of timing out. On the sync connection each follow-up waits until the page has responded, by which point the batch before it has released its overlap lock, so the batches run back to back in the same PHP process
• Inbound sync is serialized per schedule with a lock, so the webhook and the 15-minute poll cannot import the same event twice

API Endpoints

These are the application's own session-authenticated routes, not part of the public REST API. Every route except the two webhook routes requires a signed-in user with a verified email address. The webhook routes are public, and are authenticated by the channel token instead.

Scheduled Commands

These Artisan commands keep inbound sync and the change channels healthy:

Troubleshooting

Common Issues

Pick the line that matches what you see.

Logs

Sync operations are logged in the application logs. Check storage/logs/laravel.log for detailed information about sync operations, and storage/logs/scheduler.log for the scheduled sync and channel-renewal runs.

Security Considerations