# Immunisation Update Message - Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1) v1.28.0-SNAPSHOT

* [**Table of Contents**](toc.md)
* **Immunisation Update Message**

## Immunisation Update Message

Also known as GP notifications.

## Immunisation Update Message Overview

An ‘Immunisation Update Message’ interaction is initiated by ImmSOT when it wishes to notify interested parties that a new immunisation has been recorded or an existing immunisation is updated. The notification can be either an 'HL7' message or via the NEMS messaging service.

The request includes details of the patient who received the immunisation, the next of kin who attended the immunisation encounter, the immunisation itself, the pracitioner who administered the immunisation and the PMS systems to which the message should be sent. At a later time, after the health provider has processed the request, they send a response back to the nominated endpoint indicating if the immunisation request has been accepted or declined.

If the patient has opted to suppress access to their immunisation records, an 'Immunisation Update Message' notification **will not be sent** to either the Enrolled facility or the Immunization event facility.

### Immunisation Update Message Request

#### Immunisation Update Message Request processing steps:

1. ImmSOT creates the immunisation record
1. Notification record is created in ImmSOT
1. Notification batch process runs
1. lookup up all pending notification records
1. Lookup enrolled facility from NHI service
1. Populate Immunisation event details from DB
1. Publish event to NEMS
1. If the Recording facility uses HL7
1. Publish HL7 RESEND request to the AIR Orchestration server**$process-message**endpoint. (EventType=IMMUNISATION_UPDATE)
1. Update ACK record status

1. If the Enrolled facility uses HL7
1. Publish HL7 RESEND request to the AIR Orchestration server**$process-message**endpoint. (EventType=IMMUNISATION_UPDATE)
1. Update ACK record status


1. lookup up all unacknowledged notification records
1. Populate Immunisation event details from DB
1. Publish HL7 RESEND request to the AIR Orchestration server**$process-message**endpoint.
1. Update ACK record status

1. The Orchestration server enriches the Patient reference with additional patient details
1. The Orchestration server enriches the Pracitioner reference with additional pracitioner details
1. The Orchestration server determines which PMS systems should be notified of the new Immunisation, based on the value of the**air-immunisation-notification-action-code**.
1. The Orchestration server gets the facility id and edi of the nominated target PMS systems
1. The Orchestration server creates a message for each target PMS and sends it to the Healthlink Air Broker
1. The Healthlink Air Broker transforms the message to an HL7 v2.0 VXU^V04 request and sends it to the PMS
1. The Healthlink Air Broker returns a synchronous 202 response to the Orchestration server
1. Once it has recieved responses form each request sent to the HealthLink AIR broker, the Orchestration server sendsa synchronous 202 response to ImmSOT, containing information about each message which was sent.

#### Immunisation Update Message Request Example - ImmSOT To Orchestration

[update-immunisation-request3](Bundle-82020190.json.md) - RESEND

#### Immunisation Update Message Request Example - Orchestration To HealthLink

[update-immunisation-request1](Bundle-72178030.json.md)

#### Business Rules

1. Requests which specify a processing flag value of 'D' in the bundle **meta.tag[0].code** element should be treated as debug messages. The server must ensure that processing these messages results in no change to production data. They server should return a success response to indicate that it is healthy, and failure response to indicate that it is unhealthy
1. If the ID of the Immunisation resource matches an ID held in the receiving system then the message should be treated as an update rather than a create. This should be regarded as a full update rather than a delta, so the existing Immunisation record should be replaced with the Immunisation resource in the request
1. The **air-immunisation-notification-action-code** is used by Orchestration server to determine which PMS systems messages should be sent to as described in the table below

| | |
| :--- | :--- |
| **RESEND** | send an immunisation notification message to the facilityId in**MessageHeader.destination.name** |

​
1. The Orchestration server will return a 202 if one or messages are successfully sent
1. If one message fails with a 50x (from Healthlink or HIP) and the other succeeds or gets a 40x, the Orchestration server returns a 202 response with an OperationOutcpome. The message which returns a 50x will have error code**TBC**within the OperationOucome issue
1. If Orchestration server fails with a 50x for both messages it should return a 50x response and raise an operational alert

#### Response Codes

One of the following a synchronous error response may be returned by the server

