New Zealand NES IG - Local Development build (v1.4.0-SNAPSHOT) 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 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:

• NHI Patient
• HPI Practitioner
• HL7 FHIR RelatedPerson
• MessageHeader

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