The personal Webcal feed
Every Clepsy user has a personal calendar feed that publishes their shifts as a standard iCalendar (ICS) file. Once you subscribe to it in a calendar app, new published shifts appear automatically without signing in to Clepsy again.
The feed is available in two equivalent forms:
- Subscription form:
webcal://{host}{basePath}/cals/{calendar_hash}.ics - Direct form:
https://{host}{basePath}/api/cals.php?u={calendar_hash}
Use the host and base path from your own distribution table. The {calendar_hash} is a 12-character base62 identifier, unique to one person, generated once and never reissued.
Treat the link as a secret. Anyone who has your feed URL can read your published shifts. There is no password prompt on the feed itself. Do not post the link in a group chat, on a public wiki, or anywhere a former colleague or stranger could keep a copy.
Administrators and chiefs generate these links from Distribute Schedules, which lists each resident in the selected residency with a personal Webcal link and a public-schedule link. Distributing a link is not a publishing step.
What the feed includes
The feed is deliberately narrow. It returns only assignments that are both Active and published, and it covers a rolling window from 30 days in the past through 1 year in the future. Draft assignments, cancelled assignments, and anything outside that window are omitted.
| Calendar field | What Clepsy puts there |
|---|---|
SUMMARY (title) | The shift name, such as Day, Evening, or Night. |
LOCATION | The site name for the assignment. |
DESCRIPTION | The fixed text "Shift assignment from Clepsy". |
DTSTART | The shift start, converted to UTC. |
DTEND | The shift end, converted to UTC. |
Each assignment produces exactly one event with a stable UID. Overnight shifts are handled correctly: when the end time is earlier than or equal to the start time, Clepsy anchors the end on the following calendar day before conversion, so a 19:00 to 07:00 night shift does not collapse.
Times are written as UTC instants with a trailing Z. The source wall-clock data is Eastern Time, so Clepsy performs the conversion itself, including daylight-saving transitions. Your calendar app renders those instants in its own time zone. A 07:00 Eastern shift viewed from Central Time appears at 06:00, which is the same moment.
Caching and refresh
The server caches the generated feed for 5 minutes, so back-to-back requests do not rebuild the file. After that, the next request regenerates it from current data.
Calendar applications refresh subscriptions on their own schedule, and some are much slower than the server. Clepsy's interface warns that changes may take up to 24 hours to appear. That conservative copy describes the user experience, not the server cache. If a newly published shift or an executed swap does not show up, give the app time and force a refresh before assuming the feed is wrong.
Publish first. A shift that exists only as a draft will never appear in the feed, no matter how long you wait. Confirm the assignment was published, then check the calendar refresh.
Apple Calendar and iOS
Use the webcal:// link from your distribution table.
- Copy your personal Webcal link.
- Open the Settings app on your iPhone or iPad.
- Tap Calendar, then Accounts, then Add Account, then Other.
- Tap Add Subscribed Calendar.
- Paste the link into the server field.
- Tap Next, review the details, then tap Save.
On macOS you can also add the subscription from the Calendar app's account settings using the same link.
Google Calendar
Google Calendar subscriptions are managed on the web, even if you read the calendar on an Android phone.
- Open Google Calendar on the web at calendar.google.com.
- Click the + next to Other calendars, then choose From URL.
- Paste your personal link. If the field rejects
webcal://, change that prefix tohttps://and paste again. - Click Add calendar.
- On Android, if the calendar does not appear in the app, open the app menu, go to Settings, and confirm the Google account holding the subscription is added.
Google's own refresh interval is outside Clepsy's control. New events often appear well before the 24-hour warning, but do not expect an immediate update after a publish.
Outlook
Outlook is not documented in this codebase. Clepsy ships no Outlook-specific setup flow, and there are no verified menu steps to copy. If your Outlook build supports internet calendars, try adding the direct https:// ICS URL. Clepsy cannot guarantee that Outlook will accept the feed or how quickly it refreshes. Follow your organization's Outlook documentation rather than guessing at menu names.
Public schedule sharing
Clepsy also offers a public, read-only HTML view of a site's published schedule. It requires no login and is intended for people who need to see the schedule but should not have an account, such as attending physicians or rotating staff.
- Site public schedule:
/public/schedule/{site}or/public-schedule.html?site={site_key} - Personal public schedule:
/public-schedule.html?id={calendar_hash}
The public schedule shows published shifts only. It is a web page, not a calendar subscription, and it does not update an external calendar app. A QR code on the sharing card encodes the HTML page URL, not the ICS feed. The "Scan to subscribe" caption beside that code is misleading: scanning it opens the public schedule page. To subscribe to a calendar, use the personal Webcal link instead.
Separate the two jobs clearly. Sharing a public schedule link tells someone where to look at a web page. Sharing or subscribing to a Webcal feed puts events into their calendar app.
Privacy and security
The calendar hash is a capability token: possession of the URL grants read access, so distribute it only to the calendar's owner.
- There is no in-app rotation or revocation. The value is never reissued, so a leaked link keeps working.
- Only published shifts are exposed. Draft shifts stay hidden until an administrator publishes them.
- The public HTML schedule strips email addresses, the numeric user ID, role, and quota information at the query layer.
- What remains is display name, first and last name, PGY, service, and published shifts.
- Numeric user IDs are rejected to prevent enumeration.
Troubleshooting
| Symptom | Likely cause and what to try |
|---|---|
| The feed returns 404 | The hash is wrong, truncated, old, or no longer matches a user, or the URL uses a numeric ID. Copy the full link again and confirm the 12-character hash. |
| Some events are missing | The assignments may be draft, unpublished, or outside the 30-day-back to 1-year-forward window. Confirm you subscribed to the right person and that the app refreshed. |
| Times look shifted | The feed stores UTC and your app renders it in local time. If your calendar is set to another time zone, the wall-clock time will differ from Eastern even though the moment is correct. Confirm the source shift time and your calendar's time-zone setting. |
| The same shifts appear twice | You likely subscribed to the same feed more than once, or added both the Webcal and HTTPS forms. Remove the duplicate calendar and keep a single subscription. |
| Outlook will not add the feed | Outlook support is not documented by Clepsy. Try the HTTPS ICS URL if your Outlook build allows internet calendars, and otherwise use Apple Calendar, Google Calendar, or the public schedule page. |
If the link itself is unusable and you need a new one, contact your program administrator. Do not create workarounds by sharing another resident's feed.
Where to go next
If you are still setting up your account, start with Getting started. If you are planning a schedule change, see Shift swaps for the request, approval, and auto-approval rules that determine when an updated shift reaches your feed. For shorter answers across roles, browse the FAQ.