SOAPware DocumentationSOAPware InterfaceSOAPware InterfaceSOAPwareXchange HL7SOAPwareXchangeHL7 Demographics Interface Specifications

SOAPwareXchangeHL7 Demographics Interface Specifications

This lesson describes the specific manner in which HL7 is implemented in SOAPwareXchangeHL7, and how the various standard fields will be used.

SOAPwareXchangeHL7 accepts HL7-compliant messages from other systems, and uses them to create formatted reports in a chart section of the appropriate SOAPware® chart. In the case of ADT messages, it is assumed that the patient does not already exist in SOAPware. The XchangeHL7 will use the PID (Patient Identifier) segment to create a new chart in SOAPware.

You will first need to enable the Auto Create Charts function in the SOAPwareXchangeHL7. This is found under Settings > Advanced > Auto Create Charts.

Check the "Enable Auto-Creat Charts" box, then Click OK.


Matters of communication are between the lab and the site. SOAPware®, Inc does not provide communication services.

SOAPwareXchangeHL7 supports file-based or TCP-based interfaces. A file based interface will consist of the interfacing system, or system user, depositing HL7 messages in a specified location on the SOAPwareXchangeHL7 machine. SOAPwareXchangeHL7 will then retrieve and parse these messages. When the messages have been parsed, SOAPwareXchangeHL7 will remove them.

A TCP based interface will require a TCP connection between SOAPwareXchangeHL7 and the sending system.SOAPwareXchangeHL7 will listen for incoming messages, and parse them as they arrive.SOAPwareXchangeHL7 will always return an ACK messages for TCP messages received.


File based communication is the preferred communication method and allows for easiest troubleshooting for SOAPware Support. All incoming lab messages should be deposited to the same directory.This directory must be reserved for the sole purpose of incoming messages; no other file types or information should be stored there.SOAPwareXchangeHL7 will remove each file after processing.


Current versions of SOAPwareXchangeHL7 are only capable of monitoring a single port.If multiple labs are interfaces to the same site, one lab may use the TCP connection. The other labs must use a file-based method, depositing result files into the same directory.

The TCP connection should not be closed after each send, as this will require the SOAPwareXchangeHL7 user to reset the connection from their end.

While we realize the value of TCP connections and offer these, we do not have the resources to troubleshoot them, and will recommend a file-based solution if problems turn up with the connection. If a sending facility/application has issues with connecting to a specific port on a clients local network, SOAPware staff will recommend contacting the clients IT personnel for further troubleshooting.

The XchangeHL7 will automatically send an ACK after each report is received. This cannot be controlled or altered via the XchangeHL7 GUI.

SOAPware, Inc. does offer connectivity services when none are available through the Lab company for an additional setup and subscription fee. Speak with the SOAPware Sales Team if these services are needed.

The MSH (Message Header) Segment

The MSH (Message Header) Segment

The Sending Application value in MSH-3 is used by SOAPwareXchangeHL7 to determine the source of the message and the proper parser to invoke.  This value must be "ADT" unless a custom interface parser has been developed.  

Receiving Application in MSH-5 must be "SOAPWARE."

The EVN (Event Type) Segment

The EVN (Event Type) Segment

Possible values for EVN-1 are:

A01 - admit a patient

A04 - register a patient

A05 - pre-admit a patient

A08 - update patient information

A10 - patient arriving

A31 - update patient information

All of these codes will result in an update of demographic information in SOAPware®, and the creation of a new chart if necessary.

The PID (Patient Identifier) Segment

The PID (Patient Identifier) Segment

The Patient ID in PID-3 will be entered into a matching table.  This ID is required to be unique for each patient.  First Name, Last Name, Birthdate, Sex, and Social Security Number are all used for the patient matching algorithm.  Omitting any of this information may cause the record to be queued for manual assignment.  Demographic information included in the PID (Patient Identifier) segment will be used to update the demographics in the patient chart.

The PV1 (patient visit) Segment

The doctor ID and name from PV1-7 (attending doctor) will be used to create the physician mapping. Once established, XchangeHL7 will assign that primary provider to newly created charts.

The IN1 (Insurance) Segment

The IN1 (Insurance) Segment

Accepted Insured Relation Codes:

00 Self

01 Spouse

04 Grandfather or Grandmother

05 Grandson or Granddaughter

07 Nephew or Niece

09 Adopted Child

10 Foster Child

15 Ward

17 Stepson or Stepdaughter

19 Child

20 Employee

21 Unknown

22 Handicapped Dependent

23 Sponsored Dependent

24 Dependent of a Minor Dependent

29 Significant Other

32 Mother

33 Father

34 Other Adult

36 Emancipated Minor

39 Organ Donor

40 Cadaver Donor

41 Injured Plaintiff

43 Child Where Insured Has No Financial Responsibility

53 Life Partner

G8 Other Relationship