Publisher API HL7 Messages: Difference between revisions

From Discovery Data Service
Jump to navigation Jump to search
Line 1,148: Line 1,148:
|NOT IN SCOPE
|NOT IN SCOPE
|-
|-
|Microbiology
|Microbiology - discrete results
|ORU - Unsolicited Results  
|ORU - Unsolicited Results  
|REQUIRES ELABORATION
|REQUIRES ELABORATION
|-
|-
|Virology
|Virology - discrete results
|ORU - Unsolicited Results  
|ORU - Unsolicited Results  
|REQUIRES ELABORATION
|REQUIRES ELABORATION
|}
|}

Revision as of 11:59, 25 October 2021


This page summarises the messages that are currently supported by DDS

Acknowledgement

  • ACK - general acknowledgement

Records

Encounters

Observations

Not currently defined

Standard segments

See Publisher API HL7 Segments for definitions of the segments that are used across the DDS message set. Note that in many cases individual messages refine the standard definitions. Where this is the case it is made clear in the definition of each message below.

ACK: General acknowledgement

This message is used to indicate whether or not DDS has successfully received an inbound message or not.

The value of MSH:9.2 (trigger event) is always the same as the trigger event in the inbound message that is being acknowledged.

Segment Optionality Repeating
MSH - Message Header R N
MSA - Message acknowledgement R N

ADT A28: Create patient record

Overview

This message will create a new patient record within DDS. [TODO - what happens if the record exists - will this act as A31?]

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PD1 - Patient Additional Demographics O N

Example

ADT A31: Update patient record

Overview

This message will update an existing patient record within DDS. [TODO - what happens if the record does not exist - will this act as A28?]

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PD1 - Patient Additional Demographics O N

Example

ADT A34: Merge Patient Information - Patient ID Only

Overview

This message is used when two patient records are merged at the patient identifier list level.

The "incorrect" identifier from MRG:4 is to be merged with the "correct" identifier from PID:3 where both identifiers have the same identifier type code.

In theory the identifier from MRG:4 should not be used in future transactions when referring to the patient.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
MRG - Merge Patient Information R N

Example

ADT A01: Admit Patient

Overview

This will create an Encounter for the specified patient

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location R If not known please provide "UNKNOWN" for PV1:6.9 ^^^^^^^^UNKNOWN
PV1:4 - Admission Type R
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name ^UNKNOWN^^^^^^^^^^^^^^
PV1:14 - Admit source R
PV1:36 - Discharge Disposition X Ignored if supplied
PV1:37 - Discharged to Location X Ignored if supplied
PV1:44 - Admit Date/TIme R 202105250824
PV1:45 - Discharge Date/Time X Ignored if supplied

Example

ADT A11: Cancel admit

Overview

The A11 is sent following the cancellation of an admission event (A01). The reason for cancellation could be that the original admission (A01) was created in error or that a decision was taken to not admit the patient.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location X Ignored if supplied
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name ^UNKNOWN^^^^^^^^^^^^^^
PV1:36 - Discharge Disposition X Ignored if supplied
PV1:37 - Discharged to Location X Ignored if supplied
PV1:44 - Admit Date/TIme X Ignored if supplied
PV1:45 - Discharge Date/Time X Ignored if supplied

Example

ADT 02: Transfer a Patient

Overview

Records a patient transfer. Note that there can be three kinds of transfer -

  1. location transfer
  2. clinician transfer
  3. location and clinician transfer

In the case of a location transfer PV1:6 (prior patient location) will be populated along with PV1:3 (assigned patient location). In the case of clinician transfer PV1:9 (consulting doctor) will be updated. Note also that EVN:2 (recorded date/time) is used to track the actual time of transfer.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location R If not known please provide "UNKNOWN" for PV1:6.9. If this is not a location transfer then provide the existing location. If this is a location transfer then provide the new location ^^^^^^^^UNKNOWN
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name. If this is not a clinician transfer then provide the existing clinician. If this is a location transfer then provide the new clinician ^UNKNOWN^^^^^^^^^^^^^^
PV1:36 - Discharge Disposition X Ignored if supplied
PV1:37 - Discharged to Location X Ignored if supplied
PV1:44 - Admit Date/TIme X Ignored if supplied. Instead see EVN:3.2 where the transfer time will be recorded
PV1:45 - Discharge Date/Time X Ignored if supplied

