Obligation register
What this page is — every dated commitment your documents contain, gathered into one dashboard: what is overdue, what falls due in the next fortnight, which documents expire soon, and the full register underneath.
What it is for — so a payment date, a delivery milestone or a notice window is something the organisation is watching, rather than a sentence on page nine of a PDF.
The problem it solves — payment dates, milestones and notice windows sit inside PDFs, and the first sign of one is a missed deadline.
Route: /org/papers/obligations · Permissions: View obligation register and renewal calendar. to
look, Manage obligations and reminders. to add, complete, renew, delete or push to Tasks,
Use AI drafting/extraction/Q&A for documents. for extraction and the renewal-risk card.
1. What it is
An obligation is a dated commitment that belongs to a document — never free-floating. Every obligation carries a type, a due date, a status and a source, and it lives on exactly one document.
The page reads top to bottom as three questions:
| Band | Answers |
|---|---|
| Renewal risk (AI) and the five counters | How exposed am I? |
| Overdue and Upcoming panels | What must be done now? |
| Expiring documents | What lapses in the next 90 days, and can I renew it from here? |
| Obligations register | Everything, filterable, with history |
It is easy to confuse with three nearby things:
| Is about | Example | |
|---|---|---|
| An obligation | Something you must do by a date | Pay the Q3 licence fee by 30 September |
| A document's validity date | When the document itself expires | The MSA ends 31 December |
| A retention date | How long the record must be kept | Keep until 2033 |
| A task | Work someone is doing, with assignee and checklist | TSK-0142 "Prepare Q3 invoice run" |
The validity date feeds the Expiring documents panel; obligations feed everything else. An obligation can be pushed into a task (§4), but the obligation stays the record of what the document committed you to.
2. Why you would use it
Contracts do not remind you. An auto-renewal passes, a notice window closes, a milestone slips — and the first anyone hears of it is an invoice, a missed exit, or a dispute.
- It turns a clause into a date someone is looking at. A 90-day notice window written in prose is invisible; the same window as an obligation appears in Upcoming, in a calendar feed, and in the owner's inbox.
- It separates "what's late" from "what's next". Overdue and Upcoming are two lists, so the Monday review starts with the three things already late rather than the forty coming up.
- It catches the renewal you would have missed. The Expiring documents panel lists every document whose validity closes within 90 days, with Renew on each row — the shortest path from noticing to doing.
- It gives finance and delivery their own view. The type filter lets a finance team see only
paymentrows while a delivery lead sees onlydeliverablerows, over the same register. - It keeps an honest record. Obligations the AI extracted cannot be deleted, only cancelled, so the register cannot quietly lose a commitment the document actually contains.
3. How it spreads
| An obligation reaches… | How | See |
|---|---|---|
| The document owner's inbox | A daily reminder email inside the reminder window | Reminders and renewals |
| An outside calendar | A subscribed .ics feed | Calendar feeds |
| The project's Orbit calendar | Mirrored as an all-day event, when publishing is switched on | Calendar feeds |
| Tasks | Push to Tasks creates a linked task | §4 |
| Integrations | Webhooks paper.obligation_created and paper.obligation_completed | API and webhooks |
| The document's timeline | Every create, update, delete and reminder is an audit event | Preview and versions |
4. Step by step
Add one by hand
- Add Obligation → pick the Document.
- Choose the Obligation type, write a Description, set the Due date.
- Set Remind (days before) — default 7.
- Add Obligation. The row appears in the register as
open.
Complete one — press Done in the Overdue or Upcoming panel, or the tick in the register. There
is no confirmation: status becomes done, reminders stop, and the calendar entry is removed.
Push one to Tasks — the list icon on an open row. A task is created in the Tasks module with the
obligation's title, due date and a link to the document, assigned to the document owner. If the
owner is not a member of the task project, the task is created unassigned and the toast says so. The
icon becomes a green Task created chip. Pushing again warns you first and, if you confirm,
creates a second independent task.
Renew an expiring document — Renew on its row in Expiring documents, then confirm. A renewal draft opens (§5, field reference).
Read the calendar — List / Calendar switches the same filtered register onto a month grid. Obligations without a due date cannot be placed and are counted instead.
The register loads with Status = Open already selected. An apparently empty register is almost always that filter — or no project selected in the top bar, in which case only organisation-level documents (those with no project) are shown, which in most organisations is none.
5. Field reference
Add Obligation drawer
| Field | Control | Required | Rules | Notes |
|---|---|---|---|---|
| Document | Searchable picker | Yes | Must be a document you can access | Lists every document in scope, by title and number |
| Obligation type | Picker | Yes | One of the six below | Descriptive only — drives the chip and filter, not behaviour |
| Description | Text | No | — | Strongly recommended: it is what everyone reads |
| Due date | Date picker | Yes | The drawer refuses to save without it | Drives panels, calendar, reminders |
| Remind (days before) | Number | No | Default 7; 0 = only on the due date | See reminders for what "days before" really does |
A bad type sent through the API is refused with invalid obligation type "x" (payment, deliverable, renewal, expiry, milestone, notice).
The six types
| Type | Use for |
|---|---|
payment | A sum falling due |
deliverable | Something owed to the other side |
milestone | A checkpoint — and the fallback when nothing else fits |
renewal | A renewal window opening |
expiry | The agreement ending |
notice | A period in which notice must be given |
The four statuses
| Status | Chip | Set by |
|---|---|---|
open | amber | Creation |
done | green | Done / tick |
missed | red | Only ever set explicitly. Nothing marks an obligation missed when its date passes |
cancelled | grey | Explicitly — the way to retire an AI-extracted obligation |
open, not missedWhen a due date passes, the obligation remains open and moves into the Overdue panel and the
Overdue obligations counter. Filtering the register to Missed for a month-end review shows
only what somebody deliberately marked missed — typically nothing.
Register columns
| Column | Holds |
|---|---|
| Document | Links to the document's workspace |
| Type | Blue chip |
| Description | Truncated — hover for the full text |
| Due | The due date. The table does not re-sort by urgency; the panels do |
| Status | One of the four above |
| Source | Manual or AI extracted |
Counters
| Counter | Counts |
|---|---|
| Expiring ≤ 30 / ≤ 60 / ≤ 90 days | Documents whose validity expires in that window. Cumulative — a document 20 days out counts in all three |
| Overdue obligations | open obligations whose due date has passed |
| Due in next 14 days | open obligations due in the next 14 days, excluding overdue ones |
Row actions and their refusals
| Action | Shown when | Refusal |
|---|---|---|
| Push to Tasks | open and never pushed | this obligation was already pushed (task …); pass force=true to push again — the UI turns this into the Push again? confirmation |
| Mark done | open | — |
| Delete | Source is Manual | only manual obligations can be deleted; cancel AI-extracted obligations instead |
Renew — what the draft contains
| Relation | A child document with relation renewal |
| Title | The original's title plus " (Renewal)" |
| Data | Every field value carried forward |
| Validity | Rolled forward by the original's term, measured from creation to expiry |
| The original | Untouched |
| Type gate | None. Renew works even when the type's Allows amendment is off, unlike the workspace's Amend menu |
That last row has a consequence worth knowing: a document created in January, signed in March and expiring the following March has a term of 14 months as far as renewal is concerned. Check the new expiry date on the draft.
6. Worked example
A contracts manager at a facilities company reviews the register on a Monday.
Overdue shows one row: payment · "Quarterly AMC fee — Chiller Maintenance" · due last Friday.
Finance confirms it was paid on Friday afternoon. The manager presses Done; the row leaves the
panel, the counter drops to zero, and the document owner stops receiving reminders.
Upcoming shows a notice obligation on "Office Lease — Koramangala": "Give landlord 90-day exit
notice by registered post", due in 9 days. This one is real work, so the manager pushes it to Tasks —
TSK-0142 is created and assigned to the lease's owner, and the row shows Task created.
Expiring documents shows "AMC — Chiller Maintenance" with a red 12d left badge. The business has already agreed to renew at a new price. Renew → confirm → a draft titled "AMC — Chiller Maintenance (Renewal)" opens with the same parties and next year's expiry. The manager updates the fee field and submits it for approval.
Finally, a verbal agreement from last week's call is not in any document: the supplier will deliver
revised service reports by the 15th. Add Obligation → the AMC document → deliverable → due the
15th → remind 3 days before.
Ten minutes, and every commitment on the page has either been completed, assigned, renewed or recorded.
7. The admin contract
| Must be true | Where | What breaks without it |
|---|---|---|
The role holds View obligation register and renewal calendar. (and .menu for the sidebar) | Role editor | The page is unreachable |
| The role holds Manage obligations and reminders. | Role editor | No Add, Done, Renew, Delete or Push buttons — the page is read-only |
| The role holds Use AI drafting/extraction/Q&A for documents. | Role editor | No Extract from document button and no Renewal risk card |
| A project is selected in the top bar | Global switcher | Only organisation-level documents show — usually nothing |
| Documents carry a validity expiry date | Finalize and numbering | They never appear in Expiring documents or the 30/60/90 counters |
| The Papers - Obligation Reminder email template is installed, active and mapped to a gateway | Communication Channels | Reminders silently fail; a delivery-readiness banner appears on this page |
The PAPERS_OBLIGATION_REMINDERS job is enabled | Job monitor | No reminder emails are sent at all |
| The Tasks module is enabled for the organisation | Packages | Push to Tasks cannot create anything |
8. Downstream
| When you… | This changes |
|---|---|
| Mark an obligation done | Reminders stop; the Orbit calendar entry is removed; paper.obligation_completed fires — once, not on every later save |
| Change a due date | The reminder window moves; the feed and Orbit calendar entry move with it |
| Delete a manual obligation | It is gone, with an obligation_deleted event on the document timeline |
| Renew a document | A new draft enters its own lifecycle; the original keeps its obligations, the renewal starts with none |
| Push to Tasks | A task exists independently — completing the task does not complete the obligation |
That last row catches people out: the task and the obligation are linked for navigation only. Close both.
9. Don't confuse this with…
| Extract key terms | The AI capability that seeds this register |
| Retention and holds | How long a record is kept — not what it commits you to do |
| Amend, renew, supersede | The document-side view of the same Renew action |
| Tasks | Where work is tracked. The obligation remains the record |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The whole page is empty | No project is selected in the top bar (§4) |
| The register is empty but the panels are not | The Status = Open filter, or a type filter, is still set |
| Nothing ever shows as missed | Nothing sets missed automatically — late obligations stay open in Overdue (§5) |
| An obligation has no Delete bin | It is AI extracted. Cancel it instead |
| A document never appears in Expiring documents | It has no validity expiry date |
| The renewal's expiry date looks too far out | The term is measured from the original's creation, not its signature (§5) |
| Completing the task did not complete the obligation | They are independent once pushed (§8) |
| The pushed task has no assignee | The document owner is not a member of the task project |
| Buttons described here are missing | Your role lacks Manage obligations and reminders. or Use AI drafting/extraction/Q&A for documents. (§7) |
Every obligation appears twice, one AI extracted and one Manual | See Extracting obligations |