Developer documentation‎ > ‎HL7 API‎ > ‎Messages‎ > ‎

ADT A28


ADT^A28: Create a new medical record

Overview

This message will either create or update a medical record in PKB. If the specified medical record (identified by the PID segment) is not found, it will be created. Otherwise, it will be updated.

If an update is performed, then the entire set of medications, allergies or diagnoses sent by your Organisation will be replaced, depending on what is sent. Note - this includes any medications, allergies or diagnoses added by a Professional from your Organisation. For example, if a Professional from your Organisation manually adds an allergy, but then a different allergy is provided in an A28 message from your Organisation, the entry manually added by the Professional will be replaced.

Note - an email address can be provided when creating a new medical record, but an email address cannot be added to an existing medical record via the HL7 API unless that record is already associated with an email address. See here for more information on how PKB handles email addresses.

Relevant Entities

Please click through to the Data Model to explore the presentation of these entities in the web interface.

Update Behaviour

Message Entity Matching Criteria Behaviour (Matched) Behaviour (Not Matched)
A28 [[Patient]] See here for full details of our approach to matching [[Patient]] entities via HL7. Partial update will be performed on the [[Patient]] if the supplied MSH-7 timestamp is greater than or equal to [[Patient.Entered Timestamp]] held on the record. Note: the [[Patient.Entered Timestamp]] may have been set via any route e.g HL7, FHIR or UI.

See PID specification for which fields will be left unmodified if a blank is provided.
 New [[Patient]] created.

[[Patient.Entered Timestamp]] will be set to the value in MSH-7.
  [[Contact]] [[Contact.Type]] and [[Contact.Value]]. Note that only email contacts can be added via HL7 - the phone number is stored directly on the [[Patient]]. No action. Any contacts already known will remain on the record. New [[Contact]] created, unless this message is updating an existing [[Patient]] which does not already have an email address. See here for more information on how PKB handles email addresses. 
  [[National ID]] Since only a single National ID for any given National ID Type is permitted on a medical record, an instance of a National ID for a patient can be matched on the [[National ID Type]] alone. The corresponding [[National ID.Value]] is updated if a valid value was provided. An existing National ID can be changed but not removed. New [[National ID]] added to the medical record.
  [[National ID Type]] [[National ID Type.HL7 Assigning Authority]] as derived from PID-2.4 and PID-3.4 and [[National ID Type.HL7 Type Code]] as derived from PID-2.5 and PID-3.5. Matching the type is a prerequisite for processing the corresponding National ID. The corresponding National ID is silently ignored. New types cannot be created via HL7 messaging.
  [[Organisation Level ID]] [[Organisation Level ID.Value]] as derived from PID-2.1 and PID-3.1 in conjunction with the specified [[Organisation Level ID Type]] No action. Any Organisation Level IDs already known will remain on the record. New [[Organisation Level ID]] added to the medical record.
  [[Organisation Level ID Type]] [[Organisation Level ID Type.HL7 Assigning Authority]] as derived from PID-2.4 and PID-3.4 and [[Organisation Level ID Type.HL7 Type Code]] as derived from PID-2.5 and PID-3.5. Matching the type is a prerequisite for processing the corresponding Organisation Level ID. The corresponding Organisation Level ID is silently ignored. New types cannot be created via HL7 messaging.
  [[Team Level ID]] [[Team Level ID.Value]] as derived from PID-2.1 and PID-3.1 in conjunction with the specified [[Team Level ID Type]] No action. Any Team Level IDs already known will remain on the record. New [[Team Level ID]] added to the medical record.
  [[Team Level ID Type]] [[Team Level ID Type.HL7 Assigning Authority]] as derived from PID-2.4 and PID-3.4 and [[Team Level ID Type.HL7 Type Code]] as derived from PID-2.5 and PID-3.5. Matching the type is a prerequisite for processing the corresponding Team Level ID. The corresponding Team Level ID is silently ignored. New types cannot be created via HL7 messaging.
  [[Allergy]] [[Allergy.Allergen]] as derived from AL1-3 The matching [[Allergy]] is replaced with the new information. A partial update is not performed.
