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.

If you provide an email address in the message then this will be added to the record and the patient will be sent an email invitation to register (unless they have already registered, in which case they are sent a request to confirm the newly added email address). You are able to provide an email address in both PID-13 and PID-14, but a maximum of 1 from each field can be accepted. See here for more information on how PKB handles email addresses.

When creating a new patient, the following fields are mandatory:

at least 1 identifier (either National ID, Organisation Level ID, or Team Level ID)
first name
last name

Relevant entities

Patient demographic information is used to populate [[Patient]] entities, including [[Contact]], [[National ID]], [[Organisation Level ID]] and [[Team Level ID]] entities. [[National ID Type]], [[Organisation Level ID Type]] and [[Team Level ID Type]] must match pre-agreed information; new types cannot be created via HL7 messaging.
Allergy information is used to populate [[Allergy]] entities
Diagnosis information is used to populate [[Diagnosis]] entities
Medication information is used to populate [[Medication]] entities

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

[[Patient]]

Matched on: See our notes on identifiers & matching for full details of our approach to matching [[Patient]] entities via HL7.

When matched: 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 our PID specification for which fields will be left unmodified if a blank is provided.

When not matched: New [[Patient]] created. [[Patient.Entered Timestamp]] will be set to the value in MSH-7.

[[Contact]]

Matched on: [[Contact.Type]] and [[Contact.Value]]. Note that only email contacts can be added via HL7 - the phone number is stored directly on the [[Patient]].

When matched: No action. Any contacts already known will remain on the record.

When not matched: New [[Contact]] created. If this is the first email address for the record then an invitation to register will be sent to the email address. If there was already an email address on the record then a confirmation request will be sent to the email address. See our notes on email address handling for more information.

[[National ID]]

Matched on: 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.

When matched: The corresponding [[National ID.Value]] is updated if a valid value was provided. An existing National ID can be changed but not removed.

When not matched: New [[National ID]] added to the medical record.

[[National ID Type]]

