New Zealand Rheumatic Fever FHIR Implementation Guide
1.0.0 - draft
New Zealand Rheumatic Fever FHIR Implementation Guide
1.0.0 - draft
New Zealand Rheumatic Fever FHIR Implementation Guide, published by Te Whatu Ora. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/fhir-rheumatic-fever/ and changes regularly. See the Directory of published versions
As a basic protection for FHIR resource types that may contain patient health information, this FHIR API requires valid FHIR Consent instances to be present that reference FHIR resource instances.
See this page for details on representing patient consent using FHIR Consents.
Consider a FHIR API request to GET the instance CarePlan/X where CarePlan is a consent-protected resource type and X is the instance unique identifier.
The FHIR API will permit such a request if:
If the request has suitable OAUTH scopes but the API cannot find a valid Consent instance referencing CarePlan/X, the API rejects the GET request with a 403 Forbidden error.
If the request lacks suitable OAUTH scopes the GET request is rejected with a 401 Not Authorized error.
If the CarePlan/X instance access attempt occurs through a FHIR search, and the instance is not covered by a valid consent, either the search request is rejected or the entry is redacted from search results depending on the deficiency of the request.
The API applies consent-based access control to FHIR requests on the following resource types (includes profiled variants):
- Appointment
- CarePlan
- Condition
- Encounter
- ServiceRequest
- QuestionnaireResponse
- Goal
- Observation
- Patient
- Person
- EpisodeOfCare
A patient consent is normally expected to be represented in a FHIR Consent instance in #active status,
which is meant to reflect a consent actually obtained from the patient.
To be considered valid for API access, an #active Consent instance must:
Have a permitting provision (Consent.provision.type of #permit),
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 .organization (or .performer) the organisation that obtained the consent and is custodian of the patient data.
On the other hand when a patient opts out (declines to give consent) for data sharing, a FHIR Consent resource will represent this using an #active status but with a Consent.provision.type of #deny as illustrated below.
Applications may create a Consent in a #proposed state.
This is a placeholder for patient consent that is anticipated, but an application needs to create other FHIR resources before the consent can actually be obtained.
Rules for accessing FHIR resources protected by a #proposed Consent are yet to be defined by Health NZ but are likely to involve
the requesting party following a 'break-glass' protocol and their API client presenting an additional btg OAUTH scope in the access token.
When patient consent is obtained from a person related to the patient, not the patient themselves, an application may create a Consent instance with the .performer identifying the related person.
No special rules for API access to FHIR resources protected by an on-behalf Consent have yet been defined by Health NZ.
When a resource requiring Consent is requested either by a FHIR read, vread or search operation, the API will determine if a valid Consent is active for the resource according to the rules described above.
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": ["..."]
}
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.