Note: Any allergies previously stored by this organisation, but which were not provided this time, will be deleted.		 A new [[Allergy]] is added to the medical record.
  [[Diagnosis]] [[Diagnosis.Diagnosis]] as derived from DG1-3 The matching [[Diagnosis]] is replaced with the new information. A partial update is not performed.
Note: Any diagnoses previously stored by this organisation, but which were not provided this time, will be deleted.		 A new [[Diagnosis]] is added to the medical record.
  [[Medication]] [[Medication.Substance]] as derived from ZRX-2 and [[Medication.Start Date]] as derived from ZRX-1.4.
Note: a match on both Substance and Start Date is sought first, but failing that a match on just Substance is accepted.		 The matching [[Medication]] is replaced with the new information. A partial update is not performed.
Note: Any medications previously stored by this organisation, but which were not provided this time, will be deleted.		 A new [[Medication]] is added to the medical record.

Definition


Segment Field Component Description Example Data Model
MSH

Message header. This conforms to PKB's standard definition.
 
PID

Patient identification. This conforms to PKB's standard definition.
 
{ [
AL1

Allergy information. When creating or updating a medical record you can specify allergy information for the patient. The AL1 segment has no fields to indicate source; to include the provider who entered the allergy, use a NTE segment following it.

When updating - the specified information replaces any existing allergy information from the sender.
 

AL1-3
Allergen. Although each component is optional individually, at least one of AL1-3.1 or AL1-3.2 must be provided.


Read V2 codes can be mapped to privacy labels if sent in AL1-3. See the coded data page.
[[Allergy.Allergen]]


[ AL1-3.1 ] Allergen code A_01


[ AL1-3.2 ] Allergen text Paracetamol


[ AL1-3.3 ] Allergen coding system



[ AL1-3.4 ] Allergen alternate code A.1


[ AL1-3.5 ] Allergen alternate text Paracetamol


[ AL1-3.6 ] Allergen alternate coding system INT

[ AL1-4 ]
Allergen severity
[[Allergy.Severity]]


[ AL1-4.1 ] Allergen severity code S_01


[ AL1-4.2 ] Allergen severity text Mild


[ AL1-4.3 ] Allergen severity coding system HOSP


[ AL1-4.4 ] Allergen severity alternate code RS.M


[ AL1-4.5 ] Allergen severity alternate text Mild


[ AL1-4.6 ] Allergen severity alternate coding system


{ [ AL1-5 ] }
Allergy reaction
 


AL1-5.1 Allergy reaction code Coughing, Sneezing [[Allergy.Reactions]]

[ AL1-6 ]
Identification date
 


AL1-6.1 Identification date 201408310408 [[Allergy.Onset Timestamp]]
[ NTE ]
] }

An NTE can be optionally included after an AL1 to specify source information.
 

NTE-5
Source information. If provided, at least the family name must be given.
[[Allergy->Source.Source Text]]


NTE-5.2 Family name Foster  


[ NTE-5.3 ] Given name John  


[ NTE-5.4 ] Middle names Harry  


[ NTE-5.6 ] Prefix Dr  
{ [ DG1 ] }

Diagnosis information. When creating or updating a medical record you can specify diagnosis information for the patient.

When updating - the specified information replaces any existing diagnosis information from the sender.
 

DG1-3
Diagnosis. Although each component is optional individually, at least one of DG1-3.1 or DG1-3.2 must be provided.

Read V2 codes can be mapped to privacy labels if sent in DG1-3. See the coded data page. 
[[Diagnosis.Diagnosis]]


[ DG1-3.1 ] Diagnosis code D01


[ DG1-3.2 ] Diagnosis text Asthma


[ DG1-3.3 ] Diagnosis coding system HOSP


[ DG1-3.4 ] Diagnosis alternate code D.100


[ DG1-3.5 ] Diagnosis alternate text Asthma


[ DG1-3.6 ] Diagnosis alternate coding system


[ DG1-5 ]
Diagnosis timestamp
 


DG1-5.1 Diagnosis timestamp 201408310408 [[Diagnosis.Start Timestamp]]

[ DG1-16 ]
Diagnosing clinician. If provided, at least the family name must be given.
[[Diagnosis->Source.Source Text]]


