ORE Studio User Manual Introduction Connecting to ORE Studio Initial Setup Provisioning from the Shell Acme Corporation Accounts and Roles Tenants Reference Data Currencies Currency Pairs Countries Business Centres Portfolios Books Parties Counterparties

The chapter advances the argument that the reader should understand what ORE Studio is before learning how to use it, and it builds that understanding in layers. It begins by establishing identity in What is ORE Studio?, which explains the application and the open-source engines it rests upon; this is the premise the rest of the chapter depends on. From there it considers for whom the manual is written in Audience, before mapping the territory the application covers in Functional Areas. It then draws the boundary in What ORE Studio Is Not, distinguishing a learning environment from a production system, and shows how the book itself is laid out in How This Manual Is Organised. Finally it sets expectations with two cautions — the Early-Stage Software Notice on the maturity of the software and A Note on This Document on how the manual was produced. The Conclusion draws these steps together.

ORE Studio is a desktop application for exploring, configuring, and running quantitative finance calculations, backed by a set of headless services and a database rather than doing any of that work itself. The Qt client you interact with is a thin presentation layer: it renders what you see and forwards every action to the appropriate backend service, which does the actual work and persists the result. It provides a graphical environment built around the Open Source Risk Engine (ORE)^{1, 2}, a widely-used open-source library for pricing derivatives and measuring financial risk, which is itself built on QuantLib^{3, 4}. ORE Studio handles the data — storing trades, market data, and model configurations, and presenting the results — while ORE and QuantLib provide the mathematics. You cannot understand ORE Studio without understanding these two engines beneath it, so it is worth being precise about what each one is and where ORE Studio sits relative to them.

This manual is written for several kinds of reader:

• Analysts, traders, quants, and middle-office staff who want to explore financial instruments and risk calculations through a graphical interface. No programming experience is required.
• Students and researchers learning quantitative finance. ORE Studio makes it possible to experiment with derivative pricing, yield curve construction, and risk measures without writing code.
• LLM-based agents and coding assistants that interact with ORE Studio on a user's behalf, help configure workspaces, interpret results, or draft analytical reports. Multimodal models — those capable of processing both text and images — are preferred, as the manual makes extensive use of screenshots to describe the user interface.

The focus throughout is on what you can do through the application itself: entering trades, configuring market data, running analytics, and understanding the results.

ORE Studio is organised around a set of functional areas accessible from the main menu:

• Reference data — currencies, business calendars, counterparties, and market conventions that form the foundation for everything else.
• Instruments and trades — define, store, and manage financial instruments and their terms.
• Market data — yield curves, volatility surfaces, fixing histories, and other inputs to pricing and risk models.
• Model configuration — choose and parameterise pricing engines, simulation models, and sensitivity specifications.
• Analytics — run calculations and view results: net present value, sensitivities (Greeks), credit and funding valuation adjustments (XVA), Monte Carlo simulations, and stress tests.

All data is stored persistently, so trades, curves, and configurations can be saved, revisited, and reused across sessions.

ORE Studio is a learning and exploration environment, not a production trading or risk system. It is independent of and unaffiliated with ORE, QuantLib, or any financial institution. For the key valuation cases, the quantitative mathematics are provided by ORE and QuantLib; ORE Studio is the surface through which they are configured and their results explored. ORE Studio does reimplement a small subset of QuantLib for its own internal purposes, but that reimplementation is not used by the engine's valuation code. Users who need production-grade performance, real-time market data feeds, or regulatory reporting should look to enterprise risk platforms.

The chapters follow the natural order of first use. After this introduction, Connecting to ORE Studio covers launching the application, establishing a connection to the backend, and orienting yourself in the main window; Initial Setup then covers provisioning the system, tenants, and parties. Later chapters cover each functional area in turn. You do not need to read the manual cover to cover; each chapter can be read independently once the system is up and running.

Early-stage software. ORE Studio is currently in active development (version 0.x). Features, workflows, and this documentation are all evolving and may change between releases. Numbers produced by the system are for learning and exploration only — they must not be used for real trading, risk management, or any financial decision-making.

This manual was generated entirely by large language models (LLMs) working under human supervision. While every effort has been made to ensure accuracy, LLM-generated content can contain errors, omissions, or descriptions that do not match the actual software behaviour. If you find a discrepancy between this manual and the application, trust the application. Please report inaccuracies via the project issue tracker so they can be corrected.

The chapter set out to orient the reader before any operation begins, and it has done so in layers. It established what ORE Studio is — a desktop surface over the open-source ORE and QuantLib engines — and for whom this manual is written, then mapped the functional areas through which the application is organised and drew a firm boundary around it as a learning and exploration environment rather than a production trading or risk system. With that frame in place it described how the book is arranged for first use and tempered expectations with two cautions: that the software is early-stage and evolving, and that the manual itself was generated by language models under human supervision. The takeaway is a sense of place: the reader now knows where ORE Studio sits in the risk-technology landscape and how to read the chapters that follow, which take up each functional area in turn.

This chapter advances the argument that reaching a working session means starting the application, teaching it about the backends it may talk to, authenticating against one of them, and learning to read the session's state — and it proceeds in that order. It begins with Getting started, which launches the application and explains the disconnected state in which it first appears, and The main window before login, which describes what is and is not available until a login succeeds. From there it turns to The Connection Browser, the central place where backends are defined, walking through adding, editing, and deleting a connection, organising connections into folders, protecting credentials with a master password, grouping by environments and tags, and where the connection store lives and how to back it up. With a connection in place it moves to Connecting and logging in — selecting the active connection, the login screen, filtering Quick Connect by label, the distinct ways a connection can fail, the first login and default account, and registering a new account. It then covers Connection status and reconnection and the vocabulary of The status bar, so the reader can tell the connection's state at a glance. Finally it gathers the operational periphery — Starting ORE Studio from the command line, Finding the application version, Running in the background and the system tray, and Logging out — and the Conclusion draws these steps together.

When you launch ORE Studio a splash screen appears briefly while the application initialises, showing the ORE Studio logo and the build version in its lower-right corner.

Once initialisation completes you are greeted by the main window in its disconnected state. The application is running but has not yet established a connection to the backend service that performs calculations. Before you can work with trades, market data, or analytics, you need to connect to a running ORE Studio backend.

In the disconnected state most of the application is inactive. The menu bar and toolbar are present but workspace panels, trade lists, and analytics views are all unavailable until a successful login. Two toolbar buttons are always accessible:

• Connect — opens the login dialog for the currently selected connection.
• Connections — opens the Connection Browser, where you configure the list of backends ORE Studio knows about.

The Connection Browser is the central place where you maintain the list of ORE Studio backends the application can connect to. You might have a local development backend, a shared team backend, and a staging backend — each appears as a separate entry here. It lets you add, edit, delete, and organise those entries before you attempt a login.

Open it at any time from the toolbar Connections button or from the File menu.

Once you have at least one connection configured, you can log in.

The status bar always shows whether you are connected. After a deliberate log-out — or once a stopped backend is running again — use the Connect button to re-establish the session: your saved connection is retained, so you only re-enter your password.

The status bar runs along the bottom of the main window and provides a continuous read on the application's connection state. It is always visible regardless of what is open in the workspace.

The status bar is divided into zones from left to right:

• Connection name — the name of the active connection as entered in the Connection Browser (e.g. "Local dev"). Clicking this zone opens the Connection Browser directly.
• Environment badge — the coloured environment label (e.g. Production in red) if one is assigned to the active connection. Absent when no environment is set. This is the most prominent safety indicator: always glance at the environment badge before performing any write operation.
• Username — the account name of the currently logged-in user. Absent in the disconnected state.
• Server — the backend address (host and port) the session is connected to, e.g. localhost:42221.
• Active party — the party context for the session (e.g. Root / System Party), set at login when your account spans multiple parties.
• Connection indicator — a coloured icon at the right showing the live link state (green when connected).

The status bar changes appearance to reflect the connection state:

• Disconnected (no active connection) — grey; shows "Not connected".
• Connecting (handshake in progress) — animated indicator; shows "Connecting to /name/…".
• Connected and logged in — normal; shows all zones as described above.

In the disconnected state the strip is reduced to the environment marker and the connection label, with the broken-link icon on the right:

The connected state is shown at the start of this section. Compare it with the disconnected strip above to recognise at a glance which state the application is in.

ORE Studio can be launched directly from a terminal, which is useful for scripting, for telling several windows apart, or for pointing the application at a non-default configuration directory. Run ores --help to see the full list of accepted options for your installed version; the most commonly used ones are documented below.

ores --help

Knowing exactly which build you are running matters when reporting an issue or checking client/backend compatibility. ORE Studio shows its version in several places.

The title bar of the main window always shows the version next to the application name:

It also appears in the lower-right corner of the splash screen at start-up:

…and in the footer of the login dialog, below the Register link:

From the command line, ores --version prints the client version string (e.g. ORE Studio 0.0.19) and exits — handy in scripts or when filing a bug report.

ores --version

While ORE Studio is running it places an icon in your desktop's system tray (notification area). The icon keeps the application reachable when its window is minimised or hidden, and shows the instance name so you can tell multiple windows apart.

To end your session, choose File → Log Out or click the Disconnect toolbar button. ORE Studio closes the connection to the backend and returns to the disconnected main window. Your saved connection configurations are preserved; you can log back in at any time.

Logging out does not stop the backend service — it only terminates your client session. Other users connected to the same backend are unaffected.

To close the application entirely, quit the window (or choose File → Exit). ORE Studio asks you to confirm so you do not lose an active session by accident:

The chapter set out to show that reaching a working session follows from starting the application, defining the backends it may talk to, authenticating against one, and reading the session's state in turn, and it has traced exactly that path. It began at the disconnected main window, where nothing but the Connect and Connections actions is available, and used the Connection Browser to build up the set of known backends — adding and editing entries, organising them into folders, sealing their credentials behind a master password, and grouping them by environment and tag, all held in a single local store that travels with a file copy. Building on that, the connect-and-login sequence took a configured connection through to an authenticated session, with Quick Connect and labels narrowing the choice and the distinct failure messages distinguishing a wrong password from an unreachable server. The status bar then gave the session a continuous, glanceable account of its own state, and the command-line options, version markers, system tray, and log-out path filled in the operational periphery. The reader can now reach a live backend; the next chapter covers what must happen before a brand-new backend is usable at all: provisioning.

The chapter advances the argument that provisioning a fresh installation is a fixed sequence that follows from the data model it serves, and it proceeds in that order. It begins by sketching that model in The model in brief, establishing the tenant as the unit of isolation and the party as the organisational hierarchy within it; this is the premise the rest of the chapter builds on. From there it lays out the The provisioning sequence as a whole — the three steps and the login identity each one requires — before working through each wizard in turn. It walks the System Provisioner, which creates the platform administrator and the first tenant; then the Tenant Provisioner, whose first page forks between the ready-made Acme Corporation reference entity and a Manual path that seeds a tenant with reference data and its own house party hierarchy; and then the Party Provisioner, which equips a single manually-created party with counterparties and report definitions. Finally it shows where provisioning hands over to daily use in Choosing a party at login, and the Conclusion draws these steps together.

ORE Studio organises data around two concepts that the provisioning wizards exist to create. A tenant is a fully isolated organisational space — its users, reference data, and results are invisible to every other tenant; typically one per organisation. Within a tenant, parties form the organisational hierarchy: the house — your own legal entities, desks, and booking centres — alongside the external counterparties it trades with. Users log in to a specific party, and their position in the hierarchy determines what they can see. The full model — tenant types, the system tenant and system party, hierarchy visibility, and the house versus counterparty distinction — is covered in the Tenants chapter.

A freshly installed ORE Studio backend goes through a fixed sequence before it is ready for normal use. Each step requires a specific login identity:

1. System provisioning — no login is needed; the backend is in provisioning mode and the System Provisioner wizard launches automatically the first time any client connects. This step creates the platform administrator account and provisions the first tenant and its tenant administrator. Until it completes, no normal user logins are accepted.
2. Tenant provisioning — log out of the system administrator session (or simply connect as a new user) and log in as the tenant administrator created in step 1. OreStudio detects that this account has never logged in before and launches the Tenant Provisioner automatically. Here the path forks: choosing Acme Corporation (full sample bank) populates the tenant with the system's ready-made reference entity in one step (see the Acme Corporation chapter); choosing Manual setup instead seeds the tenant with reference data and creates your own house party hierarchy, step by step, as described below.
3. Party provisioning — log in to a specific house party using the tenant administrator account, or any operational account that holds party setup permissions for that party. OreStudio detects that the party has not yet been provisioned and launches the Party Setup wizard. Repeat this step for each party in the hierarchy that needs its own counterparties, books, and reports.

Each step has a corresponding wizard in the ORE Studio UI. The following sections walk through each one.

The first time you connect to a backend that has never been initialised, ORE Studio detects provisioning mode and launches the New System Provisioner automatically. This one-time wizard creates the platform administrator account, chooses a single- or multi-tenant layout, and provisions the first tenant together with its own administrator.

The first time you log in as a tenant administrator, ORE Studio launches the New Tenant Provisioner. It seeds the tenant with reference data and, optionally, an initial party hierarchy. You can skip it with Cancel and set everything up by hand later from the Data Librarian and Parties windows.

