HL7 Specification

Overview

You can create orders in Ovation by importing HL7®  messages. Similarly, you can receive results that Ovation exports as HL7 messages. This article documents Ovation’s standard HL7 message specification so that you can generate and interpret these messages.

Standard HL7 Specification (version 1.1)

General Considerations

The HL7 standard

HL7 is an international standard that specifies both the syntax and semantic of health-care related interchange files. You should review the information at hl7.org or at any of a number of useful third-party sites easily found on the Internet to understand the general concepts and the specific syntax.

Forward compatibility

Ovation may expand this specification in the future to write information to (and read information from) more locations than are currently specified. You should not rely on the absence of segments or on empty fields in segments since that may change without notice in the future. Conversely, while you can import messages with information in fields that do not currently appear in this specification, future changes to the specification may cause Ovation to interpret that information, which is likely to result in failed imports.

Segments

Ovation reads the HL7 segments described below. You must provide the MSH segment first, but the others can be in any sequence. All segments must be separated by a carriage return character. In some cases, which are noted, you can provide multiple of the same segment.

Import and export differences

Generally, information is expected in the same location in the file upon import as it is written to upon export. There are, however, some cases where the same information is written to multiple locations (but still only importable from one). There are also some segment types that are not importable at all – and only written on export.

Required information

Very little information is required to create a requisition with an HL7 message. (What is required is noted.) However, your configuration of Ovation may require many fields in order for the requisition to be verified and processed. These requirements are not checked during the import process and do not stop the requisition from being created. You can provide any additional required information by directly editing the order’s req form.

Date and time formatting

Some fields hold a date and some hold a date with a time-of-day together. Follow these standards to interpret this information in an exported message or to provide it upon import:

  • Dates must be in this format: YYYYMMDD. For example: 19850419 for April 19, 1985
  • Datetimes must be in this format: YYYYmmddHHMMSSZ. For example: 19850419235930-0500 for April 19, 1985 at 11:59:30 PM EST

Errors

If Ovation is unable to import your HL7 message or unable to create a requisition with it after having read it, Ovation will produce an error message and will not create the order. You will see this error in the Event log (and you can see it immediately if you are manually importing). You can retry after correcting the error in your file. While Ovation will sometimes discover and report multiple errors in one attempt to import a message, this is not generally true. You should resolve each error as reported and retry the import to discover any remaining errors.

MSH Segment (Message Header)

Required: Yes (and must be the first segment)
Multiple: No
Import/Export: Both

Purpose: Provide message metadata

Field Usage
MSH-1 Field separator, which must be provided and must be |
This is different from all other fields. It is actually the first character after “MSH” in MSH|
MSH-2 Required encoding characters
These describe the following, in this order:
  1. Component Separator (normally ^)
  2. Subcomponent Separator (normally &)
  3. Field Repeat Separator (normally ~)
  4. Escape Character (normally \)
Ovation does not support subcomponents or and only supports repeating fields on export in some cases, so those separator characters do not matter in an import message, but you must provide the component separator, even to use ^ and if you need to escape characters (which you do if your field separator might ever appear in field values), then you need to provide all four characters.

Together with the field separator, the typical beginning of your MSH header will usually be:

MSH|^&~\|

and you can choose to only provide that.

Note that the second | is required.

Messages exported by Ovation always use  ^~\&.

MSH-3 Export only
Always   Ovation
MSH-4
Export only
Always   Ovation
MSH-7 Export only
The date and time in UTC of when the message was generated
MSH-9 Export only
Always   ORU^R01, regardless of the message purpose
MSH-10 Export only
The date and time in UTC of when the message was generated
MSH-11 P when the message was exported by lab.ovation.io, D when it was exported by lab-sandbox.ovation.io
MSH-12 Always  2.3 
MSH-21 Alternative field for the mapping identifier
This is a deprecated field. Please use ZOV-1 instead. If you do provide ZOV-1, the value in MSH-21 will be ignored.
If you choose to use MSH-21 please note that multiple OBR segments are not then allowed.

ZOV Segment (custom message-wide information)

Required: Yes
Multiple: No
Import/Export: Import only

Purpose: Identify the Mapping, which indicates how to read the message and the template in which to create the resulting requisition

Field Usage
ZOV-1 The Identifier of the Mapping you want the message to use

Find the list of Mappings on the Mappings tab at Integrations > HL7 Import via SFTP.

DG1 Segment (Diagnosis)

Required: No
Multiple: Yes
Import/Export: Both

Purpose: List the diagnostic codes on the requisition

Field Usage
DG1-3
DG1-3.2 ICD-10 Code

GP1 Segment (Grouping/Reimbursement - Visit)

Required: No
Multiple: No
Import/Export: Both

Purpose: Indicate the billing type