| | | | |
| :--- | :--- | :--- | :--- |
| Success | 202 | OperationOutcome | The message has been accepted for processing |
| Server Error | 50x | empty | An unexpected error occurred on the part of the server. The client may resend the message at a later time once the server is issue is resolved |
| Data Error | 400 | OperationOutcome | If the server cannot process the message due to a data error, it should return a 400 error with an OperationOutcome in the body describing the error |
| Data Error | 429 | OperationOutcome | If the server cannot process the message because it under too much load it should return a 429 error with an OperationOutcome with OperationOutcome.issue[].code= "throttled" |
| Other processing errors | 40x | empty | Other 40x errors may be returned by intermediary gateways (e.g. 401 Unauthorized). These may not provide an OperationOutcome |

#### Response Body

The Response body may contain an OperationOutcome resource describing the result of the request message processing. Since the Orchestration server may have sent two separate messages to HealthLink for a single ImmSOT request, the OperationOutcome it returns to ImmSOT may contain two Issue elements, each describing the outcome of a separate notification message. The **OperationOutcome.Issue[n].expression** field should be used to hold the facility id of the target PMS to which the message was sent. The table below describes how the OperationOutcome should be populated

| | | |
| :--- | :--- | :--- |
| OperationOutcome.issue |   | 0..n |
| OperationOutcome.issue[].severity | error | 1 |
| OperationOutcome.issue[].code | processing (or throttled for 429) | 1 |
| OperationOutcome.issue[].diagnostics | Details of the error | 0..1 |
| OperationOutcome.issue[].expression | FacilityId of the PMS to which the message was sent | 0..1 |

Population of he issue.details will element be depend on the source of the error:

| | | | |
| :--- | :--- | :--- | :--- |
| OperationOutcome.issue[].details.coding.code | HIP | HIP error code | 1 |
| OperationOutcome.issue[n]details.coding.system | HIP | https://standards.digital.health.nz/ns/hip-error-code | 1 |
| OperationOutcome.issue[].details.coding.code | HealthLink | AA or AE | 1 |
| OperationOutcome.issue[n]details.coding.system | HealthLink | http://terminology.hl7.org/CodeSystem/v2-0008 | 1 |

#### Example Response from Orchestration to ImmSOT

This is an example of a case where Orchestration server sends two immunisation update messages to two PMS systems in response to a single request from ImmSOT. One of the messages is successfully sent to Healthlink and one fails

[update-immunisation-request-response1](OperationOutcome-update-immunisation-request-response-message-1.json.md)

Here is a second example, similar to the first except one of the messages fails due to a 429. ImmSOT should respond by backing off and retrying

[update-immunisation-request-response2](OperationOutcome-update-immunisation-request-response-message-2.json.md)

### Immunisation Update Message Response

#### Immunisation Update Message Response processing steps:

1. The PMS sends an HL7v2.0 VXU^V04 ACK message to the Healthlink Air Broker indicating if the immunisation update request has been accepted or not
1. The Healthlink Air Broker creates a bundle containing an OperationOutcome with an appropriate Result Code and sends it to the Orchestration server's**$process-message**endpoint (eventType=IMMUNISATION_UPDATE_ACK).The**MessageHeader.response.identifier**should hold the value of the**Messageheader.id**of the message being acknowledged.
1. The Orchestration server forwards the response message to the ImmSOT server's**$process-message**endpoint.
1. ImmSOT returns a synchronous 200 response to the Orchestration server.
1. The Orchestration server returns a synchronous 200 response to the Healthlink Air Broker.

#### Response Codes

The response codes which may be sent in response to an Immunisation Update Message Response message are the same as those described for Immunisation Update Message Request [Responses Codes](immunisationUpdateMessage.md#responses-codes)

The Orchestration Server should simply forward whatever it receives from ImmSOT

#### Immunisation Update Message Response Example

[update-immunisation-response-message-1](Bundle-update-immunisation-response-message-1.json.md)

### HL7 Message Definitions

[Update Immunisation Request](MessageDefinition-UpdateImmunisationRequestMessageDefinition.md)

[Update Immunisation Response](MessageDefinition-UpdateImmunisationResponseMessageDefinition.md)