Where the Tenant Provisioner establishes the party hierarchy, the Party Setup wizard configures the operational structure within a party: it imports counterparties, then publishes every party-scoped data bundle the party needs — risk management (business units, portfolios, books, and a standard set of risk-report definitions), synthetic market data configuration, and curated FX driver rates. It runs for a party that needs initial setup, and can be skipped with Cancel (counterparties and bundles can be configured later from the application menus).

Some accounts are associated with more than one party — for example a group administrator who can act for several entities. When you log in with such an account, ORE Studio asks which party context to use for the session.

Choose System Party for administrative work, or Operational Party to work within a specific business entity. Filter the list by booking centre, or type in the search box to narrow it.

Select a party and click Select. Your data visibility for the session is determined by the party you choose and its position in the hierarchy.

The chapter set out to show that provisioning a fresh installation is a fixed sequence that follows from the data model it serves, and it has traced exactly that path. The tenant and party model came first — the tenant as the unit of isolation, the party as the hierarchy within it, with the full treatment reserved for the Tenants chapter — because the provisioning steps exist to create precisely those structures. Building on that premise, the three wizards did the work in turn: the System Provisioner created the platform administrator and the first tenant, the Tenant Provisioner forked between the ready-made Acme Corporation reference entity and a Manual path seeding the tenant with reference data and its own house party hierarchy, and the Party Provisioner equipped each manually-created party with counterparties, an organisational structure, and report definitions. Each step required its own login identity, and each ran once. Provisioning ends where daily use begins — choosing a party at login — and the accounts the wizards created, like every account after them, are managed through the windows described in the next chapter.

The chapter advances the argument that provisioning a complete system from the command line means understanding the client that runs the commands, then each provisioning command in the order it must be run, then the smaller commands they are built from, and finally how to tie them together into a repeatable script — and it proceeds in that order. It begins by establishing the client and the rules it enforces in The shell and provisioning, which explains how the shell speaks to the backend and why provisioning follows a fixed sequence; this is the premise the rest of the chapter builds on. From there it walks the sequence one stage at a time — Provisioning the system, then Provisioning a tenant, then Provisioning a party — each command standing in for the wizard it replaces. It then opens up the machinery in The supporting commands, the smaller commands the provision phases call and that you can run by hand to inspect the system or recover a failed run, before showing in Scripts how the shell runs those commands unattended from a file. Finally A complete example runs the fast Acme Corporation path from a single shipped script, and A custom example: your own organisation points to the equivalent script for building your own house instead, before the Conclusion draws these steps together.

ores.shell is ORE Studio's interactive command-line client. Like the desktop application it speaks to the backend services over the message bus, so anything it does respects the same validation, audit trail, and permissions. Start it, connect, and type help to see the available commands; every command described here also explains its own arguments through the shell's built-in help.

Provisioning from the shell follows exactly the sequence described in the previous chapter — system, then tenant, then party — including the logouts and logins between the stages, because each login is what refreshes your session's view of the system's state. The difference is that each wizard collapses into a single command whose options carry the same defaults the wizard pre-fills, so the common case needs very few of them.

provision system performs the System Provisioner's work: it checks the installation is in bootstrap mode, creates the platform administrator, logs in as that account, and provisions the first tenant together with its tenant administrator.

provision system super_admin Secure-Password-123 admin@localhost.com --tenant-admin-password Secure-Password-123 --tenant-hostname default
logout
exit

The tenant administrator's password is the only option without a default — everything else mirrors the wizard's single-tenant mode: tenant code default, name Default Tenant, type evaluation, and the tenant administrator named tenant_admin with the e-mail address admin@<code>.com. To provision a custom tenant instead — what the wizard calls multi-tenant mode — override what you need with --tenant-code, --tenant-name, --tenant-type, --tenant-hostname, --tenant-description, --tenant-admin and --tenant-admin-email.

The command validates everything before touching the backend, refuses to run when you are already logged in or the system is not in bootstrap mode, and on success prints the login for the next stage:

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-system>>
EOF

✓ Connected to nats://localhost:42222
⚠ WARNING: System is in BOOTSTRAP MODE
ores-shell> [1/3] Creating initial admin account 'super_admin'...
  Account created (ID: b88d04ec-ac25-4137-981a-ddefb1d92592).
[2/3] Logging in as 'super_admin'...
✓ Login successful!
[3/3] Provisioning tenant 'default'...
✓ System provisioned. Tenant 'Default Tenant' (ID: 93b5d425-...), admin 'tenant_admin'.
Next: logout, then: login tenant_admin@default <password>  — the tenant is in bootstrap mode; run provision tenant.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

Note the login principal is the username at the tenant's hostname (tenant_admin@default above), not its display name.

provision tenant performs the Tenant Provisioner's work for the tenant you are logged in to. Log in as the tenant administrator the previous stage created — the tenant is in bootstrap mode, which is exactly what the command requires — and run:

login tenant_admin@default Secure-Password-123
provision tenant --source synthetic --seed 42
logout
exit

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-tenant>>
EOF

ores-shell> ✓ Login successful!
ores-shell> Using bundle 'base' (first available).
[1/4] Publishing bundle 'base'...
  Dispatched 31 dataset(s); workflow instance: 7c059b7f-...
✓ All 31 step(s) completed.
[2/4] Generating synthetic organisation...
✓ Synthetic organisation generated (seed 42):
  parties:             5
  counterparties:      10
  ...
[3/4] Associating 'tenant_admin' with the operational parties...
  5 parties associated.
[4/4] Finalizing tenant provisioning...
✓ Tenant provisioned: bundle 'base', 5 parties associated.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

With no options this publishes the first available reference data catalogue and uses the GLEIF registry as the data source, just as the wizard's defaults do. The options mirror the wizard's Welcome-page fork and its Manual sub-pages:

• --source acme — the fastest path to a fully populated, realistic installation, matching the wizard's Acme Corporation (full sample bank) choice. Ignores every other option below: it imports Acme Corporation's four-entity LEI hierarchy and publishes all of its business units, portfolios, books, and staff accounts server-side in one command. See the Acme Corporation chapter for what this produces, and A complete example below for the full worked run.
• --bundle <code> selects a specific reference-data catalogue for the Manual path (bundles list shows what is available).
• --source gleif (the default when --source is omitted) optionally takes --root-lei <lei> to build your own house hierarchy from a real organisation; find the LEI with lei countries and lei entities <country> --filter <text>.
• --source synthetic generates a realistic but fictional organisation instead, for evaluation or testing without importing real data. All the generation controls from the wizard's synthetic page are available as options with the same defaults (--party-count, --counterparty-count, --portfolio-leaf-count and so on); --seed <n> makes the result reproducible — the same seed always generates the same organisation, names included.

Choose --source acme to explore ORE Studio quickly; choose gleif or synthetic when you want to model your own organisation instead.

The command publishes the catalogue and waits while the backend works through its datasets, printing each step as it completes; generates the synthetic organisation when selected; associates your administrator account with every operational party; and finally marks the tenant active. As with the wizard, log out and back in afterwards so your session picks up the now-active tenant.

provision party performs the Party Provisioner's work for one party. Unlike the wizard — which runs for the party you selected at login — the command always names its target explicitly, either by its full name or by its identifier; parties list --category Operational shows the candidates:

login tenant_admin@default Secure-Password-123
provision party "Lloyds Wealth Management Ltd"
logout
exit

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-party>>
EOF

ores-shell> ✓ Login successful!
ores-shell> [1/5] Importing counterparties (dataset small)...
✓ All 1 step(s) completed.
[2/5] Publishing organisation structure and risk reporting...
✓ All 4 step(s) completed.
[3/5] Publishing synthetic market data configuration...
✓ All 2 step(s) completed.
[4/5] Publishing FX driver rates...
✓ All 1 step(s) completed.
[5/5] Activating party 'Lloyds Wealth Management Ltd'...
✓ Party 'Lloyds Wealth Management Ltd' provisioned and active.
ores-shell> ✓ Logged out successfully.
ores-shell> Bye!

The only option is --dataset-size small|large, selecting the counterparty import size (small is the default). The command imports the counterparties, then publishes every party-scoped bundle in turn – risk management (business units, portfolios, books, and report definitions; reports reference the book/portfolio tree, so both publish together), synthetic market data configuration (FX, IR curve, and any future asset class – adding one is a data change in dq_dataset_bundle_member_populate.sql, never a shell code change), and the curated FX driver-rate dataset – and finally activates the party.

The provision commands are built from smaller commands you can use on their own — to inspect the system, to recover when a step fails, or to assemble a custom flow. Each provision phase prints which of these it is performing, so a failed run tells you where to pick up by hand.

The provision commands call these in sequence; you can call them individually to inspect the system or to recover a failed run from where it stopped.

The shell runs scripts with the load command: one command per line, # starts a comment, and blank lines are ignored. A script stops at the first command that fails — so a run that reaches the end has genuinely succeeded — and reports the failing line and command. When you want a script to press on regardless, for example while exploring, pass --continue-on-error:

load my_script.ores
load my_script.ores --continue-on-error

ORE Studio ships a small library of provisioning scripts in projects/ores.shell/scripts/. Each .ores script in the library is generated from a documentation file alongside it that explains, step by step, what the script does and what it expects of the system — read that file before running a script for the first time. Treat the shipped scripts as templates: copy one and adjust the copy rather than editing the original, which the build regenerates.

The library's how_do_i_provision_the_system_with_acme_corporation_holding_group.ores provisions a complete system from a fresh installation with a single --source acme call: platform administrator, an Acme Corporation tenant, and all four of its legal entities — business units, portfolios, books, staff accounts, and market data — server-side orchestrated in one step. It is the quickest way to a fully populated installation and the recommended starting point for exploring ORE Studio; see the Acme Corporation chapter for what it produces. It expects a fresh installation in bootstrap mode, all services running, and a connected, logged-out session.

load projects/ores.shell/scripts/library/provisioning/how_do_i_provision_the_system_with_acme_corporation_holding_group.ores
exit

An error-free run ends with all four legal entities active (the excerpt below elides most of the per-entity dataset/bundle detail — the full output reports every step for all four companies as it lands):

./projects/ores.compass/compass.sh shell << 'EOF'
<<shellprov-acme>>
EOF

ores-shell> Loading script: .../how_do_i_provision_the_system_with_acme_corporation_holding_group.ores
> provision system super_admin Secure-Password-123 super_admin@localhost.com ...
✓ System provisioned. Tenant 'Acme Corporation' ...
> login tenant_admin@acme_corporation Secure-Password-123
✓ Login successful!
> provision tenant --source acme
Step 1: Publishing base reference data: ... completed
Step 2: Importing Acme Corporation LEI hierarchy: ... completed
Step 3: Publishing group-level staff: ... completed
Step 4: Publishing ACME Corporation UK plc: ... completed
Step 5: Publishing ACME Corporation US Inc: ... completed
Step 6: Publishing ACME Corporation HK Ltd: ... completed
Step 7: Granting cross-entity access: ... completed
✓ Acme Corporation holding group provisioned.
> logout
✓ Logged out successfully.
Script complete: 6 commands executed.

Unlike the generic provision party flow, --source acme handles every one of Acme's four legal entities internally — there is no per-party stage to call separately, and no seed to track: the same script against a fresh installation always produces the same four entities, the same fifty-eight staff, and the same structure.

Log in — from the shell or the desktop application — as tenant_admin@acme_corporation, select one of the four operating companies, and daily use begins, just as at the end of the previous chapter.

Where the Acme Corporation script above is the fast path, building your own house from scratch — modelling a real organisation, or a synthetic one shaped to your own testing needs — uses the generic three-stage sequence Provisioning the system through Provisioning a party set out earlier: provision system, then provision tenant --source gleif (or --source synthetic), then provision party for each party that needs its own counterparties and bundles. The library's barclays_system_provision.ores is the worked example of this path — real GLEIF-imported data rather than Acme's curated dataset — and follows exactly the same =load=/logout/login shape as the Acme example above, just with more stages since each party is provisioned individually.

The chapter set out to show that a complete system can be provisioned from the command line by understanding the client, the provisioning commands in sequence, the supporting commands beneath them, and the scripts that tie them together, and it has traced exactly that path. The shell speaks to the same backend services as the desktop application, so it enforces the same validation, audit trail, and permissions, and provisioning follows the same fixed sequence — system, then tenant, then party — with the logouts and logins between stages that refresh the session's view of the system. Each provision command collapses a wizard into a single line whose options carry the same defaults, and each is built from smaller supporting commands that can be run by hand to inspect the system or recover a failed run. The load command then runs those commands unattended from a file, and the shipped script library showed both paths executing end to end from a fresh installation: --source acme for the fast, fully populated Acme Corporation entity, and the generic gleif=/=synthetic sequence for building a house of your own. Because the same script against the same starting point always produces the same system, scripted provisioning is the natural tool for development environments, testing, and automation — everything the wizards do, reproducibly and without the desktop.

