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

Compliance Testing Write API Tests

Requests and Parameters

Write API tests apply to all requests that change immunisation data in the AIR. For server end points and supported FHIR resource interactions refer to the Open API Specification available under the Support menu in this IG. Use the UAT end points for Compliance Testing.

Tests marked Mandatory / Recommended / Conditional for 'stateful clients' apply to PMS applications, which persist immunisation records locally.

Create, Update and Upsert Tests

Reference Test Test Data Input Compliance Test Evidence Mandatory
AIR-Writer-1 GIVEN I have the appropriate permission
AND a valid NHI
AND immunisation events with values required for completed and not-done immunisation events
WHEN Create API calls are made to create the immunisation events
THEN the Application sends the following elements for each record:
  • person (NHI)
  • status (see Test Data Input)
  • statusReason (see Test Data Input)
  • vaccineCode, reasonCode (Indication)
  • vaccine lot number, expiration date (required for statusReason GIVEN)
  • route, site (required for statusReason GIVEN)
  • occurrence (datetime of administration with Day precision, preferably better - refer to FHIR data types)
  • location (facility HPI-F of patient encounter or system where data is entered)
  • one to two health workers (one Administering Provider and optionally one other provider, both meeting rule nz-prac-1 in the AIR FHIR IG)
AND if the record is persisted locally, then the Application links the record using the AIR Identifier in the response.		 Subscriber's application sends an Immunisation Create request with the minimum data elements for these scenarios:
1) status completed: statusReason GIVEN
2) status completed: statusReason GIVNOS
3) status not-done: any one of DMC, DPC, DIC		 Send the x-correlation-ID header sent with each of the 4 requests and the AIR Identifiers (Immunization.id) received from AIR. Mandatory
AIR-Writer-2 GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event completed in NZ with all fields supported by the Application populated
WHEN a Create API call is made to create the immunisation event
THEN the Application sends the following elements for each record additional to the previous test:
  • dose number
  • diluent lot number, expiration date (when statusReason GIVEN)
  • up to two related persons with relationship code from AIR Related Person Relationship Codes value set
  • serology report (required for statusReason DNI - see Test Data Input)
  • mobile site sub-location identifier (if supported)
  • Administered Product (if supported)
AND if the record is persisted locally, then the Application links the record using the AIR Identifier in the response.		 Subscriber's application sends an Immunisation Create request with all supported data elements for these scenarios:
1) status completed: statusReason GIVEN.
2) status: not-done, statusReason: DNI, vaccineCode one of CVX 05, 43, 52 with serology report.
API Version 1:
3.1) dose number 99
3.2) dose number 98
API Version 2:
3.1) dose number "0"
3.2) dose number ""		 Send the x-correlation-ID header sent with each of the requests and the AIR Identifiers received from AIR. Mandatory
AIR-Writer-3 GIVEN I have the appropriate permission
AND a valid NHI
AND an updated immunisation event completed in NZ with all fields supported by the Application populated
AND the record has an AIR Identifier
WHEN an Update API call is made to update the existing immunisation record using the AIR Identifier
THEN the Application sends updates to the following elements for each record, where supported:
  • status
  • statusReason
  • VaccineCode, Administered Product (if supported)
  • reasonCode, dose number
  • vaccine lot number, expiration date (required for statusReason GIVEN)
  • diluent lot number, expiration date
  • occurrence
  • location, mobile site sub-location identifier (if supported)
  • route, site (required for statusReason GIVEN)
  • one to two related persons
  • one to two health workers
  • serology report (required for statusReason DNI)
 Subscriber's application sends an update Request to an existing Immunisation Record with all supported data elements in addition to the VersionId field in the meta. Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory
AIR-Writer-4 This test only applies if the Application holds local records previously sent to AIR via HL7 messaging.

