FHIR & Standards
SPICE uses HL7 FHIR (release R4) as its clinical data store. Clinical records are not held in a bespoke relational model with FHIR as an export format. They are stored natively as FHIR resources, and the other platform services read and write them through a thin mapping layer.
Components
FHIR server
A HAPI FHIR JPA server backed by PostgreSQL. It is the system of record for clinical data. It is based on the upstream HAPI FHIR JPA server starter, with SPICE customisations (below).
FHIR mapper service
Translates the platform's domain objects (households, members, screenings, assessments, prescriptions, follow-ups and so on) to and from FHIR resources. It is the only application service that builds FHIR resources and talks to the FHIR server.
Other platform services
Call the mapper over REST for clinical reads and writes. They keep non-clinical data (users, organisations, geography, configuration) in their own PostgreSQL databases.
Analytics ETL
A batch job that reads FHIR resources and loads flat reporting tables. See Analytics.
How clinical data is mapped
Writes from the platform arrive at the mapper as domain objects. The mapper builds the matching FHIR resources and submits them to the FHIR server as a single FHIR transaction bundle, so that the resources belonging to one clinical event are saved together or not at all. Reads work in the opposite direction: the mapper issues FHIR searches, follows paging links, and converts the returned resources back into domain objects.
Resources are mostly linked with standard references (for example an Observation points at its Encounter, and an Encounter points at its subject and participants).
Resources in use
The table below lists the resource types the mapper builds or queries. The list reflects the code, but the exact set used in a deployment depends on which programmes and workflows are enabled.
Patient
Registered patients.
RelatedPerson
Household members, who are the people services are delivered to in community workflows.
Group
Households.
Encounter
Each visit, screening, assessment or review. It is the anchor for the clinical data captured in that event.
Observation
Measurements and answers: blood pressure, glucose, vitals, symptoms, pregnancy and other clinical values.
Condition
Diagnoses, including whether a diagnosis is active.
MedicationRequest, MedicationDispense
Prescriptions and their fulfilment.
ServiceRequest, Appointment
Referrals and scheduled follow-up.
CarePlan
Treatment plans.
Immunization
Vaccination records.
DiagnosticReport
Laboratory and investigation results.
QuestionnaireResponse
Form responses that do not map to a more specific resource.
Organization, Location, Practitioner
Facilities and administrative areas, geographic position of a household or visit, and the health workers who deliver care.
Provenance
Who recorded a change, and when (see below).
Other resource types appear in a small number of workflows (for example Coverage, Procedure, Device and MedicationStatement).
Provenance
Writes carry a Provenance resource recording the user who performed the action and the time it was recorded. This lets offline-captured data keep its original author and timestamp even though it reaches the server later (see Offline Sync Design).
Identifiers and versioning
Business identifiers. SPICE does not add its own fields to FHIR resources. It tags resources with
Identifierentries whose system is a SPICE-defined URI under a configurable base. These carry classification such as the kind of encounter or observation, the village or area a record belongs to, a patient's national or programme identifier, and household numbers. Because the base URI is configuration, an installation can use its own namespace.Custom search parameters. The mapper registers a small set of additional FHIR search parameters at start-up, for example searching Patient and RelatedPerson by national identifier, finding Conditions with an active diagnosis, and filtering by enrolment date. These make common lookups efficient without scanning resources client-side.
Resource IDs. The FHIR server assigns each resource a numeric logical ID from a sequence. When the optional partitioning feature (below) is used, ID ranges are allocated per administrative area so that areas can later be moved to separate database servers without renumbering.
Versioning. Updates create a new version of a resource, as in standard FHIR. Updates to existing records are normally sent as
PUTs, which creates a new version and advances the resource's last-updated time. Downstream consumers use that last-updated time, or the version history, to find what changed.
FHIR server customisations
The server stays close to upstream HAPI so that it can follow upstream releases. The SPICE-specific additions are:
Authentication
Each request must carry a bearer token, which the server validates against the platform's authentication service. Validation can be switched off for local development.
Database
PostgreSQL, with schema changes managed by migrations. This includes the custom search parameters and geolocation definitions used by SPICE.
Partitioning
Optional scaling features (below).
Packaging
A minimal container image with telemetry support, and deployment manifests and Helm charts.
Exposing data: REST API and search
Clinical data is available through the standard FHIR REST API (read, search, create, update, transaction bundles) on the FHIR server. Every request must present a valid bearer token (see customisations above). In the reference deployment the platform services are the callers.
Searches use standard FHIR parameters (_count, _sort, _include, reference and token searches) plus the custom parameters above. Large result sets are paged with the standard next link.
For the REST API surface, see the FHIR server's own capability statement and the HAPI FHIR documentation.
Preparing data for analytics
Analytics does not query the FHIR REST API. A batch ETL job reads the stored resource JSON from the FHIR server's PostgreSQL database, enriches it with administrative data such as the geography hierarchy and user and facility reference data, and writes denormalised reporting tables to a separate reporting database. The stable contract is the FHIR resource content, not the FHIR server's internal tables.
The job runs incrementally, using a watermark on the resource-version history.
It processes the FHIR resource types needed for reporting (for example Encounter, Observation, Condition, Immunization, medication resources, household and member resources).
The watermark advances only when all consumers of a resource type have succeeded, so a failed run is retried rather than skipped.
Dashboards and BI tools then read the reporting database. See the analytics documentation for the downstream pipeline.
Interoperability with other systems
FHIR REST. Because data is stored as R4 resources with a standard API, any FHIR-capable client can read or write it, subject to authentication and the server's identifier conventions.
Bulk and analytics export. Analytical use is served by the ETL above.
Aggregate reporting platforms. The facility and reporting service contains configuration for pushing summary reports to a DHIS2-style aggregate reporting platform.
Optional: database partitioning
For deployments that span many administrative areas (for example several districts or regions) the FHIR server supports partitioning by administrative area. It is a scaling and data-isolation feature, and it is optional in the sense described below.
Multi-area (default configuration)
Requests are routed to a partition per administrative area. Clinical resources live in their area's partition. Shared reference data (practitioners, organisations, code systems, value sets and similar) lives in a common default partition.
Single partition
A configuration switch pins every operation to the default partition, with no area routing. It is intended for deployments that do not need per-area separation.
Notes for implementers:
The partition-aware database schema is always applied. The switch changes request routing, not the schema, so it cannot be turned off in an existing database.
Physical PostgreSQL table partitioning on the largest tables is a separate, manual, administrative step that operators run in a maintenance window. It is never run automatically at start-up.
The mapper, the CQL service and the analytics ETL each have their own matching setting. Keep all of them consistent with the server's mode.
Per-area resource ID ranges are an additional option for preparing to move areas onto separate database servers.
See the FHIR server's customisation notes in its repository for the full list of settings and a non-partitioned installation recipe.
Standards followed
HL7 FHIR R4
Data model and API of the FHIR server and mapper.
LOINC
Used for coding some observation concepts and value sets.
SNOMED CT
Used for coding clinical concepts in observations and conditions.
Last updated