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 is MangoApps Workforce’s full scheduling hub: employees view a unified FullCalendar grid of their work events, create and host their own events (one-off or recurring), invite colleagues, collect RSVPs, and sync everything to the external calendars they already use — Google Calendar, Microsoft Outlook, or any iCal-compatible client. It combines a native events/invitations system with a multi-provider sync engine, so shifts, approved leave, company holidays, training, interviews, meetings, and personally-hosted events all live in one place — and flow to personal calendars automatically.
Core Value Proposition:
- 📅 Native Events & Invitations — Create timed, all-day, or recurring events; invite colleagues; track Yes / Maybe / No RSVPs
- 🔄 Automatic External Sync — Work events flow to Google, Outlook, or iCal without manual copying
- 📋 Unified Work View — Shifts, leave, holidays, interviews, training, tasks, meetings, and hosted events in one grid
- 🙋 RSVP for Everyone — Internal attendees respond inline; external (email) guests RSVP via a secure one-click link, no login
- 🔐 Privacy First — Encrypted credential storage; host-only edit controls; signed external RSVP tokens
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 |
CalendarSyncAllJobruns on a 10-minute cron, queuing individualCalendarSyncJobworkers for each integration that is due- Each integration tracks
last_sync_atand 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
.icsformat 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 |
📝 Native Events & Composer
Beyond syncing external events, users create their own calendar events directly in the app.
| Capability | Description |
|---|---|
| Timed / All-day events | Create events with start/end times, or all-day events |
| Recurring series | Google-parity recurrence (RRULE); edit “this only” or the whole series |
| Per-event color | Pick an accent color shown on the grid and details |
| Event types | Tag events with an admin-defined type (icon + color + default reminders) |
| Reminders | New events default to a single 10-minute-before reminder |
| Rich location | Physical, virtual (Zoom / Teams / Google Meet link), or hybrid |
| Quick-add (natural language) | Type a phrase and the composer parses date/time/title |
Use Case: A team lead schedules a recurring weekly standup, invites the team, sets a virtual Meet link, and a 10-minute reminder — all from one composer.
💡 Pro Tip: When editing one occurrence of a recurring event, choose “This only” to change a single date without disturbing the rest of the series.
🙋 Invitations & RSVP
| Capability | Description |
|---|---|
| Invitee picker | Type-ahead search to add colleagues as invitees |
| Inline RSVP | Invitees respond Yes / Maybe / No directly from the event card or details |
| Pending Invites panel | A side panel (and mobile bottom sheet) lists invites needing a response, grouped Starts soon / This week / Next week / Later, with cursor pagination |
| Delegation | Events can be sent on behalf of another host |
Use Case: An employee opens the Pending Invites panel, sees three events awaiting a response, and RSVPs to each without leaving the page.
📧 Public RSVP (External Attendees)
External guests with no MangoApps login can still respond.
| Capability | Description |
|---|---|
| Signed one-click link | Each external invitee gets an HMAC-signed link; clicking Yes / Maybe / No records the RSVP without login |
| Tamper-proof | A modified or expired token shows a friendly error page — it can’t be used to access another event |
| Grace window | Links remain valid until the event ends plus a grace period |
| Secret rotation | Admins can rotate the signing secret to invalidate all outstanding external links |
👥 Events I Host (Host Rollup)
For hosts and managers running events.
| Capability | Description |
|---|---|
| Host dashboard | Lists events you host with per-event bucket counts (Going / Declined / Maybe / No response) |
| Sort & scope | Sort by response counts or time; scope to Upcoming / Past / All (selection persists per user) |
| Nudge non-responders | One click sends a reminder to everyone who hasn’t responded |
| Message a bucket | Send a message to all attendees in a response bucket (e.g., everyone attending) |
| Live updates | RSVP counts update in real time via a streaming channel |
Use Case: Before a town hall, the host sorts by “No response,” nudges that group, then messages confirmed attendees a reminder with the join link.
🏷️ Event Types (Admin Catalog)
Admins curate the event-type catalog used by the composer.
| Capability | Description |
|---|---|
| Custom types | Create types with a name, curated icon, color, and default reminders |
| Reorder | Drag to set the order shown in the composer |
| Enable / disable | Disable a type so new events can’t use it (existing events keep theirs) |
| Composer feed | The enabled catalog is available to any logged-in user composing an event |
📊 Analytics & Sync-Health Export
Admins and leadership get a sync-health analytics dashboard.
| Capability | Description |
|---|---|
| Dashboard | Total integrations, active connections, sync success/error counts, attendance and feedback insights |
| CSV export | “Export CSV” downloads a per-integration sync-health snapshot (calendar-sync-health-<date>.csv) with provider, status, last sync, and 24-hour sync/failure totals |
| Access | Restricted to Leadership / Calendar Admin (same gate covers the CSV) |
🤖 AI Agent (Ask AI)
The Calendar Sync agent answers sync questions from the Ask AI sidebar.
| Capability | Description |
|---|---|
| List connections | “What calendars do I have connected?” |
| Sync status | “When did my Google Calendar last sync?” |
| Sync history | “Show my recent sync history” / “Show the last 5 Google attempts” |
| Errors | “Why isn’t my calendar syncing?” |
| Sync settings | “What event types am I syncing to Outlook?” |
The agent is read-only — it reports on your own connections (never other users’) and never connects, disconnects, or triggers a sync; it points you to settings for those actions.
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_oauth2SSO configurations (business-level or system-level) - Microsoft Outlook — uses
entra_idSSO 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
- Open the Calendar app from the marketplace sidebar
- Choose your provider — Google Calendar, Outlook, or iCal
- For Google/Outlook: Click “Connect” and sign in with your work account. Grant calendar permissions when prompted
- For iCal: Copy the generated feed URL and paste it into your calendar app’s “Subscribe to Calendar” feature
- Verify the connection — Your shifts and upcoming events should appear in your external calendar within minutes
- Customize sync settings — Toggle which event types you want synced from the integration detail page
For Admins
- Enable the Calendar app from the Marketplace
- Open Settings and verify the master sync toggle is on
- Configure providers — Enable Google, Outlook, and/or iCal based on your organization’s needs
- Select OAuth configurations — Choose which SSO configuration each provider should use
- Set sync preferences — Adjust frequency, event types, and automation settings
- 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.