GIVEN I have the appropriate permission
AND a valid NHI (active or dormant)
AND an updated immunisation event completed in NZ with all fields supported by the Application populated
AND the record does not have an AIR Identifier having been sent successfully to AIR/NIR previously,
WHEN a call is made to $upsert the record
THEN the Application sends updates to the following elements, where supported by the Application:
  • person (NHI)
  • vaccineCode, Administered Product (if supported)
  • dose number, reasonCode (Indication)
  • occurrence (datetime of administration with Day precision, preferably better - refer to FHIR data types)
  • status, statusReason
  • vaccine lot number, expiration date (required for statusReason GIVEN)
  • diluent lot number, expiration date
  • occurrence
  • location, mobile site sub-location identifier (if supported)
  • route, site (required for statusReason GIVEN)
  • one to two related persons
  • one to two health workers
  • serology report (required for statusReason DNI)
AND if the record is persisted locally, then the Application links the record using the AIR Identifier in the response.		 Subscriber's application sends an upsert request with an Immunisation Record containing all supported data elements. Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR. Mandatory (stateful clients)
AIR-Writer-5 GIVEN my application is a consumer of the immunisation Create API
WHEN a call is made to the Create API, or an upsert that will result in creating a record,
AND one or more rejection errors occur
THEN a meaningful message is displayed to the end user in near real time
AND the message provides instruction on what the user needs to do to resolve the problem
AND no data is lost unless the user chooses to discard their entry.

Note: the upsert method applies where the application holds local records it sent to AIR via HL7 messaging. An upsert creates a new record in AIR when edits to the local record affect key fields.		 To cause rejection the Subscriber's Application should send an invalid request (e.g. no VaccineCode).

Suggested methods: allow token to expire or don't request sufficient scope (HTTP 401), omit VaccineCode from the request, supply a coding.display or coding.version value longer than 2048 characters, or an invalid value in a field with Required binding (e.g. status, Administered Product code).		 Send a screenshot showing the message displayed to the end user and the instructions on what they should do.

Provide a list of error messages expected to be displayed to users when AIR responds with the following HTTP status codes: 403, 404, 412, 429, 500.		 Recommended
AIR-Writer-6 GIVEN my application is a consumer of the immunisation Update API
WHEN an API call is made to the Update API, or an upsert that will result in updating a record,
AND one or more rejection errors occur
THEN a meaningful message is displayed to the end user in near real time
AND the message provides instruction on what the user needs to do to resolve the problem
AND no data is lost unless the user chooses to discard their entry.

Note: the upsert method applies where the application holds local records it sent to AIR via HL7 messaging. An upsert updates the record in AIR when edits to the local record do not affect key fields.		 Subscriber's application sends an Immunisation update request with all required data elements except the Vaccine code.

Suggested methods: change local resource version to not match AIR's or work with HNZ TA who can update the record in AIR while PMS edits are uncommitted (HTTP 412), or any method suggested for Create.		 Send the x-correlation-ID sent in the request and a screenshot that shows the message displayed to the end user and what they should do. Recommended
AIR-Writer-7 GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation record that has been withdrawn (invalidated or deleted)
AND the record has an AIR Identifier
WHEN an Update API call is made, or an upsert that will result in updating a record,
THEN the Application sends the following elements for each record:
  • status (entered-in-error)
  • person (NHI, unchanged)
  • any other data available for the record.
AND if the record is persisted locally, then the Application links the record using the AIR Identifier in the response.

Note: the upsert method applies where the application holds local records it sent to AIR via HL7 messaging. An upsert updates the record in AIR when edits to the local record do not affect key fields.		 Subscriber's application sends an update Request to an immunisation record that has been invalidated or deleted. Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR. Mandatory
AIR-Writer-8 This test only applies if the Application supports updates, but does not preserve at event level the NHI number originally submitted.

GIVEN I have the appropriate permission
AND an update to a completed or declined immunisation event successfully created in AIR previously, or successfully created then changed to entered-in-error,
AND the PMS record has an AIR Identifier
AND the patient's NHI number has been updated to a different valid NHI number
WHEN the Application calls the Update API with an NHI number different from the one in AIR for that record
AND the response from AIR contains meta.tag="patient-identifier-immutable"
THEN the Application verifies the NHI number returned is not used by another patient in its system
AND if no conflict exists, then the Application processes the response normally as if the correct NHI had been used, otherwise handles the anomaly in a way the user can understand.		 Test setup procedure: subscriber's application sends an Immunisation Create request for the first NHI value and links the local record to AIR.
Test run procedure: 1. subscriber's application sends an Immunisation Update request with the second NHI value.

