FHIR / SNOMED CT
PPP uses FHIR R4 in two ways: read-only SNOMED CT terminology lookups for the surgical logbook, and a FHIR R4 Procedure export endpoint that returns logbook cases in standard format. When a clinician types a procedure name ("hip replacement", "appendectomy"), the frontend queries the CSIRO Ontoserver to find matching SNOMED CT concepts and persists the selected concept's code to PPP's PostgreSQL database. The stored logbook data can then be retrieved as a conformant FHIR R4 Procedure resource via GET /fhir/r4/Procedure/{id}. No patient data is exchanged. No FHIR resources are written to external systems.
Quick navigation
- Need to update the SNOMED CT version? Jump to Updating the SNOMED CT version.
- Developing without internet? See Offline mode.
- Something's broken? Check Error handling & diagnostics.
1. What FHIR is and is not used for
Used for
- Procedure search — clinicians search for surgical procedures by name using SNOMED CT codes (
ValueSet/$expand) - Concept lookup — retrieving full details about a specific SNOMED CT concept (synonyms, hierarchy, fully specified name) once the user selects it (
CodeSystem/$lookup) - Procedure export — authenticated
GET /fhir/r4/Procedure/{logbookCaseId}returns a logbook case as a conformant FHIR R4 Procedure resource (SNOMED CT coding, status, performer, bodySite, performedDateTime)
Not used for
- Data writes — every surgical logbook row is written via a tRPC mutation to PostgreSQL. FHIR is never used to create or update records.
- Patient data exchange — PPP does not send or receive patient data as FHIR resources
- Clinical document storage — documents and attachments go through the core storage service, not a FHIR DocumentReference
If you ever need to integrate with an authenticated FHIR server (EHR, hospital HIE, etc.), that is a different class of integration with its own credential management — do not bolt it onto this one.
2. 2032 Australian Health Blueprint alignment
The Australian Digital Health Strategy and the 2032 Health Blueprint call for national health information to be exchanged using open interoperability standards — specifically FHIR R4 for data exchange and SNOMED CT for clinical terminology. PPP's FHIR implementation directly supports this goal in two ways:
SNOMED CT procedure coding
Every procedure added to the surgical logbook via the External Lookup is stored with a SNOMED CT concept code (procedures.snomed_ct in PostgreSQL). This ensures:
- Procedure data uses the national clinical terminology standard rather than free-text or proprietary codes.
- Records are machine-readable and semantically interoperable with other FHIR-capable systems in the national health infrastructure.
- The SNOMED CT edition is per-instance, sourced from
instance_config(#1087, #8875) — not hardcoded. Both the frontend live picker (instances/ppp/src/services/fhirApi.ts) and the backend auto-matcher (api/backend-ppp/src/services/snomedLookup/fhirService.ts) read the sameinstance_config.snomed_edition+fhir_base_url, so the picker and matcher always resolve against the same edition + ValueSet. The AU deployment is configured with the AU edition (http://snomed.info/sct/32506021000036107), aligning with the national release managed by the Australian Digital Health Agency; UK / unconfigured instances default to the UK edition (http://snomed.info/sct/999000031000000106).
FHIR R4 Procedure export
GET /fhir/r4/Procedure/{logbookCaseId} returns a conformant FHIR R4 Procedure resource for any logbook case:
{
"resourceType": "Procedure",
"id": "12345",
"status": "completed",
"code": {
"text": "Total hip replacement",
"coding": [
{
"system": "http://snomed.info/sct",
"code": "52734007",
"display": "Total hip replacement"
}
]
},
"performedDateTime": "2025-06-15",
"subject": { "reference": "Patient/PAT-12345" },
"performer": [
{ "actor": { "reference": "Practitioner/789", "display": "Dr A Smith" } }
],
"bodySite": [{ "text": "Lower limb" }],
"category": { "text": "Elective" }
}Authentication: PPP session token required (Authorization: Bearer <token>). The endpoint returns 401 for unauthenticated requests. Third-party consumer access (API tokens, per-institution licensing) is specified in #6336.
Patient pseudonymisation: the subject.reference uses a PPP-internal ID (Patient/PAT-{id}) rather than a real patient identifier. PPP does not store patient PII beyond what the clinician records in the logbook.
This positions PPP within the required national health infrastructure and enables third-party data integration without bespoke extraction work.
3. Data flow
User types procedure name
|
v 350ms debounce
ExternalSurgeryLookup (React component)
|
v
fhirApi.searchConcepts()
|
v GET /fhir/ValueSet/$expand
CSIRO Ontoserver (r4.ontoserver.csiro.au)
|
v FHIR R4 JSON
Parse ValueSetExpansion
|
v
User selects concept
|
v
tRPC mutation saves SNOMED code + display to PostgreSQLThe frontend talks to Ontoserver directly — no PPP backend hop. This is deliberate: Ontoserver is public and unauthenticated, every ms of latency matters for autocomplete, and round-tripping through tRPC would add load on the Container App for no benefit. See Architectural conventions on the integrations overview for the general "frontend never speaks to third parties" rule and why this is one of the two exceptions.
4. Key files
| File | Purpose |
|---|---|
instances/ppp/src/services/fhirApi.ts | FHIR API client (search + lookup, frontend) |
instances/ppp/src/types/fhir.ts | TypeScript types for FHIR resources |
instances/ppp/src/components/ExternalSurgeryLookup/ExternalSurgeryLookup.tsx | Search UI component |
instances/ppp/src/test-files/1st-expand-response.json | Offline mode fixture for $expand |
instances/ppp/src/test-files/2nd-lookup-response.json | Offline mode fixture for $lookup |
instances/ppp/.env.sample | Environment variable template |
api/backend-ppp/src/services/fhir/procedure.ts | Backend FHIR Procedure service (export) |
api/backend-ppp/src/rest/fhir/procedure.ts | REST handler for GET /fhir/r4/Procedure/{id} |
api/backend-ppp/src/rest/index.ts | REST route registry |
5. Environment variables
Configured via instances/ppp/.env and the deployment config per environment:
| Variable | Required | Purpose |
|---|---|---|
VITE_FHIR_BASE_URL | Yes | Ontoserver base URL — https://r4.ontoserver.csiro.au/fhir |
VITE_FHIR_SYSTEM_VERSION | Yes | SNOMED CT edition + release date (see below) |
VITE_OFFLINE_MODE | No | When true, use local fixtures instead of hitting Ontoserver |
All three are VITE_-prefixed because the FHIR client runs in the browser. None of them are secrets — Ontoserver is public, and the system version is a well-known URI.
6. Endpoint reference
ValueSet/$expand — procedure search
Purpose: search for SNOMED CT concepts matching a text filter.
URL:
GET {baseUrl}/ValueSet/$expand
?url={valueSetUrl}
&filter={searchTerm}
&system-version={version}
&includeDesignations=true
&count={count}
&elements=expansion.contains.code,expansion.contains.display,expansion.contains.fullySpecifiedName,expansion.contains.active
&_format=jsonHeaders:
Accept: application/fhir+json
Content-Type: application/fhir+jsonAuthentication: none. CSIRO Ontoserver is a public terminology server.
Parameters:
| Parameter | Required | Description |
|---|---|---|
url | Yes | ValueSet URL scoping the search (default: procedures descending from SNOMED concept 71388002) |
filter | Yes | Free-text search term (e.g. hip replacement) |
system-version | Yes | SNOMED CT edition and version string |
includeDesignations | No | When true, includes synonyms and FSN in the response |
count | No | Maximum results to return (default: 50) |
elements | No | Projection to limit response fields |
_format | No | Response format (json) |
Response: ValueSetExpansion resource containing expansion.contains[]:
{
"resourceType": "ValueSet",
"expansion": {
"contains": [
{
"system": "http://snomed.info/sct",
"code": "52734007",
"display": "Total hip replacement",
"fullySpecifiedName": "Total replacement of hip joint (procedure)",
"active": true
}
]
}
}Timeout: 10 seconds via AbortController. Anything slower is treated as a failure and surfaced to the user.
CodeSystem/$lookup — concept details
Purpose: retrieve full details about a single SNOMED CT concept after the user has selected it.
URL:
GET {baseUrl}/CodeSystem/$lookup
?code={snomedCode}
&system=http://snomed.info/sct
&property=*Parameters:
| Parameter | Required | Description |
|---|---|---|
code | Yes | SNOMED CT concept code (e.g. 52734007) |
system | Yes | Always http://snomed.info/sct |
property | No | * returns all properties (parents, children, inactive status) |
Response: Parameters resource, parsed into ConceptDetails:
{
code: "52734007",
display: "Total hip replacement",
system: "http://snomed.info/sct",
inactive: false,
parents: ["36682004"],
children: ["..."],
synonyms: ["THR - Total hip replacement"],
fullySpecifiedName: "Total replacement of hip joint (procedure)",
designations: [/* ... */],
properties: { /* additional SNOMED properties */ }
}Timeout: 10 seconds.
GET /fhir/r4/Procedure/{logbookCaseId} — procedure export
Purpose: retrieve a logbook case activity as a conformant FHIR R4 Procedure resource.
URL:
GET /fhir/r4/Procedure/{logbookCaseId}Headers:
Accept: application/fhir+json
Authorization: Bearer <ppp-session-token>Authentication: required. Returns 401 OperationOutcome if the session token is missing or invalid.
Parameters:
| Parameter | In | Required | Description |
|---|---|---|---|
logbookCaseId | path | Yes | PPP activity ID of the logbook case |
Response (200):
{
"resourceType": "Procedure",
"id": "12345",
"status": "completed",
"code": {
"text": "Total hip replacement",
"coding": [
{
"system": "http://snomed.info/sct",
"code": "52734007",
"display": "Total hip replacement"
}
]
},
"performedDateTime": "2025-06-15",
"subject": { "reference": "Patient/PAT-12345" },
"performer": [
{ "actor": { "reference": "Practitioner/789", "display": "Dr A Smith" } }
],
"bodySite": [{ "text": "Lower limb" }],
"category": { "text": "Elective" }
}Status mapping (activities.status → FHIR status):
| PPP status | FHIR status |
|---|---|
verified | completed |
completed | completed |
pending | in-progress |
draft | preparation |
cancelled | not-done |
| (other) | unknown |
Error responses (OperationOutcome): 400 invalid ID, 401 unauthenticated, 404 not found, 500 internal error.
7. SNOMED CT configuration
Version string format
The SNOMED CT version is specified as a composite URI:
http://snomed.info/sct|http://snomed.info/sct/{editionId}/version/{releaseDate}| Part | Example value | Description |
|---|---|---|
| System | http://snomed.info/sct | SNOMED CT code system URI |
| Edition ID | 32506021000036107 | Australian SNOMED CT edition (AU) |
| Release date | 20250630 | Version release date (YYYYMMDD format) |
Current configuration
The SNOMED edition is resolved per-instance from instance_config (#1087, #8875), not pinned by a single global constant. instance_config.snomed_edition (+ optional snomed_version and fhir_base_url) is the single source of truth shared by:
- the frontend live picker (
instances/ppp/src/services/fhirApi.ts), and - the backend auto-matcher (
api/backend-ppp/src/services/snomedLookup/fhirService.ts, viaresolveSnomedEditionConfig→getInstanceConfig).
Because both read the same row, the picker and the stored masterlist resolve a given procedure to the same SNOMED code under the configured edition. A VITE_FHIR_SYSTEM_VERSION env override is still honoured by the frontend for local development:
VITE_FHIR_SYSTEM_VERSION=http://snomed.info/sct|http://snomed.info/sct/32506021000036107/version/20250630The AU deployment is configured with the Australian SNOMED CT edition (32506021000036107); UK / unconfigured instances fall back to the UK edition (999000031000000106). When instance_config is absent, the backend service falls back to the historic UK default, so non-AU / unconfigured environments are unaffected.
ValueSet scope
Search is scoped to procedures via the configured edition's Procedure hierarchy ValueSet, e.g. for the AU edition:
http://snomed.info/sct/32506021000036107?fhir_vs=isa/71388002This filters to concepts that are a (ISA) descendant of SNOMED concept 71388002 ("Procedure"), within the configured edition. Without the ISA scope, a search for "chest" would return body parts, clinical findings, and anatomical regions mixed in with the procedures you actually want.
Update cadence
SNOMED CT International releases twice per year, in January and July. The Australian edition follows roughly one month later. The expected rhythm is:
- International releases: ~31 January and ~31 July
- Australian edition releases: ~February/March and ~August/September
- PPP should update within 1–2 months of each Australian edition release
8. Updating the SNOMED CT version
Check for new releases at CSIRO Ontoserver or the National Clinical Terminology Service.
Identify the new version URI — only the release date portion changes (e.g.
20250630→20260131).Update the environment variable in every environment:
instances/ppp/.env.sample— update the template so new devs land on the current version- Local
.envfor each developer ppp-uk-uatandppp-uk-prod— update via Doppler or the deployment configuration
Update the fallback in
instances/ppp/src/services/fhirApi.ts:tssystemVersion: env.VITE_FHIR_SYSTEM_VERSION || 'http://snomed.info/sct|http://snomed.info/sct/32506021000036107/version/20260131',Smoke-test the update by searching for a handful of common procedures and verifying results come back:
hip replacement→52734007(Total hip replacement)appendectomy→80146002(Appendectomy)laparoscopy→ multiple laparoscopic procedures
Refresh the offline fixtures if the response structure has changed (unlikely between minor versions). See Updating test fixtures.
Version must exactly match Ontoserver
The VITE_FHIR_SYSTEM_VERSION string must exactly match a version available on Ontoserver. An invalid version returns a FHIR OperationOutcome error for every search. If procedure search suddenly stops working, this is the first thing to check.
9. Ontoserver integration
Base URL
| Environment | URL |
|---|---|
| All environments | https://r4.ontoserver.csiro.au/fhir |
The same public Ontoserver instance is used across dev, UAT, and production. There is no PPP-hosted terminology server — running one would require licensing SNOMED CT directly, which is non-trivial.
Offline mode
For development without internet, or when Ontoserver is rate-limiting aggressively (it is a shared public resource), the platform supports an offline fixture mode.
Enable:
VITE_OFFLINE_MODE=trueBehaviour:
searchConcepts()returns fixture data from1st-expand-response.jsonafter a simulated 200ms delaylookupConcept()returns fixture data from2nd-lookup-response.jsonafter a simulated 150ms delay- No network requests are made to Ontoserver
- The search filter is ignored — the same fixture data is returned regardless of input
When to use it:
- Local development without internet
- UI development and styling work where you want deterministic results
- Automated tests where Ontoserver availability is not guaranteed
When not to use it:
- Any test that exercises search ranking or multi-term queries
- Any smoke test you want to actually prove connectivity
Operations used
| FHIR Operation | Purpose | Endpoint |
|---|---|---|
$expand | Search/filter SNOMED CT concepts within a ValueSet | GET /fhir/ValueSet/$expand |
$lookup | Get full details for a single concept by code | GET /fhir/CodeSystem/$lookup |
10. Error handling & diagnostics
OperationOutcome format
When Ontoserver hits an error, it returns a FHIR OperationOutcome resource instead of the expected response — often with a 200 HTTP status, which makes "check the status code" insufficient:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"text": "Unknown system version: http://snomed.info/sct|http://snomed.info/sct/32506021000036107/version/99999999"
},
"diagnostics": "Additional diagnostic information"
}
]
}fhirApi.ts detects OperationOutcome responses and extracts the error message from issue[0].details.text or issue[0].diagnostics.
HTTP status codes
| Status | Meaning | Handling |
|---|---|---|
200 | Success | Parse response as ValueSetExpansion or Parameters |
200 + OperationOutcome | Server-side error | Extract error message, throw |
400 | Bad request (invalid parameters) | Throw with status text |
404 | Resource not found | Throw with status text |
408 / 504 | Timeout | Caught by AbortController after 10s |
500 | Server error | Throw with status text |
Client-side error handling
The ExternalSurgeryLookup component displays errors inline above the search field using a dismissible MUI Alert:
- Network / timeout errors → "SNOMED search timed out — Ontoserver did not respond"
- FHIR operation errors → the error message from
OperationOutcome - Generic errors → "Unable to search procedures — please try again"
Users can dismiss the alert and retry without refreshing the page.
11. Testing
Frontend tests
cd instances/ppp
pnpm testTesting with offline mode
Set VITE_OFFLINE_MODE=true in your .env to use fixture data during development. This is useful for:
- Verifying UI behaviour without network dependencies
- Testing error states by temporarily modifying fixture files
- Running automated tests in CI environments
Testing against live Ontoserver
Set VITE_OFFLINE_MODE=false (or remove it) and ensure VITE_FHIR_BASE_URL points to Ontoserver. Search for known procedures to verify connectivity:
hip replacement→ should return52734007appendectomy→ should return80146002laparoscopy→ should return multiple laparoscopic procedures
Manual testing checklist
- [ ] Search returns results for common procedure names
- [ ] Search with fewer than 2 characters shows no results (debounce guard)
- [ ] Loading spinner appears during search
- [ ] Error alert appears and is dismissible on failure
- [ ] Selecting a concept populates the form field
- [ ] Clearing selection resets the field
Backend tests
The backend has two test suites for FHIR:
- Unit tests (
api/backend-ppp/src/rest/fhir/procedure.test.ts) — mock the service layer; cover path parsing, auth guards, and all HTTP response codes. - Integration tests (
api/backend-ppp/src/services/fhir/procedure.integration.test.ts) — run against a real database; cover SNOMED CT coding, performer fallback chain, date formatting, andshrimpTitlefallback.
SNOMED CT code storage itself is exercised via the createExternalProcedure path in api/backend-ppp/src/services/settingsServices/procedures.ts.
Updating test fixtures
To refresh the offline-mode fixtures with current Ontoserver data:
# 1. Expand response (search for a known procedure)
curl -H "Accept: application/fhir+json" \
"https://r4.ontoserver.csiro.au/fhir/ValueSet/\$expand?url=http://snomed.info/sct/32506021000036107?fhir_vs=isa/71388002&filter=total+hip+replacement&includeDesignations=true&count=50&_format=json" \
| jq . > instances/ppp/src/test-files/1st-expand-response.json
# 2. Lookup response (fetch details for a known concept)
curl -H "Accept: application/fhir+json" \
"https://r4.ontoserver.csiro.au/fhir/CodeSystem/\$lookup?code=52734007&system=http://snomed.info/sct&property=*" \
| jq . > instances/ppp/src/test-files/2nd-lookup-response.jsonCommit both files as part of the same PR as the version bump.
12. Extending to new FHIR resources
The current integration is scoped to SNOMED CT procedure lookups. To extend the FHIR layer for additional use cases (e.g. conditions, body structures, medications):
- Define types in
instances/ppp/src/types/fhir.tsfor the new resource shape. - Add API functions to
instances/ppp/src/services/fhirApi.tsthat hit the appropriate ValueSet scope. - Add offline fixtures in
instances/ppp/src/test-files/by querying Ontoserver directly (see Updating test fixtures). - Create a UI component following the pattern of
ExternalSurgeryLookup— MUIAutocompletewith debounced search, error handling, and offline mode support.
ValueSet scopes for other resource types
| Use case | SNOMED hierarchy | ValueSet URL fragment |
|---|---|---|
| Procedures | 71388002 (Procedure) | fhir_vs=isa/71388002 |
| Conditions | 404684003 (Clinical finding) | fhir_vs=isa/404684003 |
| Body structures | 123037004 (Body structure) | fhir_vs=isa/123037004 |
Important considerations
- Read-only pattern — FHIR is never used to write data; tRPC handles all creates and updates. The Procedure export endpoint (
GET /fhir/r4/Procedure/{id}) reads from PostgreSQL and returns FHIR — it does not write to any FHIR server - Offline mode — always provide fixture data for new resources to support offline development
- Error handling — reuse the existing
OperationOutcomedetection pattern - Timeout — maintain the 10-second
AbortControllertimeout for all new endpoints - No authentication — CSIRO Ontoserver is public; if you integrate with an authenticated FHIR server, add credential management and keep it server-side
13. Failure modes at a glance
| Failure | User impact | Operator action |
|---|---|---|
| Ontoserver is down | Procedure search shows "Ontoserver did not respond" | Monitor CSIRO status; no PPP action |
VITE_FHIR_SYSTEM_VERSION stale | Every search returns OperationOutcome | Update env var, redeploy frontend |
| Ontoserver rate-limits PPP | Intermittent search failures | Enable offline mode during development |
| Debounce set too low | Too many requests, Ontoserver rate-limits harder | Keep the 350ms debounce in place |
| Network timeout (>10s) | User sees timeout error, can retry | No PPP action unless Ontoserver is sick |
Canonical implementation docs
The full internal guide lives in the backend repo alongside the backend's own FHIR reference material:
Related
- Integrations overview — the five external services PPP depends on
- Surgical Logbook feature spec — where the procedure lookup surfaces in the product
- CSIRO Ontoserver — the public terminology server PPP queries
- National Clinical Terminology Service (AU) — where Australian SNOMED CT editions are published