Matched on: [[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.

When matched: Matching the type is a prerequisite for processing the corresponding National ID.

When not matched: The corresponding National ID is silently ignored. New types cannot be created via HL7 messaging.

[[Organisation Level ID]]

Matched on: [[Organisation Level ID.Value]] as derived from PID-2.1 and PID-3.1 in conjunction with the specified [[Organisation Level ID Type]]

When matched: No action. Any Organisation Level IDs already known will remain on the record.

When not matched: New [[Organisation Level ID]] added to the medical record.

[[Organisation Level ID Type]]

Matched on: [[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.

When matched: Matching the type is a prerequisite for processing the corresponding Organisation Level ID.

When not matched: The corresponding Organisation Level ID is silently ignored. New types cannot be created via HL7 messaging.

[[Team Level ID]]

Matched on: [[Team Level ID.Value]] as derived from PID-2.1 and PID-3.1 in conjunction with the specified [[Team Level ID Type]]

When matched: No action. Any Team Level IDs already known will remain on the record.

When not matched: New [[Team Level ID]] added to the medical record.

[[Team Level ID Type]]

Matched on: [[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.

When matched: Matching the type is a prerequisite for processing the corresponding Team Level ID.

When not matched: The corresponding Team Level ID is silently ignored. New types cannot be created via HL7 messaging.

[[Allergy]]

Matched on: [[Allergy.Allergen]] as derived from AL1-3 and [[Allergen.Onset Timestamp]] as derived from AL1-6.

When matched: 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.

When not matched: A new [[Allergy]] is added to the medical record.

[[Diagnosis]]

Matched on: [[Diagnosis.Diagnosis]] as derived from DG1-3 and [[Diagnosis.Start Date]] as derived from DG1-5.

When matched: 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.

When not matched: A new [[Diagnosis]] is added to the medical record.

[[Medication]]

Matched on: [[Medication.Substance]] as derived from ZRX-2, [[Medication.Start Timestamp]] as derived from ZRX-1.4 and [[Medication.End Timestamp]] as derived from ZRX-1.5.

When matched: 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.

When not matched: A new [[Medication]] is added to the medical record.

Definition

Segment	Field	Opt	RP/#	Component	Description	Example	Data Model

Segment	Field	Opt	RP/#	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. Duplicate allergies within the AL1 set will result in the entire message being rejected. An allergy is identified as being duplicate if AL1-3 (allergen) and AL1-6 (identification date) match that of another AL1 segment within the message. The duplicate check within AL1-3 (allergen) gives precedence to the uniqueness of either AL1-3.1 (code) or AL1-3.5 (alternate coding). When coding values are not supplied in AL1-3 then the check references AL1-3.2 (text) or AL1-3.5 (alternate text) instead. The duplicate check is conducted versus the other AL1 segments in the message.
	AL1-3	R			Allergen. Read V2 codes can be mapped to privacy labels if sent in AL1-3. See the coded data page for more information. Although each component is optional individually, at least one of AL1-3.1 or AL1-3.2 must be provided.		[[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	O			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	O	Y		Allergy reaction
				AL1-5.1	Allergy reaction code	Coughing, Sneezing	[[Allergy.Reactions]]
	AL1-6	O			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	O			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. Duplicate diagnosis within the DG1 set will result in the entire message being rejected. A diagnosis is identified as being duplicate if DG1-3 (diagnosis) and DG1-5 (diagnosis timestamp) match that of another DG1 segment within the message. The duplicate check within DG1-3 (diagnosis) gives precedence to the uniqueness of either DG1-3.1 (code) or DG1-3.5 (alternate coding). When coding values are not supplied in DG1-3 then the check references DG1-3.2 (text) or DG1-3.5 (alternate text) instead. The duplicate check is conducted versus the other DG1 segments in the message.
	DG1-3	R			Diagnosis. Read V2 codes can be mapped to privacy labels if sent in DG1-3. See the coded data page for more information. Although each component is optional individually, at least one of DG1-3.1 or DG1-3.2 must be provided.		[[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	O			Diagnosis timestamp
				DG1-5.1	Diagnosis timestamp	201408310408	[[Diagnosis.Start Timestamp]]
	DG1-16	O			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. Duplicate medications within the ZRX set will result in the entire message being rejected. A medication is identified as being duplicate if ZRX-2 (give code), ZRX-1.4 (start timestamp) and ZRX-1.5 (end timestamp) match that of another ZRX segment within the message. The duplicate check within ZRX-2 (give code) gives precedence to the uniqueness of either ZRX-2.1 (code) or ZRX-2.4 (alternate coding). When coding values are not supplied in ZRX-2 then the check references ZRX-2.2 (text) or ZRX-2.5 (alternate text) instead. The duplicate check is conducted versus the other ZRX segments in the message. This custom segment is based on an RXE v2.4 segment.
	ZRX-1	O			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	R			Give code. The medication text is the only required component.		[[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	O			Dose quantity This must be a numeric value.
				ZRX-3.1	Dose quantity	1	[[Medication.Dose Value]]
	ZRX-5	O			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	O	Y		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	O			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 or updating a medical record this segment will contribute to determining which teams the patient should be linked to. Note: You cannot use the ZTM segment to exclude the Team which would have otherwise been used. See our guidance on Team membership for more information.
	ZTM-1	O	Y		Alias
				ZTM-1.1	Alias	first_alias~second_alias
	ZTM-2	O	Y	ZTM-2.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|||9999999999^^^NHS^NH||Smith^John^Joe^^Mr||19700101|M|||Flat name^1, The Road^London^London^SW1A 1AA^GB-ENG||01234567890^PRN~07123456789^PRS|^NET^^john.smith@company.com~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|first_alias|

Response

PKB will respond with a standard HL7 acknowledgement.