Configure an onboarding journey for a country

◆ How config fits together#

Three layers. Understanding them makes every screen in the studio obvious, and prevents the one mistake that causes real damage: editing something shared when you meant to change one country.

What follows from this

• You never edit a base form to serve one country. Open the form for your country and change what differs; the studio records just the difference. Kenya renaming “State” to “County” is a two-line overlay, not a copy of the form.
• A journey references forms, it doesn't contain them. Reordering steps never touches field definitions.
• Precedence is base → all-channel overlay → channel overlay. A web-only overlay wins over an all-channel one, for web only.

▸ Set up the studio#

npm install
npm start        # then open the URL it prints

Requires Node 24.15 or newer. If npm start complains about your Node version, switch it (nvm use 26) and try again.

Three things to know before your first session:

1 Create the workspace#

Catalogue → New country · about 2 minutes

Always start by cloning a country that already works. You inherit a journey that is known to be valid and adapt what differs — far faster and safer than assembling one from nothing.

Press Create workspace →. The studio deep-copies the source journey — steps, branches, workflow settings, exit rules — and rewrites its wording keys from the source country to yours (retail_onboarding.ke.step… → …tz.step…), carrying the source's text over as your starting point. When country-data copying is selected, the account products and privacy policy are independently deep-copied and the local product currency is remapped to the code you confirmed.

You land on the workspace hub: three numbered sections that double as your to-do list. You can leave and return at any time; the draft persists in this browser.

2 Shape the journey#

Hub section 1 → Edit journey · every change auto-saves to your draft

This is where you decide what happens in what order. The Flow map at the top is a read-only picture of the current path — check it before and after editing.

Main steps

• Order is the customer's experience. Reorder with the ↑ / ↓ arrows.
• Step type matters — see the types table. Use FORM for data entry, REVIEW_FORM / CONFIRM_FORM for “check your details” screens, CONSENT_FORM for accept/decline, STATUS_PAGE for a wait-while-we-check screen, and INFO for a screen with no form attached.
• Form is the base form the step renders — choose from the list. A typo becomes a publish-blocking error rather than a production surprise.
• Title must be a wording key, not literal text (e.g. retail_onboarding.tz.step.basic_info.title). Literal text still publishes but raises a warning, and customers see that same string in every language.
• Remove steps this country doesn't need. That never deletes the form — other countries keep using it.

Workflow settings

Three values the backend needs. Both step references must name main steps (not steps inside a branch), or publishing is blocked.

Branches — the conditional detours

Exit rules (on branch steps) end a journey early — for example when a customer declines a mandatory waiver. Each needs a condition, the action terminate_journey, and a reason.

Read the Lint panel before you leave

It sits at the bottom of the builder. Errors block publishing; warnings are advice worth taking. Aim for zero errors now rather than at handoff time — see what blocks a handoff.

3 Adapt the forms#

Hub section 2 → Edit · the longest step, and the one that decides how screens look

The table lists every form your journey touches, whether it already carries overlays, and an Edit → link. Open only the forms that genuinely differ for your country; inherited overlays are often already correct.

First, set the scope

Scope decides where your change lands, and it is the most common thing to get wrong.

Then work through the tabs

Watch the live preview as you type

The preview on the right renders the screen the way the selected channel's app renders it, and it is interactive: choose values, watch conditional fields appear, watch validation fire. Fill sample populates plausible data in one click.

Below it, Generated change shows the exact patch your edits produce. If that panel is empty you haven't changed anything that differs from the base — which is a perfectly good outcome.

Finish with Save to workspace →. Overlays don't publish individually here; they're bundled into the country's single change set.

4 Account products, privacy & consent#

Hub section 3 → Edit country data · /country-data/{CC}

Not every piece of country configuration is a form. The account the customer picks, the currencies on offer and the privacy notice are database-backed country data: the app fetches them from onboarding lookup endpoints. Terms & conditions and other consent documents remain linked content on their FormEngine forms. A country with a perfect journey but no account products still cannot onboard anyone.

Account products

One entry per account the customer can open, keyed by currency + residency + scheme code — that combination must be unique, and the studio blocks publishing if you repeat one. Each product carries what the picker renders: account type, description, features, requirements, the tariff guide link, and the optional cost/special notes.

Cloning a country copies its products as a starting point. Always revisit them: scheme codes, requirements and the tariff guide are country-specific, and a copied SB100 from Kenya is almost certainly wrong elsewhere.

Privacy and consent documents

The privacy notice is a database-backed lookup. Configure its published document link, journey, content type (url) and media type (application/pdf) here. It must use https. Use Open the document ↗ to confirm the link resolves before publishing — a 404 here is a legal problem, not a UI one.

What this produces

