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:19850419for April 19, 1985 - Datetimes must be in this format:
YYYYmmddHHMMSSZ. For example:19850419235930-0500for 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-2 | Required encoding characters These describe the following, in this order:
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:
and you can choose to only provide that. Note that the second Messages exported by Ovation always use |
| MSH-3 | Export only Always |
| MSH-4 | Export only Always |
| MSH-7 | Export only The date and time in UTC of when the message was generated |
| MSH-9 | Export only Always |
| 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.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.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.1 | Billing type. Either 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.1 | Sample Identifier |
| FT1-3.1 | Requisition Identifier |
| FT1-4.1 | Collection date and time for the sample; see above regarding the datetime format |
| FT1-6.1 | Transaction type: always CG |
| FT1-7.1 | Test CPT coded |
| FT1-10.1 | Units; only applicable when Billing Rules are applied |
| FT1-20.1 | The laboratory’s CLIA number |
| FT1-25.1 | Test Code |
| FT1-25.2 | Test Name |
| FT1-26.1 | 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.1 | Export only Insurance ID Number |
| IN1-3.1 | Export only Billing service provider's payer code |
| IN1-4.1 | Insurance Provider Name |
| IN1-8.1 | Insurance Group Number |
| IN1-16.1 | Insured’s first name |
| IN1-16.2 | Insured’s last name |
| IN1-18.1 | Insured Date of Birth; see above regarding the date format |
| 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. (Non-U.S. addresses are not supported.) |
| 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.1 | Insured Date of Birth; see above regarding the date format |
| IN1-19.1 | Insured address. Non-U.S. addresses are not supported. |
| IN1-36.1 | Insurance ID Number |
| IN1-43.1 | Insured Sex. Provide M , F or U in any case |
| IN1-49.1 | 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.1 | Insurance Subscriber Number |
| 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.1 | Export only Requisition Identifier |
| OBR-4.1 | Test Panel Code 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.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.1 | ED for the result report segment, otherwise empty |
| OBX-3.1 | The test for test result segments, otherwise empty |
| OBX-3.1 | Test Type The test for test result segments, otherwise empty. |
| OBX-3.2 | Test Code See OBX 3.1 above. |
| OBX-3.3 | Test Name |
| 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.2 | Units for the test result; only applicable when Billing Rules are applied |
| OBX-14.1 | The date and time when the result was generated; see above regarding the datetime format |
| OBX-17.1 | 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.1 | Order control: RE on export; NW on import |
| ORC-2.1 | Requisition Identifier Note that this is required on import even if you have configured the template to auto-generate requisition identifiers. |
| ORC-3.1 | Export only Requisition Identifier |
| ORC-5.1 | Export only Order status: CM on export |
| ORC-12.1 | 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.1 | Provider Account Name This is the provider account placing the order 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. |
| ORC-21.3 | Provider Account Account Number See ORC-21.1 above. |
PID Segment (Patient Identification)
Required: No
Multiple: No
Import/Export: Both
Purpose: Describe the Patient
| Field | Usage |
|---|---|
| PID-2.1 | Patient’s Medical Record Number |
| PID-5.1 | Patient Last Name |
| PID-5.2 | Patient First Name |
| PID-5.3 | Patient Middle Name |
| PID-7.1 | Patient Date of Birth |
| PID-8.1 | Patient Sex: M, F or U in any case |
| PID-7.1 | Patient Date of Birth |
| PID-8.1 | Patient Sex: M, F or U in any case |
| PID10.2 | Patient Race: white, asian, native, black, islander or undisclosed in any case |
| PID-11 | Patient’s address. |
| PID-11.1 | Patient Street 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.2 | Patient Street Address Line 2 See PID-11.1 |
| PID-11.3 | Patient City See PID-11.1 |
| PID-11.4 | Patient State or Province/Region: if the Country in PID-11.6 is See PID-11.1 |
| PID-11.5 | Patient Zip or Postal Code: if the Country Code in PID-11.6 is See PID-11.1 |
| PID-11.6 | Patient Country: match the spelling and case shown in the requisition form See PID-11.1 |
| PID-13.1 | Patient Phone Number |
| PID-13.4 | Patient Email |
| 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.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.1 | Sample Identifier |
| SPM-4.2 | Sample Type |
| SPM-7.2 | Collected By |
| SPM-11.2 | Sample Group |
| SPM-17.1 | Collection date and time for the sample; see above regarding the datetime format |
| SPM-18.1 | Received date and time for the sample; see above regarding the datetime format |
| SPM-27.1 | Container ID |
| SPM-27.2 | Container Type |
| 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.1 | Type of custom attribute: Requisition , Patient , or Sample |
| ZCF-3.1 | Sample identifier for a sample custom attribute, otherwise empty |
| ZCF-4.1 | 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.1 | Custom attribute value. This is the value for the custom attribute indicated by the key in ZCF-4.
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.