The purpose of this test is to validate handling of live and dormant NHI numbers. This scenario is where:
1. An event is first submitted with NHI number A.
2. NHI number A is made dormant so the PMS patient record is updated to B. The Application now knows the patient as B.
3. Following that, in the NHI, A is split from B and made live again. At this point the Application has the record under patient B, but AIR will return NHI number A - possibly now existing in the PMS in their own right.
At some point in this sequence a patient's identity was assigned wrongly then corrected. The immunisation event record in AIR remains associated with the NHI number originally submitted.		 Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional, stateful clients)
AIR-Writer-9 This test only applies if the Application supports updates to legacy records, but does not preserve at event level the NHI number originally submitted.

GIVEN I have the appropriate permission
AND an update to a unique completed, declined immunisation event successfully created in AIR previously, or successfully created then changed to entered-in-error,
AND the PMS record does not have an AIR Identifier
AND the patient's NHI number has been updated to a different valid NHI number
WHEN the Application calls the $upsert API with an NHI number different from the one in AIR for that record
AND the response from AIR contains meta.tag="patient-identifier-immutable"
THEN the Application verifies the NHI number returned is not used by another patient in its system
AND if no conflict exists, then the Application processes the response normally as if the correct NHI had been used, otherwise handles the anomaly in a way the user can understand,
AND the Application links the local record to AIR.

The purpose of this test is to validate handling of live and dormant NHI numbers as above.		 Test setup procedure:
1. Subscriber's application sends an Immunisation Create request for the first NHI value. The record must differ sufficiently from any other so a potential duplicate case doesn't arise.
2. Remove the AIR Identifier from the PMS record.
Test run procedure: 1. subscriber's application sends an Immunisation $upsert request with the second NHI value.		 Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional, stateful clients)
AIR-Writer-10 GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event record that is an exact duplicate of one other immunisation event previously submitted and linked successfully
AND the other immunisation record has an AIR Identifier
WHEN a call is made to the Create API to create the immunisation event
AND the API has responded to the API call with HTTP status 200 an Immunization resource with an AIR Identifier that already exists locally in the Application
THEN the Application invalidates or does not persist the new record
AND the Application informs the user of the outcome.

Note: in this scenario the returned resource contains `meta.tag.code:` "exact-duplicate-not-created" - the application may use this tag to identify when this happens.		 Subscriber's application sends a Create request for an immunisation event record that is an exact duplicate of an immunisation event previously submitted successfully.

For the purposes of this test, an exact duplicate is a record that has status completed or not-done, occurrence datetime exactly the same, and all other values the same except id and meta values. Refer to sheet 'Exact Duplicate Field List'. Applications are expected to instead use the existing record stored in AIR, rather than create an exact duplicate.		 Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing the status message displayed.

Provide evidence of the outcome where there is a single up-to-date record for the immunisation event, with the id of the existing AIR record.

Note that the corresponding Duplicate Resolution NEMS event may be ignored if handled correctly at the time of submission.		 Mandatory
AIR-Writer-11 GIVEN I have the appropriate permission
AND a valid NHI
AND an update to an immunisation event record that now is an exact duplicate of one other immunisation event previously submitted and linked successfully
AND the other immunisation record has an AIR Identifier
WHEN a call is made to the Update API to update the immunisation event
AND the API has responded with HTTP status 201 and an Immunization resource within the body of the response
THEN the Application detects the Potential Duplicate data quality condition
AND the Application informs the user of the outcome.

Note that in this scenario, a NEMS Duplicate Resolution event is published identifying both records.