The chapter advances the argument that understanding Acme Corporation means first knowing what it is, then the organisational model its structure is built from, then the structure itself, then the departments within it, and finally how to stand it up — and it proceeds in that order. It begins by establishing the premise in What is Acme Corporation. From there The organisational model: parties, business units, portfolios, and books sets out the two hierarchies — organisational and portfolio — that every party's structure is built from, the premise the rest of the chapter assumes. Building on that model, The holding-group structure walks Acme's four legal entities and the trading floor each one carries, The holding company's own treasury footprint sets out what the group centre itself carries and how that differs from an operating company's trading floor, Departments and segregation of duties explains why a trading floor is never a single undifferentiated team, and Staff and accounts introduces the people who staff those desks and the org-chart view that renders their reporting lines. Finally Provisioning Acme Corporation shows how to stand the whole entity up yourself, from the Qt wizard or the shell, before the Conclusion draws these steps together.

Acme Corporation is ORE Studio's reference entity: a synthetic four-legal-entity investment-bank holding group, fully populated with business units, portfolios, books, and staff, provisioned in one command and ready to explore the moment it lands. Every screenshot in this manual and every worked example in every other chapter needs a populated system to point at, and Acme Corporation is that system — a fully populated organisational structure to walk through rather than a single flat party.

"Acme" is the archetypal fictional-company name — from the Acme Corporation, the mail-order supplier of absurdly over-engineered products in Looney Tunes' Road Runner cartoons, now a byword for any generic placeholder business. Reusing it here signals plainly, to anyone browsing the data, that Acme Corporation is a synthetic reference/demo entity, not a real institution — the same signal slovaris, ORE Studio's other synthetic dataset, sends for its own domain. But the resemblance stops there. Slovaris is a fully self-contained fictional universe, deliberately isolated from the system's real reference data. Acme Corporation takes the opposite approach: it is designed to integrate. Its four legal entities carry LEIs that are fake but well-formed — real, checksum-valid (ISO 17442 / mod-97) 20-character codes built on GLEIF's reserved 9695 pre-LOU test prefix, which GLEIF explicitly sets aside for non-production use and will never assign to a real entity — stored in exactly the same refdata_party_identifiers_tbl rows a real GLEIF-imported LEI occupies, so nothing in the schema or the UI needs to special-case a "fake" identifier. Acme's counterparties, in turn, are not synthetic at all: they are the real, GLEIF-imported counterparty universe — Deutsche Bank, Barclays, and every other institution the GLEIF registry supplies — so Acme's own trades can reference real-world institutions exactly as a production tenant's would.

With the premise established — a synthetic house trading real counterparties — the rest of the chapter turns to the model that gives Acme's own structure its shape.

ORE Studio organises trading activity around two hierarchies that share a common root but serve different audiences. The first is organisational: a party — a legal entity or organisational subdivision — owns a tree of business units, typed and geographically anchored, that mirrors the bank's actual reporting lines. A division sits above business areas, which sit above trading desks and cost centres, each carrying a business-centre code (GBLO for London, USNY for New York, and so on) that ties it to a physical trading location. This hierarchy is what risk and middle office read: which desk, in which jurisdiction, is accountable for a given position.

The second hierarchy is portfolio: books, the atomic unit to which every trade is booked, sit beneath physical portfolios that aggregate their risk and P&L, which in turn can sit beneath virtual portfolios — reporting overlays with no organisational meaning of their own, used to build cross-desk or cross-region views such as "Global Rates" spanning both London and New York. This is the hierarchy traders and front office read: not who is accountable, but how risk rolls up for management reporting. The two hierarchies are independent but linked at the book level — every book carries both an owning business unit and a parent portfolio — which is precisely how a bank practises "follow the sun" trading without a single book ever appearing to move between cities: London's book and New York's book are two separate books, each owned by its own desk, reconciled at end of day through an interbook trade, and reunited only in a virtual portfolio's consolidated view.

Both hierarchies are scoped to a party within a tenant, following the same tenant isolation and party-visibility rules set out in the Tenants chapter. Acme Corporation's four legal entities are four such parties, each the root of its own pair of hierarchies — which is exactly the shape the next section walks in concrete terms.

Acme Corporation comprises four legal entities: Acme Corporation Plc, the group holding company, and three regional operating companies — ACME Corporation UK plc, ACME Corporation US Inc, and ACME Corporation HK Ltd — each booking business in its own jurisdiction (London, New York, and Hong Kong respectively). Every entity carries its own checksum-valid, 9695-prefixed LEI, and the three operating companies are children of the holding company in the party hierarchy: a real corporate shape built from fake-but-valid identifiers.

Acme Corporation Plc              (party, root — group holding company)
  ├─ ACME Corporation UK plc      (party — booking entity, GBLO)
  ├─ ACME Corporation US Inc      (party — booking entity, USNY)
  └─ ACME Corporation HK Ltd      (party — booking entity, HKHK)

Each operating company carries its own trading floor, modelled on a global investment bank's Markets division: a Global Markets division split into Rates, Credit, and FX trading desks, alongside a Risk Management division and Middle Office and Market Risk cost centres — the follow-the-sun pattern the previous section introduced, expressed concretely. ACME Corporation UK plc's Global Markets division goes further, with EMEA, Americas, and APAC business areas beneath it — the London entity is where Acme's global trading footprint is broadest, reflecting a UK head office coordinating trading across time zones rather than each region booking in total isolation. Today only the EMEA business area is actually staffed; the Americas and APAC business areas exist as structural placeholders for that footprint to grow into, with desks defined but no accounts or books under them yet.

Every desk owns one book, sitting beneath a physical portfolio scoped to that desk; every operating company's business units, portfolios, and books carry the company_code that ties them back to their owning legal entity, since each of the four entities needs its own independent organisational structure. Open the Parties window on a freshly provisioned Acme Corporation tenant and the hierarchy above is what you see, four levels deep and fully populated.

With the corporate shell and its trading floors in place, the chapter turns first to the holding company's own footprint at the group centre, before turning to why a trading floor is divided the way it is.

Acme Corporation Plc is not a pure legal shell sitting above the three operating companies with nothing of its own underneath it — unlike a holding company with zero market-data footprint, it carries genuine parent-level treasury activity: FX visibility into the rates its subsidiaries trade in, for remittance and hedging decisions, and a Group Treasury book/portfolio for the intercompany loans and FX hedges the parent itself carries. This is what distinguishes a real holding company from a passive legal wrapper, and it is deliberately modelled differently from an operating company's trading floor rather than as a fourth, smaller copy of one.

FX visibility works without the holding company needing a feed of its own: the Cross-Rates Matrix, opened at Acme Corporation Plc, shows live cross rates across GBP, USD, and HKD — the three operating companies' own currencies — fed entirely by the offices' FX feeds. A EUR/USD print is the same real-world rate regardless of which office's feed_binding happens to be subscribed to it, so FX driver ticks are tenant-wide for CRM-matching purposes rather than scoped to whichever party's feed produced them; each party's own topology configuration still governs what it is authorised to see, so this shares nothing beyond what a real FX rate already is.

Where each operating company's own business unit is a full trading floor — Global Markets, Risk Management, desks and cost centres, as the previous section walked — Acme Corporation Plc's own business unit is a single DIVISION-type unit, "Group Treasury" (acme_group.treasury), holding one virtual GBP portfolio ("Group Treasury Portfolio") and two books, both classified Banking rather than Trading: "Group Intercompany Loans" (GL-TREAS-001) and "Group FX Hedges" (GL-TREAS-002), both carrying cost centre CC-GROUP-TREASURY and rates centre GBLO. Neither book is a held-for-trading desk. "Group Intercompany Loans" carries the loans and deposits between the holding company and its subsidiaries; "Group FX Hedges" carries the forwards and swaps that hedge the group's remittance and translation exposure back to GBP, the group's own reporting currency — the Banking classification is the correct prudential treatment for financing and for hedges of non-trading exposure, not the Trading classification an operating company's desks carry.

Consolidated group-level risk reporting — rolling the three operating companies' books up into a single group-level NPV/VaR/XVA view at the holding company — is the natural next question a real group treasury function would ask, and the underlying data-visibility a report like that would need already exists (a session scoped to the holding party already sees every subsidiary's books and trades, the same mechanism that grants staff cross-entity access during provisioning); building and exposing that view is not yet in place.

With the holding company's own footprint established alongside its three operating companies, the chapter turns from structure to why a trading floor is divided the way it is.

A trading floor is never a single undifferentiated team, and Acme Corporation's structure exists to make that concrete rather than abstract. Each operating company separates three functions that never report through one another: the desks that take positions, Middle Office, which processes and reconciles what the desks book, and Market Risk, which independently measures and monitors the resulting exposure. This three-way split — front office takes risk, middle office processes it, risk management measures it — is the standard shape of a bank's control environment: no single function both takes a position and marks or monitors it, so no single individual's error or misconduct can go unchecked by construction of the org chart alone. The rest of this section walks each department in turn — what it does, who staffs it, and which of ORE Studio's seeded roles its accounts hold — before the following section on leadership and the caveat about what this buys you today.

The fifty-eight accounts the previous section walked by department share a common identity pattern regardless of which one they belong to. Every account's name is generated from the office's own locale — British names for London, American names for New York, Cantonese-appropriate names for Hong Kong — rather than a single Western default stamped across all three, and every account carries a profile picture drawn from a tagged face dataset, loosely matched to the generated name's apparent gender and the office's predominant ethnicity mix. Every generated account shares one fixed demo password, so any of the fifty-eight is immediately usable for exploring party-scoped access without a separate credential to look up per account.

Reporting lines run true to the departmental structure: a trader reports to their Head of Desk, who reports to their Head of Trading; an analyst reports to their Head of Middle Office (under the COO) or Head of Market Risk (under the Head of Risk); every one of those intermediate heads reports to their Country Head, and each Country Head to the Group Chief Executive Officer — so the whole fifty-eight-account structure is one connected tree rather than three disconnected regional trees. Rather than tracing that tree by hand through each account's detail dialog, open it at a glance from User Accounts > Org Chart: a maximisable window that lays every account out top-down as a card — photo, name, job title, office — connected to its manager, with a distinct colour per operating company and the currently logged-in account's own card highlighted.

A multi-party account — tenant_admin, for instance, which carries cross-entity access to all four legal entities — is not locked to whichever party it logged in against. The party picker in the top-level toolbar switches the in-session party context without logging out, so moving from ACME Corporation UK plc's books to ACME Corporation US Inc's is a menu selection, not a re-login.

With the people in place, the chapter closes with how to bring this entity into being on your own installation.

Acme Corporation is the fastest way to get a fully populated ORE Studio installation: one command, no manual party-by-party setup. It is provisioned the same way any tenant is — through the platform administrator's tenant-creation wizard, or the equivalent shell command — with one difference: rather than the Manual path, where you build up parties, business units, and staff one wizard screen at a time, selecting Acme Corporation (full sample bank) hands the entire holding-group build to the server. One command imports the four-entity LEI hierarchy, publishes every entity's business units, portfolios, books, and accounts dataset, and activates the tenant — no repeated per-party logins, no client-side orchestration to babysit. The choice sits on the tenant-creation wizard's Welcome page, reached via System > Administration > Tenants > Onboard: a simple radio choice between Acme Corporation (full sample bank) and Manual setup — see the Initial Setup chapter for the full wizard walkthrough, including the Manual path for setting up your own organisation instead.

The same choice is available from the shell, for scripted or repeatable provisioning: bootstrap the platform, then provision the tenant with --source acme.

provision system super_admin Secure-Password-123 super_admin@localhost.com --tenant-admin-password Secure-Password-123 --tenant-code acme_corporation --tenant-name "Acme Corporation" --tenant-hostname acme_corporation
logout

login tenant_admin@acme_corporation Secure-Password-123
provision tenant --source acme
logout

This follows exactly the shell provisioning sequence the Provisioning from the Shell chapter sets out — system, then tenant, with the logout between stages that refreshes the session's view of the newly active tenant — and the full worked example, runnable end to end against a fresh installation, is documented as its own recipe: How do I provision the system with Acme Corporation (holding group)?. Either path — wizard or shell — ends with the structure this chapter has walked: four legal entities, their trading floors, and fifty-eight staff accounts, ready to log in and explore.

The chapter set out to show that understanding Acme Corporation means knowing what it is, the organisational model its structure is built from, the structure itself, the departments within it, and how to stand it up, and it has traced exactly that path. Acme Corporation is a synthetic house, identified by fake-but-valid LEIs, integrated into the system's real GLEIF counterparty universe rather than isolated from it. That house's four legal entities are built from the same organisational and portfolio hierarchies every party in ORE Studio uses — business units typed and anchored to a business centre, books aggregating beneath physical and virtual portfolios — and those hierarchies exist to enforce a real control principle: trading, processing, and risk measurement kept organisationally separate, even though that separation is not yet an access-control boundary. The holding company at the group's centre is not a passive shell either: its own Group Treasury business unit, FX visibility across every subsidiary's currency, and Banking-classified books for intercompany funding and remittance hedging show a real parent company's own treasury activity, modelled distinctly from an operating company's trading floor rather than as a smaller copy of one. Populated concretely with fifty-eight staff across Rates, Credit, and FX desks, Middle Office, and Market Risk, whose reporting lines the org-chart view renders at a glance, provisioning — from either the Qt wizard's one-click choice or the equivalent shell command — showed that the whole entity, structure and staff and all, is one command away on any installation. Every other chapter's screenshots and worked examples now have somewhere to point.