Example

ADT A12: Cancel transfer

Overview

The A12 is sent following the cancellation of a transfer event (A02). The reason for cancellation could be that the original transfer (A02) was created in error or that a decision was taken to not transfer the patient.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location X Ignored if supplied
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name ^UNKNOWN^^^^^^^^^^^^^^
PV1:36 - Discharge Disposition X Ignored if supplied
PV1:37 - Discharged to Location X Ignored if supplied
PV1:44 - Admit Date/TIme X Ignored if supplied
PV1:45 - Discharge Date/Time X Ignored if supplied

Example

ADT A03: Discharge Patient

Overview

This message signals that the patient's stay in the healthcare facility has ended.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location X Ignored if supplied
PV1:6 - Prior Patient Location O If not known please provide "UNKNOWN" for PV1:6.9 ^^^^^^^^UNKNOWN
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name ^UNKNOWN^^^^^^^^^^^^^^
PV1:36 - Discharge Disposition R If not known please provide "UNKNOWN" UNKNOWN
PV1:37 - Discharged to Location R If not known please provide "UNKNOWN" 19
PV1:44 - Admit Date/TIme R
PV1:45 - Discharge Date/Time R 202105250824

Example

ADT A13: Cancel discharge

Overview

The A13 is sent following the cancellation of a discharge event (A03). The reason for cancellation could be that the discharge transfer (A03) was created in error or that a decision was taken to not discharge the patient.

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Optionality Notes Example
PV1:3 - Assigned Patient Location R Assigned Patient Location should record the location of the patient following the cancellation. In the case of a discharge created in error the location could be different from the patient’s location prior to the erroneous discharge. In this scenario the prior Location could be used to show the location before the erroneous A03 was sent. If Assigned Patient Location is not known please provide "UNKNOWN" for PV1:6.9 ^^^^^^^^UNKNOWN
PV1:9 - Consulting Doctor R If not known please provide "UNKNOWN" for the family name ^UNKNOWN^^^^^^^^^^^^^^
PV1:36 - Discharge Disposition X Ignored if supplied
PV1:37 - Discharged to Location X Ignored if supplied
PV1:44 - Admit Date/TIme X Ignored if supplied
PV1:45 - Discharge Date/Time X Ignored if supplied

Example

ADT A08: Update Patient Information

Overview

An A08 message is used to update existing encounter information. Note that it is important to supply a value for PV1:19 (Visit number) in order to match the encounter to update.

[TODO] -

  • confirm behaviour if A08 is sent an no encounter exists
  • confirm what happens to the previous version of the updated data (is it retained and retrievable?)
  • What are the rules around triggered an update, for example if a field is left blank in PV1 does that mean that the existing data in DDS will not be updated?
  • is it only the PV1 segment that is used as a source data to update i.e. the PID segment is ignored?

Definition

Segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type R N
PID - Patient Identification R N
PV1 - Patient Visit R N

Fields

PV1 - Patient Visit

Refines the DDS standard definition of PV1 -

