Reporting journeys

Table of Contents

A report definition belongs to one party, and the party runs it on demand or on a schedule. Each firing creates a report instance, one record of one run, and the run walks the report execution pipeline: it prepares the engine's input, submits it to the compute grid, waits while the engine runs on a worker node, retrieves the output archive, and closes. The run records where its archive landed and every error the engine reported. These journeys are a person's view of that record: the reports their party owns, the runs of each, what a run produced, what went wrong, and when the next one starts.

Nine journeys cover the lifecycle of a run. Seven more cover the configurations a report binds: five for the pricing engine configuration, one for the engine run settings, and one for the published curves the run prices from. The first is the front door, the one a reader opens with a question and no identifier: which reports does my party run, and how did each one last go? From it a person runs a report, opens what a run produced, reads that result by counterparty as well as by book, follows an error down to the trade, analytic or curve that caused it, looks back over the runs of one report, and changes when the report runs next. The front door is what makes the others reachable, so it carries the health words the whole group uses.

Four of the nine write. Running a report creates a run, and choosing when it runs changes the definition's schedule. The other five read rows that a run already wrote. That split is why the group is cheap to build: the reporting service already stores the definitions, the runs, the output location and the errors, and every journey below reads them, with the gaps recorded in each journey's What is missing.

1. Journeys

Journey Actor Gist
See the reports a party runs trading-desk, market-risk, tenant administrator Every definition the party owns, with the latest run's health: never run, running, completed clean, completed carrying errors, or failed
Run a report and watch it finish trading-desk, market-risk Trigger one report on demand, then follow the run through its phases to a terminal state
Read what a run produced trading-desk, market-risk The run's output message and archive, the engine's output down to one trade's result and rolled up as a book tree from a portfolio to a book to a trade, and the ORE package the run exported
Find out why a run went wrong engineer, market-risk, tenant administrator The run's errors, placed by scope and subject, down to which trade, which analytic and which curve
Choose when a report runs tenant administrator Set the schedule that makes a definition run, run it now, pause and resume the schedule, and take it away again
See a report's results by counterparty market-risk, credit, trading-desk One run read by counterparty: each name's aggregate NPV, notional, trade count and, where the report runs saccr, exposure, largest first, grouped through the parent counterparty, down to one name's trades, netting sets and errors
Look back over a report's history trading-desk, market-risk, engineer Every run of one report newest first, with the last five fire times, the newest marked latest, and a notice when the run being read stops being the newest
Create a report tenant administrator, market-risk Define a report: name it, bind the five configurations it reads, choose the analytics and their settings, scope it to a portfolio, and save it
Change what a report runs market-risk, tenant administrator Turn an analytic on or off, change a parameter, and see what the change reaches: the next run of every definition sharing the configuration, and the runs it makes incomparable
Bind a report to a published curve market-risk, tenant administrator Bind each market role of the run settings to a published curve, pick the set by curve, party and as-of with its state, be refused a candidate, pin an ended set at its historical as-of, and run the report, whose record names the publish record it priced from
See the pricing engine configurations a party holds market-risk, tenant administrator The pricing engine configurations the party holds, which one is official for each cycle, what each prices with, which reports bind it, and which product types the reports need that it leaves unpriced
Author a pricing engine configuration market-risk, tenant administrator Build a draft or a candidate in six steps: what it is for, the products, a model and engine for each, their parameters, a check against what the reports of a cycle need, and a review
Change how a product is priced market-risk, tenant administrator Propose a change to the model, engine or parameters of one product, read which reports it reaches once it is approved, and try it in a draft copy first
Bring in a pricing engine configuration file market-risk, tenant administrator Bring in an ORE pricing engine configuration file, read what it adds, changes and removes against a configuration the party holds, and save it as a draft or as a proposal
Sign off a pricing engine change market-risk, quant, model validation Each inbox approval part model risk names approves or refuses a proposed change to an official configuration, the proposer cannot sign it off, and an approved proposal is made official
See and change the engine run settings a party holds market-risk, tenant administrator How the engine runs a report: the fixings and cash flows, the market and trade building and the execution, read with their defaults and changed section by section, with the reach and the history

The last seven journeys are the first of the report configurations. A report definition binds several configurations, and each configuration needs its own screens to be created and changed. They start with the pricing engine configuration and the engine run settings, and with the published curves the run settings name as the market each role prices from. The other types follow, and the conventions are authored in their own work.

Model risk controls the model settings, so a party holds few official pricing engine configurations, one for each cycle, and a change to one is signed off by the approval parts model risk names. The five pricing journeys draw that: a status on every configuration, a proposal in place of an edit, and a sign-off with four eyes. The engine run settings carry the rule too, attached to a section: a change that alters the numbers is a proposal, and an operational change writes directly. The approval is the one that ores.inbox already runs. Market Risk is a seeded part. Quant and Model Validation are new parts, and their names and order are assumed until model risk confirms them.

