Skip to content

Apple Calendar#

Apple Calendar is registered for credential-backed CalDAV sync with sync-coupled user import. It connects to iCloud Calendar through an encrypted Apple Account/app-specific-password credential, discovers visible CalDAV calendar collections, pulls bounded VEVENT resources into a reviewable import session, proposes TeamBoost user mappings from event actors, and projects each event into the internal integrations task-create draft for operator review.

Capability Method Status
CSV_IMPORT — Not built
SYNC Pull iCloud Calendar events through CalDAV ✅ Built
USER_IMPORT Organizer and attendees imported during sync ✅ Built
WEBHOOK — Not built

The endpoints below live under /api/v1/providers/apple-calendar/.... All routes require an organization-scoped user token (see Authentication).

Credential Setup#

Apple Calendar uses the generic encrypted credential routes:

PUT /api/v1/providers/apple-calendar/credentials?organization_id=<id>
GET /api/v1/providers/apple-calendar/credentials?organization_id=<id>
POST /api/v1/providers/apple-calendar/credentials/verify?organization_id=<id>
DELETE /api/v1/providers/apple-calendar/credentials?organization_id=<id>

The stored secret is a JSON string with these fields:

{
  "username": "apple-account@example.com",
  "app_specific_password": "xxxx-xxxx-xxxx-xxxx",
  "base_url": "https://caldav.icloud.com"
}

base_url must be HTTPS and must point to an Apple CalDAV host. The current entrypoint used by the adapter is https://caldav.icloud.com; discovered account shard hosts in the *-caldav.icloud.com family are followed only when Apple returns them through CalDAV discovery. App-specific password whitespace is normalized before use. The username, password, authorization header, raw event body, and account-specific CalDAV URLs are never logged by the adapter.

Verification performs a cheap CalDAV discovery probe:

  • PROPFIND for DAV:current-user-principal;
  • PROPFIND for CALDAV:calendar-home-set;
  • PROPFIND for calendar collections.

Invalid credentials return invalid_api_key. CalDAV 429 and server errors are retried with bounded backoff. HTTP redirects are not followed while sending Basic Auth; the adapter follows only returned CalDAV hrefs that pass the Apple host allowlist.

Importing From Apple Calendar#

POST /api/v1/providers/apple-calendar/imports/sync?organization_id=<id>

The first shipped sync is intentionally bounded:

  • all visible calendar collections returned by CalDAV discovery;
  • VEVENT resources only;
  • a review window from 30 days in the past through 60 days in the future;
  • no persisted incremental sync-token state.

The adapter sends CalDAV XML requests and parses returned iCalendar resources. It preserves the CalDAV resource href, resource URL, ETag, calendar context, UID, RECURRENCE-ID, SEQUENCE, STATUS, CLASS, TRANSP, categories, organizer, attendees, and start/end context in the import source record and projected descriptionJson.

Projection Field Coverage#

Apple Calendar source TeamBoost draft field Notes
SUMMARY title Missing or hidden summaries are blocking projectionErrors.
Calendar event type Calendar events default to OTHER with a mapping note.
DESCRIPTION description Passed through when present.
STATUS status CONFIRMED and TENTATIVE map to NOT_STARTED; CANCELLED maps to CANCELED; tentative/cancelled statuses add mapping notes.
Calendar priority priority iCalendar events have no TeamBoost priority equivalent; defaults to UNKNOWN.
ORGANIZER creatorId Resolved through the user mapping when matched; otherwise left unset with a note.
ATTENDEE ownerId Attendees are imported for user mapping but are not assigned as owners automatically.
Organizer requestedById Preserved in descriptionJson; requester mapping is left unset until the product rule is confirmed.
DTSTART / DTEND plannedStartDate, estimatedStartDate, plannedEndDate Calendar length is not converted into TeamBoost effort duration.
Calendar display name projectTitle
CalDAV/iCalendar refs descriptionJson Preserves resource href/URL, ETag, UID, recurrence, status/class/transparency, categories, actors, and raw parsed start/end context.

User Import During Sync#

USER_IMPORT rides sync. Proposed users come from iCalendar ORGANIZER and ATTENDEE values, deduped by normalized e-mail/calendar address and name. Apple Calendar is not an Apple directory API; standalone Apple user-directory import is not built.

Not Built Yet#

  • CSV or .ics file import.
  • Calendar selection and per-organization sync window preferences.
  • Persisted incremental DAV:sync-token state.
  • Apple Calendar writeback or two-way sync.
  • Apple Calendar webhooks or push notifications.
  • Standalone Apple user-directory import.