• Trading Structure: Party, Book, Portfolio, Business Unit, Business Centre — the organisational and portfolio hierarchy this chapter's model section draws on, including the FRTB desk-attribution use case.
• Tenants — the tenant/party model Acme Corporation is provisioned into.
• Accounts and Roles — the RBAC model, including the desk-scoping gap noted above.
• Provisioning from the Shell — the shell provisioning sequence Acme Corporation follows.
• Initial Setup — the Qt provisioning wizards, including the Acme Corporation vs Manual choice.
• Acme Corporation (Wikipedia) — the fictional-company namesake the dataset borrows.

The chapter advances the argument that managing accounts well means understanding the population of accounts you administer, the individual record and what it carries, how a new one is brought into being, and finally the model that decides what any of them may do — and it proceeds in that order. It begins by surveying the body of records in The Accounts window, where the list reflects who you are logged in as and updates live as others make changes; this establishes the administrator's vantage point the rest of the chapter works from. From there it narrows to a single record in The account detail dialog and its six tabs — general identity, security, login status, roles, parties, and provenance — the dialog that serves equally for inspection and editing. It then turns to bringing a new account into being in Creating an account, the same dialog in create mode, with the password, role, and party steps and the warnings that guard them. Finally it sets out the model underneath it all in Roles and permissions — the Role-Based Access Control scheme by which accounts hold roles and roles bundle permissions — distinguishing the service roles that run OreStudio's own machinery from the domain roles modelled on a financial institution's desks. The Conclusion draws these steps together.

Open the Accounts window from the Administration submenu of the System menu. The Administration menu is only present for accounts that hold administrative permissions.

The provisioning wizards described in the Initial Setup chapter create the first accounts for you — the platform administrator during system provisioning and the tenant administrator during tenant creation. Those wizards are a one-time bootstrap: every account after that is created and managed in the Accounts window described here. Accounts come in four types, shown as coloured badges throughout the UI: User for people, Service for OreStudio's own backend services, Algorithm for automated processes, and LLM for large language model agents. What an account is allowed to do is determined by the roles assigned to it; which data it can see is determined by the tenant it belongs to and the parties it is assigned (see Initial Setup for the tenant and party model).

The window lists every account visible to your login identity, one row per account. Alongside the username and email, badge columns show the account type, the login status (Online, Recent, Old, or Never for accounts that have never logged in), and whether the account is locked. The remaining columns carry the record version and provenance — who last modified the record and when.

The toolbar follows the standard entity-window layout (Reload, Add, Edit, Delete, History) and adds four account-specific actions: Lock and Unlock to suspend and restore login access, Reset Pwd to set a new password, and Sessions to inspect the account's login sessions.

Double-click an account (or select it and press Edit) to open the detail dialog. The dialog has six tabs; the same dialog serves creation, editing, and read-only inspection of historical versions.

• General — username, email, and the account type. The type is chosen at creation time and is read-only afterwards.
• Security — set or change the account password (see the new-account flow below).
• Login Status — read-only login telemetry: whether the account is online, locked, its failed login count, last login time, and last known IP addresses.
• Roles — the roles assigned to this account (next section).
• Parties — the parties this account may log in to.
• Provenance — who changed this record version, when, and why.

Press Add in the Accounts window toolbar to open the same detail dialog in creation mode, titled New Account.

Passwords are set on the Security tab. The confirmation field outlines green once both entries match; tick Show passwords to verify what you typed before saving.

Passwords are entered masked; ticking Show passwords reveals both fields, useful when setting an initial password you are about to hand to the new user:

Next, assign at least one role on the Roles tab — without one the account will hold no permissions (see the note below):

For accounts that should log in to a party context, assign at least one party on the Parties tab; the combo box offers the tenant's party hierarchy:

If you save without assigning a party, OreStudio asks for confirmation — such accounts exist but cannot enter any party context at login:

OreStudio implements industry-standard Role-Based Access Control (RBAC). RBAC separates three concepts that are easy to conflate:

• An account is an identity — it answers "who is this?". It carries credentials (a password for users, certificates for services) and is the thing that logs in, appears in provenance records, and gets locked or unlocked. An account grants nothing by itself.
• A permission is the atomic unit of capability — it answers "what single thing may be done?". Permissions are fine-grained strings following a domain::resource:action pattern: refdata::currencies:read allows reading currency records, iam::tenants:create allows creating tenants. A trailing wildcard covers a whole domain — analytics::* grants every analytics permission — and the bare wildcard * grants everything.
• A role is a named bundle of permissions — it answers "what job does this identity do?". Roles are the only bridge between the two: accounts never hold permissions directly, they hold roles, and every permission an account exercises arrives through one of its roles.

This indirection is what keeps administration tractable: when a new permission is needed by everyone in trading, it is added to the Trading role once rather than to every trader's account, and an account's capabilities can be read at a glance from its role list.

Open the Roles window from the Administration submenu of the System menu to see the bundles:

The chapter set out to show that managing accounts well follows from understanding the population you administer, the individual record, the flow that creates one, and the model that governs them all in turn, and it has traced exactly that path. The Accounts window presented every account your login identity may see — the platform administrator sees the system tenant's service machinery, a tenant administrator only their own tenant — and the detail dialog then managed a single account's credentials, roles, parties, and provenance across its six tabs. Creating an account proved to be the same dialog in create mode, with the party warning (and the silent role gap noted above) to watch for. Underneath it all, the RBAC model tied identity to capability: accounts are identities, permissions are atomic capabilities, and roles are the named bundles that bridge them — service roles for OreStudio's own components, domain roles for the desks and functions of a financial institution. The next chapter completes the administration picture with the tenants those accounts live in.

• Initial Setup — the tenant and party model, the provisioning wizards that create the first accounts, and party selection at login.
• Tenants — managing the tenants that accounts belong to.
• Reference Data — the provenance and change-reason conventions shared by all entity windows.
• Role-Based Access Control — the general RBAC model behind OreStudio's roles and permissions.

The chapter advances the argument that administering a tenant well means first understanding the organisational model it anchors, then the taxonomy that fixes its operational posture, and finally the interface that governs its lifecycle — and it proceeds in that order. It begins by establishing that model in The multi-tenant, multi-party model, which sets out tenant isolation and the party hierarchy of the house and its counterparties; this is the premise the rest of the chapter builds on. From there it turns to Tenant types, the four-way taxonomy that distinguishes the system, production, evaluation, and automation tenants by the controls each carries. It then surveys the body of records in The Tenants window, explaining the list view and its lifecycle status badges, before narrowing to a single record in The tenant detail dialog and its General and Provenance tabs, where an administrator moves a tenant through its lifecycle under the same audit regime as every other entity. This chapter picks up once tenants and parties exist; the Initial Setup chapter walks through the wizards that create them. The Conclusion draws these steps together.

A tenant's isolation extends to everything it contains: its own users, its own reference data (currencies, counterparties, books), and its own analytics results. Data belonging to one tenant is completely invisible to another tenant; there is no cross-tenant data leakage by design.

A typical deployment has one tenant per organisation. If you are running ORE Studio for your own firm, you will create one tenant representing your organisation. A managed-service provider running ORE Studio on behalf of multiple clients might create one tenant per client.

The system tenant is special — it is created automatically during system provisioning and cannot be deleted. It is the home of the platform administrator accounts. There is exactly one system tenant per deployment. All other tenants are created by platform administrators working from the system tenant.

Tenants come in several types with different operational controls; the next section covers the taxonomy.

ORE Studio supports four tenant types, each with different operational controls:

• System — platform administration; one per deployment; platform-managed.
• Production — real customer organisations with live data; strict controls.
• Evaluation — demos, UAT, training, and exploratory testing; relaxed controls.
• Automation — programmatic test infrastructure; not for human use; no controls.

The system tenant is created automatically during system provisioning and cannot be deleted. It is the home of the platform administrator accounts; all other tenants are created by platform administrators working from it.

Production tenants are for live operations. They enforce strict controls including four-eyes authorisation for sensitive operations and KYC-gated counterparty onboarding.

Evaluation tenants provide a realistic but relaxed environment for demonstrations, user acceptance testing, and training. Bulk data import from external sources (such as the GLEIF/LEI registry) is available in evaluation tenants but not in production tenants.

Automation tenants exist for programmatic test infrastructure. They carry no operational controls and are not intended for human use.

Open the Tenants window from the Administration submenu of the System menu.

Each tenant carries:

• Code — the stable identifier (system, barclays_plc).
• Name — the human-readable display name.
• Type — one of the four tenant types described above; system for the root tenant, here evaluation for the business tenant.
• Hostname — the hostname the tenant's users connect through, which is how OreStudio routes a login to its tenant.
• Status — the lifecycle state, shown as a badge: bootstrapping while a newly created tenant awaits its provisioning wizard run, active once it is in service, with suspended and terminated closing out the lifecycle.

The toolbar extends the standard entity-window actions with Onboard — which creates a tenant and walks it through provisioning — and Reset, which returns a tenant to its post-provisioning state.

Double-click a tenant (or select it and press Edit) to open the detail dialog.

The General tab carries the fields described above; the status combo is how an administrator moves a tenant through its lifecycle. The second tab holds the record's provenance:

Tenant records are versioned with full provenance like every other entity — see the Provenance section of the Reference Data chapter. The History toolbar action shows a tenant's full version history.

The chapter set out to show that administering a tenant well follows from understanding its organisational model, its type taxonomy, and its interface in turn, and it has traced exactly that path. The multi-tenant, multi-party model supplied the foundation — the tenant as the unit of isolation and the party hierarchy within it, the house and its counterparties, with visibility following the hierarchy. Building on that, the four tenant types fixed the operational posture of each tenant, ranging from the strictly controlled production tenant to the uncontrolled automation tenant. The Tenants window then took the record from the list view, where lifecycle status reads at a glance from the badges, down to the detail dialog, where an administrator edits a tenant's identity and moves it through its lifecycle under the same provenance regime as every other entity. With connection, provisioning, and administration now covered, the manual turns from the system itself to the data it manages: reference data.

• Initial Setup — the tenant model and the provisioning wizards.
• Accounts and Roles — the accounts that live inside each tenant.

The chapter advances the argument that managing reference data well depends first on knowing what it is, and then on the quality framework that governs how it changes — and it proceeds in that order. It begins by establishing the category itself in What is Reference Data?, setting reference data apart from market data and trades and surveying the entity types OreStudio manages; this is the premise the rest of the chapter builds on. From there it turns to Data Quality, the heart of the chapter, which opens with the six industry-standard DQ dimensions and then examines the mechanisms that realise them: bitemporality and its two independent time dimensions, versioning and immutable history, provenance tracking who changed what and why, and the structured change reasons that make every modification an auditable event. The Conclusion draws these foundations together and points to the entity chapters that build on them.

Reference data is the static or slowly-changing master data that all financial activity depends on. It defines the vocabulary of the system — the currencies a trade is denominated in, the counterparty on the other side of a deal, the book it settles into, the country a legal entity is incorporated in. Without it, nothing else can be described precisely.

OreStudio's reference data covers a wide range of entity types:

• Currencies — ISO 4217 codes, display formatting, and rounding rules.
• Countries — ISO 3166 alpha-2 codes and names.
• Trading conventions and calendars — holiday calendars, settlement day rules, date rolling conventions, and tenor definitions that drive date arithmetic in trade processing and valuation.
• Counterparties — the external legal entities your organisation trades with.
• Books — the internal trading books that own positions.
• Business units and portfolios — the organisational structure within a party.
• Party types and statuses — the classification vocabulary for parties.
• Classifications — supplementary taxonomies such as currency market tiers and monetary natures.

Reference data is distinct from the other two main categories of data in the system:

• Market data — prices, FX rates, yield curves, and volatility surfaces that update continuously throughout the trading day. Market data is time-stamped and immutable once recorded; a new observation does not overwrite an old one.
• Trades — specific financial transactions between parties with defined cashflows, valuation models, and lifecycle states. Trades reference the reference data (they need a currency, a counterparty, a book) but they are not reference data themselves.

The key property of reference data is that it changes slowly and deliberately. A currency's rounding convention is not something that shifts intraday — it is corrected through a controlled, audited process. OreStudio enforces this with a comprehensive data quality framework described in this chapter.

GLEIF and the Legal Entity Identifier (the LEI standard, and how OreStudio uses it to seed parties and counterparties from real organisational data) is covered in the Parties chapter rather than here — legal-entity identification is a property of the parties and counterparties themselves, not of reference data generally.

Financial calculations are only as reliable as the data they consume. A misspelled currency name is a cosmetic nuisance; an incorrect rounding rule, a wrong counterparty identifier, or a stale market tier classification can silently propagate into risk figures, margin calls, collateral calculations, and regulatory reports. The consequences range from minor reconciliation breaks to significant financial loss or regulatory censure.

OreStudio's reference data layer is designed around the definition of data quality from ISO 8000 and the DAMA Data Management Body of Knowledge (DAMA-DMBOK): data quality is the measure of how well a dataset satisfies the requirements of its intended business use. In financial markets this means data must be not only accurate but also complete, consistent, timely, valid, and unique — the six industry-standard DQ dimensions described below.

The chapter set out to show that managing reference data well follows from understanding what it is and the framework that governs how it changes, and it has traced exactly that path. Reference data is the slowly-changing vocabulary of the system, distinct from streaming market data and transactional trades, and OreStudio governs it with the six industry-standard data quality dimensions. Building on that definition, the bitemporal storage model gives every record an immutable version history; provenance records who changed what, when, through which service, and why; and the structured change reason system turns every modification into an auditable event. These mechanisms are not specific to any one entity — they appear identically in every entity window. The chapters that follow, starting with currencies, document each entity on top of this shared foundation.

