User Journey: Retire a convention

"This swap document is wrong, or nobody uses it. I want runs to stop reading it, and I want to know what else reads it before I close it."

The journey is done when the document is closed, the person can read that it is closed, who closed it and why, and the screen has stated what the close did not do. The history of the document stays readable.

This is a different job from Change the convention a party uses for one kind. That journey corrects a document or picks another one, and it sends no delete. This journey sends the delete and nothing else.

The actor is the person who maintains the tenant's reference data for the desks: an account holding Operations, or a tenant administrator. The delete permission exists for every kind, for example refdata::swap_conventions:delete. Which role holds it is not checked here. A change that touches a convention needs a second person from Market Risk (Book types and the controls on each), so this person asks and a different person decides.

The trigger is a document a run reads that should not be read: a duplicate, an obsolete term set, or a wrong document that was authored by mistake. The person arrives from a kind's list, from Find a convention by its terms, or from the history of a document that was replaced.

The journey starts on one document and ends when the close is read back, or when the request is read back as waiting. This journey closes one row of one kind. It does not write a replacement, and it does not choose one.

The journey keeps server state while the request waits for a decision. No other step waits on the server after its reply.

1. Open the document. The person opens one document from its kind's list. The system shows its key, its version, its terms in words and the party that owns it. A document of a tenant kind has no party, and the screen says that it belongs to every party.
2. Read the reach. The system shows what reads the document: the party's conventions file, which names every document the party holds; the convention sets that name it; and the report definitions that bind those sets. It also says what it cannot find. No trade points at a convention, because a trade carries its terms inline, and no run records which version it read.
3. Read the twin. The system shows other documents of the kind that state the same terms. A retired duplicate is the common case, and the person needs the twin to be sure that a run keeps a document with those terms.
4. Say why. The person chooses a reason code and writes a commentary. The screen states the consequence in one sentence: the next run of the party does not read this row, and a run that read it before keeps the version it read.
5. Ask for approval. The person raises one request that names the close. The request names Market Risk as the decider. The person cannot decide their own request.
6. Read the result. When the last decider approves, the system closes the row. The screen reports the version that holds the close, who closed it, when and why. It states what the close did not do: it did not choose a replacement, because no default marker exists, and it did not change a set that names the document, so the set now names a closed row.
7. Read the record. The person opens the history. The closed row stays readable with its valid_to, and the earlier versions stay beside it.
8. Leave, or go on. The person returns to the kind's list, or goes to Decide a convention change when another person asked for the close.

One screen of four panels: the document, the reach, the reason and the result. The reach panel is the one the journey is about. A close is a small act, and the only thing that makes it safe is knowing what else reads the row.

A clickable prototype draws this journey: prototype, with its design note retire-a-convention. It opens with no build and reads mock data only. The page marks each server gap this journey names.

The per-kind delete is generated and takes ids. This journey needs a reason on the close. Whether the delete request carries a change intent is not checked here, and the first task of the implementation reads the request shape.

1. Nothing checks that a document is unreferenced before it is closed. The delete closes the row. A set that names the row, and a run that expects it, find it closed. The screen shows the reach it can read, and the server does not refuse the close.
2. The reach cannot be read in full. A configuration has no children, so no set names a document, and no run records the version of a document it read. The reach panel states both as unknown and does not show an empty list as if it meant none.
3. No default marker. A person who closes the document a run took has no way to say which document the run takes next. The party's conventions file then carries the other documents of the kind and nothing chooses between them. See See the conventions a party uses.
4. No approval kind for a convention. Only iam.role_grant, refdata.book_change and refdata.counterparty_change are seeded. Market Risk has a deciding part and the permission inbox::approvals:decide_market_risk. No kind names them for a convention, no request holds a pending close, and nothing applies the close when the last decider approves.
5. A close of a tenant kind reaches every party. currency_pair, ibor_index, overnight_index and tenor carry no party_id. The screen states the scope. Nothing in the server refuses the close on that ground.
6. The wider write cannot retire. refdata.v1.conventions_documents.put leaves rows it is not given alone, so it can neither delete nor retire. The per-kind delete is the only way to retire a document.
7. A close does not travel. A re-publish from the curated dataset inserts the row again where it is absent, for 25 of the 26 kinds. A document retired in a tenant can come back with the next publish.
8. No BFF route deletes a convention. GET and PUT /api/conventions/<family> exist. The journey adds DELETE /api/conventions/<family>/<key>.

• Change the convention a party uses for one kind — the neighbouring job, when a document is wrong and a correction is enough
• See the conventions a party uses — read what a run takes after the close
• Find a convention by its terms — find the twin that stays
• Decide a convention change — the second person's half of step 5
• Name a convention set — a set that names the closed document needs a new choice
• Publish conventions from data quality — the publish that can bring a retired document back

• Conventions journeys — the group this journey belongs to
• Book types and the controls on each — who decides a convention change
• Reference Data — versioning, change reasons and the bitemporal record
• User Journeys — the index

• User Journey Extraction Standard — the checklist this journey is written against
• Document type: user_journey — the sections this page fills