Field Component Data Type Optionality Repeating Description Example
PV1:2 - Patient Class PV1:2.1 ID O N Allowed values are from table 0004-PatientClass
PV1:3 - Assigned Patient Location PV1:3.1 IS O N General patient location
PV1:4 - Admission Type PV1:4.1 ID O N Allowed values are from table 0007-AdmissionType
PV1:6 - Prior Patient Location PV1:6.9 ST O N Free text description of the location
PV1:7 - Attending Doctor - - O N Attending doctor. If provided, at least the family name must be given.
PV1:7.2 ST R N Family Name
PV1:7.3 ST O N Given Name
PV1:7.4 ST O N Middle Names
PV1:7.6 ST O N Prefix
PV1:8 - Referring Doctor - - O N Referring doctor. If provided, at least the family name must be given.
PV1:8.2 ST R N Family Name
PV1:8.3 ST O N Given Name
PV1:8.4 ST O N Middle Names
PV1:8.6 ST O N Prefix
PV1:9 - Consulting Doctor - - O N Consulting doctor. If provided, at least the family name must be given.
PV1:9.1 ST R N ID number
PV1:9.2 ST R N Family Name
PV1:9.3 ST O N Given Name
PV1:9.4 ST O N Middle Names
PV1:9.6 ST O N Prefix
PV1:10 - Hospital Service PV1:10.1 IS O N Allowed values are from table 0069-HospitalService
PV1:13 - Re-admission Indicator PV1:13.1 IS O N Allowed values are from table 0092-Re-AdmissionIndicator
PV1:14 - Admit source PV1:14.1 IS O N Allowed values are from table DDS-AdmissionSource
PV1:18 - Patient Type PV1:18.1 IS O N Allowed values are from table HL7v3-EncounterType
PV1:36 - Discharge Disposition PV1:36.1 IS O N Allowed values are from table 0112-DischargeDisposition
PV1:37 - Discharged to Location PV1:37.1 ID O N Allowed values are from table 0113-DischargedToLocation
PV1:44 - Admit Date/Time PV1:44.1 TS O N Admit timestamp
PV1:45 - Discharge Date/Time PV1:45.1 TS O N Discharge timestamp

ORU R01: Unsolicited Observation

Overview

DDS supports two kinds of Observation -

DDS differentiates these by examining the value of MSH:3.1. For Radiology observations that value MUST be "RADIOLOGY". Any other value is interpreted as a Laboratory observation.

Schema

ORU Schema.png

Note - In the diagram above the grey boxes are logical groupings of segments

Definition

segments

Segment Optionality Repeating
MSH - Message Header R N
EVN - Event Type O N
PID - Patient Identification R N
PV1 - Patient Visit O N
ORC - Common Order O Y
OBR - Observation Request C Y
OBX - Observation or result C Y
NTE - Notes and Comments O Y

ORU R01: Unsolicited Observation (Laboratory)

Overview

This message is used to transmit unsolicited laboratory results into DDS. [TODO - how to differentiate path from rad results?]

Interpretation of observations

Depending upon the structure of the R01, DDS will interpret the message in one of three ways.

Single textual laboratory report

The following criteria are used to determine if an OBR contains a single textual laboratory report -

  • There are one or more OBX segments which when combined hold at least two lines of text
  • Each OBX segment has a textual data type (TX, FT or ST)
  • Each OBX segment has the same test ID as the others (OBX:3)

The OBX segments are interpreted as lines of a report as are any NTE segments directly associated with the OBR.

It's worth noting that OBX:13 can be used to carry details of any delay that is to be applied before the patient should see the results. If there is a delay associated with the report then this should be included on the first OBX segment.

Collection of individual test results

If an OBR group does not meet the criteria for a single textual laboratory report then DDS assumes it to contain a collection of individual test results. DDS considers the comments for a given test result (OBX) to be the combination of the comments (NTE segments) associated directly with the OBR plus the comments (NTE segments) associated directly with the test result.

Embedded PDF result

If OBX.2.1 (Value Type) contains "ED" then it is expected that the OBX segments contains an embedded, Base64-encoded PDF document

NTE - Notes and Comments

DDS will interpret comments differently depending on where in the R01 message an NTE segment is found -

  • NTE segments that immediately follow the OBR segment are considered by DDS to apply to all results in the R01 message
  • NTE segments immediately following an OBX segment are considered by DDS to apply only to the immediately preceding result

Definition

Fields

OBX - Observation

Refines the DDS standard definition of OBX -

