Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V2)
2.0.0-SNAPSHOT - ci-build
New Zealand
Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V2)
2.0.0-SNAPSHOT - ci-build
New Zealand
Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V2) - Local Development build (v2.0.0-SNAPSHOT) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Search and Read API tests apply to all applications accessing immunisation data.
For server end points refer to the Open API Specification available under the Support menu in this IG. Use UAT end points for Compliance Testing.
Search: POST https://api_endpoint/Immunization/_search - with patient reference parameter in the body of the request
Read: GET https://api_endpoint/Immunization/{id}
Both requests support the optional _include parameter, which enriches the response with data from NHI and HPI.
| 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:
|
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://fhir-ig-uat.digital.health.nz/air/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:
|
The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for the following NHI numbers |
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://fhir-ig-uat.digital.health.nz/air/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 ZHZ9215 |
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: Restricted Access 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 provides an NHI with restricted access to immunisation history WHEN an API call is made THEN the application display makes it clear to me that the immunisation history is redacted. |
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: ZKC4641 Has 7 events: - 1 with DQ Pass - 2 with minor issues (Body Site & Route) - 2 with major issues (Vaccine Code & Expiry Date) - 1 with moderate issue (Indication) - 1 with 3 DQs (Body 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 
|
Mandatory |
| 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 ZDH3572 has events with status not-done and completed (GIVNOS, HSTGIVN) or ZMM8521 has set of events that have all statuses 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.
|
Mandatory |