One native EF data migration under OmniDos.Onboarding.Infra/Migrations. It upserts account products and privacy-policy rows through the database-migration path DigitalOnboardingSvc already runs at startup. In a draft workspace it goes out with the rest of the change set; for a live country it downloads as a bundle of its own.

5 Wording & languages#

Form editor → Translations tab

Every visible string is a key (identity.documentNumber.label), and the text behind it is authored per language. Nothing in the config holds literal customer text — that's what makes one form serve many languages. The service swaps the key for the text as it answers the request, so a customer can switch language mid-journey and the form itself never changes.

• The Translations tab lists the keys this form uses and which languages are missing. Fill the gaps for every language the country launches in.
• In the preview, switch Lang to check each language, and toggle keys to reveal the raw key behind any string.
• If you see a key where you expect words (e.g. address.county.label), that key has no text for the selected language. Add it.

6 Walk it as a customer#

Hub → Preview journey (or /preview/{CC}) · the step that catches what reading config never does

Read the two panels below the phone

Cover these cases before you publish

• Web from first screen to last.
• Android / iOS from first screen to last — the mobile layout is one field per row and has a sticky button.
• Every branch you expect to fire — change the country of residence, decline a waiver, leave optional fields empty.
• Every language the country launches in.
• The review / confirm screens — do they show the data captured earlier?

7 Review & download#

Hub section 4

The final section shows the complete change set — the journey file, one file per overlay, the country data migration, the translation store and one copy catalogue per language — with every path listed. The download is blocked while any lint error remains, and the panel tells you which.

Download {CC} bundle → gives you a single zip containing everything, which you hand to the repository in step 8. Inside:

See what's in the bundle if you want to understand the files themselves.

8 Raise the pull request#

The studio has no access to the repository — by design, so it never holds a credential that could write to it. You take the bundle the last few metres.

1. Unzip it and copy the files in. The repo/ folder mirrors the repository's own structure, so a single copy puts every file at its correct path:

   unzip {CC}-config-bundle.zip
   cp -R {CC}-config-bundle/repo/. /path/to/DigitalOnboardingSvc/
   cd /path/to/DigitalOnboardingSvc && git status

   git status should list exactly the files the studio showed you in step 7. If it lists more, you copied from the wrong level.
2. Branch, commit and push.

   git checkout -b config/{cc}-onboarding
   git add . && git commit -m "Add {CC} onboarding configuration"
   git push -u origin config/{cc}-onboarding

3. Open the pull request against the lower-environment branch your team uses, and paste PR.md as the description. It already lists the country, the files and what reviewers should check, so there's nothing to write.
4. Get it reviewed — ideally by someone who can re-walk the journey. Give them the review checklist.
5. Merge — the lower environment then picks the configuration up.
6. Verify in the lower environment, especially anything the preview only approximates: branch predicates, real document capture, the actual workflow and OTP.
7. Then talk about production.

✓ You're finished when…#

• The journey lints clean — zero errors, warnings understood.
• Every form the journey uses renders correctly on web and mobile.
• Required fields, formats and cross-field rules behave in the preview.
• Branches enter and resume where you intended.
• No raw wording keys in any launch language.
• Account products cover every currency the country offers, and both legal links open.
• The change set is one PR, reviewed and merged.
• Behaviour confirmed in the lower environment.

▤ Change a country that already exists#

No workspace is involved — you're editing live configuration, so changes are handed off one at a time, each as its own small bundle and its own pull request. Everything else (scope, tabs, preview, lint) works exactly as above.

◎ Reviewing someone else's change#

You don't need to read patch JSON to review well. Ask five questions:

1. Does the description match the files? A “relabel one field” change shouldn't touch the journey.
2. Is the scope right? A channel-specific file (…_web_ui_patch.json) where the change should apply everywhere — or the reverse — is the most common mistake.
3. Are titles and labels wording keys, with translations included? A change that adds keys but touches neither translations/translations.json nor Locales/{lang}.json shows raw keys to customers — the service falls back to English and then to the key itself.
4. Do branch anchors still make sense if steps were reordered?
5. Has the author walked it? Ask which branches fired and which channels they checked.

The fastest review is to check the branch out, run the studio, and walk the journey yourself.

⟨⟩ Hand it to the client teams#

The web, iOS and Android apps don't read the files you publish — they call the onboarding API and render whatever comes back. API Response Mock shows exactly those payloads, rebuilt from your configuration, so a client team can stub against them before anything ships.

Open it from the sidebar (Client contract → API Response Mock), from a country page, or from the journey builder. Address: /api-mock/{CC}. It is read-only — nothing you do there changes configuration.

What's on the page

Pick the channel before you copy. The page resolves the same way the service does: a variant matching that channel exactly, otherwise the channel-less one, with channel-specific overlays applied on top of the shared ones. Switching between web and ios is the quickest way to prove a channel overlay actually lands.

Taking it away — three buttons