• ISO 8000 — international standard for data quality.
• DAMA-DMBOK — data management body of knowledge, including the DQ-6 framework.
• Temporal database — background on transaction time, valid time, and the bitemporal model.
• Time and Timestamps: Architecture and Conventions — internal architecture document (doc/knowledge/architecture/time-architecture.org).
• BCBS 239 — Basel Committee principles for effective risk data aggregation and reporting.
• GLEIF — the Global Legal Entity Identifier Foundation; publishes the LEI registry and the LEI-to-BIC mapping dataset.

The chapter advances the argument that managing a currency well means understanding what a currency actually is, its identity, the extensions that make it usable, the interface that governs its lifecycle, and the programmatic equivalents — and it proceeds in that order. It begins with the conceptual foundation in Money, currency, and cash, distinguishing three terms routinely conflated in casual usage; this framing is what makes the rest of the chapter's choices legible, not just a list of fields. It then turns to a currency's own birth-to-retirement Currency lifecycle, background the chapter draws on without OreStudio exposing it as a field. From there it establishes identity in ISO 4217 and its limitations, which sets out the codes that name a currency and the gaps that motivate ORE Studio's extensions. It then surveys the body of records in The Currencies window before narrowing to a single record in Currency Details and its General, Formatting, Rounding, and Provenance tabs. It then turns to changing a record under audit — Editing and Currency history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. It then documents the auxiliary classification tables — rounding types, market tiers, and monetary natures — whose values a currency references, and finally shows the same operations automated from the shell and the CLI. The Conclusion draws these steps together.

Money, currency, and cash are used almost interchangeably in everyday speech, yet they name three distinct, if related, concepts, each nested within the one before it. Disentangling them clarifies what ORE Studio's Currency record is actually modelling, and, just as importantly, what it deliberately is not.

Money is the broadest of the three terms: any item or verifiable record generally accepted as payment for goods and services, or as repayment of debts, within a particular society. It is best understood not as a physical thing but as a social convention, one that functions precisely because a sufficiently large group of people believes it functions, and which ceases to function the moment that belief collapses. What qualifies as money is best captured by what it does rather than what it is: it serves as a medium of exchange, offering an efficient alternative to barter; as a unit of account, letting value be expressed numerically and compared across otherwise incommensurable goods; as a store of value, preserving purchasing power across time; and as a standard of deferred payment, so that an amount agreed today retains roughly the same value when it falls due in the future. Anything fulfilling these functions counts as money, which is why money has, historically, taken several distinct forms. Commodity money derives its value from the scarcity and physical usefulness of the substance embodying it, gold and silver being the paradigm cases. Fiat money, by contrast, carries no intrinsic value of its own; it is money purely because a government or a mutual agreement between parties declares it so. Bank money is more abstract still, consisting entirely of records: it is created the moment a bank extends a loan by crediting the borrower's deposit account, and destroyed the moment that loan is repaid. Despite the popular association of "money" with notes and coins, bank money constitutes the overwhelming majority of the money supply in any modern economy, physical cash typically accounting for a small single-digit percentage of the total. Cryptocurrencies form a fourth, more recent and non-standard category: digital assets used as a medium of exchange, with ownership recorded cryptographically and, typically, no central issuing authority standing behind them.

Currency narrows money down to a system of money in common use within a defined area of circulation, usually a country or a group of countries sharing a monetary union. Two meanings coexist in ordinary usage, the physical representation of banknotes and coins on one hand, and the abstract system of money itself on the other, the latter being the more useful framing for a system such as ORE Studio, given how small a fraction of any modern money supply physical cash actually represents. Being standardised by ISO 4217 is not a precondition for counting as a currency in this conceptual sense; standardisation is better understood as a seal of approval than as a definition. The currencies of smaller nations not covered by the standard, and cryptocurrencies, which rely on informal, community-driven symbols such as BTC or XBT for Bitcoin rather than an assigned ISO code, are no less currencies for lacking one. A currency also has a lifecycle of its own, distinct from the lifecycle of any individual note or coin — see Currency lifecycle below.

Cash narrows the concept furthest of the three. It is money in the physical form of banknotes and coins, or, in the bookkeeping sense more relevant to a system like ORE Studio, the broader class of current assets comprising currency or currency-equivalents that can be accessed immediately or near-immediately. A bank deposit falls under this broader definition: it is a financial asset rather than physical currency, yet liquid enough to count as cash for most practical purposes. The relationship between the three terms can be summarised as a chain of increasingly narrow specialisation: not all money is a currency in the systemic sense, since commodity money and cryptocurrencies stretch the definition in different directions; and not all currency holdings are cash, since a currency can equally be held in a comparatively illiquid financial-asset form.

ORE Studio's Currency reference-data record, the subject of the remainder of this chapter, models currency in precisely this narrower, systemic sense: a named, identified system of money, equipped with the extensions described in the next section that let ORE Studio put it to practical use in calculations. The chapter does not attempt to model money in the abstract, nor the accounting concept of cash; those notions are drawn upon, where relevant, by the trading and booking chapters that build upon the currency reference data documented here.

A currency is born when created and put into circulation, lives while in general use, and dies when eventually withdrawn — whether replaced by a successor currency, absorbed into a monetary union, or simply discontinued — though records of transactions conducted during its life must still be retained long after that withdrawal. This is background the rest of the chapter builds on, not a field OreStudio exposes directly: unlike a book, a currency record carries no status column of its own; a withdrawn currency simply stops being referenced in new records; its history remains intact under the same bitemporal audit trail as any other change.

The same birth-life-death shape recurs at three nested levels: the currency itself, its individual denominations (a given note or coin value can be introduced or discontinued independently of the currency surviving), and individual physical instances. Recognising the pattern as fractal is what keeps "currency lifecycle" from being mistaken for a single, currency-wide, all-or-nothing event.

Redenominations, currency replacements, and monetary unions forming or dissolving occur more often than a system designer might expect, and rarely afford the luxury of careful advance planning; a system not built to anticipate such events — positions, reference data, and historical records all still keyed to a code that has just been withdrawn or redefined — can find itself significantly disrupted when one eventually occurs.

The international standard for currency codes is ISO 4217. It defines a three-letter alphabetic code (USD, EUR, GBP), a three-digit numeric code (840, 978, 826), a currency name, and the number of decimal places — for example, USD has 2 minor units, meaning amounts are expressed to the nearest cent.

ISO 4217 is widely adopted and ORE Studio uses it as its primary identifier. However, the standard has gaps that matter in practice:

• It does not classify currencies by market tier — the distinction between major G10 currencies and emerging-market currencies is economically important but absent from the standard.
• It does not cover digital assets. Cryptocurrencies such as Bitcoin or Ethereum are increasingly relevant in financial systems but have no ISO 4217 code.
• It says nothing about display formatting — whether a symbol precedes or follows the amount, what the thousands and decimal separators are, or how the fractional unit is labelled.
• It does not specify rounding conventions — whether a calculation result should be rounded up, down, or to the nearest unit.

ORE Studio extends the ISO 4217 model with additional fields to cover these gaps: monetary nature, market tier, currency symbol, fraction symbol, a printf-style format string, and configurable rounding rules. The standard fields remain primary; the extensions are supplementary.

With the underlying model in place, both the standard fields ISO 4217 provides and the extensions layered on top of them, the rest of the chapter turns from what a currency record contains to where you go to work with one. That begins, as it does for any list-backed entity in ORE Studio, with the window listing every currency the tenant holds.

Open the Currencies window from the Reference Data menu. It lists all currencies defined in the tenant, with one row per currency.

The toolbar buttons reload the list and adjust the display. The list is paginated; use the page controls at the bottom right to navigate. Double-clicking a row opens the Currency Details dialog.

The Currency Details dialog has four tabs: General, Formatting, Rounding, and Provenance. The three action buttons at the bottom — Delete, Close, and Save — apply to the currency as a whole.

To edit a currency, open it in the Currency Details dialog, make your changes, and click Save. Before the record is written, ORE Studio prompts for a change reason.

Select a Reason from the drop-down and add optional Commentary. Click Save to confirm. Every save creates a new version; the previous version is never overwritten.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain.

The three tables described in this section act as classification vocabularies for currencies. In a standard deployment their values are fixed at provisioning time and rarely change; ORE Studio still versions and audits them the same way as any other reference data. They are managed by the system tenant and are accessible from the Reference Data → Currencies sub-menu.

The ORE Studio interactive shell provides quick currency access without opening the Qt UI:

# List all currencies (paginated)
currencies get

# Add a new currency:
#   <iso_code> <name> <numeric_code> <symbol> <fractions_per_unit>
#   <change_reason_code> <change_commentary>
currencies add XTS "Test Currency" 963 T$ 100 system.test "manual example"

# Delete a currency by ISO code
currencies delete XTS

# Show history for a currency
currencies history USD

The ores.cli command-line tool provides a richer interface for automation. All currency commands live under ores.cli refdata currencies:

# List all currencies as a table
ores.cli refdata currencies list --tenant "$ORES_TENANT" --format table

# List a specific currency as JSON
ores.cli refdata currencies list --tenant "$ORES_TENANT" --format json --key EUR

# Add a new currency
ores.cli refdata currencies add \
  --tenant "$ORES_TENANT" \
  --iso-code XTS --name "Test Currency" \
  --numeric-code 963 --modified-by operator \
  --currency-type fiat

# Delete a currency by ISO code
ores.cli refdata currencies delete --tenant "$ORES_TENANT" --iso-code XTS

# Export all currencies to a file
ores.cli refdata currencies export --tenant "$ORES_TENANT" --output currencies.json

The chapter set out to show that managing a currency well follows from understanding its identity, the extensions that make it usable, its interface, and its programmatic equivalents in turn, and it has traced exactly that path. Its own birth-to-retirement lifecycle set the background the rest of the chapter operates against. ISO 4217 supplies the standard identity — code, numeric code, name, and minor units — while ORE Studio's extensions cover what the standard leaves out: market tiers, monetary natures for digital assets, display formatting, and rounding conventions. Building on that, the Qt interface took the record from the list view down to a single detail dialog and through the editing and history workflows, where reverting to an earlier version demonstrated the bitemporal audit trail keeping the full record intact. The three auxiliary classification tables then fixed the vocabulary a currency may reference, and the shell and CLI reproduced the same operations for scripted use. Currencies are the template: subsequent entity chapters follow this same progression.

• Currency Lifecycle — the domain-knowledge note this chapter's Currency lifecycle section is drawn from.
• ISO 4217 Currency Codes — the international standard for currency identification.
• SIX Financial Information — the ISO 4217 maintenance agency.
• MSCI Market Classification — framework for developed, emerging, and frontier market designations.

The chapter follows the same progression as the previous one, adapted to a case where two closely related entities, rather than one, share the stage. It opens with the domain foundation in Currency pairs and market conventions, distinguishing what a pair is from the market conventions layered on top of it, and setting out the classification scheme, the base/quote precedence rule, and the pip and tick mechanics that later sections draw on. It then turns to the first entity, walking from The Currency Pairs window through Currency Pair Details, editing, and history, in the same pattern the Currencies chapter established. It then does the same for the second entity in Currency Pair Conventions, and closes by explaining how the two windows are cross-navigable from one another. The Conclusion draws the pair of entities back together.

A currency pair names an exchange rate relationship between two currencies rather than a currency itself: it answers the question of how many units of one currency, the quote currency, are needed to buy one unit of the other, the base currency. Market convention writes this as CCY1/CCY2, base over quote, and, crucially, treats the two directions as the same market rather than as independent instruments: EUR/USD and USD/EUR are not two pairs but one pair quoted two ways, and a well-behaved system permits only one canonical direction to exist as a record. Which currency of the two takes the base position is itself conventional rather than arbitrary, governed by a fixed precedence order with the euro at its head, followed by sterling, the Australian and New Zealand dollars, the US dollar, and then the remaining currencies — so market participants write EUR/USD, never USD/EUR, even though both describe the same underlying rate.

Currency pairs are not a homogeneous population; the market classifies them by liquidity and tradability, a taxonomy independent of the mere fact that both legs are valid ISO 4217 currencies. A major pairs the US dollar with one of the six other currencies with the deepest global markets — the euro, sterling, the yen, the Swiss franc, and the Australian, Canadian, and New Zealand dollars — and carries the tightest spreads and the most continuous liquidity of any pair in the market. A minor, sometimes called a cross, pairs two of those major non-dollar currencies against one another with no dollar leg at all, a pair such as EUR/GBP or GBP/JPY; because the dollar is absent, such a rate is frequently derived by triangulating through it rather than quoted directly. An exotic pairs a major currency against the currency of a smaller or developing economy, carrying markedly wider spreads, thinner liquidity, and greater sensitivity to domestic political and economic events. A further distinct classification exists alongside this one for commodity-backed instruments, where one leg is not a sovereign currency at all but a precious metal such as gold or silver traded under currency-like conventions; ORE Studio labels this fourth case commodity. It is worth noting explicitly that classification and raw trading volume diverge in at least one well-known respect: the Scandinavian currencies, the Danish krone, the Norwegian krone, and the Swedish krona, trade in somewhat lower volume than the seven majors and are sometimes loosely called exotic on that basis, yet institutionally they belong to the same deep-liquidity tier as the majors and should be classified as minors, not exotics, when paired with the dollar.