Field Component Data Type Optionality Repeating Description Example
OBX:3 - Observation Identifier OBX:3.3 ST R N DDS will only accept a measurement if this value is "SNOMED-CT" 26604007 | Complete blood count (procedure)
OBX:5 - Observation value - VARIES N The number of sub-fields varies depending upon the value of OBX:2.1
OBX:5.1 ST R N If OBX:2.1 = "ED" then this must be the source application

Otherwise the raw observation value

OBX:5.2 ID C N Required if OBX:2.1 = "ED" and MUST be "document" document
OBX:5.3 ID C N Required if OBX:2.1 = "ED" and MUST be "pdf" pdf
OBX:5.4 ID C N Required if OBX:2.1 = "ED" and MUST be "Base64" Base64
OBX:5.5 ST C N Required if OBX:2.1 = "ED" and must be Base64 encoded PDF document

ORC - Common Order

Refines the DDS standard definition of ORC -

Field Component Data Type Optionality Repeating Description Example
ORC:3 - Filler Order number ORC:3.1 ST C N This string is required if OBR:3.1 is not provided

Example

ORU R01: Unsolicited Observation (Radiology)

Overview

Interpretation of observations

DDS can interpret a radiology observation in three different ways -

  1. as a single textual report with multiple image attachments
  2. as carrying an embedded PDF report
  3. [TODO - DICOM integration]

It's worth noting that OBX:13 can be used to carry details of any delay that is to be applied before the patient should see the results. If there is a delay associated with the report then this should be included on the first OBX segment.

Single textual report with multiple image attachments

If an OBX segments contains an image (OBX:2.1 = "ED" and OBX:5.2 = "image") then the image will be extracted and added as an attachment to the textual report. The ordering of the OBX segments containing images is not meaningful to DDS.

An NTE segment or an OBX segment that does not hold an image is considered to contain a portion of the report. The ordering of these segments will be respected by DDS and it will concatenate them to form a single textual report. Note that each segment will be delineated by a UNIX line feed character (escape sequence - \n Unicode character - U+000A).

Embedded PDF report

DDS interprets a radiology observation in this way if the following is true -

OBX:2.1 = "ED" and OBX:5.2 = "document" and OBX:5.3 = "pdf"

An NTE segment or an OBX segment that does not hold an image is considered to contain a portion of the report. The ordering of these segments will be respected by DDS and it will concatenate them to form a narrative block that will be associated with the PDF element of the observation.

Definition

Fields

OBX - Observation

Refines the DDS standard definition of OBX -

Field Component Data Type Optionality Repeating Description Example
OBX:2 - Value Type OBX:2.1 ID R N Radiology messages only support FT, TX or ED ED
OBX:3 - Observation Identifier OBX:3.2 ST O N Needed to allow consumers to understand the type of radiology study that this observation represents. Note that if this is not specified then the OBR:4.2 value must be present. In this case the OBR:4.2 value is interpreted as the test code X-ray pelvis
OBX:5 - Observation value - VARIES N The number of sub-fields varies depending upon the value of OBX:2.1
OBX:5.1 ST R N If OBX:2.1 = "ED" then this must be the source application

Otherwise the raw observation value

OBX:5.2 ID C N Required if OBX:2.1 = "ED" and MUST be "image" or "document" image
OBX:5.3 ID C N Required if OBX:2.1 = "ED"

if OBX:5.2 = "image" then MUST be "TIFF"

else if OBX:5.2 = "document" then must be "pdf"

TIFF
OBX:5.4 ID C N Required if OBX:2.1 = "ED" and MUST be "Base64" Base64
OBX:5.5 ST C N Required if OBX:2.1 = "ED" and must be Base64 encoded image or PDF document

Not currently defined

The following types of message are not currently in scope or need further elaboration

Use case Messaging type Status
DICOM ORU - Unsolicited Results NOT IN SCOPE
Microbiology - discrete results ORU - Unsolicited Results REQUIRES ELABORATION
Virology - discrete results ORU - Unsolicited Results REQUIRES ELABORATION