Breast Screening NZ FHIR Implementation Guide
1.1.0 - Release

Breast Screening NZ FHIR Implementation Guide - Local Development build (v1.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Developer Guide

HTTP Header Details

  • This is a list of any additions to standard HTTP header protocol

Request Headers

HTTP Header (Key) HTTP Header (Value) Description Mandatory / Recommended / Optional
Authorization Bearer {string} The OAuth2 access token Mandatory
X-Correlation-Id {string} Client provided
All requests should contain a unique transaction id in the X-Correlation-Id field
If present in the request this will be returned in the response, and can be used to track API calls
Preferred less than 64 characters
Recommended
Content-Type Application/json Supported content type Mandatory
request-context base64 Audit information Mandatory

References

References to Patients and Provider Organisations should be in the form of Logical References

  • e.g. the logical reference to the subject of a CarePlan would look like this
 "subject": {
          "type": "Patient",
          "identifier": {
            "value": "ZXE24NV"
          }

It is the responsibility of the client to determine the correct URL to sue when resolving the reference. The Patient identifier will always be an NHI, and it should be resolved by calling the the NHIPatient service The Organisation identifier will always by an HPI Org ID, and it should be resolved by calling the the HPIOrganization service.

Security

OAUTH2

This FHIR API uses standard OAUTH bearer token authentication.

All requests to this FHIR API must include an access token in the Authorization header.

​Authorized clients can obtain access tokens from the Health New Zealand authorization server (KeyCloak) using OAUTH2 Client Credentials flow to request the necessary OAUTH SMART scopes.

Scopes

See API for a description of the scopes required for each operation.

Request context

All FHIR API requests must include metadata about the context of usage for the application consuming the API. This is done by setting properties in the Request-Context custom header (which is a string containing a Base64-encoded JSON object).

property Required? Attribute value
userIdentifier YES The userid of the user as authenticated by RFCCS or other authorized PMS/health application.
purposeOfUse YES Set to "POPHEALTH"
userFullName YES Display name of the user of RFCCS or the PMS/health application.
hpiOrganisation YES The HPI Organisation identifier (format GAAANNN-A) for Secondary Prevention Service the application user is working within
hpiPractitioner optional If available, the HPI Practitioner identifier (Common Person Number) of the user
hpiFacility optional If available, the HPI Facility identifier of the health facility where the application is being used

The schema for defining and validating these properties can be found here

An example request context follows illustrating FHIR API access on behalf of the Northland / Te Tai Tokerau RF Secondary Prevention Service:

{
  "userIdentifier": "11AAbb@#",
  "purposeOfUse": "POPHLTH",
  "userFullName": "Alice Archer",
  "hpiOrganisation": {
    "type": "Organization",
    "identifier": {
      "use": "official",
      "system": "https://standards.digital.health.nz/ns/hpi-organisation-id",
      "value": "G0M086-B"
    }
  }
}