Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1) - Local Development build (v1.28.0-SNAPSHOT) 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. Do not update/change any of the immunisation data or NHI records in the table below. These consumers and related data are reserved for these compliance tests.

To access a list of NHI test identifiers follow this link and search for text NHI Test Data. To specifically test the new NHI number format, go to Upcoming Changes to the NHI and download the spreadsheet under the heading 'Change to the check digit algorithm'.

Links

Compliance Test Structure

Test Specifications are grouped as follows.

Base API Compliance Testing

• Base tests apply to all types of request to AIR APIs.

Search and Read Compliance Testing

• These tests apply to all applications accessing immunisation data.

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.

Create, Update, Upsert, NEMS and NZHTS tests are not given here, as any new API Clients are required to use version 2 or later of this API.

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 (conditional). These tests apply only if you are using this data or functionality for your use case.

• ​A template for reporting compliance test results is available here: AIR_Compliance - Template v1.2.docx

• For further information, either add a comment to your onboarding request form or reach out using the Enquiry form.

Base Tests

Base API tests apply to all types of request to AIR APIs. For server end points refer to the Open API Specification available under the Support menu in this IG. Use the UAT end points for Compliance Testing.

        {
          "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"
        }
        

Search and Read API Tests

Requests and Parameters

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}

• Search supports the optional _include parameter, which enriches the response with data from NHI and HPI.

Search and Read Tests

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://fhir-ig.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: 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 ZHZ9398 - 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://fhir-ig.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