Calendar App Overview

Keep your work life and personal calendar perfectly in sync — shifts, time off, interviews, and every important deadline in one unified view.

---

What Is the Calendar App?

The Calendar app bridges MangoApps Workforce with the external calendars your employees already use every day. It automatically pushes work shifts, approved leave, company holidays, training deadlines, interviews, 1:1 meetings, and more directly into Google Calendar, Microsoft Outlook, or any iCal-compatible client. Instead of manually copying schedules between systems, employees connect once and stay in sync.

Core Value Proposition:

• 🔄 Automatic Sync — Work events flow to your personal calendar without lifting a finger
• 🌐 Multi-Provider Support — Google Calendar, Microsoft Outlook, and iCal/CalDAV all supported
• 📋 Unified Work View — Shifts, leave, holidays, interviews, training, tasks, and meetings in one calendar
• 🔐 Privacy First — Events default to private visibility with encrypted credential storage

---

At a Glance

🔗 Providers	📅 Event Types	⚡ Sync Modes	📱 Platforms
3 (Google, Outlook, iCal)	10+ (Shifts, Leave, Holidays, Training, Interviews, Tasks, Meetings, and more)	3 (Scheduled, Real-Time, Webhook)	Web, Mobile

Perfect For:

• 🏭 Shift Workers — See upcoming shifts alongside personal commitments to avoid conflicts
• 🏢 Office & Hybrid Teams — Keep 1:1 meetings, reviews, and training on your Outlook or Google calendar
• 🧑‍💼 Recruiters & Hiring Managers — Interview schedules sync directly to external calendars with candidate details
• 📊 Managers & HR — Company holidays, business deadlines, and performance cycles visible at a glance

---

How It Works

Calendar Sync Flow

┌────────────────────────────────────────────────────────────────────────┐
│                    CALENDAR SYNC ARCHITECTURE                          │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌──────────────┐                          ┌────────────────────────┐  │
│  │  MANGOAPPS   │    Push Events           │  EXTERNAL CALENDAR     │  │
│  │  WORKFORCE   │ ─────────────────────▶   │                        │  │
│  │              │                          │  • Google Calendar      │  │
│  │  • Shifts    │                          │  • Outlook / O365      │  │
│  │  • Leave     │    Webhook Triggers      │  • iCal / CalDAV       │  │
│  │  • Holidays  │ ◀─────────────────────   │    (Apple, etc.)       │  │
│  │  • Training  │                          │                        │  │
│  │  • Meetings  │                          └────────────────────────┘  │
│  └──────────────┘                                                      │
│                                                                        │
│  ─────────────────────── SYNC ENGINE ───────────────────────────────   │
│                                                                        │
│  ┌──────────────┐   ┌──────────────┐   ┌─────────────────────────┐    │
│  │  SCHEDULED   │   │  REAL-TIME   │   │  WEBHOOK LISTENERS      │    │
│  │  Every 10min │   │  On change   │   │  Google Push / Outlook  │    │
│  │  (cron job)  │   │  (job queue) │   │  Subscriptions          │    │
│  └──────────────┘   └──────────────┘   └─────────────────────────┘    │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Connection Flow (Employee)

┌─────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────────┐   ┌─────────┐
│ OPEN    │──▶│ CHOOSE      │──▶│ OAUTH LOGIN  │──▶│ GRANT        │──▶│ SYNCING │
│ Calendar│   │ Provider    │   │ Google /     │   │ Calendar     │   │ Active  │
│ App     │   │ (3 options) │   │ Outlook      │   │ Permissions  │   │         │
└─────────┘   └─────────────┘   └──────────────┘   └──────────────┘   └─────────┘
                    │                                                        │
                    │  iCal Path                                             │
                    └──▶ Copy Feed URL ──▶ Paste in Calendar App ───────────┘

Event Aggregation

