social-media/docs/FEATURES/calendar-integrations.md

Calendar Integrations

Status

Draft

Goal

Add .ics calendar import and export support so teams can plan social content with public holidays, observances, marketing moments, and personal work dates visible in the Content calendar.

The experience should feel familiar to users who already subscribe to calendars from Google Calendar, Android calendar apps, Apple Calendar, or Outlook.

User Outcomes

• Organization admins can configure shared calendar sources that apply across the organization.
• Workspace admins can configure calendar sources for a specific workspace and see inherited organization sources.
• Users can configure private calendar sources for their own calendar view.
• Users can subscribe to a private Socialize .ics feed so their upcoming Socialize work appears in external calendar apps.
• Content planners can see dates such as Mother's Day, Christmas Eve, Ramadan, Queen's Day, public holidays, and marketing moments next to planned content.
• Users can search a curated catalog of trusted calendar sources instead of manually finding .ics URLs.

Calendar Source Scopes

Calendar sources can exist at three scopes:

• Organization: managed by organization admins and inherited by workspaces in that organization.
• Workspace: managed by workspace admins/managers for one workspace.
• User: private to one user.

Organization calendars have an inheritance mode:

• Required: inherited by all workspaces and cannot be hidden at the workspace level.
• Optional: inherited by default, but workspace admins can hide the source for that workspace.

Workspace calendar settings must show inherited organization calendars as read-only sources. If an inherited source is optional, workspace settings may expose a workspace-level visibility override without allowing edits to the source itself.

User calendar settings show contextual organization and workspace sources plus private user sources. Private user calendars are visible only to that user.

Permissions

• Organization admins can add, edit, remove, refresh, and set inheritance behavior for organization calendar sources.
• Workspace admins/managers can add, edit, remove, and refresh workspace calendar sources.
• Any authenticated user can add, edit, remove, refresh, and manage their own private calendar sources and exported feed.
• Client approvers and external collaborators can view shared calendar context in workspaces they can access but cannot manage shared sources.
• Private user calendar sources never become visible to other users.

Curated Calendar Catalog

Socialize maintains a searchable curated catalog of calendar source metadata. The catalog presents trusted external sources through a polished product experience.

Catalog entries may point to providers such as:

• Google exported .ics calendars
• government public holiday feeds
• trusted holiday or observance APIs that can be represented as .ics
• other verified public .ics sources

Catalog metadata should include:

• title
• description
• country
• region or subdivision
• language
• category, such as public holiday, cultural observance, religious observance, or marketing moment
• culture or religion when relevant
• provider name
• source URL or provider configuration
• trust level or verification status
• default color

Initial curated catalog coverage should include:

• country and region public holidays
• major cultural and religious observances
• common social and marketing moments, such as Mother's Day, Valentine's Day, Black Friday, Cyber Monday, Pride Month, and Earth Day

Platform-specific social media event calendars are out of v1 unless they are added later as maintained catalog entries.

Curated calendars are added and removed as whole calendar sources. V1 does not require editing individual imported events from curated sources.

Custom ICS Imports

V1 supports custom calendar import by URL subscription only.

One-time .ics file upload is deferred because URL subscriptions stay current and map better to the expected calendar-app mental model.

Each imported source stores:

• source scope
• source URL or catalog source reference
• display title
• color
• category
• enabled state
• last successful sync timestamp
• last attempted sync timestamp
• last sync error, when applicable

Import Sync

Socialize fetches subscribed .ics calendars on a background schedule, for example every 6-12 hours.

Calendar settings also provide a manual refresh action for sources the current user can manage.

Imported events are normalized and stored for fast calendar rendering. Recurring events from the feed must be expanded into the date range needed by calendar views. The importer should support yearly observances and moving-date observances when the upstream feed provides them.

The importer should preserve useful event fields where available:

• title
• description
• start and end date/time
• all-day flag
• recurrence identity
• source event UID
• location
• source URL
• last modified timestamp

Imported events are read-only in Socialize.

Timezones

All-day imported events remain attached to their calendar date and should not shift backward or forward because of timezone conversion.

Timed imported events follow these rules:

• If the event has a timezone, Socialize respects that timezone and displays the event at the equivalent local time for the viewer.
• If the event has no timezone, Socialize treats it as a floating local time.
• Floating times use the workspace timezone for organization and workspace calendars.
• Floating times use the user's timezone for private user calendars.

Exported user .ics feeds should use the user's timezone for display and include stable UTC timestamps for timed Socialize events where possible.

Content Calendar Experience

Imported calendar events appear as read-only calendar context in the Content calendar.

They should:

• appear as all-day context entries when the source event is all-day
• use a distinct calendar-event style separate from Socialize content items
• be lower visual priority than actual content work on crowded days
• use the source calendar color
• be filterable by source, scope, and category
• never affect content status, approval state, deadlines, notifications, or workflow automation by themselves

Each calendar source has a configurable color.

• Curated catalog sources provide sensible default colors by category.
• Organization and workspace admins can change colors for shared calendars they manage.
• Users can change colors for private calendars.
• A later task may allow user-level display color overrides for inherited/shared sources.

Calendar Source Control

The Content calendar includes a compact calendar source dropdown placed next to the calendar view selector.

The dropdown lists currently displayed calendar sources with each source's visibility toggle. Inherited read-only sources still appear in this list. The last entry is Add calendar.

The Add calendar flow lets users search the curated catalog or add a custom .ics URL, subject to their permissions and selected scope.

V1 focuses on source-level visibility. Per-event hiding is deferred.

Content Creation From Events

Imported events are not editable as Socialize objects.

An imported event may provide a quick action such as Create content for this date. This opens the normal content creation flow with the planned date and event title prefilled.

Content Detail And Date Picker Context

When a content item has a planned publish date, the content detail view should show compact calendar context pills near the publish date or scheduling area.

Examples:

• Mother's Day
• Christmas Eve
• Ramadan
• Queen's Day

Each pill comes from a visible calendar source. Clicking a pill opens a small event detail popover or the matching calendar day.

Calendar context pills are read-only hints. They do not automatically become content tags or hashtags.

The content create/edit date picker should lightly mark dates that have visible calendar events and show event names in a small date context panel.

Imported calendar events should not appear in unrelated dashboards or notification feeds in v1.

User ICS Export

Each user can enable a private exported Socialize .ics subscription feed.

The feed:

• uses a private unguessable URL
• does not require login because calendar apps fetch it in the background
• can be regenerated or revoked by the user
• includes only that user's my work dates
• excludes imported holiday and observance events by default

My work includes:

• content items assigned to the user
• content items where the user is an approver
• content items the user created or owns, if ownership exists
• approval due dates
• planned publish dates
• campaign dates only when the user has access to that campaign

Feed entries should avoid sensitive discussion details. They may include:

• title
• date and time
• status
• workspace
• client
• campaign
• a link back to Socialize

Localization

Imported event names are shown using the source-provided event name.

Curated catalog metadata may be localized, including calendar titles and descriptions.

Out Of Scope For V1

• One-time .ics file upload
• Editing imported events in Socialize
• Per-event hide controls
• Automatic scheduling warnings or blocked dates
• Automatic hashtag creation from calendar events
• Imported event notifications
• Platform-specific event calendars unless maintained as curated sources
• Full holiday-rule engine maintained manually inside Socialize

Open Questions

• Which initial countries, regions, cultures, religions, and marketing calendars should ship in the first curated catalog?
• Which backend library should be used for robust .ics parsing and recurrence expansion?
• What default sync cadence should be used in production?
• Should user-level color overrides for shared calendars be included in v1 or deferred?