# Compliance Testing Base API Tests - Aotearoa Immunisation Register (AIR) FHIR Implementation Guide v2.1.0

* [**Table of Contents**](toc.md)
* **Compliance Testing Base API Tests**

## 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](mailto: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)

1. 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)
 

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

#### Links

* Description: Health NZ Aotearoa Immunisation Register – Immunisation API
  * Link: [https://www.tewhatuora.govt.nz/health-services-and-programmes/digital-health/digital-services-hub/explore-apis-digital-services/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)
* Description: How to access Health NZ Digital Services Hub
  * Link: [https://www.tewhatuora.govt.nz/health-services-and-programmes/digital-health/digital-services-hub/consumer-onboarding](https://www.tewhatuora.govt.nz/health-services-and-programmes/digital-health/digital-services-hub/consumer-onboarding)
* Description: AIR FHIR Implementation Guide
  * Link: [https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html](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](https://mohapis.atlassian.net/servicedesk/customer/portal/3/group/35/create/112).

#### Search API Compliance Tests

Endpoint for AIR Search API

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

* Reference: AIR-Base-1
  * Requirement: RBAC: Role-Based Access Control (RBAC)
  * Purpose: The application demonstrates the ability to ensure only authorised users are allowed to access clinical immunization information.
  * Test: 1a. Given my application is a subscriber to the immunisation history (Search Immunisation) APIAnd I am an authorised user with an authenticated applicationAnd I am classified as registered workforce or working on behalf of a person classified as registered workforceWhen I navigate to view immunisation history informationThen an API call can be madeAnd the Application displays Immunisation history information1b. Given my application is a subscriber to the immunisation history (Search Immunisation) APIAnd I am an authorised user with an authenticated applicationAnd I am NOT classified as registered workforce or working on behalf of a person classified as registered workforceWhen I navigate to view immunisation history informationThen an API call can NOT be madeAnd the Application does NOT display Immunisation history informationAnd the application displays a message stating that authorisation has failed.
  * Test Data Input: 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.
  * Compliance Test Output: 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: Mandatory
* Reference: AIR-Base-2
  * Requirement: Request context header appropriately populated
  * Purpose: The Request-Context HTTP header is populated in each request/API call with correct information as specified in the Request-Context.json schema
  * Test: Given my application is a subscriber to the immunisation history (Search Immunisation) APIWhen an API call is madeThen 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](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.
  * Test Data Input: 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](https://github.com/tewhatuora/schemas/blob/main/README.md)and[Developer Guide](https://github.com/tewhatuora/schemas/blob/main/Developer%20Guide%20System-to-System%20authentication%20%20clinical%20applications.pdf)
  * Compliance Test Output: Send a screenshot showing the logged in userSend 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: Mandatory
* Reference: AIR-Base-3
  * Requirement: Credentials: ensure the value assigned to userIdentifier reflects the Application's logged-in user
  * Purpose: userIdentifier within the Request-Context changes when different end users are initiating the request
  * Test: Given my application is subscribed to the Immunisation History (Search Immunisation) APIWhen a new API call is madeThen the sending user's userIdentifier must correspond to the currently logged-in user.
  * Test Data Input: Repeat the above Test AIR-Base-2 with a**different**user being logged to the subscriber's application.
  * Compliance Test Output: Send a screenshot showing the logged in userSend the X-Correlation-ID and the value that have been set for the userIdentifier field in the context-header
  * Mandatory: Mandatory
* Reference: AIR-Base-4
  * Requirement: Credentials: Universally Unique ID (UUID) in the Correlation ID
  * Purpose: Each request has a UUID in the X-Correlation-ID fieldIf present this will be returned in the response
  * Test: Given my application is a subscriber to the immunisation history (Search Immunisation) APIWhen an API call is madeThen a universally unique ID is present in the X-Correlation-Id HTTP header
  * Test Data Input: 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.
  * Compliance Test Output: 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: Mandatory
* Reference: AIR-Base-5
  * Requirement: Error Handling and messages to end users
  * Purpose: The application has robust error handling and ensures meaningful, friendly error messages are displayed.
  * Test: Given my application is a subscriber to the immunisation history (Search Immunisation) APIWhen an API call is madeAnd an error occursThen a meaningful, friendly message is displayedAnd 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.
  * Test Data Input: Send an Immunisation Search Request for an invalid NHI (e.g. "ZZZ0B12")
  * Compliance Test Output: Send a Subscriber's Application screenshot showing the message displayed to the end user with the Application window displayed when the error occurred.
  * Mandatory: Mandatory
* Reference: AIR-Base-6
  * Requirement: Application can appropriately handle rate limiting (HTTP 429)
  * Purpose: The application has robust error handling and ensures meaningful, friendly error messages are displayed.
  * Test: Given my application is a subscriber to the immunisation history (Search Immunisation) APIWhen an API call is made and the application receives 429 error code having reached its usage plan limitThen 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.
  * Test Data Input: 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.
  * Compliance Test Output: 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,EitherSend a Subscriber's Application screenshot showing the message displayed to the end user with the Application window displayed when the error occurred.ORState 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: 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: AIR-Reader-1
  * Requirement: 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.
  * Purpose: The application demonstrates the ability to handle Immunisation search results that contain live and dormant NHIs.
  * Test: Given my application has the appropriate permissionAnd my application uses a dormant NHI number for a searchWhen an API call is madeThen the application displays person information for the live NHIAnd I can see all NHI numbers for the person distinguishing live from dormantAnd I can see all immunisation history related to the person
  * Test Data Input: 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.
  * Compliance Test Output: 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: Mandatory
* Reference: AIR-Reader-2
  * Requirement: Data integrity: Minimum data displayed accurately
  * Purpose: 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](https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html)
  * Test: Given my application has the appropriate permissionAnd the NHI has multiple immunisation recordsWhen an API call is madeThen 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/timeAnd the data is displayed to the user in the format specified in the Aotearoa Immunisation Register (AIR) FHIR Implementation Guide
  * Test Data Input: 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
  * Compliance Test Output: 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 inputAs 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![](assets/images/search-api-air-reader2-1.png)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.![](assets/images/search-api-air-reader2-2.png)
  * Mandatory: Mandatory
* Reference: AIR-Reader-3
  * Requirement: Data integrity: No truncation
  * Purpose: 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](https://healthnz-prm.gitlab.io/air/air-api-fhir-ig/index.html)
  * Test: Given my application has the appropriate permissionAnd my application is providing an NHI with an immunisation record with maximum allowable size data fieldsWhen an API call is madeThen the Application displays the maximum allowable size for all immunisation data fieldsAnd no data is truncated
  * Test Data Input: The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for NHI number**ZDH3530**
  * Compliance Test Output: Send a screenshot for the Subscriber's Application showing the lotNumber field displayedThe lotNumber for the rZV immunisation event has the maximum characters:BiglotNumberthatisupto50characterslong-ZZ-12345678This 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: Mandatory
* Reference: AIR-Reader-4
  * Requirement: Message to end user: Suppressed immunisation history
  * Purpose: The application demonstrates the ability to indicate that a person has a restricted immunisation history
  * Test: Given my application has the appropriate permissionAnd my application is providing an NHI with suppressed immunisation historyWhen an API call is madeThen the application display makes it clear to me that the immunisation history is suppressed
  * Test Data Input: 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
  * Compliance Test Output: 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.*![](assets/images/search-api-api-air-reader4.png)
  * Mandatory: Mandatory
* Reference: AIR-Reader-5
  * Requirement: Message to end user: This consumer has no vaccination records to display
  * Purpose: The application demonstrates the ability to indicate that a person has no immunisation history despite search being successful
  * Test: Given my application has the appropriate permissionAnd my application is providing an NHI with no immunisation historyWhen an API call is madeThen 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
  * Test Data Input: The subscriber's Application sends an Immunisation History (Search Immunisation) API Request for NHI number**ZUA48EH**
  * Compliance Test Output: 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: Mandatory
* Reference: AIR-Reader-6
  * Requirement: Application is able to display all immunisation events
  * Purpose: The application demonstrates the ability to display all immunisation events for a patient.
  * Test: Given my application has the appropriate permissionAnd my application is providing an NHI with multiple immunisation eventsWhen an API call is madeThen the application displays all events returned
  * Test Data Input: Input NHI:**ZMM8637**NHI has 32 completed immunisation events
  * Compliance Test Output: 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: Mandatory
* Reference: AIR-Reader-7
  * Requirement: Applications displays records with data quality flags appropriately
  * Purpose: 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.
  * Test: Given my application has the appropriate permissionAnd my application is providing an NHI with immunisation events that contain data quality issuesWhen an API call is madeThen the application displays all events returned including fields with data quality
  * Test Data Input: 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)
  * Compliance Test Output: 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![](assets/images/search-api-air-reader7-1.png)![](assets/images/search-api-air-reader7-2.png)
  * Mandatory: 
* Reference: AIR-Reader-8
  * Requirement: Applications displays records that have status of not-done with the reason
  * Purpose: 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.
  * Test: Given my application has the appropriate permissionAnd 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 madeThen the application is able to display all events returned
  * Test Data Input: 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 HSTGIVNor**ZMM8521**has set of events that have all status and status reasons
  * Compliance Test Output: 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.![](assets/images/search-api-air-reader8.png)
  * Mandatory: 

