Task: Write party manual chapter
Table of Contents
This page documents a task in the Commission: party, counterparty, and party_status story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Add a Parties chapter to the user manual, documenting the party entity's hierarchy rule and its Qt UI (list window, General, Identifiers, Contact Information, Hierarchy, and Provenance tabs) in the same style as the existing reference-data chapters.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Commission: party, counterparty, and party_status |
| Now | Nothing. |
| Waiting on | Screenshots (tracked as outstanding, not blocking). |
| Next | Nothing. |
| Last touched | 2026-07-16 |
Acceptance
- A new
chapter_8_parties.orgexists underdoc/manual/user_guide/, wired intouser_manual.org's table of contents after the Books chapter. - The chapter explains what a party is, the single-root-per-tenant hierarchy rule, and why the Parent Party combo in the Create/Edit dialog is required rather than optional.
- The chapter documents the Parties window and all five Party Details
tabs (General, Identifiers, Contact Information, Hierarchy,
Provenance), following the structure established by
chapter_7_books.organdchapter_6b_business_centres.org. - Cross-references to Reference Data, Currencies, Business Centres, Standard Financial Identifiers, and Temporal Composite Entity Versioning are in place.
Plan
Modelled the chapter on the two closest existing precedents:
chapter_7_books.org (a composite/hierarchical entity, for the
overall shape — Overview, concept section(s), list window, detail
dialog with tabs, editing/deleting/history, Conclusion, See also) and
chapter_6b_business_centres.org (a shorter reference-data chapter,
for tone and the flagged-combo/Change-Reason-Required
cross-reference pattern). Read ores.refdata.party.org's Detail
fields table and the party_identifier=/=party_contact_information
models directly to get field lists, combo semantics (Parent Party
required, Business Center flagged, Country Code flagged-and-optional)
and enum values (identifier schemes, contact types) right, rather
than inferring them from the UI alone. Confirmed no dedicated
domain-knowledge hub doc exists yet for Party (unlike Book's
book.org), so the chapter's "See also" links to Reference Data,
Currencies, Business Centres, Standard Financial Identifiers, and
Temporal Composite Entity Versioning instead. Screenshots are left as
placeholders (#+caption + image link, no accompanying capture
note/todo) since no running client capture was taken as part of this
task — flagged in Status as outstanding, not blocking, matching how
chapter_7_books.org itself still carries "[SCREENSHOT OUTDATED]"
markers.
Notes
- Counterparty and party_status get their own, separate manual-chapter tasks on this story; this task covers only the Party entity.
- All 7 screenshots captured, cropped to just the dialog/window (no QA
Validation Runner chrome in frame — see how do I capture manual
screenshots?), and committed under
doc/manual/user_guide/assets/images/. - Real bugs found and fixed while running the screenshot scenario
(not pre-existing acceptance criteria, but directly blocking it):
- Missing party history provider:
ores.refdata.core/src/messaging/registrar.cpphad noregister_history_provider("ores.refdata.party", ...)(norcounterparty) entry, andparty_history_field_mapper.hpp/.cppdidn't exist at all (counterparty's did, confirmed zero-diff on regen). Regenerated the missing presentation files viacompass codegen entity generate party --address ores.cpp.presentationand hand-added both entities' registrar wiring (this aggregator file is hand-maintained, not itself codegen'd) alongside their =#include=s, matching every other refdata entity's pattern. - party_type badge colour collisions:
Internal=/=Corporateboth mapped to the same teal (#14b8a6), andBank=/=CorporateGroupboth mapped to the same blue (#3b82f6), inprojects/ores.sql/populate/dq/dq_badge_system_populate.sql. RemappedCorporate→asset_class_bondandCorporateGroup→account_type_algorithm(both otherwise-unused-by-party_type colours); applied live via the bitemporal close-old/insert-new pattern (not a rawUPDATE) so existing rows keep proper history. - Stale generator-test expectations:
party_contact_information_generator_produces_valid_instanceand its counterparty equivalent inores.refdata/api/tests/generators_tests.cppassertedversion =1= /change_reason_code ="system.new", but the generators (confirmed zero-diff against current codegen templates via =compass codegen entity generate ... --diff) correctly produceversion =0= /\"system.test\". Fixed the test expectations, not the generators.
- Missing party history provider:
- Review round (chapter content, not code): converted the inline
http://www.fpml.org/coding-scheme/business-centerURL inchapter_6b_business_centres.orginto a footnote using\url{}and added\usepackage{url}touser_manual.org's LaTeX preamble; audited the rest of the manual and found no other inline-URL-clutter offenders (chapter_1's URLs are already footnoted; every other manual URL is already a proper[[url][label]]"See also" link, not clutter). Added a Tenants cross-link and rewrote "What is a Party?" / "The party hierarchy" to (a) not duplicate the Tenants chapter's house/counterparty/system-party model, just point at it; (b) add the legal-entity-identification domain framing (LEI/GLEIF, linking Standard Financial Identifiers); (c) fix a real contradiction found against the DB (confirmed live: BARCLAYS PLC's ownparent_party_idis genuinely null, i.e. the house root, not the system party as a screenshot misleadingly suggested via the known pre-existing QComboBox auto-select-index-0 bug) — a tenant has two possible parentless parties (the system party and one operational house root), not one, and the chapter previously only described one; (d) drop the "through the Qt UI" qualifier on required-parent-on-create, since the shell'sprovision partycommand can also create parties (Conclusion's "shell access not yet implemented" caveat corrected to scope that to general-purpose CRUD commands, not the existing provisioning-level command). - Filed Capture missing Books screenshots and refresh legacy history
dialog screenshots to fix an unrelated gap surfaced during review:
the regulatory book type combo screenshot in
chapter_7_books.orgwas never captured, and the History dialogs inchapter_6_countries.org=/=chapter_5_currencies.org=/=chapter_7_books.org=/=chapter_6b_business_centres.orglikely predate the current All Fields/Only Changes toggle UI.
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
| Capture party manual chapter screenshots | PASSED | All 8 steps passed; also surfaced and drove the fix for the missing party history provider registration (real bug, see Notes). |
| Recapture party_details_hierarchy.png with a non-root party | PASSED | Redo of one screenshot on a non-root party so both ancestors and descendants are visible. |
| Capture missing Books screenshots and refresh legacy history dialog screenshots | PASSED | All 9 steps passed; unrelated gap fix surfaced during review, spanning Books/Countries/Currencies/Business Centres chapters. |
PRs
| PR | Title |
|---|---|
| #1602 | [docs] Write party manual chapter |
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | counterparty_contact_information generator test was not actually fixed (still asserted version==1/"system.new") | projects/ores.refdata/api/tests/generators_tests.cpp |
Fixed | Mirrored the party-side fix: version==0, change_reason_code=="system.test", matching the actual generator output. |
| 2 | Conclusion's tab recap omits Provenance (Overview correctly lists all five) | doc/manual/user_guide/chapter_8_parties.org |
Fixed | Added Provenance to the Conclusion's tab list. |
| 3 | Three party_type badge colours (HedgeFund/Corporate/CentralBank) sit in the same violet/indigo family — technically distinct hex, may be hard to tell apart at a glance | projects/ores.sql/populate/dq/dq_badge_system_populate.sql |
Declined | Nit-level per reviewer's own note; the literal duplicate-hex bug this PR fixes is resolved, and re-tuning hue distinctiveness across all 8 codes is a separate, broader design pass. |
Result
Added doc/manual/user_guide/chapter_8_parties.org and wired it into
user_manual.org after the Books chapter. The chapter covers what a
party is, the single-root-per-tenant hierarchy rule and why the
Parent Party combo is required, the Parties window, and all five
Party Details tabs (General, Identifiers, Contact Information,
Hierarchy, Provenance), plus editing/deleting/history and a
Conclusion naming the still-missing shell/CLI access and the
not-yet-written Counterparty chapter. All 7 screenshots captured
against a live Barclays Plc (GLEIF) environment, cropped to the
dialog/window, and wired in. Along the way, running the screenshot
scenario surfaced and drove the fix for a real bug (party/counterparty
had no history provider registered, so History always failed) plus a
party_type badge colour-collision fix and two stale generator-test
assertions — see * Notes for detail. A review round also fixed URL
clutter (footnoted), added a Tenants cross-link and legal-entity
identification framing (inlined, not linked out, per feedback) to
chapter_8_parties.org, and captured/refreshed 9 unrelated Books and
History-dialog screenshots across four other chapters.