2. What a report is here

A report is one of the report types the installation registers: risk and grid. Every definition the seed creates is of type risk, and the names a reader meets are the thirty-one the seed writes. They include Group Consolidated Exposure, Cross-Entity Counterparty Concentration, Intercompany Exposure Matrix, Large Exposures, Leverage Ratio, Liquidity Coverage, Board Risk Dashboard, Data Quality Completeness, System Health, Audit Trail Summary, Headline Position, SA-CCR Exposure, Intraday Risk Monitor, FRTB SA Capital, Stressed VaR, CVA/DVA/FVA, Bucketed DV01, Delta and Gamma, NPV, Exposure, Cashflows, Yield Curves, Volatility Surfaces and Credit Curves. A report page states the cycle a report serves, intraday or eod, and its frequency, on-demand or scheduled. Its audience is one of trading-desk, market-risk, engineer or release check. The definition row carries the report type and the schedule expression, which is what a screen can list; the cycle and the audience live on the report page.

The analytics a report runs are not free choice either. A report configuration names a set of them, and the set is what the report's numbers come from: Headline Position runs npv and sensitivity, Board Risk Dashboard runs npv, parametricVar and saccr, Large Exposures runs npv and saccr, and Cashflows runs cashflow. A screen that shows a report's figures is showing those analytics' output and should name them.

The names are not shared between parties. A definition is owned by one party, and the parties of a group run different reports; a reader at ACMCOR and a reader at ACCOUK see different definition rows even when both reports are risk reports. The party codes a reader meets are ACMCOR, ACCOUK, ACCOUS and ACCOHK, and every row below is party-scoped by row-level security rather than by a filter the screen applies.

A definition is configuration and a run is state. The definition carries the name, the party, the report type, the schedule expression and the run configuration that decides how much of the pipeline a run executes. The run carries what happened: when it started, when it completed, its state, its output message, where its output archive landed, and its errors. A change to the definition affects the next run and no earlier one.

3. The pipeline, in the words the screens need

Six phases run in order: Pre-processing, Submission, Execution, Retrieval, Post-processing and Finalisation. Pre-processing is four workflow steps rather than one, so the workflow has seven steps while the pipeline has six phases. Retrieval and post-processing are one step today, collect_compute_results, and are to become two: the design, the canonical row and where the work happens are on report post processing. Execution runs on a worker node and is not a step any ORE Studio service performs: the services submit the work and wait. Only finalisation touches the state machine. No phase calls another; the workflow engine invokes each step, and each step is handed the identifier or location of what the previous step produced.

The seven steps are reporting.v1.ops.gather_trades, reporting.v1.ops.gather_market_data, reporting.v1.ops.assemble_bundle, ore.v1.ops.prepare_ore_package, compute.v1.ops.submit_compute, reporting.v1.ops.collect_compute_results and reporting.v1.ops.finalise_report. A definition whose run configuration substitutes pre-processing starts at resolve_prepared_input instead of the three gathering steps; one that ignores post-processing uses ignore_compute_results; and a run that cannot finish uses fail_report.

4. Who reaches the screens

Actor What they read What they change
trading-desk The definitions their party owns, the latest run of each, the outputs and the errors Run a report on demand
market-risk The same rows, read for sign-off rather than for the desk's position Run a report on demand
engineer The rows plus the errors, to place a failure in the engine Nothing
tenant administrator Every row of their tenant, and the schedule of every definition Run a report on demand; schedule a definition; pause and resume its schedule; unschedule it. Pause and resume are not available yet, because no operation sets the scheduler job's is_active

The reads are gated by permissions the reporting service already holds: reporting::report_definitions:read, reporting::report_instances:read, reporting::report_error_events:read and reporting::report_error_scopes:read. Two writes are named: reporting::report_instances:write and reporting::report_instances:delete. The error reads are held by no role below TenantAdmin and SuperAdmin, and those two hold *; a trading desk that can run a report therefore cannot read why it failed, which the group's What is missing sections state rather than paper over.

5. Where the screens are

No BFF route serves a reporting screen, and nothing in the web application shows a report today. Each journey names the route it needs in What is missing, and each carries a wireframe that is the design intent for the prototype that will draw it. The prototypes belong under doc/prototypes/reporting/, one directory per journey, except where two journeys share a screen: analytic management is one prototype that both Create a report and Change what a report runs link to, so the interaction is written once.

6. Related

7. See also

Emacs 29.3 (Org mode 9.6.15)