DG1-16.2 Family name Foster  


[ DG1-16.3 ] Given name John  


[ DG1-16.4 ] Middle names Harry  


[ DG1-16.6 ] Prefix Dr  
{ [ ZRX ] }

Medication information. When creating or updating a medical record you can specify the medication information for the patient.

When updating - the specified information replaces any existing medication information from the sender.

This custom segment is based on an RXE v2.4 segment.
 

[ ZRX-1 ]
Quantity/timing.
 


[ ZRX-1.2 ] Repeat pattern Once A Day [[Medication.Frequency Text]]


[ ZRX-1.4 ] Start timestamp 201409020909 [[Medication.Start Timestamp]]


[ ZRX-1.5 ] End timestamp. If null (or in the future), this is considered a current medication; otherwise, it's medication history. 201409160909 [[Medication.End Timestamp]]

ZRX-2
Give code
[[Medication.Substance]]
    [ ZRX-2.1 ]
 Medication code 13968911000001194  

 ZRX-2.2 Medication text Paracetamol
    [ ZRX-2.3 ]
 Medication coding system Dm+d  
    [ ZRX-2.4 ]
 Medication alternate code 13968911000001194  
    [ ZRX-2.5 ]
 Medication alternate text Paracetamol  
    [ ZRX-2.6 ]
 Medication alternate coding system Dm+d  

[ ZRX-3 ]
Dose quantity
 


ZRX-3.1 Dose quantity 1 [[Medication.Dose Value]]

[ ZRX-5 ]
Give units
[[Medication.Dose Units]]


[ ZRX-5.1 ] Unit code U01


[ ZRX-5.2 ] Unit text Tablet


[ ZRX-5.3 ] Unit coding system HOSP_1


[ ZRX-5.4 ] Unit alternate code U02


[ ZRX-5.5 ] Unit alternate text Tablets


[ ZRX-5.6 ] Unit alternate coding system HOSP_2

[ ZRX-7 ]
Instructions. For multiple lines of instructions -- separate lines with the HL7 repeat character (~), or include HL7-escaped linebreaks directly (using \.br\)
 


ZRX-7.2 Instruction text Instructions [[Medication.Instructions]]

[ ZRX-13 ]
Source information. If provided, at least the family name must be given.
[[Medication->Source.Source Text]]


ZRX-13.2 Family name Foster  


[ ZRX-13.3 ] Given name John  


[ ZRX-13.4 ] Middle names Harry  


[ ZRX-13.6 ] Prefix Dr  
[ ZTM ]

This is a custom PKB team segment. If you have agreed some source aliases with PKB then you can specify 1 or more of those aliases in this ZTM segment. When creating a new medical record, the record will be added to the Team associated with each alias in this list. If you include an alias to an Organisation, then the medical record will be added to the default Team for that Organisation.
Note: If you include this segment, you must include as a minimum the alias for the Organisation or Team that you are using to send the message.
 

{ ZTM-1 }
Alias
 


ZTM-1.1 Alias first_alias  

Examples

Create a new patient with these IDs, demographics, medications list, allergies, and diagnoses.
MSH|^~\&|SendingApp|SendingFacility|HL7API|PKB|20160102101112||ADT^A28|ABC0000000001|P|2.4
PID|||5555555555^^^NHS^NH||Smith^John^Joe^^Mr||19700101|M|||My flat name^1, The Road^London^London^SW1A 1AA^GBR||john.smith@hotmail.com^NET~01234567890^PRN~07123456789^PRS|john.smith@company.com^NET~01234098765^WPN||||||||||||||||N|
AL1|1||^Paracetamol^|^Mild^|Coughing|201408310408
NTE|||||^Foster^John^Harry^^Dr|
DG1|1||^Asthma^||201408310408|||||||||||^Foster^John^Harry^^Dr|
ZRX|^Once A Day^^201409020909^201409160909|^Paracetamol^|1||^Tablet^||^Instructions||||||^Foster^John^Harry^^Dr|
ZTM|first_alias~second_alias~third_alias|

Response


PKB will respond with a standard HL7 acknowledgement.
Comments