Field Usage
GP1-1 Billing type. Either Insurance, Patient Bill, or Institutional Bill in mixed case as shown. For import, provide a billing type that is configured to be allowed in the requisition template referenced by the Mapping.

Note that, while the attribute that indicates Patient Bill or Institutional Bill is available for import and export, the attributes for who to bill in those cases (name, phone number, email and address) require a custom HL7 specification.

FT1 Segment (Financial Transaction)

Required: Yes
Multiple: Yes
Import/Export: Export only

Purpose: Provide details related to reimbursement for each test that is included in the message.

Note that configuration options control whether originally selected tests, subsequently deselected tests or both are included. In the unlikely case that all tests are excluded by these options, there will be a single FT1 segment that only has values for FT1-2, FT1-3 and FT1-4.

Field Usage
FT1-2 Sample Identifier
FT1-3 Requisition Identifier
FT1-4 Collection date and time for the sample; see above regarding the datetime format
FT1-6 Transaction type: always CG
FT1-7 Test CPT coded
FT1-10 Units; only applicable when Billing Rules are applied
FT1-20 The laboratory’s CLIA number
FT1-25
FT1-25.1 Test Code
FT1-25.2 Test Name
FT1-26 Modifiers; only applicable when Billing Rules are applied

IN1 Segment (Insurance)

Required: No
Multiple: Up to two; the second segment describes the secondary insured
Import/Export: Both

Purpose: Provides reimbursement information for the requisition

Field Usage
IN1-2 Export only
Insurance ID Number
IN1-3 Export only
Billing service provider's payer code
IN1-4 Insurance Provider Name
IN1-8 Insurance Group Number
IN1-16 Name of Person Insured
IN1-16.1 Insured’s first name
IN1-16.2 Insured’s last name
IN1-17
IN1-17.2 Relationship to Insured: Self, Spouse, Life partner, Child, Ward, Handicapped Dependent, Sponsored Dependent, Dependent of a minor Dependent, Other in mixed case as shown
IN1-18 Insured Date of Birth; see above regarding the date format
IN1-19.1 Insured address. Non-U.S. addresses are not supported.
IN1-19.1 Insured Street Address
IN1-19.3 Insured City
IN1-19.4 Insured State: the 2-character code for any U.S. state or territory
IN1-19.5 Insured Zip Code: the U.S. zip code either in 5-digit or 9-digit form. For 9-digit, any punctuation before the final 4 digits is accepted.
IN1-36 Insurance ID Number
IN1-43 Insured Sex. Provide M, F or U in any case
IN1-49 Export only

Insurance ID Number

IN2 Segment (Insurance Additional Information)

Required: No
Multiple: Up to two; the second segment describes the secondary insured
Import/Export: Both

Purpose: Provide additional information regarding the person insured

Field Usage
IN2-26 Insurance Subscriber Number
IN2-53
IN2-53.4 Insured Email

OBR Segment (Observation Request)

Required: Yes
Multiple: Yes
Import/Export: Both

Purpose: List test panels that are part of the requisition

Field Usage
OBR-2 Export only

Requisition Identifier
OBR-4 Provide the code for a test panel that is configured in your template. Look at the requisition template’s form configuration to see what is configured. Go to More > Other > Test Panels to get the code to use (only the name of the test panel is shown elsewhere).
OBR-4.1 Test Panel Code
OBR-4.2 Export Only

Test Panel Name

OBX Segment (Observation/Result)

Required: Yes
Multiple: Yes; the first two segments hold the overall result of the order and Base64-encoded PDF result report itself; arbitrarily many subsequent segments hold results for specific tests
Import/Export: Export

Purpose: Provide the results of the ordered test(s)

Field Usage
OBX-2 ED for the result report segment, otherwise empty
OBX-3 The test for test result segments, otherwise empty
OBX-3.1 Test Type
OBX-3.2 Test Code
OBX-3.3 Test Name
OBX-5
OBX-5.1 The overall result for the overall result segment, otherwise empty
The values for the overall result in the message, as well as whether an overall result is provided at all, depend on your specific configuration. Please contact Ovation for details as they apply to you.
OBX-5.3 Base64 for the PDF segment, otherwise empty
OBX-5.4 PDF for the PDF segment, otherwise empty
OBX-5.5 The Base64-encoded PDF result report for the PDF segment, otherwise empty
OBX-6
OBX-6.2 Units for the test result; only applicable when Billing Rules are applied
OBX-14 The date and time when the result was generated; see above regarding the datetime format
OBX-17 Test LOINC for test results segments; otherwise empty

ORC Segment (Common Order)

Required: Yes
Multiple: No
Import/Export: Both

Purpose: Describe the order itself

Field Usage
ORC-1 Order control: RE on export; NW on import
ORC-2 Requisition Identifier
Note that this is required on import even if you have configured the template to auto-generate requisition identifiers.
ORC-3 Export only