Once a pair's identity and classification are settled, a further set of market conventions governs how its rate is actually quoted and handled operationally, and these live on a separate record from the pair itself. A pip is the standard unit of rate movement for a pair, and its size is not universal: most pairs quote to four decimal places, so that a single pip equals 0.0001 of the rate, while pairs with a yen leg quote to only two decimal places, making a pip equal to 0.01. The pip factor is this decimal scaling made explicit and storable, the multiplier that converts a count of pips into an absolute rate move, and getting it wrong does not produce a merely inaccurate result but one whose sign and order of magnitude are both wrong, since it governs how forward points are added to or subtracted from a spot rate. Layered on top of the pip convention is the tick size, the smallest increment by which a quoted rate is actually permitted to move, stated in units of pips and capable of varying by pair, by trading venue, and by instrument; a pip defines the denomination, a tick defines the smallest coin in that denomination actually in circulation. Finally, settlement timing follows its own convention: an FX rate, notwithstanding the informal name spot rate, is very rarely a rate for immediate delivery but rather a forward rate for the earliest date on which funds can actually settle, arrived at by advancing from today by the number of business days each currency's home market needs to clear a payment, one day for the US dollar and typically two for most other currencies, with the pair as a whole taking the longer of its two legs' requirements — which is why most pairs are conventionally said to settle two business days after the trade date.

A word of scope is due before moving on. Real FX markets also distinguish pairs by deliverability — whether a trade in that pair settles through physical delivery of both currencies or, for currencies subject to capital controls, is instead settled in cash in a third currency against a published fixing, the non-deliverable forward arrangement. ORE Studio explored modelling this distinction directly on the currency pair record and withdrew it again during this development cycle: a single flag proved unable to express the reality that some pairs support more than one settlement arrangement, sometimes depending on the trading centre involved, and a proper treatment needs its own structure rather than a field bolted onto the pair. Deliverability and non-deliverable settlement are, at the time of writing, not represented anywhere in ORE Studio's reference data and are not described further in this chapter.

With the domain foundation in place, the base/quote relationship and its precedence rule, the classification taxonomy, and the pip, tick, and settlement-timing conventions that will recur throughout the entity descriptions below, the chapter turns from what these concepts mean to where a user goes to work with the records that carry them.

Open the Currency Pairs window from the Reference Data menu. It lists all currency pairs defined in the tenant, with one row per pair.

