User Journey: Set up a currency pair

"I want this pair to quote, display and settle the way the desk trades it." The journey is done when the pair, its convention and its settlement calendars read correctly on one screen.

The actor is the tenant administrator: an account with the TenantAdmin role, acting inside their own tenant. The Operations role holds only the convention calendar permissions, so it cannot run this journey. The trigger is a pair the desk starts to trade, a market that changes its quoting precision, or a settlement date that came out wrong. The journey starts at the pair list, or at a link from a currency, and ends when the person leaves the pair.

1. Find the pair. The person opens Currency pairs. The system lists the pairs: the pair code, the base and quote currencies, and the classification. The person filters, or chooses Add pair.
2. Name the pair. For a new pair, the person picks the base and the quote currency. The system builds the pair code as BASE/QUOTE. If the quote currency has the higher base precedence, the system offers to swap the legs. Base-precedence order is the stored convention, and this screen enforces it; the server does not (see What is missing). The person picks the classification: major, minor or exotic.
3. Set the convention. The person sets the quoting convention on the same screen: the pip factor, the tick size in pips, the decimal places for display, the business day convention, whether forward dates count from spot, and whether the end-of-month rule applies. The system shows a sample rate at the chosen precision, so the person sees what the desk will see.
4. Save the pair. The person states a change reason and saves. The system writes the pair first and then its convention, because the convention refers to the pair. A new pair is written with must_not_exist; a change is written with must_match_version.
5. Set the settlement calendars. The person adds or removes the calendars that advance the pair's spot and maturity dates, usually one per leg. The system writes or deletes one currency_pair_convention_calendar row each time. A calendar name links to Keep a holiday calendar right, which can show the two calendars side by side.
6. Check the history. The person opens the history of the pair or of its convention. The system shows every version with the field-level difference from the one before. The person can revert to an older version, which the system writes as a new version.
7. Leave. The person goes back to the list.

No step waits on the server after its reply, and the journey keeps no state. Step 4 makes two writes; see What is missing.

One screen. The pair and its convention are one record to the person, so they share one form with one Save. The settlement calendars sit below as a plain list, because no operation reads their history.

Currencies, desk groups and pairs prototype, under doc/prototypes/currencies/, draws every state of this journey's screens at an address, and its design note cites the rule identifiers each state follows and names what it leaves to the server.

The history request is the generic one, with entity_type ores.refdata.currency_pair or ores.refdata.currency_pair_convention; both register a history provider.

1. The pair and its convention are not written together. Captured as Write a currency pair and its convention together, and check the pair code. They are two writes, and the convention refers to the pair. If the second write fails, the pair exists without the convention it is meant to have one of. The candidate is one operation that writes both in one transaction. Until then the screen writes the pair, then the convention, and if the second write fails it says so and keeps the convention form open for a retry. A pair found later without a convention opens with an empty convention form and a notice that the convention is missing, so the half-written pair can be completed from Find the pair.
2. The pair code is not checked against its legs. Captured with the write above. The insert validates that the base, the quote and the classification exist, but not that the pair code is BASE/QUOTE, that the legs differ, or that they are in base-precedence order. The candidate is to derive the pair code on the server, or to check it there. Until then the screen derives it and never lets the person type it.
3. The pair list cannot be filtered by currency or classification. The filter takes pair codes only. Showing "the pairs of this currency" means paging through every pair. The candidate is a filter on the base and quote currencies and on the classification.
4. The convention model names the wrong table. The business_day_convention note on the convention model says it refers to a trading table; the insert validates against the refdata business_day_convention_type list. The model text is out of date; the behaviour is right.
5. Only a tenant administrator can run this journey. Captured as No role below the tenant administrator can maintain reference data. Operations holds the convention calendar permissions but not the pair or convention ones, and no read on the lists the pickers need.

• Add or correct a currency — each leg opens its currency
• Keep a holiday calendar right — each settlement calendar opens there
• Group currencies for the desk — the desk groups the legs belong to
• Maintain a classification list — correct the pair classifications or business day conventions the pickers offer

• Currency pairs
• FX currency conventions
• Currency pair classification: major, minor, exotic
• Currency pair and currency entity fields
• Pip, tick size, and pip factor
• FX spot date and settlement

• Currencies and FX journeys
• User Journeys