┌───────────────────────────────────────────────────────────────────┐
│                  EVENT SOURCES → UNIFIED CALENDAR                  │
├───────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Work & Scheduling ──┐                                            │
│   • Shifts           │                                            │
│   • Availability     ├──┐                                         │
│                      │  │                                         │
│  Time Off ───────────┤  │   ┌──────────────────┐                  │
│   • Leave Requests   │  ├──▶│  CalendarEvents   │──▶ JSON API     │
│   • Holidays         │  │   │  Service          │──▶ iCal Feed    │
│                      │  │   │  (Aggregator)     │──▶ Push Sync    │
│  Recruiting ─────────┤  │   └──────────────────┘                  │
│   • Interviews       │  │                                         │
│                      ├──┘                                         │
│  Development ────────┤                                            │
│   • Training         │                                            │
│   • Tasks            │                                            │
│                      │                                            │
│  Management ─────────┤                                            │
│   • 1:1 Meetings     │                                            │
│   • Review Cycles    │                                            │
│   • Business Events  │                                            │
│                      │                                            │
│  Wellness ───────────┘                                            │
│   • Benefits Events                                               │
│   • Onboarding                                                    │
│                                                                    │
└───────────────────────────────────────────────────────────────────┘

---

Key Features

🔗 Multi-Provider Calendar Integration

Connect to the calendar service your team already relies on.

Provider	Auth Method	Real-Time Sync	Push Notifications	iCal Feed
Google Calendar	OAuth 2.0 (via SSO config)	✅	✅ (Webhooks)	—
Microsoft Outlook	OAuth 2.0 (Entra ID / Graph API)	✅	✅ (Subscriptions)	—
iCal / CalDAV	Signed URL token	—	—	✅

• Google and Outlook use the same SSO configuration the employee logged in with for a seamless experience
• iCal generates a signed, read-only feed URL that works with Apple Calendar, Thunderbird, or any calendar client
• Credentials are encrypted at rest using Rails encrypted attributes
• Each user can connect one integration per provider per business

📅 Supported Event Types

The Calendar app aggregates events from across the platform into a single calendar view.

Event Type	Color	Source	Always Available
Work Shifts	🟢 Green	Scheduling module	✅
Time Off / Leave	🔵 Blue	Leave Management	✅
Company Holidays	🟡 Yellow	Business holidays	✅
Training & Development	🟣 Purple	Training app	Feature-dependent
Interviews	🔴 Red	Recruiting / Job Board	Feature-dependent
Tasks & Deadlines	🔵 Teal	Tasks app / EPMS	Feature-dependent
Business Events	⚫ Dark	Performance cycles	Feature-dependent
1:1 Meetings	🟣 Deep Purple	EPMS Meetings	Feature-dependent
Wellness & Benefits	💚 Green	Benefits Management	Feature-dependent
Onboarding Checkpoints	👤 Blue	Onboarding Hub	Feature-dependent

Feature-dependent event types appear automatically when their corresponding marketplace app is enabled.

⚡ Sync Engine

Three layers of synchronization keep calendars current.

Sync Mode	Trigger	Latency	Use Case
Scheduled Sync	Cron job every 10 minutes	≤ 10 min	Baseline sync for all integrations
Real-Time Sync	Shift/leave created or updated	Seconds	Immediate push on schedule changes
Webhook Sync	Google/Outlook push notification	Seconds	External calendar changes trigger re-sync

• CalendarSyncAllJob runs on a 10-minute cron, queuing individual CalendarSyncJob workers for each integration that is due
• Each integration tracks last_sync_at and respects configurable sync frequency (default: 30 minutes)
• Sync jobs use exponential backoff retry (up to 3 attempts) and automatically discard unrecoverable errors like revoked tokens
• Push notification channels are automatically renewed by CalendarPushNotificationRenewalJob

📱 iCal Feed (Subscribe URL)

For users who prefer a read-only subscription without OAuth:

• A signed URL is generated per user using Rails.application.message_verifier(:calendar_feed)
• The feed serves standard .ics format with events from the past 30 days to 90 days ahead
• Events include emoji prefixes for quick visual identification (💼 Shift, 🏖️ Leave, 🎉 Holiday, 📚 Training, etc.)
• Works with any calendar client that supports iCal subscriptions — Apple Calendar, Thunderbird, Yahoo Calendar, etc.

🔧 Sync Settings (Per Integration)

Each connected calendar integration has granular sync controls.

