New Zealand NES IG
1.4.6 - Release

New Zealand NES IG - Local Development build (v1.4.6) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Enrolment Nomination

Enrolment Nomination Overview

An ‘Enrolment Nomination ’ interaction is initiated by a user who wishes to request that a health provider enrol a patient for a health service. The request includes details of the patient, the Patient’s guardian and in some cases the provider. At a later time, after the health provider has processed the request, they send a response back to the nominated endpoint indicating if the enrolment request has been accepted or declined.

Enrolment Nomination Request

Enrolment Nomination RequestWhaihuaWhaihuaNESNESHealthlink Air BrokerHealthlink Air BrokerPMSPMS1. POST[base]/$process-message2. validate and enrich3. POST[base]/$process-message4. Transform to HL7 v2[]5. ADT^28 request6. 202 Response7. 202 Response

Enrolment Nomination Request processing steps:

  1. Whaihua creates a bundle containing Patient, RelatedPerson and MessageHeader resources and posts it to the NES $process-message endpoint.
  2. NES validates and enriches the message with additional Patient details and posts it to the HealthLink AIR Broker's $process-message endpoint. (EventType=FLS_ENROLMENT_NOMINATION)
  3. The Messaging Hub transforms the message to an HL7v2.0 ADT^28 request and sends it to the PMS
  4. The Messaging Hub returns a synchronous 202 response to NES

Enrolment Nomination Request Examples

1. - Whaihua to NES

Example of a "skinny" enrolment nomination request message sent by Whaihua to NES enrolment-nomination-request-message-2

3. - NES to HealthLink AIR Broker

Example of an enriched enrolment nomination request message sent by NES to the HealthLink AIR broker enrolment-nomination-request-message-1

7. - NES to Whaihua - error response

enrolment-nomination-response-message-1

Enrolment Nomination Message - Resources:

The FHIR enrolment nomination message will be created as a FHIR Bundle containing the below resources:

Enrolment Nomination Request Business Rules

Enrolment Nomination request rules

  • An enrolment nomination request must include a
    • Baby NHI number
    • Baby date of birth
    • Baby gender
    • Nominated GP facility ID
    • At least 1 Next of kin family and last name
  • A request may also include a
    • Baby name
    • Nominated GP name
    • Next of kin 1
      • NHI number, address and contact details (up to 3 contact details).
    • Next of kin2
      • NHI number, family and last name, relationship code, address and contact details (up to 3 contact details).

Baby’s NHI rules:

  • Baby needs to have valid NHI
  • Baby cannot be deceased
  • Baby must not have PRE-ENROL/ENROL (un-expired) status in NES

Baby’s birthdate rules:

  • A birth date must be after 1 January 1900 and not a future date

Baby’s gender rules:

  • Baby must have a current gender, supplied as a valid gender code as per FHIR codeset

Next of Kin (NoK) rules:

  • At least one NoK name (minimum of first and family name) needs to be provided
  • The relationship code must be a valid code as per the FHIR codeset

Nominated Provider rules:

  • Nominated provider must have a valid Legacy-ClinicID/Clinic ID in HPILocation

Enrolment Nomination Request Errors

Error Scenario Error Code Error Message HTTP Status code
Baby’s NHI is a required field - - 422 Unprocessable entity
Baby’s birthdate is a required field
Date of birth cannot be a future date
EM13009 The baby's date of birth is missing or invalid -
Baby’s gender is a required field EM13008 The baby's gender is missing or invalid -
Nominated GP facility ID is a required field EM13004 No nominated clinic has been provided -
At least 1 Next of kin name is a required field EM13010 No next of kin details provided -
Invalid code for valueset for baby’s gender - - 422 Unprocessable entity
Missing resource in FHIR input bundle - - 422 Unprocessable entity
Relationship code mismatch - - 422 Unprocessable entity
The NHI of the baby cannot be found in the NHI database EM13001 Baby's NHI not found -
The baby already has an active unexpired pre-enrolment/full-enrolment in the NES EM13002 The baby is already enrolled or pre-enrolled in NES -
The baby is deceased, and NHI has record of death EM13003 The baby has been marked as deceased in NHI -
The nomination request that came through contains a GP's facility ID that cannot be found in HPILocation EM13005 The nominated clinic provided cannot be found in HPI -
The gender of the baby supplied by Whaihua does not match against what is recorded in the NHI database EM13006 The provided gender does not match the NHI record for the baby -
The date of birth of the baby supplied by Whaihua does not match against what is recorded in the NHI database EM13007 The provided date of birth does not match the NHI record for the baby -

Responses Codes

One of the following asynchronous error response may be returned by the server

Scenarios http status code body description
Success 202 empty 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,422 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
Other processing errors 4xx empty Other 4xx errors may be returned by intermediary gateways (e.g. 401 Unauthorized). 429 Too many requests. These may not provide an OperationOutcome

Enrolment Nomination Response

This is an asynchronous response message indicating how the destination PMS has acted on the nomination request message

Enrolment Nomination ResponseNESNESHealthlink Air BrokerHealthlink Air BrokerPMSPMS1. ADT^28 ACK response2. Transform HL7 v2 to FHIR3. POST[base]/$process-message4. 202 Response

Enrolment Nomination Response processing steps:

  1. The PMS sends an HL7v2.0 ADT^28 ACK message to the HealthLink AIR Broker indicating if the enrolment nomination request has been accepted or not
  2. The Messaging Hub creates a bundle containing an OperationOutcome with an appropriate HL7 Result Code and sends it to the NES $process-message endpoint. The MessageHeader.response.identifier should hold the value of the Messageheader.id of the message being acknowledged
  3. NES returns a synchronous 202 response to the Messaging Hub.

Enrolment Nomination Request Examples

3. PMS to NES - Success

This is an example of an asynchronous response message returned from the PMS indicating that the the enrolment nomination request has been processed succesfully and accepted enrolment-nomination-response-message-1

3. PMS to NES - Failure

This is an example of an asynchronous response message returned from the PMS indicating there was an error processing the enrolment nomination request enrolment-nomination-response-message-2

4. NES to healtlInk - response

This an example of an error response returned by NES if it receives an invalid Enrolment Nomination Response message

enrolment-nomination-response-response-error-message-1.

Responses Codes

The response codes which may be sent in response to an Enrolment Nomination Response are the same as those describer for Enrolment Nomination Request

Responses Codes

Enrolment Nomination Response - Success Example

This is an example of an asynchronous response message returned from the PMS indicating that the the enrolment nomination request has been processed succesfully and accepted enrolment-nomination-response-message-1

Enrolment Nomination Response - Error Example

This is an example of an asynchronous response message returned from the PMS indicating there was an error processing the enrolment nomination request enrolment-nomination-response-message-2

Enrolment Nomination Response Response- Error Example

This an example of an error response returned by NES if it receives an invalid Enrolment Nomination Response message

enrolment-nomination-response-response-error-message-1.