Health NZ | Te Whatu Ora FHIR Screening Implementation Guide - Local Development build (v1.0.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
API consumption sequence diagrams
FHIR screening summary API typical operation
Cervical screening summary API - typical sequence HNZ digital services hub / connector plane HNZ FHIR APIs health practitioner (screening) health practitioner (screening) NZ health app/PMS NZ health app/PMS API authn. server API authn. server API gateway API gateway Screening FHIR API Screening FHIR API HNZ FHIR API HNZ FHIR API National Health Index / Health Provider Index National Health Index / Health Provider Index 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 " normal API usage [03] enter patient name, NHI [04] NHI search [05] present NHI matches [06] request screening summaries for selected NHI and programme type App/PMS supplies metadata in Request-Context : "userIdentifier " - userId as known to PMS/app "purposeOfUse":"SCREENING " "useFullName " - user's name "hpiFacility " - facility identifier for the user's location from Health Provider Index "registrationAuthorityNumber " - The practitioner number and Registration Authority that issued it "hpiPractitioner " (if available) - practitioner's Common Person Number (CPN) from Health Provider Index [07] GET /DocumentReference?{search-params} [08] validate OAUTH token (issuer,sig) [09] GET / DocumentReference ?<params> break alt [Bad/missing access OAUTH token (issuer, scope, audience, expiry)] [10] HTTP 401 error: Unauthorized alt [Bad/missing Request-Context custom header] [11] HTTP 400 error: Bad Request [12] Search for Terms Acceptance Forms by Facility + Practitioner GET /QuestionnaireResponse?subject=X&source=Y [13] MATCHES [14] Confirm Practitioner and Facility Terms Acceptance alt [normal report generation] [15] get data from backend APIs [16] generate screening summary content as HTML and PDF [17] include participant data as Patient instance [18] 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] [19] 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] [20] HTTP 4xx|5xx error code In technical error scenarios, the response is just a FHIR OperationOutcome [21] process results and display to user [22] present screening summary / search result
User/practitioner special data access terms acceptance sequence
Cervical screening API data access - Practitioner terms acceptance form flow HNZ FHIR APIs health practitioner (screening) health practitioner (screening) NZ health app/PMS NZ health app/PMS Screening FHIR API Screening FHIR API Health Provider Index Health Provider Index HNZ FHIR API HNZ FHIR API HNZ Application Form API HNZ Application Form API API first time use by new practitioner/user [01] request screening summary for a patient [02] Get screening summaries by NHI GET / DocumentReference ?<params> [03] search Terms Acceptance by facility GET /QuestionnaireResponse?subject=<hpiFacility> [04] MATCH [05] search Terms Acceptance by practitioner GET /QuestionnaireResponse?subject=<hpiPractitioner> [06] NO MATCH alt [The practitioner user has not previously accepted the Terms of Access] [07] Searches for Practitioner and Facility [08] HPI details break [HPI identifier validation failures] alt [Practitioner Id not valid] [09] HTTP 400 Bad Request alt [HPI Facility Id not valid] [10] HTTP 400 Bad Request [11] Generate Terms Acceptance Form POST /v1/auth/{formName}/generate-questionnaire-link A Terms Acceptance form is prepopulated with practitioner, facility and organisation details as sent by the PMS. [12] Prepare Form [13] Prepopulated Form Url (aka 'magic link') [14] Prepare OperationOutcome 403 response containing 'magic link' [15] HTTP 403 Forbidden error + 'magic link' On receipt of a 403 response, the App/PMS must check for magic link in the FHIR OperationOutcome.diagnostics property. [16] Display form in browser using magic link [17] Read special terms of access; complete form; submit to accept [18] Record practitioner's acceptance of terms [19] 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.