Setting	Default	Description
Sync Shifts	✅ On	Push work shift events to external calendar
Sync Leave Requests	✅ On	Push approved time off
Sync Holidays	✅ On	Push company holidays
Sync Interviews	✅ On	Push interview appointments
Sync Training	✅ On	Push training due dates
Sync Tasks	✅ On	Push task deadlines
Sync Business Events	✅ On	Push performance cycles and deadlines
Sync 1:1 Meetings	✅ On	Push EPMS meetings
Event Visibility	Private	Calendar event privacy setting
Include Location	✅ On	Add location details to events
Include Description	❌ Off	Keep events clean by default
Sync Direction	Push to External	One-way from MangoApps to calendar

📊 Sync Monitoring & Logs

Every sync operation is tracked with detailed logs.

Metric	What It Tracks
Events Created	New events pushed to external calendar
Events Updated	Modified events re-synced
Events Deleted	Removed events cleaned up
Events Skipped	Unchanged events not needing sync
Duration	How long the sync took
Status	Success, Error, Partial, or Running

Sync logs use atomic SQL counter increments to prevent race conditions, and cap stored event details at 100 entries per log to control database size.

🔐 Connection Attempt Tracking

Failed OAuth connection attempts are tracked for visibility and troubleshooting.

Field	Purpose
Provider	Google, Outlook, or iCal
Status	Pending, Success, or Failed
Error Type	unauthorized_client, access_denied, invalid_client, redirect_uri_mismatch, etc.
Admin Recommendation	Actionable fix steps (e.g., “Add callback URL to Google Cloud Console”)
IP & User Agent	Security audit trail

---

User Roles & Permissions

Capability	Employee	Manager	HR	Admin
View unified calendar	✅	✅	✅	✅
Connect own calendar (Google/Outlook/iCal)	✅	✅	✅	✅
Toggle sync on/off for own integration	✅	✅	✅	✅
Trigger manual sync	✅	✅	✅	✅
Disconnect own calendar	✅	✅	✅	✅
Subscribe via iCal feed URL	✅	✅	✅	✅
View own sync logs	✅	✅	✅	✅
Access admin settings	—	—	—	✅
Enable/disable calendar sync globally	—	—	—	✅
Configure allowed providers	—	—	—	✅
Toggle provider availability (Google/Outlook/iCal)	—	—	—	✅
Choose which event types sync	—	—	—	✅
Set sync frequency	—	—	—	✅
Select OAuth configuration per provider	—	—	—	✅
View all user integrations	—	—	—	✅
Toggle sync for any user’s integration	—	—	—	✅
Trigger sync for any user	—	—	—	✅
Reset settings to defaults	—	—	—	✅
View organization-wide sync statistics	—	—	—	✅

---

Admin Configuration

Settings Dashboard

Admins access calendar settings from the app’s Settings tab. The configuration is organized into sections:

Core Settings
| Setting | Default | Description |
|———|:——-:|————-|
| Calendar Sync Enabled | ✅ | Master switch for all calendar sync |
| Allow User Self-Setup | ✅ | Let employees connect their own calendars |
| Sync Frequency | 30 min | How often the scheduled sync runs |
| Event Prefix | (empty) | Optional prefix for all synced events |
| Make Events Read-Only | ✅ | Prevent external edits to synced events |

Provider Settings
| Setting | Default | Description |
|———|:——-:|————-|
| Google OAuth Enabled | ✅ | Allow Google Calendar connections |
| Outlook OAuth Enabled | ✅ | Allow Outlook connections |
| iCal Enabled | ✅ | Allow iCal feed subscriptions |

Automation Settings
| Setting | Default | Description |
|———|:——-:|————-|
| Auto-Sync New Shifts | ✅ | Push new shifts immediately |
| Auto-Sync Shift Changes | ✅ | Push shift modifications immediately |
| Auto-Sync Leave Requests | ✅ | Push approved leave immediately |
| Enable Real-Time Sync | ✅ | Trigger sync on data changes |
| Notification on Sync Errors | ✅ | Alert on failed syncs |
| Conflict Resolution | Manual | How to handle event conflicts |
| Require Admin Approval | ❌ | Require admin approval for new connections |
| Sync Historical Events | ❌ | Sync events from the past |
| Max Days Ahead | 60 | How far into the future to sync |

Integration Mode

The Calendar app operates in one of three modes:

Mode	Description
Disabled	Calendar sync is turned off entirely
Admin Managed	Sync is enabled but only admins can set up integrations
User Self-Setup	Employees can connect their own calendars (default)

OAuth Configuration

Admins can select which SSO/OAuth configuration is used for each provider:

• Google Calendar — uses google_oauth2 SSO configurations (business-level or system-level)
• Microsoft Outlook — uses entra_id SSO configurations (business-level or system-level)
• Priority order: User’s login SSO → Admin-selected config → Business default → System default

Statistics Dashboard (Admin View)

Metric	Description
Total Integrations	All calendar connections across the business
Active Integrations	Connections in “active” status
Sync Enabled	Connections with sync turned on
Recent Syncs (24h)	Syncs completed in the last 24 hours
Failed Syncs (24h)	Syncs that errored in the last 24 hours
Providers Breakdown	Count per provider (Google, Outlook, iCal)

---

Mobile Experience

The Calendar app includes a dedicated mobile interface accessible at /m/apps/calendar:

• Upcoming Events View — See the next 7 days of shifts, leave, and holidays at a glance
• Integrations List — View all connected calendars with status indicators
• Toggle Sync — Enable or disable sync per integration with a single tap
• Manual Sync — Queue an immediate sync from mobile
• Provider Availability — See which providers are available to connect

The mobile interface uses the shared mobile layout with dark mode support, touch-optimized targets, and offline detection.

---

Getting Started

For Employees

1. Open the Calendar app from the marketplace sidebar
2. Choose your provider — Google Calendar, Outlook, or iCal
3. For Google/Outlook: Click “Connect” and sign in with your work account. Grant calendar permissions when prompted
4. For iCal: Copy the generated feed URL and paste it into your calendar app’s “Subscribe to Calendar” feature
5. Verify the connection — Your shifts and upcoming events should appear in your external calendar within minutes
6. Customize sync settings — Toggle which event types you want synced from the integration detail page

For Admins

1. Enable the Calendar app from the Marketplace
2. Open Settings and verify the master sync toggle is on
3. Configure providers — Enable Google, Outlook, and/or iCal based on your organization’s needs
4. Select OAuth configurations — Choose which SSO configuration each provider should use
5. Set sync preferences — Adjust frequency, event types, and automation settings
6. Monitor adoption — Use the statistics dashboard to track how many employees have connected

---

Best Practices

Practice	Recommendation
Start with defaults	The default configuration enables all providers and event types — a good starting point for most organizations
Use SSO alignment	When possible, use the same Google/Microsoft account for SSO login and calendar sync for a seamless experience
Monitor failed syncs	Check the admin statistics dashboard weekly for failed sync counts; expired tokens are the most common issue
Keep events private	The default “private” visibility protects employee schedule details from being visible to calendar-sharing recipients
Use iCal for read-only needs	If employees only need to see their schedule (not sync interactively), the iCal feed is the simplest option
Set a reasonable sync frequency	30 minutes is the default and works for most teams. Reduce to 15 minutes for fast-paced shift environments
Enable real-time sync	For shift-based organizations, real-time sync ensures last-minute schedule changes reach employees immediately
Review connection attempts	Use the connection attempt log to diagnose OAuth setup issues before employees report problems

---

Troubleshooting

Issue	Likely Cause	Fix
“Calendar sync is not enabled”	Admin has not enabled sync	Admin enables via Settings → Core Settings
“Google OAuth not configured”	No SSO configuration for google_oauth2	Admin configures Google OAuth in SSO settings
“Calendar credentials could not be decrypted”	Encryption key mismatch (e.g., after environment migration)	Employee reconnects calendar via the Reconnect button
Events not appearing	Sync has not run yet or event type is disabled	Trigger manual sync; verify event type is enabled in settings
“Rate limit exceeded”	More than 60 API requests per minute	Wait 1 minute and retry
“Authorization failed”	Token expired or revoked	Click Reconnect to re-authenticate with the provider
iCal feed shows old data	Client caches the feed	Most iCal clients refresh every 15-60 min; wait for the next refresh

---

Related Resources

• Scheduling & Teams — Manage the shifts that sync to calendars → Scheduling & Teams App Overview
• Time & Attendance — Track clock-ins alongside synced shift events → Time & Attendance App Overview
• Leave Management — Approved leave flows into the calendar automatically
• Training — Training deadlines sync as calendar events when the Training app is enabled
• EPMS (Performance Management) — 1:1 meetings and review cycles appear as calendar events

---

Your work schedule, your calendar, always in sync — MangoApps Workforce Calendar.