For the purposes of this test, an exact duplicate is a record that has status completed or not-done, occurrence within the same day NZ time, and all other values the same except id and meta values, with the exception that Rabies and HepB occurrence comparison must be exact. Applications are expected to instead use the existing record stored in AIR, rather than create an exact duplicate.		 Subscriber's application sends an Update request for an immunisation event record that is an exact duplicate of an immunisation event previously submitted successfully. Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing the status message displayed.		 Mandatory
AIR-Writer-12 GIVEN I have the appropriate permission
AND a valid NHI
AND an updated immunisation event completed in NZ which now is an exact duplicate of another immunisation event previously submitted and linked successfully
AND the updated record does not have an AIR Identifier,
WHEN a call is made to $upsert the record
AND the API has responded with HTTP status 200 and an Immunization resource with an AIR Identifier that already exists locally in the Application
THEN the Application invalidates or does not persist the new record
AND if the version is later than the previous record then the Application syncs the previous record
AND the Application informs the user of the outcome.		 Subscriber's application sends an upsert request for an immunisation event record that is an exact duplicate of an immunisation event previously submitted successfully. Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing the status message displayed.

Provide evidence of the outcome where there is an single up-to-date record for the immunisation event, with the id of the existing AIR record.		 Mandatory (stateful clients)
AIR-Writer-13 GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event with a health worker who has an additional practicing credential (nurse, doctor, midwife, paramedic or pharmacist) as an Administering Provider of a vaccination completed in NZ
WHEN an API call is made to create or update or upsert the immunisation event
THEN the Application assigns performer.function.coding.code the value "VC".

Note: the VHW function similarly may only be associated with AIR Vaccinating Health Workers administering vaccinations in NZ.		 Subscriber's application sends an Immunisation Create and Update requests with correct data elements for an administering provider with "VC" role, identified by NZMC, NZNC or CPN identifier. Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional)
AIR-Writer-14 This test only applies where the Application maintains its own identifiers for health workers who have no CPN, VHW, AIR Vaccinating Health Worker or recognised registration identifier.

GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event with a Health Care Assistant or Kaiāwhina Hauora as an Administering Provider of a vaccination completed in NZ
WHEN an API call is made to Create or Update or $upsert the immunisation event
THEN the Application assigns performer.actor.identifier.system the value "https://HCA"

For context, HCA supports the special case where the Responsible Provider is accountable, for traceability to an individual person authorised to administer vaccinations.		 Subscriber's application sends Immunisation Create and Update requests with correct data elements for an individual Administering Provider with no external identifier. Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Recommended (conditional)
AIR-Writer-15 This test only applies if the Application supports updating of records first entered via the AIR Portal on behalf of the facility, for a vaccine not yet supported by the Application.

GIVEN I have the appropriate permission
AND a valid NHI
AND an update to an immunisation given at my facility that was first entered via the AIR portal and recorded in my system from a GET or search result
with a vaccineCode unknown in the version of the AIR Vaccine Product Value Set supported in the Application
WHEN an API call is made to Update the immunisation event,
THEN the Application preserves the vaccineCode.coding.code and .system from the original record.

Note: vaccineCode is one among several fields where the binding to the value set is 'preferred'. In the case of Health Worker identifier.system, no binding is present. WHEN such values are unchanged, value or code and system must be returned verbatim in the update request.		 Test setup procedure: import into the subscriber's application a record from AIR for an Immunisation given at the subscriber's facility, or create an event with a valid TPUU code.
Test run procedure: the subscriber's application sends an Update request for the record.		 Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional)
AIR-Writer-16 This test only applies if the Application supports Administered Products.

GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event with a Administered Product TPUU code
WHEN a Create API or Update API call is made to create or update or upsert the immunisation event
THEN the Administered Product is consistent with the Vaccine Code.		 Test setup procedure: import into the subscriber's application a record from AIR for an Immunisation given at the subscriber's facility.
Test run procedure: the subscriber's application sends an Update request for the record.		 Send the x-correlation-ID sent in the request that was used in the update AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional)
AIR-Writer-17 This test only applies if the Application supports updating of records entered via the AIR Portal for its facilities and either does not support Administered Products or the event's Administered Product is not yet supported locally.

