Te Whatu Ora Shared Care FHIR API
0.3.9 - release
Te Whatu Ora Shared Care FHIR API
0.3.9 - release
Te Whatu Ora Shared Care FHIR API - Local Development build (v0.3.9) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Like any NZ organisation collecting/sharing patient health information, Te Whatu Ora has to abide by the requirements of the NZ Health Information Privacy Code.
In support of this, the Te Whatu Ora Shared Care API has implemented the following measures:
.provision.data. references in an associated Consent instance.It is up to the each health organisation storing/sharing health information through this FHIR API to
When a client application, authorized by TWO to access the FHIR API (by NIA API key and client credentials), tries to access an instance of
a FHIR resource X of an access-controlled type at a Url like:
FHIR_API_URL/resource-type/X (where X is a resource instance identifier)
The Te Whatu Ora Shared Care API applies consent-based data access control to all instances of the following FHIR resources types (includes profiled variants):
- Appointment
- CarePlan
- Condition
- Encounter
- ServiceRequest
- QuestionnaireResponse
- Goal
- Observation
- Patient
- Person
- EpisodeOfCare
A normal record of a patient consent in the Te Whatu Ora Shared Care API is a FHIR Consent instance in #active status.
In business terms, active status here is used to represent a consent actually obtained from the patient, and current as in not expired.
To be considered valid, an #active Consent instance must:
Be current (current date must fall within Consent.provision.period start and end dates
Be scoped Consent.scope = #patient-privacy
Identify the patient
Consent.patient MUST be a valid FHIR logical reference to a patient by NHI identifier
Reference the prevailing policies (Privacy Act and Health Information Privacy Code) see examples.
Identify how the consent was obtained:
EITHER reference in .sourceReference a FHIR QuestionnaireResponse instance that captures the consenting response,
OR reference in .performer the organisation that obtained the consent (reference by HPI Org id).
Sometimes patient consent is not yet established at the time an application needs to create FHIR resources about that patient.
For example in rheumatic fever patient scenarios it is common for patients to be registered on referral from primary care but those patients’ consents are not officially obtained until the first nurse appointment which can be someway down the track.
To facilitate scenarios like this, the Te Whatu Ora Shared Care API allows for consents to be formed provisionally using the FHIR Consent #proposed status.
This status is intended to represent placeholders for patient consents that will be subsequently obtained, but where an application needs to create FHIR resources earlier than that.
Client FHIR API access to a resource protected by a #proposed Consent has the following additional requirements:
CareTeam which identifes the (HPI) organisations responsible for collecting and managing the patient data,If these two conditions are not met API requests to resource instances covered by a #proposed consent will get an HTTP 403 Forbidden error, and those instances will be redacted in any FHIR search results.
Sometimes patient consent has to be obtained from a person related to the patient, not the patient themselves.
For example in rheumatic fever patient scenarios it is common for patients to be registered on referral from primary care but those patients’ consents are not officially obtained until the first nurse appointment which can be someway down the track.
To facilitate scenarios like this, the Te Whatu Ora Shared Care API consent should represent the related person is a party to the patient’s consent but not the subject of it, as follows:
#datasubject as is usual, andConsent.performer[] entry refers to the RelatedPerson instance.When a resource requiring Consent is requested either by a read, vread or search query, the API will determine if a valid Consent is active for the resource.
When a valid Consent is NOT found, the outcomes seen by the API caller will be as follows.
GET /{consentedResourceType}?_count=25
Response status: 200
Response body:
{
"resourceType": "Bundle",
"id": "38ccf3b4-2bd6-4076-bfa2-66bef78d1fbf",
"meta": {
"lastUpdated": "2022-12-15T19:55:07.892Z",
"security": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "REDACTED",
"display": "redacted"
}
]
},
"total": 41,
"entry": [{consentedResources}]
}
In this request example, a request is made to return _count=25 resources. In this case, for each 25 resources in the result set (entry), the Consent check is performed. If any resources in this result set have been omitted, the meta.security REDACTED tag is added to the search result Bundle. This indicates to the API consumer that some portion of the resource has been filtered and not included in the content returned, and that there may not be 25 resources returned within the Bundle.
GET /{consentedResourceType}/{id}
Response status: 401
Response body:
{
"resourceType": "OperationOutcome",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">error</td><td>[]</td><td><pre>Consent not valid</pre></td></tr></table></div>"
},
"issue": [
{
"severity": "error",
"code": "security",
"diagnostics": "Consent not valid"
}
]
}
In this request example, a request is made to a single resource which does not have an associated Consent. This returned a 401 error.
As a convention the Te Whatu Ora Shared Care FHIR API requires all date and dateTime FHIR values to be recorded in UTC.
Client applications are responsible for converting UTC dateTimes to the timezone of the user and formatting the date and time display according to the user’s preferred locale.
The server will assess currency of a Consent for access purposes using a UTC time comparison with the dates/times in a Consent.period.