Overview
Google Calendar integration is an optional feature that allows staff members to automatically sync their room reservations to Google Calendar. This creates calendar events that include the room name, reservation time, and staff member’s username.This feature is only available for staff users. Student reservations are not synced to Google Calendar.
When to Use Google Calendar
Google Calendar integration is useful when:- Staff members want room bookings to appear in their shared calendar
- You need centralized visibility of all room reservations
- You want calendar invites sent to participants
- Integration with other calendar systems is needed
If you don’t need calendar integration, you can skip this setup. The application will work fine without it.
Prerequisites
- Google Account with access to Google Cloud Console
- Google Calendar where events will be created
- Basic understanding of Google Cloud Platform
Setup Process
1. Create Google Cloud Project
Access Google Cloud Console
Navigate to Google Cloud Console
Create New Project
- Click Select a project → New Project
- Enter project name:
BookMe Calendar Integration - Click Create
2. Create Service Account
Service accounts allow server-to-server authentication without user interaction.Create Service Account
- Click Create Service Account
- Service account name:
book-me-calendar - Service account ID: Auto-generated (e.g.,
[email protected]) - Description: “Service account for BookMe calendar integration”
- Click Create and Continue
3. Generate Service Account Key
4. Configure Google Calendar
Create or Select Calendar
- Open Google Calendar
- Create a new calendar or use an existing one
- Recommended: Create a dedicated “Hive Meeting Rooms” calendar
Share Calendar with Service Account
- Click on the calendar → Settings and sharing
- Scroll to Share with specific people
- Click Add people
- Enter the service account email:
client_email)
5. Set permission to Make changes to events
6. Click SendGet Calendar ID
- In calendar settings, scroll to Integrate calendar
- Copy the Calendar ID (looks like
[email protected]) - Save this for environment configuration
5. Configure Environment Variables
Add Google Calendar configuration to your.env file:
Variable Descriptions
| Variable | Description |
|---|---|
GOOGLE_CREDENTIALS_FILE | Path to service account JSON credentials |
GOOGLE_CALENDAR_SCOPE | Google Calendar API scope (fixed value) |
GOOGLE_CALENDAR_ID | Calendar ID where events will be created |
The calendar scope
https://www.googleapis.com/auth/calendar grants full read/write access to calendars. This is required to create and delete events.How It Works
When a staff member creates a reservation, BookMe:- Creates the reservation in the database
- Creates a Google Calendar event with:
- Title:
[username] Room Name meeting room - Description:
Created via BookMe - Time: Reservation start and end times
- Timezone:
Europe/Helsinki
- Title:
- Stores the Google Calendar event ID in the database
- Sends confirmation email to the user
- BookMe deletes the database record
- Deletes the corresponding Google Calendar event
Implementation details can be found in
internal/google/calender.go:74 (CreateGoogleEvent) and internal/google/calender.go:121 (DeleteGoogleEvent).Event Format
Google Calendar events created by BookMe:Testing Integration
Verify in Google Calendar
- Open your Google Calendar
- Check the shared calendar
- Verify the event appears with correct details
Health Check
BookMe includes a health check for the Google Calendar service. The health endpoint verifies:- Service account authentication
- Calendar API accessibility
- Permissions to access the configured calendar
See
internal/google/calender.go:112 for the HealthCheck implementation.Troubleshooting
Credentials File Not Found
GOOGLE_CREDENTIALS_FILE is correct:
Invalid Credentials
- Ensure the JSON file is valid
- Verify it’s a service account key (not OAuth client credentials)
- Re-download the key from Google Cloud Console
Calendar Not Found
- Verify
GOOGLE_CALENDAR_IDis correct - Ensure calendar is shared with the service account
- Check service account email has “Make changes to events” permission
Permission Denied
- Verify service account has Editor role in Google Cloud
- Check calendar sharing permissions
- Ensure
GOOGLE_CALENDAR_SCOPEincludes calendar write access
Events Not Appearing
Check:- Correct Calendar: Viewing the right calendar in Google Calendar
- Timezone: Events use
Europe/Helsinkitimezone - Date Range: Events may be in the future
- Logs: Check application logs for errors
Retry Failures
The calendar service includes retry logic:- Max retries: 3
- Wait time: 4-10 seconds
- Network connectivity
- Google API status
- Rate limits
Retry configuration is in
internal/google/calender.go:51-53.Security Considerations
Best Practices
- Principle of Least Privilege: Grant minimal required permissions
- Separate Calendars: Use dedicated calendar for BookMe events
- Monitor Usage: Track Google Calendar API usage in Cloud Console
- Key Rotation: Rotate service account keys every 90 days
- Audit Logs: Enable Google Cloud audit logging
Rate Limits
Google Calendar API has the following limits:- Queries per day: 1,000,000 (should be more than sufficient)
- Queries per 100 seconds per user: 500
Production Deployment
For production environments:Use Environment Variables
Instead of file paths, use environment variables with base64-encoded credentials:Modify your code to decode from environment variable if needed.
Secure Storage
Store credentials in:
- AWS Secrets Manager
- Google Secret Manager
- Kubernetes Secrets
- Vault
Disabling Google Calendar
If you want to disable Google Calendar integration:- Remove or comment out the Google Calendar environment variables in
.env - The application will detect missing configuration and skip calendar operations
- Staff reservations will still work, but won’t sync to Google Calendar
The application gracefully handles missing Google Calendar configuration. It will log a warning but continue operating normally.