Health NZ | Te Whatu Ora FHIR Screening Implementation Guide
1.0.2 - normative+trial-use New Zealand flag

Health NZ | Te Whatu Ora FHIR Screening Implementation Guide - Local Development build (v1.0.2) 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 sequenceHNZ digital services hub /connector planeHNZ FHIR APIshealth practitioner (screening)health practitioner (screening)NZ health app/PMSNZ health app/PMSAPI authn. serverAPI authn. serverAPI gatewayAPI gatewayScreening FHIR APIScreening FHIR APIHNZ FHIR APIHNZ FHIR APINational Health Index /Health Provider IndexNational Health Index /Health Provider IndexAPI 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 typeApp/PMS sets the following user metadata inRequest-Context  "hpiPractitioner" - practitioner's Common Person Number (CPN) from Health Provider Index  "hpiFacility | hpiOrganisation" - HPI facility OR organisation identifier from Health Provider Index[07]GET/DocumentReference?{search-params}[08]validate OAUTH token(issuer,sig)[09]GET /DocumentReference?<params>error scenariosbreak[Bad/missing access OAUTH token (issuer, scope, audience, expiry)][10]HTTP 401 error: Unauthorizedbreak[Bad/missingRequest-Contextcustom header][11]HTTP 400 error: Bad Requestbreak[Practitioner | Organisation | Facility Id not valid][12]HTTP 400 Bad Request (HPI_INVALID)[13]Search for Prior Terms Acceptance FormsSearch for FHIR QuestionnaireResponsesGET /v1/QuestionnaireResponseQueries based on available params: Org/facilityacceptance search byfacility:      ?questionnaire=https://fhir-ig.digital.health.nz/screening/Questionnaire/TermsOfUseOrgFacility      &subject:identifier=FZZ958-K Org/facilityacceptance search byorg:      ?questionnaire=https://fhir-ig.digital.health.nz/screening/Questionnaire/TermsOfUseOrgFacilityr      &subject:identifier=GZZ956-B Practitioneracceptance search byfacility:    ?questionnaire=https://fhir-ig.digital.health.nz/screening/Questionnaire/TermsOfUsePractitioner    &author:identifier=91ZABY    &subject:identifier=FZZ958-K Practitioneracceptance search byorg:    &author:identifier=91ZABY    &subject:identifier=GZZ956-B[14]MATCHES[15]Check matching Org/Facility Terms of Useacceptancebreak[No Terms of Use acceptance by org/fac][16]HTTP 403 Forbidden (NO_TOU_ORGFAC)[17]Confirm matching Practitioner Terms of Useacceptancealt[normal report generation][18]get data from backend APIs[19]generate screening summary content as HTMLand PDF[20]include participant data as Patient instance[21]200 OK, FHIR searchset BundleIn normal search response is a FHIR searchset Bundle. EachBundle entry comprises aDocumentReference (mode:#match)containingthe formatted screening summary, AND aPatient (mode:#include) instance for the patient demographic detail[No screening summary is available][22]200 OK, Bundle of mode: #outcomeWhen screening history not available for specified subject, the Bundle contains oneor moreOperationOutcomes (mode: #outcome) describing the reason(s).[technical error][23]HTTP 4xx|5xx error codeIn technical error scenarios, the responseis just a FHIROperationOutcome[24]process results and display to user[25]present screening summary / search result


User/practitioner special data access terms acceptance sequence

Cervical screening API data access - Practitioner terms acceptance form flowHNZ FHIR APIshealth practitioner (screening)health practitioner (screening)NZ health app/PMSNZ health app/PMSScreening FHIR APIScreening FHIR APIHealth Provider IndexHealth Provider IndexHNZ FHIR APIHNZ FHIR APIHNZ Application Form APIHNZ Application Form APIAPI first time use by new practitioner/user[01]request screening summary for a patientApp/PMS sets the following user metadata inRequest-Context  "hpiPractitioner" - practitioner's Common Person Number (CPN) from Health Provider Index  "hpiFacility | hpiOrganisation" - HPI facility OR organisation identifier from Health Provider Index[02]Get screening summaries by NHI  GET /DocumentReference?<params>[03]Search for completed Terms AcceptanceForm by Practitioner at current Org | Facility   GET /v1/QuestionnaireResponse    ?questionnaire=https://fhir-ig.digital.health.nz/screening/Questionnaire/TermsOfUsePractitioner        &author:identifier=91ZABY        &subject:identifier=GZZ956-B Or where facility identified rather than org      &subject:identifier=FZZ958-K[04]Empty Bundlealt[The practitioner user has not previously accepted the Terms of Access]Validate HPI identifiers[05]Validate Practitioner, Org / Facility identifiers[06]HPI match Bundlebreak[Practitioner | Organisation | Facility Id not valid][07]HTTP 400 Bad Request (HPI_INVALID)Prepare Terms Acceptance Form[08]Generate Terms Acceptance Form  POST /v1/auth/{formName}/generate-questionnaire-linkThe facade prepares a Terms Acceptance form by sending informationabout the practitioner, organisation | facility in magic linkclaims.[09]Prepare Form[10]Prepopulated Form Url (aka 'magic link')[11]Prepare OperationOutcome 403 responsecontaining 'magic link'[12]HTTP 403 Forbidden(PRACTITIONER_TOU_ACCEPT_NEEDED) + 'magic link'On receipt of a 403 response, the App/PMS must check for magic linkin the FHIROperationOutcome.diagnosticsproperty.[13]Display form in browser using magic link[14]Read special terms of access; complete form;submit to accept[15]Record practitioner's acceptance of terms[16]Practitioner terms acceptance completeAPI 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.