GIVEN I have the appropriate permission
AND a valid NHI
AND an update to an immunisation given at my facility that was first entered via the AIR portal and recorded in my system from a GET or search result
with vaccine and an unknown Administered Product that have not been changed
WHEN an API call is made to Update the immunisation event
THEN the Application preserves the administeredProduct.coding.code and .system from the original record.		 Test setup procedure: import into the subscriber's application a record from AIR for an Immunisation given at the subscriber's facility, which has an unknown administeredProduct.
Test run procedure: the subscriber's application sends an Update request for the record, not changing the vaccine or product details.		 Send the x-correlation-ID sent in the request that was used in the update AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional)
AIR-Writer-18 This test only applies where the Application supports immunisation records with inconsistent dates. Note: HNZ would prefer records with apparent inconsistencies be sent for AIR administrative review.

GIVEN a completed or not-done immunisation event allowed by the application to have inconsistent dates
WHEN the user saves the record
THEN the Application requests confirmation this data is correct
AND the Application handles the Data Quality issue in the response in near real time in a way that is understandable to the user.

Date inconsistencies could include, but are not limited to:
a. occurrence date is before the date of birth or after the date of death
b. occurrence date is in the future for a completed immunisation event
c. occurrence date is after a substance expiry date
d. serology result date in the future, before the date of birth or after the date of death (statusReson=DNI).		 Subscriber's application sends a completed or not-done immunisation event with a date to which the user has responded that it is intentionally inconsistent with other dates. Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing the message that is displayed. An example for one of the scenarios listed should be sent.		 Recommended (conditional)
AIR-Writer-19 GIVEN I have the appropriate permission
AND a valid NHI for a consumer who has Restricted Access
AND an immunisation event for a vaccination completed in NZ that has been successfully created in AIR by the Application
WHEN an API call is made to search for the immunisation event
THEN the Application handles the redacted response without error.		 Set-up procedure: Subscriber's application sends an Immunisation Create request with the minimum data elements for this scenario.
Run procedure: Subscriber's application sends a search request for the consumer.		 Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory
AIR-Writer-20 GIVEN my application is a consumer of the immunisation Update API
WHEN an API call is made to the Update API, Create API or an upsert that will result in updating a record,
AND one or more Data Quality violations occur
THEN a meaningful message is displayed to the end user
AND the message provides instruction on what the user needs to do to resolve the problem.		 Subscriber's application sends an Immunisation create, update and upsert requests with a data quality issue.

What is feasible to test will depend on client-side validation. Typical DQ violations are: CPN fails checksum, performer function not in value set, non-vaccinator registration authority, NHI number passes checksum but not in NHI, status 'completed' with no batch number, event / batch / DoD / DoB date inconsistencies, unrecognised Related Person relationship code.		 Send the x-correlation-ID sent in the requests and screenshots that show messages displayed to the end user and what they should do. Recommended
AIR-Writer-21 This test only applies when the user identifier in the request header is that of a system or other software application, such as an AI tool.

GIVEN I have the appropriate permission
AND a valid NHI
AND I am using software that provides a system-to-system client id in the request
AND an immunisation event given in NZ
WHEN an API call is made to create or update or upsert the immunisation event
THEN performer.actor identifiers are only of natural persons participating in the encounter including the responsible provider.		 Subscriber's application sends an Immunisation Create and Update requests with correct data elements for an administering provider who is the responsible person in the encounter. Send the x-correlation-ID sent in the request that was used in the update and the AIR Identifier received from AIR.

Send a screenshot showing that the version of the Immunisation record was updated.		 Mandatory (conditional)
AIR-Writer-22 GIVEN I have the appropriate permission
AND a valid NHI
AND an immunisation event record that is a double-dose Rabies event differing in time-of-day from one previously submitted and linked successfully
WHEN a call is made to the Create API to create the immunisation event
AND the API has responded to the API call with HTTP status 200
THEN the Application links the new record without error.


Future state: the Data Quality assessment will be 100%, i.e. no data quality issue (ref. IMM-6734).		 Subscriber's application sends a Create request for an immunisation event record that is the same as a successfully submitted immunisation event at a different time on the same day, for a double-dose vaccine. Send the x-correlation-ID header sent with the request and the AIR Identifier received from AIR.

Send screenshots showing the two records.		 Mandatory