Each panel also has its own Copy JSON, and so does every JSON block elsewhere in the studio (raw form JSON, generated patches, the journey seed file, the workspace change set, the walkthrough's captured payload).

Four things the mock deliberately doesn't fake

• hash and context. The live form payload carries a server-computed hash of the resolved documents plus a context dictionary. Both are produced at resolve time, so the mock leaves them out rather than inventing values — clients should treat them as present but opaque.
• Branch conditions stay server-side. A branch reaches the client with triggerHint only; the real condition tree and any step exit rules are evaluated by the backend and never serialized.
• otpEnabled is internal. Clients see workflowConfig with initiateAfterStepId and completeOnStepId only.
• Names on the wire differ from the seed files. Step types are PascalCase (REVIEW_FORM in the file becomes ReviewForm in the response), and nulls are serialized rather than dropped — a branch with no resumeBeforeStep still shows "resumeBeforeStep": null.
• A STATUS_PAGE step carries no form. It resolves one server-side, but the client receives "form": null and polls the step's status endpoint instead.

While editing a single form there's a smaller version of the same thing: the API mock tab in the form editor shows that one form's payload with your current, unpublished edits applied.

! What blocks a handoff#

Three independent checks. Use all three — they catch different classes of mistake.

1 · Journey lint — structure

Errors block the download:

• A step with no id, or a duplicate id.
• A step whose type needs a form but has none, or that references an unknown form.
• A NewGen group (sourceReference) on a step that isn't a FORM step, a group NewGen doesn't return (contacts, preferredAddress, sourceOfIncome, biometrics), or one group mapped by two steps of the same journey.
• Workflow settings pointing at something that isn't a main step.
• A branch whose trigger or resume anchor isn't a main step, that has no condition, or whose condition reads a step after its trigger.
• An exit rule with an empty condition or an unknown action.

Warnings — fix if you can: a title that isn't a wording key; no workflow settings; a branch with no steps; an exit rule with no reason.

Step ids don't have to match their form key, and one form may back several steps — the service binds each step to its own formKey. Country review also warns when a form mapped to a NewGen group has no property for one of that group's parameters.

2 · Form validation — per screen

Per-field rules (required, length, pattern, format) and cross-field rules. The preview enforces both live: the button stays grey until the screen would pass, and Blocking the CTA names each offender.

3 · The walkthrough — sequence

The only check that covers data carried between steps, branches firing, review screens filling themselves in, and each channel rendering.

⌸ What's in the bundle#

Under repo/ the studio writes files the backend already understands, at the paths it already reads. The naming is a contract, not a preference:

Wording ships as two shapes of the same thing. The config holds keys, never text; the service substitutes the text as it answers each request, reading one flat key → text catalogue per language according to the caller's Accept-Language. Those catalogues are what runs. The file under translations/ is the pivot of them — every language for a key on one row, which is the only shape a person can actually edit — and the studio generates the catalogues from it, so both ship in the same pull request as the config that introduced the keys.

Overlays are precise lists of edits against a base form version, not copies of it. That's why a small change stays a small file — and why improving a base form still reaches every country.

? Troubleshooting#

≡ Tables & conventions#

Step types

STATUS_PAGE, in more detail

This one behaves unlike the rest, so it's worth reading before you use it.

• It binds a form, but the client is sent form: null. The schema is there so the service can validate the data it fetches itself and pass it to later steps via x-source — for TZ, the name and date of birth NIDA returns, which review_information then displays. Leave the form's fields x-hidden and its layout empty; nothing there is ever rendered. You must still set formKey and formVersion: the service rejects the whole journey without them.
• The customer sees a waiting screen and a button. The button polls GET /onboardings/{id}/steps/{stepId}/status. Submitting a payload to the step is rejected outright.
• The reply's actionCode decides what happens next — 00 proceed (the reply carries the next step and its form), 80 retry (the service reverts the earlier capture steps and sends the customer back to re-capture), 99 kill (the journey ends). No action code yet means the check is still running and the client keeps polling.
• None of that behaviour is configurable here. Which upstream check runs, and where a retry sends the customer, live in the service. What you control is where the step sits in the journey, which form backs it, and its wording keys. The API response mock page shows the replies for each action code, and the Journey preview lets you walk all three.

Widgets

Condition operators

EQUALS, NOT_EQUALS, IN, NOT_IN, GREATER_THAN, LESS_THAN, IS_EMPTY, IS_NOT_EMPTY. Named predicates: isFatcaCountry, isCrsCountry.

Wording key conventions

Dotted and lower-camel: identity.documentNumber.label, address.error.zipCode.minLength, retail_onboarding.tz.step.basic_info.title. Journey keys carry the country segment (.tz.) and are rewritten when you clone; form keys are usually shared across countries.

Where things live in the studio

Glossary