Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1)
1.27.0 - release New Zealand

Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1) - Local Development build (v1.27.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## Compliance Testing Base API Tests

### Compliance Testing Important Information

#### Compliance Testing Process

Please provide the following details in a test report and email it to integration@health.govt.nz.

1. Tester Details
   - Organisation Name
   - Application name and version
   - Application HSAPP ID (if applicable)
   - AIR FHIR IG Version
   - Test Script Version
   - Testing Start Date and Time and End Date and Time
   - Tester Name and Contact Details
   - List of Operations Included in Your Integration (e.g., AIR Read, AIR Write)
2. For each test supply screen shots of the user interface for:
   - The input data as entered in the integrating application (“the application”)
   - The output:
     - Any error messages presented by the application
     - The confirmation or result of the request presented by the application
     - For update operations the state of the record pre-request should be included
     - Note: If non-interactive, please provide JSON request (update / create) or response (get)
3. For each test supply a timestamp when each request is sent.

#### Test Data

AIR uses test identifiers from the NHI UAT environment. To access a list of NHI test identifiers follow this link. For a set of current format identifiers and look for heading NHI Test identifiers and for new format NHI test identifiers see NHI records Mod23.

Please do not update/change any of the immunisation data in the table below. These have been specifically set up for compliance.

NHI | Description
--- | ---
ZMM7002 | Full set of completed childhood immunisations (no anomalies) +ZDH3912
ZUA48EH | No immunisation events
ZMM8521 | Full set of statuses & status reasons
ZJM9567 | Travel vaccinations
ZKC4641 | Vaccinations with data quality issues - 3 events
ZDH3530 | Vaccinations with maximum characters 3 events: vaccine source text field has 255 char, lotNumber is 50 char, body site is 18 char Also has Data Quality issues including; body site code, route code, unrecognised vaccine code, vaccine batch exp date, vaccine diluent exp date
ZMM8637 | Multiple events that cannot display on a single page - can also use ZMM7002
ZDH3343 (D) ZDH3351 (D) ZDH3335 (L) | Live NHI with at least 2 dormant NHIs associated to it Can also use ZAT2518 (D) ZAT2496 (L)
ZFE35PQ | Suppressed immunisation history
ZXE24NV | New format NHI (7 digits)
ZHS7524 | Historic immunisations, from a period with data that does not comply to current standards
ZAA0547 | DOD 2016-05-12 Has Imms prior to 2016 DOB is 1954-11-01
ZDH3475 | Minimum data - mandatory fields only
ZDH3769 | Minimum Data - ISD
ZDH3513 | Max data - all fields are populated
ZKL2308 | Has selection of non-done and status reasons, incl 1 entered-in-error
ZMN6354 | Has mix of status and status reasons: not-done (DPC / DMC / RESCHO) GIVNOS (given overseas), HSTGIVN (Historic)

#### Links

Description | Link
--- | ---
Health NZ Aotearoa Immunisation Register – Immunisation API | https://www.tewhatuora.govt.nz/health-services-and-programmes/digital-health/digital-services-hub/explore-apis-digital-services/aotearoa-immunisation-register-immunisation-api
How to access Health NZ Digital Services Hub | https://www.tewhatuora.govt.nz/health-services-and-programmes/digital-health/digital-services-hub/consumer-onboarding
AIR FHIR Implementation Guide | https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html

### Compliance Tests

Not all compliance tests in this implementation guide will be appropriate for every application. If there are tests that do not apply please discuss this with the integration team and where appropriate write a description in the compliance test submission why the particular test does not apply.

Mandatory vs Optional tests

- If there are tests below that are labelled mandatory but do fit the application's use case then please let us know why.

- Some tests are labelled mandatory if. These tests are Mandatory only if you are using this piece of data for your use case.

To request a template for the compliance tests either add a comment to your onboarding request form or reach out using the Enquiry form.

#### Search API Compliance Tests

Endpoint for AIR Search API

https://api.uat.air.digital.health.nz/s2s/fhir/R4/Immunization/_search

Reference | Requirement | Purpose | Test | Test Data Input | Compliance Test Output | Mandatory
--- | --- | --- | --- | --- | --- | ---
AIR-Base-1 | RBAC: Role-Based Access Control (RBAC) | The application demonstrates the ability to ensure only authorised users are allowed to access clinical immunization information. | 1a. Given my application is a subscriber to the immunisation history (Search Immunisation) API And I am an authorised user with an authenticated application And I am classified as registered workforce or working on behalf of a person classified as registered workforce When I navigate to view immunisation history information Then an API call can be made And the Application displays Immunisation history information 1b. Given my application is a subscriber to the immunisation history (Search Immunisation) API And I am an authorised user with an authenticated application And I am NOT classified as registered workforce or working on behalf of a person classified as registered workforce When I navigate to view immunisation history information Then an API call can NOT be made And the Application does NOT display Immunisation history information And the application displays a message stating that authorisation has failed. | 1a. Subscriber's Application calls the Immunisation History (Immunisation Search) API and passes the NHI number to the API only when a user authorised to view AIR immunisation data is logged in to the Application. 1b. Subscriber's Application logged in user is NOT authorised to view AIR immunisation data. | 1a. Screenshot/s showing the subscriber's application screen/s displaying the Immunisation History information only when an authorised user who is classified as registered workforce or working on behalf of a person classified as registered workforce is logged in to the Application. 1b. Screenshot/s showing the same application screen/s NOT displaying the Immunisation History information when the user logged in to the Application does not have authorisation, with the authorisation failure message that is displayed to the user, or other evidence they are denied access. Web application screen shots should include the URL attempted to be accessed, showing spoofing attempt failing. | Mandatory
AIR-Base-2 | Request context header appropriately populated | The Request-Context HTTP header is populated in each request/API call with correct information as specified in the Request-Context.json schema | Given my application is a subscriber to the immunisation history (Search Immunisation) API When an API call is made Then the Request-Context header properties are populated as specified in the schema and base-64 encoded. The schema is defined in: https://github.com/tewhatuora/schemas/blob/main/json-schema/Request-Context.json Te whatu ora will validate your request and verify it includes the request context information. | The subscriber's Application sets the following fields in the Request-Context HTTP header: userIdentifier: the subscriber's Application logged in user. facilityIdentifier: the HPI-F code assigned to the Facility secondaryIdentifier: If the person triggering the request is not registered with any New Zealand health body on the list provided, values must remain empty (empty string). userRole and purposeOfUse are also required. For detail on each attribute see README.md and Developer Guide | Send a screenshot showing the logged in user Send the context-header in plain text including userIdentifier, facilityIdentifier and secondaryIdentifier, for example:
            {
              "userIdentifier":"pms-user-id-123",
              "userRole":"PROV",
              "secondaryIdentifier":{
                  "use":"official",
                  "system":"https://standards.digital.health.nz/ns/medical-council-id",
                  "value":"RA99Z"
              },
              "purposeOfUse":[
                  "POPHLTH"
              ],
              "userFullName":"Beverly Crusher"
            }
| Mandatory
AIR-Base-3 | Credentials: ensure the value assigned to userIdentifier reflects the Application's logged-in user | userIdentifier within the Request-Context changes when different end users are initiating the request | Given my application is subscribed to the Immunisation History (Search Immunisation) API When a new API call is made Then the sending user's userIdentifier must correspond to the currently logged-in user. | Repeat the above Test AIR-Base-2 with a different user being logged to the subscriber's application. | Send a screenshot showing the logged in user Send the X-Correlation-ID and the value that have been set for the userIdentifier field in the context-header | Mandatory
AIR-Base-4 | Credentials: Universally Unique ID (UUID) in the Correlation ID | Each request has a UUID in the X-Correlation-ID field If present this will be returned in the response | Given my application is a subscriber to the immunisation history (Search Immunisation) API When an API call is made Then a universally unique ID is present in the X-Correlation-Id HTTP header | Subscriber application sets the x-correlation-id to a unique auto generated value (ideally GUID) in API calls, for example the previous two tests AIR-Base-2 and AIR-Base-3 should set the x-correlation-id to different unique values. | Send x-correlation-id or screenshot that shows them for each API request/call, for example the previous two tests AIR-Base-2 and AIR-Base-3 should have set the x-correlation-id to different unique values. | Mandatory
AIR-Base-5 | Error Handling and messages to end users | The application has robust error handling and ensures meaningful, friendly error messages are displayed. | Given my application is a subscriber to the immunisation history (Search Immunisation) API When an API call is made And an error occurs Then a meaningful, friendly message is displayed And if possible the message provides instruction on what the user needs to do. User experience should be tailored according to user needs. The OperationOutcome diagnostics text could be displayed to the end user for generic error-handling. | Send an Immunisation Search Request for an invalid NHI (e.g. "ZZZ0B12") | Send a Subscriber's Application screenshot showing the message displayed to the end user with the Application window displayed when the error occurred. | Mandatory
AIR-Base-6 | Application can appropriately handle rate limiting (HTTP 429) | The application has robust error handling and ensures meaningful, friendly error messages are displayed. | Given my application is a subscriber to the immunisation history (Search Immunisation) API When an API call is made and the application receives 429 error code having reached its usage plan limit Then the application handles this gracefully by informing the user to wait few seconds or it displays an hourglass icon as a way of backing off before sending another request. User experience should be tailored according to user needs. The OperationOutcome diagnostics text could be displayed to the user for generic error-handling. | The application reaches its usage plan limit and it receives HTTP 429 response code then it handles this gracefully, for example informing the user to wait few seconds, or displaying an hourglass icon as a way of backing off before sending another request. | Please provide estimates and evidence where available of peak API request rates and volumes, to ensure your application is assigned the correct rate-limiting tier by HNZ - by default rate limiting will be set at Bronze level (1 request per second, 10,000 requests per day). Also, Either Send a Subscriber's Application screenshot showing the message displayed to the end user with the Application window displayed when the error occurred. OR State that you are aware that AIR APIs have rate limiting and that you do not expect the number of requests that your application will make to exceed the AIR plan limit you are requesting. | Mandatory (no test evidence required but it is Mandatory the application handle this)

#### Read API Compliance Tests

Endpoint for AIR Read API

https://api.uat.air.digital.health.nz/s2s/fhir/R4/Immunization/{ID}

Reference | Requirement | Purpose | Test | Test Data Input | Compliance Test Output | Mandatory
--- | --- | --- | --- | --- | --- | ---
AIR-Reader-1 | The application demonstrates the ability to handle a dormant NHI. AIR could return search results that contain live and dormant NHI numbers and we expect the application to handle this. In other words the AIR response may contain Immunization resources with an NHI number that differs from the one provided in the search. Note that the Patient resource included in the AIR response identifies the live NHI and any dormant NHIs for that patient. | The application demonstrates the ability to handle Immunisation search results that contain live and dormant NHIs. | Given my application has the appropriate permission And my application uses a dormant NHI number for a search When an API call is made Then the application displays person information for the live NHI And I can see all NHI numbers for the person distinguishing live from dormant And I can see all immunisation history related to the person | Subscriber's application sends an Immunisation Search request for a dormant NHI number ZDH3343. Notes: • If the application does not support searching using dormant NHI numbers, then search using the live NHI number ZDH3335. • The patient's other dormant NHI number is ZDH3351. | Send the subscriber's application screenshots that show immunisation history in full context including the NHI searched for, distinguishing the dormant from live NHIs. Ensure at least 1 screenshot is supplied with the full application screen showing how the immunisation history and live and dormant NHIs are displayed on screen. | Mandatory
AIR-Reader-2 | Data integrity: Minimum data displayed accurately | The application demonstrates the ability to display clinically important elements and data is displayed in the expected format as specified in the Aotearoa Immunisation Register (AIR) FHIR Implementation Guide https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html | Given my application has the appropriate permission And the NHI has multiple immunisation records When an API call is made Then the Application should display the following key elements for each record: - person (NHI) - status - statusReason - vaccine Display Name - vaccine (product display name), if it is provided in the response - dose number - reasonCode (Indication) - occurrence - date/time And the data is displayed to the user in the format specified in the Aotearoa Immunisation Register (AIR) FHIR Implementation Guide | The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for the following NHI numbers ZDH3769 - typical immunisation details, including Product Name ZJM9567 - has dose 98 representing null dose number ZDH3513 - has dose 99 representing early-life Dose 0 | ​ The subscriber's Application sends a screenshot showing the values for the key elements stated in the test for the specific NHI and specific ImmSOT identified in the test Data input As a minimum the guidance for fields to display is based on ISD (Te Whatu Ora Immunisation Frontend System), where the vaccination history table displays: Date Vaccine Product Name (if provided) Dose Number Age Given Status Status reason Record details - link to full display of each individual immunisation record. Screenshot is from ISD and is result of selecting the link detailed in above screenshot. | Mandatory
AIR-Reader-3 | Data integrity: No truncation | The application demonstrates the ability to display the maximum allowable sizes for all immunisation data fields as specified in the Aotearoa Immunisation Register (AIR) FHIR Implementation Guide https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html | Given my application has the appropriate permission And my application is providing an NHI with an immunisation record with maximum allowable size data fields When an API call is made Then the Application displays the maximum allowable size for all immunisation data fields And no data is truncated | The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for NHI number ZDH3530 | Send a screenshot for the Subscriber's Application showing the lotNumber field displayed The lotNumber for the rZV immunisation event has the maximum characters: BiglotNumberthatisupto50characterslong-ZZ-12345678 This NHI (ZDH3530) has 7 events in total, and is also used in Air-reader-7 as 5 of the events have data quality issues | Mandatory
AIR-Reader-4 | Message to end user: Suppressed immunisation history | The application demonstrates the ability to indicate that a person has a restricted immunisation history | Given my application has the appropriate permission And my application is providing an NHI with suppressed immunisation history When an API call is made Then the application display makes it clear to me that the immunisation history is suppressed | The subscriber's Application sends a search request for Immunisation History (Search Immunisation) using the NHI number ZFE35PQ or sends a read request for Immunization resource ID: 30D1312B-6896-465F-93D9-AAE34EAC59F1 | ​ Send a screenshot for the Subscriber's Application showing a clear message to the end user that the Immunisation History for this Patient is restricted. The following is returned in ISD for NHIs that have restricted data: This consumer has chosen to restrict access to their immunisation records held in the AIR. | Mandatory
AIR-Reader-5 | Message to end user: This consumer has no vaccination records to display | The application demonstrates the ability to indicate that a person has no immunisation history despite search being successful | Given my application has the appropriate permission And my application is providing an NHI with no immunisation history When an API call is made Then the application display makes it clear to the end user that the AIR did respond successfully but the NHI does not have any immunisation events/history | The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for NHI number ZUA48EH | Send a screenshot for the Subscriber's Application showing a clear message to the end user that there are no vaccination records to display for this Patient, in full context of the application showing the NHI being searched for. | Mandatory
AIR-Reader-6 | Application is able to display all immunisation events | The application demonstrates the ability to display all immunisation events for a patient. | Given my application has the appropriate permission And my application is providing an NHI with multiple immunisation events When an API call is made Then the application displays all events returned | Input NHI: ZMM8637 NHI has 32 completed immunisation events | Send screen shots that clearly show all immunisation events returned. Note, this can be displayed on separate pages. If the application is limited to a set number of rows e.g. 20, demonstrate how the user is able to view all immunisation event. | Mandatory
AIR-Reader-7 | Applications displays records with data quality flags appropriately | When certain data quality issues are present, the 'display' field is not in the API payload, in which case the Application should use 'code', and if code is not present, then 'unknown' or nothing should be displayed. | Given my application has the appropriate permission And my application is providing an NHI with immunisation events that contain data quality issues When an API call is made Then the application displays all events returned including fields with data quality | Input NHI: ZDH3530 Has 7 events: - 2 with DQ Pass - 2 with minor issues (body site & route) - 2 with major issues (vax code & expiry date) - 1 with 3 DQs (site, route & diluent expiry date) | ​ Send screen shots that clearly show all immunisation events returned. If an event has a DQ the response will not return the "display", example below has 'needle' instead of IM or SC. Therefore, a display field is not returned in the Search payload. Guidance is that if the application is taking data from "display" then if this is blank we recommend to take what is in the "code" field. Should the code field be blank, then 'unknown' to be displayed |
AIR-Reader-8 | Applications displays records that have status of not-done with the reason | The application demonstrates the ability to display all immunisations events for a patient that have the status of not-done and the reason the event was not completed. Applications can filter events returned to return only completed in the first instance, but users must be able to view all events. | Given my application has the appropriate permission And my application is providing an NHI with multiple immunisation events that include events with a status of 'not-done' and a status reason (e.g. declined by parent) When an API call is made Then the application is able to display all events returned | Input NHI: ZKL2308 Has 9 events - - 2 x RV1 not-done (DPC, RESCHO) - 3 x PCV10 not done (DMC, RESTC, DNI) - 3 x DTaP-IPV-Heb/Hib. 2 completed (GIVEN), 1 not-done (RESREF) - 1 x MMR not-done (DIC) - 1 x MMR entered-in-error ZMN6354 has events of not-done and also GIVNOS HSTGIVN or ZMM8521 has set of events that have all status and status reasons | ​ Screenshots that clearly show immunisation events returned. If the application is filtering the events by status and initially only displays the 'completed' events, then it must show that the user is able to display all events if needed. e.g. |