ADT Specification

Introduction

The ADT (Admission / Discharge / Transfer) feed tracks the admissions of patients at a hospital. We integrate with it to populate our patient roster and set room assignments.

ADT Ingestion

ADT messages are received in HL7 format and contain a variety of fields and message shapes. We parse out only the fields we need to support our use cases and create a simple data structure for use with all message types.

ADT Message Fields

Field	Description	Example	Notes
ADT Event	ADT event code	A01	See ADT Event Types table below
MRN	Patient's unique identifier	111-22-3333	Match the ADT message to our patient record
Prior MRN	Patient's prior unique identifier	111-22-4444
Family Name	Patient's last name	Smith
Given Name	Patient's first name	Jane
DOB	Date of birth	19990123	Format: YYYYMMDD
Sex	Sex	M	M or F. Unknown values will be mapped to Other.
Language	Three-letter language code	ENG	Three letter codes from ISO 639-2/T.
Facility	ADT code for the hospital	ABCD	Match the ADT message to our hospital record
Room	ADT code for the room	LDT4-1	Match the ADT message to our room record
HL7	Raw HL7 message		For testing, this can be blank

ADT Event Types

There are many ADT event types. We support the following subset.

ADT Event Code	Type	Description
A01	admit	Admit a patient
A02	transfer	Transfer a patient to a different room
A03	discharge	Discharge a patient
A08	update patient	Update patient demographic information
A11	cancel admit	Cancel previous admit
A12	cancel transfer	Cancel previous transfer
A13	cancel discharge	Cancel previous discharge
A18, A45	merge patient info	Update a patient's MRN number or merge patient records

Field Usage

When receiving an ADT message various validations are performed. We are liberal in what we accept, and as long as we can process the message while maintaining internal data integrity, we will do so. Only fields that are required for the message are validated, all others are passed through.

HL7 messages support varied structures and therefore we collapse all fields into a single data structure. This means we may have unused fields per message type. The fields we use per type are listed below.

	A01	A02	A03	A08	A11	A12	A13	A18
MRN	●	●	●	●	●	●	●	●
Prior MRN								●
Family + Given Name	●			○
DOB	○			○
Sex	○			○
Language	○			○
Facility	●	○				○
Room	○	○				○

● required ○ optional

Message Processing

When processing messages, the values of the ADT fields are used to look up our internal records for patients, rooms and facilities. Some specific considerations:

Facility code (which maps to our division) appears in the HL7 message header as Sending Facility and Receiving Facility. It also appears in the patient visit record, which signifies where the patient is located. For our purposes, we always use the patient visit facility.
When looking up the room by ADT code, we only look at rooms that are in the facility specified in the message. This is because a hospital system may have the same room code across their hospitals.
In general, if a mapping is not found and that field is not required, the target value will be set to null. As an example, if we can't find the room code and room is an optional field, we will accept the message and remove the patient's room assignment.

After a message has been processed, its status is updated to "Processed" in the case of success and to "Rejected" in the case of failure. Rejected messages can be replayed through the UI, which will trigger re-processing.

Messages are kept for 30 days, after which they are hard deleted from the database. We will support any necessary number of pages required to view the messages in the application.

The table below lists the steps for processing each message type, in the order that they occur.

Event	Conditions	Result
all events	mrn is missing	reject

admit	facility is not found	reject
admit	family_name or given_name is missing	reject
admit	existing patient, but has active monitor	reject
admit	existing patient	update patient (room, division, status, demographics)
admit	new patient	create patient (room, division, status, demographics)

transfer	patient not found	treat as admit - new patient
transfer	patient found, but facility not found	update patient status to inactive
transfer	patient has active monitor	update patient (room, division, status)
transfer	patient had one or more historical monitoring sessions	update patient (room, division, status)
transfer	all prerequisites met	update patient (room, division, status)

discharge	patient not found	reject
discharge	patient has active monitor	reject
discharge	all prerequisites met	update patient (status)

update	family_name or given_name is missing	reject
update	patient not found	reject
update	all prerequisites met	update patient (demographics)

cancel admit	patient not found	reject
cancel admit	patient has active monitor	reject
cancel admit	all prerequisites met	update patient (status)

cancel transfer	patient not found	reject
cancel transfer	patient has active monitor	reject
cancel transfer	patient found, but facility not found	update patient status to inactive
cancel transfer	all prerequisites met	update patient (room)

cancel discharge	patient not found	reject
cancel discharge	patient has active monitor	reject
cancel discharge	all prerequisites met	update patient (status)

merge	prior_mrn is missing	reject
merge	prior_mrn is the same as new mrn	reject
merge	patient not found for prior mrn	reject
merge	patient not found for new mrn	update prior_patient.mrn with new mrn
merge	patient found for new mrn, but was prior_patient was already merged	reject
merge	patient found for new mrn	deactivate prior patient record; link old record to new one

Infrastructure & Backend

Data is sent in real-time using TCP/IP HL7 messages over a secure VPN received by our Mirth Nextgen Connect which converts them into API calls to the Rails backend. This diagram shows how Mirth Connect reads patient data from a hospital's Electronic Medical Record (EMR) system. With elements mapped in its own channel, Mirth Connect generates an HL7 message and sends it to the LookDeep application.

ADT Codes in LookDeep

ADT Codes are included on the Hospital and Room list pages for administrator convenience.