Skip to content

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

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 same instance_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:

json
{
  "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 PostgreSQL

The 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 ​

FilePurpose
instances/ppp/src/services/fhirApi.tsFHIR API client (search + lookup, frontend)
instances/ppp/src/types/fhir.tsTypeScript types for FHIR resources
instances/ppp/src/components/ExternalSurgeryLookup/ExternalSurgeryLookup.tsxSearch UI component
instances/ppp/src/test-files/1st-expand-response.jsonOffline mode fixture for $expand
instances/ppp/src/test-files/2nd-lookup-response.jsonOffline mode fixture for $lookup
instances/ppp/.env.sampleEnvironment variable template
api/backend-ppp/src/services/fhir/procedure.tsBackend FHIR Procedure service (export)
api/backend-ppp/src/rest/fhir/procedure.tsREST handler for GET /fhir/r4/Procedure/{id}
api/backend-ppp/src/rest/index.tsREST route registry

5. Environment variables ​

Configured via instances/ppp/.env and the deployment config per environment:

VariableRequiredPurpose
VITE_FHIR_BASE_URLYesOntoserver base URL — https://r4.ontoserver.csiro.au/fhir
VITE_FHIR_SYSTEM_VERSIONYesSNOMED CT edition + release date (see below)
VITE_OFFLINE_MODENoWhen 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 ​

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=json

Headers:

Accept: application/fhir+json
Content-Type: application/fhir+json

Authentication: none. CSIRO Ontoserver is a public terminology server.

Parameters:

ParameterRequiredDescription
urlYesValueSet URL scoping the search (default: procedures descending from SNOMED concept 71388002)
filterYesFree-text search term (e.g. hip replacement)
system-versionYesSNOMED CT edition and version string
includeDesignationsNoWhen true, includes synonyms and FSN in the response
countNoMaximum results to return (default: 50)
elementsNoProjection to limit response fields
_formatNoResponse format (json)

Response: ValueSetExpansion resource containing expansion.contains[]:

json
{
  "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:

ParameterRequiredDescription
codeYesSNOMED CT concept code (e.g. 52734007)
systemYesAlways http://snomed.info/sct
propertyNo* returns all properties (parents, children, inactive status)

Response: Parameters resource, parsed into ConceptDetails:

ts
{
  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:

ParameterInRequiredDescription
logbookCaseIdpathYesPPP activity ID of the logbook case

Response (200):

json
{
  "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 statusFHIR status
verifiedcompleted
completedcompleted
pendingin-progress
draftpreparation
cancellednot-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}
PartExample valueDescription
Systemhttp://snomed.info/sctSNOMED CT code system URI
Edition ID32506021000036107Australian SNOMED CT edition (AU)
Release date20250630Version 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, via resolveSnomedEditionConfig → 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/20250630

The 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/71388002

This 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 ​

  1. Check for new releases at CSIRO Ontoserver or the National Clinical Terminology Service.

  2. Identify the new version URI — only the release date portion changes (e.g. 20250630 → 20260131).

  3. Update the environment variable in every environment:

    • instances/ppp/.env.sample — update the template so new devs land on the current version
    • Local .env for each developer
    • ppp-uk-uat and ppp-uk-prod — update via Doppler or the deployment configuration
  4. Update the fallback in instances/ppp/src/services/fhirApi.ts:

    ts
    systemVersion:
      env.VITE_FHIR_SYSTEM_VERSION ||
      'http://snomed.info/sct|http://snomed.info/sct/32506021000036107/version/20260131',
  5. 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
  6. 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 ​

EnvironmentURL
All environmentshttps://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=true

Behaviour:

  • searchConcepts() returns fixture data from 1st-expand-response.json after a simulated 200ms delay
  • lookupConcept() returns fixture data from 2nd-lookup-response.json after 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 OperationPurposeEndpoint
$expandSearch/filter SNOMED CT concepts within a ValueSetGET /fhir/ValueSet/$expand
$lookupGet full details for a single concept by codeGET /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:

json
{
  "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 ​

StatusMeaningHandling
200SuccessParse response as ValueSetExpansion or Parameters
200 + OperationOutcomeServer-side errorExtract error message, throw
400Bad request (invalid parameters)Throw with status text
404Resource not foundThrow with status text
408 / 504TimeoutCaught by AbortController after 10s
500Server errorThrow with status text

Client-side error handling ​

The ExternalSurgeryLookup component displays errors inline above the search field using a dismissible MUI Alert:

  1. Network / timeout errors → "SNOMED search timed out — Ontoserver did not respond"
  2. FHIR operation errors → the error message from OperationOutcome
  3. Generic errors → "Unable to search procedures — please try again"

Users can dismiss the alert and retry without refreshing the page.

11. Testing ​

Frontend tests ​

bash
cd instances/ppp
pnpm test

Testing 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 return 52734007
  • appendectomy → should return 80146002
  • laparoscopy → 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, and shrimpTitle fallback.

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:

bash
# 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.json

Commit 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):

  1. Define types in instances/ppp/src/types/fhir.ts for the new resource shape.
  2. Add API functions to instances/ppp/src/services/fhirApi.ts that hit the appropriate ValueSet scope.
  3. Add offline fixtures in instances/ppp/src/test-files/ by querying Ontoserver directly (see Updating test fixtures).
  4. Create a UI component following the pattern of ExternalSurgeryLookup — MUI Autocomplete with debounced search, error handling, and offline mode support.

ValueSet scopes for other resource types ​

Use caseSNOMED hierarchyValueSet URL fragment
Procedures71388002 (Procedure)fhir_vs=isa/71388002
Conditions404684003 (Clinical finding)fhir_vs=isa/404684003
Body structures123037004 (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 OperationOutcome detection pattern
  • Timeout — maintain the 10-second AbortController timeout 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 ​

FailureUser impactOperator action
Ontoserver is downProcedure search shows "Ontoserver did not respond"Monitor CSIRO status; no PPP action
VITE_FHIR_SYSTEM_VERSION staleEvery search returns OperationOutcomeUpdate env var, redeploy frontend
Ontoserver rate-limits PPPIntermittent search failuresEnable offline mode during development
Debounce set too lowToo many requests, Ontoserver rate-limits harderKeep the 350ms debounce in place
Network timeout (>10s)User sees timeout error, can retryNo 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:

Internal documentation — org members only