Requisition Identifier
ORC-5 Export only

Order status: CM on export
ORC-12 The NPI of the ordering provider
If it is not linked to the provider account you describe in ORC-21, then it will be linked to it automatically. If you do not provide a provider account in ORC-21, then the provider will be linked to the “Default” provider account.
Note that this is not required to create an order, but is ultimately required to release patient test results.
ORC-21 The provider account placing the order
ORC-21.1 Provider Account Name
ORC-21.3 Provider Account Account Number

On import, you can provide either the account name or the account number to identify the provider account. If you provide both, they must both match an existing provider account.

PID Segment (Patient Identification)

Required: No
Multiple: No
Import/Export: Both

Purpose: Describe the Patient

Field Usage
PID-2 Patient’s Medical Record Number
PID-5 Patient’s name
PID-5.1 Patient Last Name
PID-5.2 Patient First Name
PID-5.3 Patient Middle Name
PID-7 Patient Date of Birth
PID-8 Patient Sex: M, F or U in any case
PID-10
PID10.2 Patient Race: white, asian, native, black, islander or undisclosed in any case
PID-11 Patient’s address. Provide an address in the U.S. or its territories. Non-U.S. addresses cannot be imported from Ovation standard HL7 files.
PID-11.1 Patient Street Address
PID-11.2 Patient Street Address Line 2
PID-11.3 Patient City
PID-11.4 Patient State or Province/Region: if the Country in PID-11.6 is United States, then this is the 2-character code for any U.S. state or territory; otherwise it can be any text
PID-11.5 Patient Zip or Postal Code: if the Country Code in PID-11.6 is United States, then this is a U.S. zip code either in 5-digit or 9-digit form (for 9-digit, any punctuation before the final 4 digits is accepted); otherwise it can be any text
PID-11.6 Patient Country: match the spelling and case shown in the requisition form
PID-13
PID-13.1 Patient Phone Number
PID-13.4 Patient Email
PID-22
PID-22.2 Patient Ethnicity: hispanic, nonhispanic or undisclosed in any case

RXE Segment (Medication)

Required: No
Multiple: Yes
Import/Export: Both

Purpose: List medications prescribed for the patient.

Field Usage
RXE-2 Prescribed medication
RXE-2.2 An RXCUI from the RxNorm database that can reference a BN, SBD/BPCK, SCD/GPCK or IN/MIN, depending on requisition template configuration
RXE-2.3 Always RXCUI in uppercase

SPM Segment (Specimen)

Required: Yes; at least one sample must be provided to create an order
Multiple: Yes
Import/Export: Both

Purpose: Describe the sample(s) collected for the ordered test(s)

Field Usage
SPM-2 Sample Identifier
SPM-4
SPM-4.2 Sample Type
SPM-7
SPM-7.2 Collected By
SPM-11
SPM-11.2 Sample Group
SPM-17 Collection date and time for the sample; see above regarding the datetime format
SPM-18 Received date and time for the sample; see above regarding the datetime format
SPM-27
SPM-27.1 Container ID
SPM-27.2 Container Type
SPM-28
SPM-28.2 Well or Position

ZCX Segment (custom attribute values)

Required: No
Multiple: Yes
Import/Export: Both

Purpose: List values for custom attributes configured in Ovation

Field Usage
ZCF-2 Type of custom attribute: Requisition, Patient, or Sample
ZCF-3 Sample identifier for a sample custom attribute, otherwise empty
ZCF-4 Custom attribute key. Refer to the requisition template’s form configuration to find the key. Note that this field is the “Key” (not the “Name”) and that it follows the exact case and punctuation shown in the form configuration.
ZCF-5 Custom attribute value. This is the value for the custom attribute indicated by the key in ZCF-4.
  • For string custom attributes that do not appear with a drop-down in the form, the value can be any text.
  • For string custom attributes that do appear with a drop-down in the form, the value from that drop down, copying case and punctuation exactly.
  • For boolean custom attributes, provide Yes or No in mixed case as shown.
  • For date custom attributes, provide a date in the format described above.
Note that the custom attribute you refer to does not have to be displayed in your template’s form. If you refer to a custom attribute that is not in the form, Ovation will still  store the value on import and you can still retrieve it on export.

Custom HL7 Specifications

In some cases, Ovation can import and export HL7 messages that do not comply with the specification described above. Some data can be in different locations and some expected/acceptable values can be modified. To request a custom engagement, click on the help beacon in the lower right corner of the application, select the Project Request Form option and complete the form. Ovation will then follow up with you directly. There may be an additional charge for this service.

Acknowledgements

HL7®, and FHIR® are the registered trademarks of Health Level Seven International and our use of these trademarks does not constitute an endorsement by HL7.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.