Health NZ | Te Whatu Ora FHIR Screening Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
API consumption sequence diagrams
FHIR API authentication and authorization checks
Cervical screening API data access - API request prerequisite checks HNZ digital services hub HNZ FHIR APIs health practitioner (screening) health practitioner (screening) practitioner's APP/PMS practitioner's APP/PMS API authn. server API authn. server API gateway API gateway screening summary FHIR API screening summary FHIR API NHI/HPI API NHI/HPI API API consumer OAUTH authentication at PMS initialisation [01] OAUTH2.0 Client Credentials Flow (client creds, scopes, audiences) [02] OAUTH token "scope": [ "system/DocumentReference.rs", "system/Patient.r" ] "aud": "https://fhir-ig.digital.health.nz/screening/StructureDefinition/nz-screening-summary " DSH "Connector Plane" and FHIR API authorization checks [03] request a screening summary PMS/APP must set up Request-Context custom header correctly: "userIdentifier " - user Id as known/authenticated by the PMS/APP "userRole " - the role of the user as defined by the PMS/APP "secondaryIdentifier " - the user's health organisation as an HPI organisation identifier. [04] GET /DocumentReference? [05] validate OAUTH token (issuer,token,scopes,sig) break [Bad/missing access token] [06] HTTP 401 error: Unauthorized [07] GET /DocumentReference?.. [08] validate OAUTH token (issuer,token,scope,audience) break [Bad/missing access token] [09] HTTP 401 error: Unauthorized Validate Request-Context custom header [10] check Request-Context required attributes break [Bad Request-Context] [11] HTTP 400 error: Bad Request alt [If HPI Practitioner Id in secondary identifiers] [12] check HPI practitioner id break [Practitioner Id not found in HPI] [13] HTTP 400 error "invalid HPI Practitioner Id" alt [If HPI Organisation Id supplied as secondary identifier] [14] check HPI org id break [Organisation Id not found in HPI] [15] HTTP 400 error "invalid HPI Organisation Id" API request processing can now proceed - see Typical Operation diagram
User/practitioner special data access terms acceptance sequence
Cervical screening API data access - special terms practitioner acceptance flow HNZ FHIR APIs health practitioner (screening) health practitioner (screening) practitioner's APP/PMS practitioner's APP/PMS screening summary API screening summary API HNZ FHIR API (AWS FHIRWorks) HNZ FHIR API (AWS FHIRWorks) FHIR forms services FHIR forms services initialisation and prequisite API checks Refer to authorization sequence diagram first time API use by new practitioner/user [01] request screening summary for a patient PMS/APP must set a valid Request-Context for each FHIR API request containing: "userIdentifier " - the practitioner Id as an HPI Practitioner Id. "userRole " - the role of the user as defined by the PMS/APP "secondaryIdentifier " - the user's health organisation as an HPI Organisation Id. "purposeOfUse " - set to XXX "HPIFacilityIdentifier " - the HPI Facility ID of the facility the practitioner is currently working in [02] GET / DocumentReference ?<params> [03] check for existing terms acceptance GET /QuestionnaireResponse [04] no matches alt [No current terms-acceptance for this practitioner/user] [05] Generate Terms Acceptance Form 1-time link POST /v1/auth/{formName}/generate-questionnaire-link The screening summary API must set two magic link claims in the link generation request based on identifiers supplied by the PMS: 1. "source" : an HPI Practitioner reference 2. "author" : an HPI Organisation reference A FHIR Questionnaire is configured to prepopulate these values in the QuestionnaireResponse submitted from the magic link. [06] Prepare Form [07] Form pre-signed Url (aka 'magic link') [08] Prepare OperationOutcome 403 response containing presigned Url 'magic link' [09] HTTP 403 Forbidden error + 'magic link' On receipt of a 403 response, the PMS/APP must check for a link in the FHIR OperationOutcome.diagnostics property. [10] Display form in browser using magic link [11] Read form special terms; submit to accept [12] POST /QuestionnaireResponse FHIR QuestionnaireResponse instance created in this step: - Specifies the FHIR Questionnaire which defines the HNZ terms of practitioner API access to HPV data. - Identifies the practitioner and their health org (as passed by the PMS). - Records details of their acceptance of the terms in items specified by the FHIR Questionnaire . [13] [14] Practitioner terms acceptance complete API request processing can now proceed - see Typical Operation diagram Now that terms acceptance has been recored, the practitioner/user can retry their request for screening summaries in the PMS.
FHIR screening summary API typical operation
Cervical screening summary - Typical API Operation HNZ FHIR APIs health practitioner (screening) health practitioner (screening) practitioner's APP/PMS practitioner's APP/PMS screening summary FHIR API screening summary FHIR API NHI FHIR API NHI FHIR API initialisation and prequisite API checks Refer to authorization sequence diagram normal API usage [01] enter patient name, NHI [02] NHI search [03] present NHI matches [04] request screening summaries for selected NHI and programme type Request-Context custom header must be setup by PMS/APP "userIdentifier " - user Id as known/authenticated by the PMS/APP "userRole " - the role of the user as defined by the PMS/APP "secondaryIdentifier " - the user's health organisation as an HPI organisation identifier. [05] GET / DocumentReference ?<params> search request query parameters: ? subject:identifier = <NHI> & category = <screening service type SNOMED> & contenttype = application/pdf & _include = DocumentReference:subject [06] validate OAUTH token (issuer,token,scope,audience) [07] validate Request-Context custom header alt [normal report generation] [08] get data from backend APIs [09] generate screening summary content as HTML and PDF [10] include participant data as Patient instance [11] 200 OK , FHIR searchset Bundle In normal search response is a FHIR searchset Bundle. Each Bundle entry comprises a DocumentReference (mode:#match) containing the formatted screening summary, AND a Patient (mode:#include) instance for the patient demographic detail [No screening summary is available] [12] 200 OK , Bundle of mode: #outcome When screening history not available for specified subject, the Bundle contains one or more OperationOutcome s ( mode: #outcome ) describing the reason(s). [technical error] [13] HTTP 4xx|5xx error code In technical error scenarios, the response is just a FHIR OperationOutcome [14] process results and display to user [15] present screening summary / search result