Each row shows the pair code (with the base and quote currencies' flag icons composited into the same cell), the base and quote currency codes individually, the classification badge, the version number, the identity of the last modifier, and when the record was last recorded. The toolbar buttons reload the list and adjust the display; a further Conventions button, described in Currency Pair Conventions below, cross-navigates to the companion window. The list is paginated; use the page controls at the bottom right to navigate. Double-clicking a row opens the Currency Pair Details dialog.

The dialog carries a compact set of fields. Pair Code is not typed directly; it is computed live from the Base Currency and Quote Currency combos while the record is still being created, and the field itself remains read-only throughout. Base Currency and Quote Currency are flagged combo boxes, each showing the relevant currency's flag alongside its ISO code, populated from the currencies already on file. Classification is a combo offering the four values described above — major, minor, exotic, and commodity.

Once a pair has been saved for the first time, its Base Currency and Quote Currency combos lock: the values remain visible, flags and all, but can no longer be changed, and Pair Code is therefore permanently fixed from the moment of creation onward. This reflects the domain reality that a currency pair's identity is its two legs; changing either leg would not modify the pair but create a different one under a different natural key.

Two checks run at creation time, both driven by the base-currency- precedence rule described in Currency pairs and market conventions. Attempting to create a pair whose code already exists is rejected outright, since that would silently create a new version of the existing record rather than a genuinely new one. Attempting to create the inverse of a pair that already exists — for example, adding USD/EUR when EUR/USD is already on file — is rejected for the same underlying reason: the two directions describe one market, not two, and only the canonically ordered direction may exist as a record.

The three action buttons at the bottom, Delete, Close, and Save, apply to the pair as a whole. The dialog also has a Provenance tab, read-only, showing the audit metadata for the current version; see the Reference Data — Provenance section for a full description of the fields common to all reference data entities.

To edit a currency pair, open it in the Currency Pair Details dialog, change its Classification — the only field still open to editing once Base Currency and Quote Currency have locked — and click Save. As with every reference-data entity, ORE Studio prompts for a change reason before the record is written; select a Reason from the drop-down, add optional Commentary, and click Save to confirm. Every save creates a new version rather than overwriting the previous one.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History. Select a version to populate the detail panel; the Changes tab shows which fields differ between the selected version and its predecessor, and the Revert button reinstates any historical version as a new version, preserving the full audit chain. The mechanics are identical to currency history, described in full in the previous chapter's Currency history section.

Where the currency pair record establishes identity, base, quote, and classification, a second, separate record establishes the market conventions that govern how a pair's rate is quoted, rounded, and dated: pip factor, tick size, decimal places, the advancing calendar, the business day convention, and two boolean flags governing forward-date generation. The two records stand in a strict one-to-one relationship, keyed by the same pair code, and are kept as distinct entities rather than merged into one for the same reason the Currencies chapter kept Rounding Types and Market Tiers separate from the Currency record itself: identity and convention change at different rates and for different reasons, and separating them keeps each record's audit history meaningful on its own terms.

Open the Currency Pair Conventions window from the Reference Data menu, or from the Conventions toolbar button on the Currency Pairs window described above.

Each row shows the pair code with its composited flag icons, pip factor, tick size, decimal places, advance calendar, business day convention badge, and the spot-relative and end-of-month flags rendered as Yes/No labels, followed by the usual version and provenance columns. Double-clicking a row opens the Currency Pair Convention Details dialog.

Pair Code is a flagged combo, but unlike the Currency Pair Details dialog it does not derive its value from two separate legs; instead it lets the user pick directly from the pairs already on file, and, as with Base and Quote Currency above, is selectable only while creating the record and locks, still showing its flags, once saved. Attempting to create a second convention record for a pair code that already has one is rejected, on the same reasoning as the duplicate- pair check on the identity entity: a pair has at most one convention record, and the correct action is to edit the existing one rather than create a second.

The remaining fields follow directly from the domain concepts set out earlier in the chapter. Pip Factor and Tick Size express the pip and tick mechanics described in Currency pairs and market conventions; a typical non-yen pair carries a pip factor of 0.0001, a yen cross 0.01. Decimal Places fixes how many digits the rate displays, consistent with the same pip convention — four for most pairs, two for yen crosses. Advance Calendar names the calendar used when advancing from the spot date to a forward date. Business Day Convention selects among the standard date-rolling rules — Following, Modified Following, Preceding, Modified Preceding, Unadjusted, Half-Month Modified Following, and Nearest — that determine how a date falling on a holiday is adjusted onto a business day. Spot Relative indicates whether forward dates for this pair are generated relative to the spot date rather than the trade date, and End Of Month indicates whether the end-of-month date-rolling convention applies.

Editing follows the same pattern as every other reference-data entity in ORE Studio: open the record, change any field still open to editing once Pair Code has locked, and click Save. A change reason is required before the save is written, exactly as for currency pairs above.

History and revert work identically to currency pair history: open the history icon or right-click and choose History, select a version, review the Changes tab, and use Revert to reinstate an earlier version as a new one.

The chapter set out to treat the currency pair as a relational entity distinct from, but built upon, the currencies documented in the previous chapter, and to separate that identity from the market conventions layered on top of it. The base-currency-precedence rule fixed how a pair's two legs are ordered and why only one of the two possible directions may ever be recorded; the major/minor/exotic/ commodity taxonomy classified the population of pairs by liquidity and tradability, independent of the raw fact that both legs are valid currencies; and the pip, tick, and settlement-timing conventions supplied the vocabulary the second entity's fields draw upon. The Qt interface then walked both entities from list to detail to history, in the pattern the previous chapter established, and showed how the two windows cross-navigate via the Conventions toolbar button. Unlike currencies, currency pairs and their conventions do not yet have shell or command-line equivalents; that gap is tracked as future work rather than glossed over here.

• Currency pairs — the domain-knowledge hub this chapter draws on.
• Currencies — the previous chapter, covering the individual currency legs a pair is built from.
• Currency Pair (Investopedia) — an accessible introduction to currency pair quoting conventions.

The chapter advances the argument that managing a country well means first understanding what identifies it, then the interface that governs its lifecycle, and finally the programmatic equivalents — and it proceeds in that order. It begins by establishing the identity of a country in ISO 3166-1 and its limitations, which sets out the codes that name a country and the gaps in the standard that motivate OreStudio's extensions; this is the premise the rest of the chapter builds on. From there it surveys the body of records in The Countries window, explaining the list view, paging, and reloading, before narrowing to a single record in Country Details and its General and Provenance tabs. It then turns to changing a record under audit — Editing, Deleting, and Country history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. Finally it shows the same operations automated from the shell and the CLI, and the Conclusion draws these steps together.

The international standard for country codes is ISO 3166-1. It defines three parallel codes for each country plus a short name:

• a two-letter alphabetic code, alpha-2 (US, GB, FR) — the most widely used form, and OreStudio's primary identifier;
• a three-letter alphabetic code, alpha-3 (USA, GBR, FRA), which is more mnemonic and collision-resistant;
• a three-digit numeric code (840, 826, 250), drawn from the UN M49 series and language-independent;
• the country's short name (e.g. United States).

ISO 3166-1 is near-universal, but it has gaps that matter in practice:

• It carries only a short name. The full official name (United States of America, French Republic) — needed for legal documents and reports — is not part of the standard.
• The country set is political and changes over time. Codes are added, withdrawn, and occasionally reassigned: a code freed by one country can later be given to another, so a bare code is not a stable historical key. ISO publishes transitional reservations, but consumers must still track the changes.
• It conflates countries with territories and dependencies and takes no position consistent with every user's expectations on contested or partially-recognised entities.
• It says nothing about visual identity — there is no flag or emblem in the standard.
• It does not model subdivisions (states, provinces); those are a separate standard, ISO 3166-2.
• A block of codes (XA to XZ) is reserved for private use, useful for fictional or internal entities that must not collide with real codes.

OreStudio uses the ISO 3166-1 fields as primary and extends the model with an official name and an optional flag image. The standard fields remain authoritative; the extensions are supplementary.

Open the Countries window from the Reference Data menu. It lists all countries defined in the tenant, one row per country, each row carrying the flag, alpha-2 and alpha-3 codes, numeric code, name, official name, version, last modifier, and when the record was last recorded.

The list is paginated; use the page controls at the bottom right to navigate the full set of countries. The toolbar buttons reload the list and open the add, edit, delete, and history actions.

Double-clicking a row opens the Country Details dialog.

The Country Details dialog has two tabs — General and Provenance — and an Icon group for the flag. The three action buttons at the bottom — Delete, Close, and Save — apply to the country as a whole.

To edit a country, open it in the Country Details dialog, make your changes, and click Save. Before the record is written, OreStudio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a country, open it and click Delete. OreStudio asks for confirmation before the record is closed off.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten.

The revert opens the chosen version's values in an editable detail dialog; saving (with a change reason) writes them as the new current version.

The ORE Studio interactive shell provides quick country access without opening the Qt UI:

# List all countries (paginated)
countries get

# Add a new country:
#   <alpha2> <alpha3> <numeric> <name> <official_name>
#   <change_reason_code> <change_commentary>
countries add XX XXX 999 "Test Country" "Test Country Official" system.new_record "manual example"

# Delete a country by alpha-2 code
countries delete XX

# Show history for a country
countries history GB

The ores.cli command-line tool provides a richer interface for automation. All country commands live under ores.cli refdata countries:

# List all countries as a table
ores.cli refdata countries list --tenant "$ORES_TENANT" --format table

# List a specific country as JSON
ores.cli refdata countries list --tenant "$ORES_TENANT" --format json --key US

# Add a new country
ores.cli refdata countries add \
  --tenant "$ORES_TENANT" \
  --alpha2-code XX --alpha3-code XXX --numeric-code 999 \
  --name "Test Country" --official-name "The Republic of Test Country" \
  --modified-by super_admin --change-reason-code system.new_record

# Delete a country by alpha-2 code
ores.cli refdata countries delete --tenant "$ORES_TENANT" --alpha2-code XX

The chapter set out to show that managing a country well follows from understanding its identity, its interface, and its programmatic equivalents in turn, and it has traced exactly that path. ISO 3166-1 supplies the identity — alpha-2, alpha-3, and numeric codes with a short name — while OreStudio's extensions add the official name and the flag, filling the gaps the standard leaves. Building on that, the Qt interface took the record from the list view down to a single detail dialog and through the editing, deletion, and history workflows, where reverting to an earlier version demonstrated the bitemporal audit trail keeping the full record intact rather than overwriting it. The shell and the CLI then reproduced the same operations for scripted use, closing the loop between interactive and automated management. Country is deliberately the same shape as the currency chapter, and the entity chapters that follow adopt the same progression.

• ISO 3166 Country Codes — the international standard for country identification.
• UN M49 Standard Country Codes — the numeric-code series ISO 3166-1 draws on.
• Currencies — the template chapter this one mirrors.

The chapter advances the argument that managing a business centre well means first understanding what it identifies, then the interface that governs its lifecycle. It begins by establishing the identity of a business centre in The FpML business centre scheme, which sets out the 4-character codes that name a business centre and the coding-scheme scoping that governs their uniqueness; this is the premise the rest of the chapter builds on. From there it surveys the body of records in The Business Centres window, explaining the list view, paging, and reloading, before narrowing to a single record in Business Centre Details and its General and Provenance tabs. It then turns to changing a record under audit — Editing, Deleting, and Business centre history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. Finally the Conclusion draws these steps together and names what is deliberately still missing.

A business centre is a 4-character code drawn from the FpML businessCenterScheme coding scheme⁷: either the real geographical location whose calendar governs a bad business day (USNY for New York, GBLO for London), or an FpML-format rate-publication calendar code used for fixing-day offsets. The scheme's own description is precise about the distinction: the geographical codes are "implicitly locatable and used for identifying a bad business day for the purpose of payment and rate calculation day adjustments", while the rate-publication codes "are used in the context of the fixing day offsets" — two different jobs sharing the same 4-character code shape.

Open the Business Centres window from the Reference Data menu. It lists all business centres defined in the tenant, one row per centre, each row carrying the code, source, description, city, coding scheme, country (with its flag), version, last modifier, and when the record was last recorded.

The list is paginated; use the page controls at the bottom right to navigate the full set of business centres. The toolbar buttons reload the list and open the add, edit, delete, and history actions.

Double-clicking a row opens the Business Centre Details dialog.

The Business Centre Details dialog has two tabs — General and Provenance. The three action buttons at the bottom — Delete, Close, and Save — apply to the business centre as a whole.

To edit a business centre, open it in the Business Centre Details dialog, make your changes, and click Save. Before the record is written, ORE Studio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a business centre, open it and click Delete. ORE Studio asks for confirmation before the record is closed off.

Deletion is a soft close — the record's history is preserved and remains visible in the History dialog.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten. Reverting a business centre follows exactly the same confirm-then-save-with-a-reason flow described for Countries; it is not repeated here.

The chapter set out to show that managing a business centre well follows from understanding what it identifies before turning to its interface, and it has traced exactly that path. The FpML businessCenterScheme supplies the identity — a 4-character code naming either a real geographical calendar location or a rate-publication calendar, scoped to a coding scheme but unique per tenant regardless of which scheme it came from — while ORE Studio's own country link adds a purely cosmetic flag icon on top. Building on that, the Qt interface took the record from the list view down to a single detail dialog and through the editing, deletion, and history workflows, where reverting to an earlier version demonstrated the same bitemporal audit trail already familiar from the Currencies and Countries chapters. Business centre does not yet have shell or command-line equivalents, nor Wt web UI or HTTP REST API support; those gaps are tracked as backlog work rather than glossed over here.

• Business Centre — the domain-knowledge hub this chapter draws on.
• Currencies — the template chapter this one mirrors.
• Countries — the country a business centre may optionally link to for its flag icon.
• Books — a book's rates centre is a business centre, referenced by code.

The chapter advances the argument that managing a portfolio well means first understanding what it represents relative to the book it sits alongside, then the interface that governs it. It begins by establishing Portfolios and books — the core distinction between the two, and the hierarchy portfolios alone carry — before turning to What is a Portfolio? and the fields a portfolio record actually carries. From there it surveys the body of records in The Portfolios window before narrowing to a single record in Portfolio Details and its General and Provenance tabs. It then turns to changing a record under audit — Editing, Deleting, and Portfolio history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. Before concluding, it turns to the lookup entity backing the portfolio's own purpose classification field in Purpose Types. The Conclusion draws these steps together.

A portfolio is a trading concept, not an accounting one: it is an arbitrary hierarchy that traders and desks shape however makes sense for risk management, and it is never reflected into the general ledger. This sets it apart from a book, which must map onto the firm's ledger and is created by Finance rather than by the trading system itself. A useful shorthand for the pair is that books are the physical representation of trading activity and portfolios the logical one — or, borrowing a filesystem analogy, a portfolio is a folder and a book is a file. A portfolio holds books and other portfolios; it never holds deals directly, just as a folder holds files and other folders but is not itself a file.

This split matters because of where hierarchy lives. In the real-world accounting sense a book can have child books through ledger setup, but ORE Studio deliberately does not model that book-to-book hierarchy — the book record has no parent-book field, and there is no plan to add one. Instead, every layer of grouping that the ledger's own structure would otherwise express — a global root grouping, retired branches, sub-groupings by desk or region — is expressed once, through the portfolio tree. A portfolio carries a self-referencing parent, so portfolios can nest inside other portfolios to any depth, and every book links to exactly one portfolio. Duplicating that structure on the book side would add a second tree to keep in sync for no benefit, since the trading system's only job with respect to books is to hold a view of the ledger, not to manage the ledger's own hierarchy.

Desks group books into portfolios for reasons such as instrument type, valuation complexity, trader seniority, or region — a Head of Desk's portfolio, for instance, can be the superset of all their traders' individual portfolios, nested arbitrarily deep. With the relationship between the two entities established, the rest of this chapter turns from that relationship to the portfolio record itself — what fields it carries and the interface that governs it.

A portfolio is a named grouping node within a party's organisational structure, identified by a system-generated id and a human-readable Name — e.g. "Global Rates" or "APAC Credit". Every portfolio belongs to exactly one party, and, per Portfolios and books above, may optionally have a parent portfolio, letting portfolios nest to represent a trading organisation's actual reporting lines. The parent relationship is not yet exposed as an editable field in the Portfolio Details dialog described below — a portfolio's place in the hierarchy is set at creation and read through the record's data rather than edited from a combo box, the same gap the Book chapter's account of owner_unit_id describes for the equivalent business-unit field on a book.

A portfolio carries a purpose type — its classification by intent, chosen from a fixed set of values: Risk (the default, for day-to-day risk-management groupings), Regulatory (portfolios kept for regulatory-reporting purposes), Client Reporting, and Internal. It also carries an optional aggregation currency — the currency P&L and risk figures roll up into at this node — and an optional free-text description. A Virtual flag distinguishes a node that exists purely for on-demand reporting, not persisted into trade attribution, from an ordinary portfolio node; and, like a book, a portfolio carries a status reflecting its position in an operational lifecycle — Active, Inactive, Closed, Frozen, or Pending. Unlike a book's status, whose real-world multi-party opening and closing workflow the Book chapter documents in detail, portfolio status is a simpler field with no equivalent formal workflow documented yet — it is set and changed directly on the record.

With the record's fields established, the rest of this chapter turns from what a portfolio contains to where you go to work with one.

Open the Portfolios window from the Reference Data menu. It lists every portfolio defined in the tenant, with one row per portfolio.

Each row shows the name, purpose type, status (as a colour-coded badge), aggregation currency (with flag icon), the virtual flag (as a colour-coded badge), version number, the identity of the last modifier, and when the record was last recorded. The toolbar buttons reload the list and open the add, edit, delete, and history actions. The list is paginated; use the page controls at the bottom right to navigate. Double-clicking a row opens the Portfolio Details dialog.

The Portfolio Details dialog has two tabs — General and Provenance. The three action buttons at the bottom — Delete, Close, and Save — apply to the portfolio as a whole.

To edit a portfolio, open it in the Portfolio Details dialog, make your changes, and click Save. Before the record is written, OreStudio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a portfolio, open it and click Delete. OreStudio asks for confirmation before the record is closed off. Deletion is a soft close — the record's history is preserved and remains visible in the History dialog.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten.

Where the portfolio record's Purpose Type field (see What is a Portfolio? above) captures a single classification chosen from a combo box, a second, separate window manages the set of values that combo box offers. Purpose types are reference data in their own right — a system-tenant-managed lookup entity, seeded on provisioning with four values (Risk, Regulatory, Client Reporting, Internal) but editable and extensible like any other reference-data record — kept as a distinct entity for the same reason the Currency Pairs chapter kept Currency Pair Conventions separate from the Currency Pair record itself: the set of valid classifications changes at a different rate, and for different reasons, than any individual portfolio that references one.

Open the Purpose Types window from the Reference Data menu.

Each row shows the code, name, description, display order, version, and the usual provenance columns. Double-clicking a row opens the Purpose Type Details dialog.

Code is the purpose type's unique identifier and, like a currency's ISO code, locks once the record is created. Name is the human-readable label shown in the Portfolio Details' Purpose Type combo. Description is free-text, explaining what the classification means in practice — the four seeded values' descriptions are the source for the meanings given in What is a Portfolio? above. Display Order is an integer controlling the combo box's ordering, lowest first — shown in the list window's Display Order column; the Details dialog does not yet expose it (tracked in Audit and standardize the display_order field across lookup/code-table entities).

Editing, deleting, and history follow the same pattern as every other reference-data entity in ORE Studio and are not repeated here in full: open the record, change a field, and Save, confirming a change reason as described for currencies in the Currencies chapter; deletion is a soft close preserving history; and the history icon opens the same Compare/Revert workflow described in Portfolio history above. Purpose types have no shell or command-line access — a gap shared by every reference-data entity in ORE Studio, not specific to purpose types, and tracked separately as part of ongoing commissioning work.

The chapter set out to show that managing a portfolio well follows from understanding what it represents relative to a book and the interface that governs its lifecycle, and it has traced exactly that path. A portfolio is the logical grouping node in a party's organisational structure — a folder to a book's file — identified by an id and name, optionally nested under a parent portfolio, and carrying a purpose type, an aggregation currency, a virtual flag, and a status. Building on that, the Qt interface took the record from the list view down to a single detail dialog — its currency picker showing flags, its status and virtual flag shown as badges — and through the editing, deleting, and history workflows, where reverting to an earlier version demonstrated the same bitemporal audit trail described in the Reference Data chapter. The chapter then turned to the purpose type lookup entity backing the portfolio's own classification field — a small reference-data record with the same list/detail/ history interface, kept separate for the same reasons a currency pair convention is kept separate from a currency pair. Shell and command-line access to portfolios and purpose types, and an editable parent-portfolio field in the Details dialog, are not yet implemented; all are tracked separately as part of ongoing commissioning work.

• Reference Data — the shared data quality and audit framework this chapter builds on.
• Currencies — the aggregation currency a portfolio references, and the Change Reason Required dialog.
• Book — the entity a portfolio groups, and the fuller account of a lifecycle workflow's real-world weight.

The chapter advances the argument that managing a book well means first understanding what it represents, then the interface that governs its lifecycle — and it proceeds in that order. It begins by establishing what a book is in What is a Book?, distinguishing a book from the counterparties and portfolios it sits alongside, and by working through the real-world Book lifecycle a book moves through — from its multi-party opening to closure — that the Status field on-screen only partially reflects; this is the premise the rest of the chapter builds on. From there it surveys the body of records in The Books window before narrowing to a single record in Book Details and its General and Provenance tabs. It then turns to changing a record under audit — Editing, Deleting, and Book history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. The Conclusion draws these steps together.

A book is the internal ledger unit that owns positions within a party's trading organisation. Every trade books into exactly one book; a book aggregates the trades it owns for risk, P&L, and reporting purposes. A book is, first and foremost, an accounting concept rather than a purely trading-system one: it must reconcile with the firm's general ledger, and OreStudio's own view of a book is downstream of that ledger rather than the other way round.

Books sit within a party's organisational structure alongside business units and portfolios, and it helps to keep the two apart: a portfolio groups related books for a trading strategy or desk, and can itself be composed of other portfolios; a book is the leaf-level unit that actually carries positions. A useful shorthand is that books are the physical representation and portfolios the logical one — or, borrowing a filesystem analogy, a portfolio is a folder and a book is a file. In the real-world accounting sense a book can have child books through ledger setup, but ORE Studio deliberately does not model that book-to-book hierarchy: a book has no parent-book field. Instead, all hierarchy in ORE Studio is expressed through the portfolio tree — portfolios can nest inside other portfolios, and every book links to exactly one portfolio — so the folder/file split above is also the whole of the tool's hierarchy, not just an analogy for it.

Every book carries a functional currency — the accounting currency its positions are reported in. Trades themselves can happen in whatever currency the deal was struck in, but the ledger needs one settled currency per book to carry balances and P&L in; that currency is designated by the ledger, not chosen freely by the desk. A book also carries a GL account reference, which is simply the general ledger account in the firm's accounting system that this book's activity maps to — the trading system's record of a position only means something once it can be traced back to a specific line in the firm's books of account. Alongside that sits a cost centre, the internal code that activity in this book is charged against for cost allocation and management reporting; a full treatment of how functional currency, GL accounts, and cost centres compose into the wider accounting hierarchy belongs to a future ledger-focused chapter, not this one.

A book also carries a status — its current operational state, such as active, closed, or frozen — chosen from the set of statuses configured for the tenant. See Book lifecycle below for what drives a book between these states.

Perhaps the most consequential classification a book carries is whether it is a trading book or a banking book — a distinction that traces back to the Basel III/IV capital adequacy framework, and specifically to a component of it called FRTB (the Fundamental Review of the Trading Book).

The distinction is about intent, not instrument type: a position held with the intent of benefiting from short-term price movements, market making, or hedging other trading-book positions belongs in the trading book; a position held to maturity or for longer-term investment purposes belongs in the banking book. The same instrument — a bond, a swap — can sit in either book depending on why it is held.

The distinction matters because the two books are subject to entirely different capital regimes. Trading-book positions are capitalised for market risk — the risk that market prices move against an open position — recognising that these positions may be actively traded and revalued daily. Banking-book positions are instead capitalised for credit risk — the risk that a counterparty fails to pay — reflecting that these positions are typically held to term. Getting this classification wrong, or moving positions between the two books opportunistically to reduce capital charges, is precisely what regulators police most closely; switching a position's classification after the fact is heavily restricted for that reason.

A book moves through a much heavier real-world process than a simple open/closed flag suggests: a deliberate opening workflow, a live phase in which deals move and access is periodically reviewed, and a closing process gated on the book being flat. This section walks through that process in its own terms; c.f. the Status field on the General tab below, which is OreStudio's simplified, editable reflection of it.

Open the Books window from the Trading menu. It lists all books defined in the tenant, with one row per book.

The toolbar buttons reload the list and open the add, edit, delete, and history actions. The list is paginated; use the page controls at the bottom right to navigate. Double-clicking a row opens the Book Details dialog.

The Book Details dialog has two tabs — General and Provenance. The three action buttons at the bottom — Delete, Close, and Save — apply to the book as a whole.

To edit a book, open it in the Book Details dialog, make your changes, and click Save. Before the record is written, OreStudio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a book, open it and click Delete. OreStudio asks for confirmation before the record is closed off. Deletion is a soft close — the record's history is preserved and remains visible in the History dialog.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten.

The chapter set out to show that managing a book well follows from understanding what it represents and the interface that governs its lifecycle, and it has traced exactly that path. A book is the leaf-level ledger unit that owns positions, identified within its party by an id and name and carrying a functional currency, a GL mapping, a cost centre, a status, and a trading/non-trading flag. Building on that, the Qt interface took the record from the list view down to a single detail dialog — its currency picker showing flags, its status governed by the book lifecycle — and through the editing, deleting, and history workflows, where reverting to an earlier version demonstrated the same bitemporal audit trail described in the Reference Data chapter. Shell and command-line access to books is not yet implemented; it is tracked separately as part of the shell and CLI commissioning work.

• Reference Data — the shared data quality and audit framework this chapter builds on.
• Currencies — the functional currency a book references, and the Change Reason Required dialog.

The chapter advances the argument that managing a party well means first understanding what it represents and how it fits into the organisation's structure, then the interface that governs its lifecycle. It begins by establishing what a party is in What is a Party?, then shows that a party's type and status are themselves configurable lookups with their own windows in Party types and statuses. From there it surveys the body of records in The Parties window before narrowing to a single record in Party Details and its five tabs — General, Identifiers (where the ten schemes a party can carry turn out to be a configurable lookup in their own right), Contact Information, Hierarchy (where the house-root rule introduced early in the chapter finally gets its screen), and Provenance. It then turns to changing a record under audit — Editing, Deleting, and Party history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. The Conclusion draws these steps together and names what is deliberately still missing.

A party is an internal legal entity participating in financial transactions — the organisation's own top-level entity and each of its subsidiaries, branches, and other group-structure members. See the Tenants chapter's Parties section for the conceptual model this chapter builds on: the house/counterparty distinction, the administrative system party, and how a user's position in the party hierarchy determines their data visibility. This chapter does not repeat that model; it picks up from it to document the Qt interface for managing individual party records.

A party is, first and foremost, a stand-in for a real legal entity — a registered company, a bank, a branch — and real legal entities are notoriously hard to identify consistently: the same organisation can appear under different names, registration numbers, and codes across different jurisdictions, counterparties, and vendor systems, with no single authority reconciling them all.

Because no single identifier scheme covers every counterpart a party might need to be recognised by, a party can carry more than one — see Identifiers below for the full set of schemes OreStudio recognises, including the LEI and BIC schemes GLEIF publishes.

Every party carries a full name (its official registered legal name) and a short code (a brief mnemonic used elsewhere in the system for quick reference), both of which participate in the party's natural key alongside its surrogate id. A party also carries a codename — a globally unique, immutable, human-readable identifier (adjective_noun, e.g. swift_falcon) auto-generated on creation and used internally as the party's per-party message-queue prefix and scheduled-job namespace; it plays no role in the Qt UI and is not user-editable.

A party's type classifies what kind of entity it is (e.g. Corporate), chosen from the tenant's configured party types, and its status tracks where it sits in its own operational lifecycle (e.g. Active), chosen from the tenant's configured party statuses — both shown as colour-coded badges once selected. A party also carries a business center — an FpML business center code identifying the entity's primary location, the same code list documented in the Business Centres chapter.

A party's type and status are not fixed enumerations built into OreStudio; they are themselves tenant-configured reference-data lookups, each with its own list and detail window under the Reference Data menu, alongside the Party Types and Party Statuses entries. Both follow the same small shape — a Code (the value stored against the party), a Name (the label shown in the combo and, once selected, on the colour-coded badge), an optional Description, and a Display Order controlling where the value falls in the combo's drop-down list — plus the standard Provenance tab described in Provenance below.

Editing, deleting, and history for party type and party status records follow the same pattern described later in this chapter for the party record itself — a change reason on save, a soft close on delete, and a full version history with revert. Because both lookups are shared across every party (and, for status, every counterparty too — see the Counterparties chapter), changing a code or renaming a value here is immediately visible wherever that type or status is displayed.

With type and status established as configurable lookups in their own right, the rest of this chapter turns to the interface OreStudio provides for the party record itself — starting with the Parties window, which lists every party in the tenant.

Open the Parties window from the Reference Data menu. It lists all parties defined in the tenant, one row per party, each row carrying the short code, full name, party type, status, business center, version, last modifier, and when the record was last recorded.

The list is paginated; use the page controls at the bottom right to navigate. The toolbar buttons reload the list and open the add, edit, delete, and history actions. Double-clicking a row opens the Party Details dialog.

The Party Details dialog has five tabs — General, Identifiers, Contact Information, Hierarchy, and Provenance. The three action buttons at the bottom — Delete, Close, and Save — apply to the party as a whole.

To edit a party, open it in the Party Details dialog, make your changes, and click Save. Before the record is written, ORE Studio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a party, open it and click Delete. ORE Studio asks for confirmation before the record is closed off. Deletion is a soft close — the record's history is preserved and remains visible in the History dialog.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs on the right. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten.

The chapter set out to show that managing a party well follows from understanding what it represents and how it fits into the organisation's structure, and it has traced exactly that path. A party is an internal legal entity identified by a short code and full name, carrying a type and status, and sitting beneath a parent party in a single corporate hierarchy tree — with the sole exception of the tenant's own house root; the Parent Party combo's No Parent choice exists precisely for that one narrow exception, with the database rejecting any second attempt to use it. Building on that, the Qt interface took the record from the list view through its General, Identifiers, Contact Information, Hierarchy, and Provenance tabs, and through the editing, deleting, and history workflows, where reverting to an earlier version demonstrated the same bitemporal audit trail described in the Reference Data chapter. The shell's provision party command covers bulk/GLEIF onboarding (see Hierarchy above), but general-purpose shell/CLI commands for adding, editing, deleting, or viewing the history of an individual party are not yet implemented — tracked separately rather than glossed over here. See the Counterparties chapter for the external-facing mirror of this one.

• Tenants — the multi-tenant, multi-party conceptual model (house vs counterparty, the system party, hierarchy-based data visibility) this chapter assumes and builds on.
• Reference Data — the shared data quality and audit framework this chapter builds on.
• Currencies — the template chapter this one mirrors, including the Change Reason Required dialog.
• Counterparties — the external-facing mirror of this chapter.
• Business Centres — the business center a party links to, and the country flag a contact record may carry.
• Temporal Composite Entity Versioning — the architecture behind the Identifiers and Contact Information child tables.

The chapter advances the argument that managing a counterparty well means first understanding how it differs from the party chapter this one mirrors, then the interface that governs its lifecycle. It begins by establishing what a counterparty is in What is a Counterparty?, leaning on the Parties chapter for everything the two entities share rather than repeating it. From there it sets out The counterparty hierarchy — a real structural difference from a party's single house-root rule — before surveying the body of records in The Counterparties window and narrowing to a single record in Counterparty Details and its General, Identifiers, Contact Information, Hierarchy, and Provenance tabs. It then turns to changing a record under audit — Editing, Deleting, and Counterparty history — culminating in reverting to an earlier version, the point at which the bitemporal audit trail does its work. The Conclusion draws these steps together.

A counterparty is an external legal entity the organisation trades with — a bank, a broker-dealer, a corporate, a fund — as distinct from a party, which represents the organisation's own internal structure. The two entities are deliberately near-identical in shape — full name, short code, party type, status, business center, identifiers, contact information, a hierarchy field — because both are answering the same underlying question (what legal entity is this, and how do we recognise it consistently), just for opposite sides of a trade. Everything about legal-entity identification — GLEIF, the LEI standard, why identification is hard, the identifier schemes OreStudio recognises — is covered once in the Parties chapter's What is a Party? section and not repeated here.

Two field-level differences are worth calling out because they reflect a genuine modelling choice, not an oversight. First, a counterparty has no codename — the auto-generated, immutable, per-party message-queue and scheduled-job identifier a party carries — because that machinery exists to namespace a party's own processing (its queues, its scheduled reports), and a counterparty has none of its own to namespace. Second, a counterparty's full name is explicitly not unique within a tenant, unlike a party's: the same external legal name can legitimately recur across distinct branches or booking entities of the same institution, each with its own short code, so OreStudio indexes full name for search without constraining it to be distinct.

A counterparty's parent_counterparty_id lets counterparties form group structures too — a subsidiary counterparty pointing at its parent institution — but the resemblance to a party's hierarchy ends there. A party's hierarchy is a single tree per tenant with exactly one designated house root, enforced by a database constraint; a counterparty's hierarchy has no such constraint at all. Any number of counterparties may have no parent, because each represents an independent external organisation — Barclays' counterparties include many unrelated banks and corporates, and there is no reason to force them into one shared tree the way a tenant's own internal structure is.

The Parent Counterparty combo reflects that directly: alongside every other counterparty, it offers a leading No Parent entry, and choosing it is a completely ordinary, unconstrained choice here — unlike a party's equivalent No Parent choice, nothing in the database restricts how many counterparties may have no parent. A standalone institution with no group structure to nest under is created or edited through this dialog like any other, simply by leaving Parent Counterparty set to No Parent.

Open the Counterparties window from the Reference Data menu. It lists all counterparties defined in the tenant, one row per counterparty, each row carrying the short code, full name, party type, status, business center, version, last modifier, and when the record was last recorded — the same column layout as the Parties window.

The list is paginated; use the page controls at the bottom right to navigate. The toolbar buttons reload the list and open the add, edit, delete, and history actions. Double-clicking a row opens the Counterparty Details dialog.

The Counterparty Details dialog has five tabs — General, Identifiers, Contact Information, Hierarchy, and Provenance — the same set as Party Details. The three action buttons at the bottom — Delete, Close, and Save — apply to the counterparty as a whole.

To edit a counterparty, open it in the Counterparty Details dialog, make your changes, and click Save. Before the record is written, ORE Studio prompts for a change reason — the same Change Reason Required dialog shown in the Currencies chapter, and not repeated here. Select a Reason from the drop-down and add optional Commentary, then confirm. Every save creates a new version; the previous version is never overwritten.

To delete a counterparty, open it and click Delete. ORE Studio asks for confirmation before the record is closed off. Deletion is a soft close — the record's history is preserved and remains visible in the History dialog.

To view the full change history, open the details dialog and click the history icon in the title bar, or right-click the row and choose History.

Pick the two versions to compare from the Compare drop-downs. The All Fields / Only Changes toggle switches between showing every field and showing only the fields that differ between the two selected versions. The Revert button reinstates any historical version as a new version, preserving the full audit chain — the old version is never rewritten.

The chapter set out to show that managing a counterparty well follows from understanding how it differs from the party it mirrors, and it has traced exactly that path. A counterparty shares a party's full name, short code, type, status, business center, identifiers, and contact information almost verbatim, but diverges in two real ways: it carries no codename, since it has no processing of its own to namespace, and its hierarchy has no single-root constraint, since each counterparty represents an independent external organisation rather than a branch of the tenant's own structure. Building on that, the Qt interface took the record from the list view through its General, Identifiers, Contact Information, Hierarchy, and Provenance tabs, and through the editing, deleting, and history workflows, where reverting to an earlier version demonstrated the same bitemporal audit trail described in the Reference Data chapter. Shell and command-line access to counterparties is not yet implemented beyond the provision tenant GLEIF import path.

• Parties — the internal mirror of this chapter; legal-entity identification, GLEIF/LEI, and the full identifier scheme table all live there rather than being duplicated here.
• Reference Data — the shared data quality and audit framework this chapter builds on.
• Currencies — the template chapter this one mirrors, including the Change Reason Required dialog.
• Business Centres — the business center a counterparty links to.
• Temporal Composite Entity Versioning — the architecture behind the Identifiers and Contact Information child tables.