Calendar feeds
What this page is — publishing obligations into the calendar people already use: a subscription URL for Google Calendar, Outlook or Apple Calendar, or events mirrored into the project's Orbit calendar.
What it is for — so contractual dates sit in the same week view as everything else, instead of on a page someone has to remember to visit.
The problem it solves — contract dates live on a page nobody visits, so they are missed in the week that matters.
Route: /org/papers/obligations → Calendar feeds · Permission:
Manage obligations and reminders. to create, rotate and revoke feeds, and to publish into the
Orbit calendar.
1. What it is
Two different mechanisms live in the same drawer:
Subscription URL (.ics) | Publish to the Orbit calendar | |
|---|---|---|
| Where the dates appear | Any outside calendar app that subscribes | The project's Papers — Obligations calendar inside Orbit |
| Who can see them | Whoever holds the URL | Anyone who can view that project's calendar events |
| Sign-in to read | None | Normal Orbit access |
| Needs | Nothing extra | The organisation must have Orbit Schedule |
| Owned by | You, per feed | The project |
| Default | — | Off |
A feed carries open obligations only, and only dated ones. Each becomes an all-day event on its due date, with a link back to the document. Editing an obligation updates its event rather than creating a new one — each event is keyed on the obligation, so a moved date moves the entry. Marking it done removes it.
2. Why you would use it
A register is a place you go to. A calendar is already open.
- Due dates land next to the meetings they collide with. Three payments on the 30th are obvious in a week view and invisible in a table.
- It needs no habit change. Nobody has to remember to check Papers on Monday — the notice window is in the same view as the dentist.
- Offboarding is automatic. Every fetch re-checks the person who created the feed. Someone leaves the company and their feed stops serving contract data within minutes, with nobody having to remember it existed.
- One feed per device means one thing to revoke. A lost laptop costs you one subscription, not your phone's as well.
3. Step by step
Create a subscription
- Select the right project in the top bar — the feed's scope is frozen at creation and never widens.
- Calendar feeds → Create feed.
- Name it after where you will paste it — "Laptop — Outlook".
- Choose the contents: every open obligation in the scope, or only mine.
- Optionally set an expiry.
- Copy the URL now. It is shown once.
- In your calendar app, subscribe from a URL — for Google Calendar, Other calendars → From URL.
Rotate when a URL has leaked or been lost: a new URL is issued for the same feed, and the old one stops working immediately. Revoke when you are finished with it: the feed is killed for good.
Publish to the Orbit calendar — switch on Publish dated obligations to this project's Orbit calendar. A Papers — Obligations calendar is created in the project (once), every open dated obligation is mirrored into it, and the toast reports how many were published.
4. Field reference
Create feed
| Field | Required | Rules | Refusal |
|---|---|---|---|
| Name | Yes | Free text | name is required — it is how you tell your subscriptions apart |
| Contents | No | Every open obligation in the scope (default), or only mine | — |
| Expiry | No | Must be in the future | expires_at must be in the future |
| Live feeds per person | — | At most 10 | you already have n live calendar feeds — revoke one before creating another |
"Only mine" means obligations on documents you own or created, or where a party on the document is linked to your user — the same definition the reminder emails use.
Feed list
| Column | Tells you |
|---|---|
| Scope | The project frozen at creation, or organisation-wide |
| Contents | Scope or mine |
| Created | — |
| Last fetched | When a calendar app last pulled it. "Never fetched yet" means the subscription was probably never added successfully |
What a fetch returns
| Situation | The calendar app gets |
|---|---|
| Live feed, subscriber still permitted | The .ics file |
| Revoked, rotated-away, expired, or subscriber no longer permitted | 410 Gone |
410 rather than 404 or an empty calendar is deliberate: calendar apps treat 404 as "try again
later" and an empty file as "delete every event", and neither is the truth.
When a feed stops on its own
Access is re-checked on every fetch. A feed stops serving when its creator is deactivated, leaves the organisation, is removed from the project, or loses the obligations permission. Restoring a lost permission resumes it; a deleted account revokes it outright.
A nightly sweep at 03:15 then closes feeds for good when:
| Condition | Revoked after |
|---|---|
| The expiry date has passed | — |
| Access has been lost | 30 days |
| The URL was never fetched | 90 days after creation |
| Nobody has fetched it | 180 days since the last fetch |
5. Worked example
A legal operations lead wants the Vendor Contracts project's dates in Outlook and on their phone.
With Vendor Contracts selected in the top bar, they create "Laptop — Outlook" (every open obligation, no expiry) and "Phone — Google" (only mine, expires in one year). Each URL is copied the moment it is shown and pasted into the matching app.
A week later the feed list shows Phone — Google as never fetched yet. The paste into Google Calendar had failed silently. The URL cannot be shown again, so they press Rotate URL, copy the new one, and subscribe properly — the next day it shows a fetch time.
In March a colleague mentions they pasted "the Outlook link" into a team channel to help someone. The
lead rotates Laptop — Outlook: the pasted URL now answers 410, and only their own Outlook needs the
new address.
6. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
| The role holds Manage obligations and reminders. | Role editor | No Calendar feeds button |
| The right project is selected before creating a feed | Top-bar switcher | The feed is frozen to the wrong scope and shows nothing useful — create another |
| Obligations have due dates | The register | Undated obligations never appear in a feed |
The PAPERS_CALENDAR_FEED_SWEEP job is enabled | Job monitor | Abandoned and orphaned feeds are never closed |
| The organisation has Orbit Schedule | Packages | The Orbit-calendar publishing switch is not shown |
It is 64 random characters, stored only as a hash, and it grants read access to contract dates with no sign-in. Do not paste it into a shared channel, a ticket or a document. If it goes further than intended, rotate it.
Everyone who can view the project's calendar events sees published obligations — typically more people than can open the obligation register. That is why the switch is off by default. Check who can see that calendar before turning it on for a project with sensitive terms.
7. Downstream
| When… | The calendar |
|---|---|
| An obligation's due date changes | The event moves — no duplicate |
| An obligation is marked done or cancelled | The event disappears |
| An obligation is created | It appears on the next fetch — calendar apps poll on their own schedule, often hours |
| A feed is rotated | Subscribed apps stop updating until re-subscribed. Events already downloaded remain |
| A feed is revoked | Same — existing events stay, nothing updates again |
8. Don't confuse this with…
| Reminders | Email a person before a date. A feed only shows the date |
| Push to Tasks | Assigns work. A feed is visibility, not ownership |
| The register's Calendar view | A month grid inside Papers. A feed takes the dates outside |
| Orbit Schedule calendars | Where published obligations land — managed in Schedule, not here |
9. Troubleshooting
| Symptom | Cause |
|---|---|
| The calendar shows nothing | The feed was created with the wrong project selected, or the scope has no open dated obligations |
| "Never fetched yet" in the list | The subscription was never added successfully — rotate and subscribe again |
| It stopped updating | The feed was rotated, revoked, expired or swept (§4) — subscribe to a new URL |
| I lost the URL | It cannot be shown again. Rotate URL |
| It stopped for someone who is still here | They lost the obligations permission or were removed from the project. Restoring it resumes the feed |
| Old events are still in my calendar after revoking | Calendar apps keep what they downloaded |
| A new obligation is not there yet | Your calendar app has not polled since. Nothing is wrong |
| you already have 10 live calendar feeds | Revoke one you no longer use |
| No publish switch | The organisation does not have Orbit Schedule |