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 NHI/HPI API NHI/HPI API 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 up Request-Context : "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. [02] GET / DocumentReference ?<params> [03] check for existing terms acceptance No current terms-acceptance for this practitioner/user [04] Prepare Terms Acceptance Form Form is prepared as a FHIR Questionnaire for the current Practitioner and Org (from Request-Context ) [05] Form Url ("magic link") [06] Prepare OperationOutcome 403 response break [Practitioner terms acceptance sub flow] [07] HTTP 403 Forbidden error with magic link On receipt of a 403 response, the PMS/APP must check for a link in the FHIR OperationOutcome.diagnostics property. The PMS/APP shall redirect the user's browser to that link to dispay the prepared Terms Acceptance form. [08] Display form via browser redirect [09] Read form and accept special terms [10] POST /QuestionnaireResponse (with Request-Context header) Request-Context custom header must set "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. [11] Extract and record acceptance submission [12] Practitioner terms acceptance complete The practitioner/user can now resume the request for screening summaries in the PMS. API request processing can now proceed - see Typical Operation diagram
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
