Platform administrator journey
Who this is for: the person setting up a new tenant, or running the platform day to day.
Source: docs/site/docs/guides/tenant.md, guides/facility.md, guides/modules.md,
guides/platform-config.md, guides/metadata.md, guides/access-control.md, guides/audit.md —
this page is the order they happen in, not a replacement for any of them.
The shape of it
Setting up a tenant is a sequence, and the order is not cosmetic — each step needs the one before it to exist:
sign in → tenant → facility → modules → settings → metadata → roles → people → audit
The most common setup problem is doing these out of order and finding a screen empty or a menu item missing. An empty screen usually means a prerequisite is missing, not that the feature is broken.
1. Sign in
Sign in as an administrator. Your account determines both what you can see and which tenant and facility you are acting in.
Choosing your tenant and facility
Signing in does not land you in the workspace directly. You choose a tenant, then a facility, and only then does the workspace open.
⚠ On the facility step, "Next" is not how you continue. The facility list is paged — a deployment loaded from a national facility register can hold tens of thousands of them — so Previous / Next move between pages of the list. Paging does not keep a selection you made on an earlier page.
"Continue" is the button that advances, and it appears only once you have selected a facility. If you cannot see it, nothing is selected yet. Use the search box rather than paging when you know the facility's name.
⚠ Your tenant and facility are part of your session, not something you type into a form. Every record you create belongs to the tenant and facility you are signed in to. If you create something and cannot find it afterwards, the usual reason is that it was created in a different scope from the one you are now looking at — check the scope selector before assuming it failed to save.
Also used for: everyone signs in here. Only administrators reach the admin screens below.
→ Guide: Signing in
2. The dashboard
The dashboard shows what the signed-in user is entitled to reach. A menu item you expected and cannot see is a permission question, not a missing feature — see What stops this working below.
→ Guide: Dashboard
3. Create the tenant
A tenant is the organisation. Everything else belongs to one.
⚠ There is also a Global tenant, which holds platform-wide reference data that every tenant can read — concepts, country-level types. You will see Global-owned rows in lists alongside your own. You can use them; you cannot edit them from a tenant, and that is deliberate: a shared row edited by one tenant would change it for all of them.
→ Guide: Tenants
4. Create facilities and care locations
Facilities are where care happens. Within a facility you define care locations — wards, rooms, beds — which the bed board then reflects.
⚠ Facility creation is scoped. You create facilities within your tenant; a facility cannot be moved to another tenant afterwards. Get the tenant right first.
→ Guide: Facilities, care locations and beds
5. Enable the modules the tenant uses
The platform ships many modules — pharmacy, laboratory, imaging, billing, insurance and so on. A tenant sees the ones enabled for it.
⚠ Enabling a module is what makes its menu appear. If a colleague reports that a whole section of the product is missing, check here before checking their roles: no amount of permission grants will show a module the tenant does not have enabled.
→ Guide: Modules
6. Platform settings and feature flags
Settings cover currency, defaults and behaviour switches. Feature flags turn individual capabilities on and off.
⚠ A setting can exist at more than one level — platform, tenant, facility — and the most specific one wins. When a setting "will not change", it is usually being overridden at a narrower scope than the one you edited.
→ Guide: Platform settings and feature flags
7. Metadata and geography
Metadata holds the categorical lists the rest of the product chooses from: facility types, identifier types, divisions and other geography.
⚠ Reference types are owned by a facility, a tenant or a country — never by "the platform" in general. That ownership decides who can see and edit them, so creating a type in the wrong scope is the usual reason a colleague cannot find it in a dropdown.
→ Guide: Metadata and geography
7b. The concept dictionary
Clinical data is coded against the concept dictionary — the shared vocabulary of questions, answers, drugs and observables that clinical screens choose from.
⚠ Concepts are largely Global-owned, so most of what you see here is shared platform vocabulary your tenant reads rather than owns. A tenant can add its own local concepts; it cannot edit the shared ones, for the same reason it cannot edit any Global row.
⚠ A local concept without a mapping to a standard code is still perfectly usable inside the platform — it simply cannot be exported to an outside system as a standard code, because no mapping says what it means. That trade-off is worth knowing before creating local concepts in bulk.
Also used for: the same dictionary supplies drug codes to prescribing, observables to lab and imaging, and answer lists to forms.
→ Guide: Concept dictionary
8. Roles, user types and access
Access has two layers that are easy to confuse:
- User type — what kind of person this is (staff, provider, patient)
- Roles and permissions — what they may do
⚠ A permission has to be declared by a module before it can be granted. If a permission you expect is not offered, it has not been declared — it is not a matter of looking harder in the list.
⚠ A menu item needs two things to appear: the user's permission, and the route being registered for that screen. A link that is missing for one person and present for another is a permission question; a link missing for everyone is a registration question.
→ Guides: Access control, Identity and visibility
9. Add people
⚠ You never create a "person" directly. People enter the system by being registered — as a patient, as staff, or as a provider. Registration creates the underlying person record as part of that act.
This is not a UI convenience. A person reachable on its own would be a way to read or change someone's identity without going through the checks that patient, staff and provider registration each apply.
→ Guides: Staff and workforce, People and patients
10. Audit
The audit log records what was done and by whom. It is the answer to "who changed this?", and it is also where access to patient records is recorded.
→ Guide: Audit log
What stops this working
The failures below are the ones that look like bugs and are not. Each is listed with what you would see, so you can recognise it rather than diagnose it.
| What you see | What it actually is | What to do |
|---|---|---|
| A whole section of the product is missing for everyone | The module is not enabled for the tenant | Enable it under Modules (step 5) |
| A menu item is missing for one user only | They lack the permission, or their role lacks it | Check the role, then the user's roles |
| A menu item is missing for everyone, but the module is on | The screen's route is not registered for that permission | A build-level fix, not a configuration one — raise it |
| A permission you want to grant is not in the list | No module has declared it, so it cannot be granted | It has to be declared in code first |
| You created something and cannot find it | It was created in a different tenant or facility than the one you are now in | Check the scope selector; scope comes from your session |
| A setting will not take effect | It is overridden at a narrower scope | Check facility, then tenant, then platform |
| A reference type is missing from a dropdown | It was created in a scope the user cannot see | Recreate it at the right ownership level |
| A Global-owned row cannot be edited | That is deliberate — it is shared with every tenant | Create your own tenant-owned row instead |
| A patient cannot be found by name after an upgrade | Existing names were not re-indexed when encryption was enabled | An operations task — see the operations guide |
Where to go next
- Registering and caring for patients → Patient journey
- Onboarding staff → Staff journey
- Clinical work and credentialling → Provider journey