Te Whatu Ora Shared Care FHIR API
0.3.9 - release New Zealand flag

Te Whatu Ora Shared Care FHIR API, published by Te Whatu Ora. This guide is not an authorized publication; it is the continuous build for version 0.3.9 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/cinc-fhir-ig/ and changes regularly. See the Directory of published versions

Consent Based Access Control

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:

  1. Client applications MUST record the patient’s actual (or provisional) consent to TWO collecting their health information using instances of the FHIR Consent resource on this server, and
  2. For all FHIR resource types that may contain patient health information, the FHIR API controls access to resource instances based on presence of a valid referencing Consent resource instances, and
  3. The actual FHIR resource instances to be protected MUST be reference in FHIR .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

  • Operate a process which obtains patient consent, and
  • Arrange for their FHIR-integrated application to call the FHIR API to create appropriate FHIR Consent resources representing the state of patients’ consents.

Access control measure

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)
  • This API permits access to X only when a valid Consent instance is found that references X - this allows all FHIR client applications authorized by Te Whatu Ora to access the resource instance.
  • If the API finds no valid Consent instance that references X, access is denied to all FHIR client applications (including the application that created the resource instance).

Resource types protected

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:

  1. Be current (current date must fall within Consent.provision.period start and end dates

  2. Be scoped Consent.scope = #patient-privacy

  3. Identify the patient
    Consent.patient MUST be a valid FHIR logical reference to a patient by NHI identifier

  4. Reference the prevailing policies (Privacy Act and Health Information Privacy Code) see examples.

  5. 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:

  1. The proposed consent MUST include a provision referencing a CareTeam which identifes the (HPI) organisations responsible for collecting and managing the patient data,
  2. The health application accessing the FHIR API MUST be using client credentials associated with one of the HPI organisations in the CareTeam described in (1).

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:

  1. The consent provision identifies the patient in its #datasubject as is usual, and
  2. A RelatedPerson resource defines the related party (by name is sufficient) and their relationship to the patient. (The RelatedPerson can be simply a contained instance within the Consent, or can be a separate server resource representation if needed), and
  3. An additional Consent.performer[] entry refers to the RelatedPerson instance.

API behaviours

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.

read, vread

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.


Example data models

HNZ FHIR API resources under managementACTIVE patient consent and provisions ^All resource instances protected by this consentCOVEREDprivacy questions:QuestionnaireactiveConsentExample:Consentstatus:#activescope:#patient-privacydateTime:2023-01-21policy: reference to NZ Privacy Act / HIPCdata access provision:Consent.provisiontype:#permitperiod:2023-01-21 to ..patient's responses:QuestionnaireResponseresource x1:Xresource y1:Y«logical resource»Patient(NHI)logical id: NHI«logical resource»HPI:OrganizationParty agreeing to privacy policy/rulesHPI Org Id:+ GXXNNN^ Consent instances do not themselves needto be covered by other Consentsdata.referencesourceReferencepatientReference(Organization)performer[0]questionnaireNotes(black dashed lines) An active consent MUST reference EITHER a QuestionnaireResponse OR an OrganizationFHIR instance data model - active patient consent scenarioHealth NZ/Te Whatu Ora. Generated from PlantUML source on 02/05/2024



HNZ FHIR API resources under managementactive patient consent given on-behalfAll resource instances protected by this consentCOVEREDprivacy questions:QuestionnaireactiveConsentExample:Consentstatus:#activescope:#patient-privacydateTime:2023-01-21policy: reference to NZ Privacy Act / HIPCdata access provision:Consent.provisiontype:#permitperiod:2023-01-21 to ..person giving consentRelatedPersonname.given: Berylname.family: Hackettrelationship:#PRNpatient's responses:QuestionnaireResponseresource x1:Xresource y1:Y«logical resource»Patient(NHI)logical id: NHI«logical resource»HPI:OrganizationParty agreeing to privacy policy/rulesHPI Org Id:+ GXXNNNNote how the RelatedPerson is a containedresource of the consent and also linked as anadditional performer.data.referenceperformer[1]patientsourceReferencepatientperformer[0]Reference(Organization)questionnaireNotes(black dashed lines) An active consent MUST reference EITHER a source QuestionnaireResponse OR an Organization as one performerFHIR instance data model - patient consent given on-behalf by related person scenarioHealth NZ/Te Whatu Ora. Generated from PlantUML source on 02/05/2024



HNZ FHIR API resources under managementrepresentation of provisional consentResource instances protectedby this consentCOVEREDProposed consent example:Consent ^(ManaakiNgaTahiConsent)status:#proposedscope:#patient-privacycategory:#npp Notice of Privacy PracticesdateTime:2023-06-12 (UTC)policy: reference to NZ Privacy Act / HIPCdata access provision:Consent.provisiontype:#permitperiod:2023-09-21 to ..actor (RF service):provision.actoractor.role:#datacollectoractor (patient):provision.actoractor.role:#datasubjectdata collector orgs.:CareTeamresource x1:Xresource y1:Y«logical resource»Patient(NHI)logical id: NHI«logical resource»HPI:OrganizationRheumatic Fever ServiceHPI Org Id:+ GXXNNN-CNew Zealand Rheumatic Fever Service|- Northland RF Secondary Prevention Service|- Counties Manakau RF Secondary Prevention Service|- .. x16 regional orgs ..data.referenceReference(CareTeam)actor.referenceactor.referenceReference(Organization) participant.member.referencepatientReference(Organization)performer[0]Notes^ Consent resource instances are not subject to consent-based access control.FHIR instance data model - provisional patient consent scenarioHealth NZ/Te Whatu Ora. Generated from PlantUML source on 02/05/2024