HL7 Templates
HeartLab HL7 Templates allow administrators to customize the HL7 messages sent to external systems such as Electronic Medical Records (EMR) and Practice Management Systems (PMS).
HL7 templates use variables to automatically insert patient information, study details, and report data.
Before You Begin
HL7 templates are usually configured with assistance from your EMR/PMS vendor (or other relevant intergration provider), and HeartLab support.
Create an HL7 Template
- Navigate to Settings > HL7 > Templates
- Select Create HL7 Template
- Enter a template name.
- Select Create Template
HL7 Template Content
The content editor contains the HL7 message structure generated by HeartLab, including dynamic sections where necessary.
For new templates, default content is provided that fulfills the requirements of most receiving systems.
Dynamic Variables
Templates use dynamic variables in this format:
{{ variable }}
These variables are automatically replaced with study, patient, or report data when the HL7 message is generated.
Dates and names must be passed through a filter before being output so that they can be formatted appropriately:
| Filter | Applies to | Description |
|---|---|---|
date | Dates and timestamps | Formats the value, e.g. {{ study.date | date: 'yyyyMMddHHmmss' }}. Defaults to yyyyMMdd when no format is given. |
person_name | Names | Formats the name in HL7 XPN component order, e.g. {{ patient.name | person_name }}. Pass 'print' for a human-readable name, or 'hl7', '&' to nest it in a component. |
measurement | Measurement names | Outputs the study's value for a measurement in the given unit, e.g. {{ 'aorticRootDiameter' | measurement: 'cm', decimalPlaces: 1 }}. See Measurements below. |
raw | Any text | Outputs the value without HL7 escaping. Use only for text that already contains HL7 separators. |
The full set of variables is below.
Message
| Variable | Description |
|---|---|
{{ message.id }} | Unique ID for this message, suitable for MSH.10 |
{{ message.timestamp }} | Timestamp when the message was generated, in your organization's timezone |
{{ message.sendingFacilityId }} | Your organization's first configured HL7 facility ID |
{{ message.applicationVersion }} | The version of HeartLab that generated the message |
Patient
| Variable | Description |
|---|---|
{{ patient.id }} | Patient identifier |
{{ patient.name }} | Patient name |
{{ patient.birthdate }} | Patient date of birth |
{{ patient.sex }} | Patient sex: M, F, O, or empty when unknown |
{{ patient.address }} | Patient address |
{{ patient.bodySurfaceArea }} | Patient body surface area in m², empty when height or weight is unknown |
Study
| Variable | Description |
|---|---|
{{ study.id }} | Unique ID of the study in HeartLab |
{{ study.studyInstanceUid }} | DICOM Study Instance UID |
{{ study.date }} | Date and time the study was performed, in your organization's timezone |
{{ study.accessionNumber }} | Study accession number |
{{ study.referringPhysicianName }} | Referring physician's name |
{{ study.performingPhysicianName }} | Performing physician's name |
{{ study.type.code }} | Study type code, e.g. ultrasoundEchocardiogramStress |
{{ study.type.name }} | Study type name, e.g. Echo - Stress. Suited to OBR-4.2 |
{{ study.type.abbreviation }} | Study type abbreviation, e.g. SE. Suited to OBR-4.1 |
{{ study.hl7DiagnosticServSectId }} | Diagnostic service section ID for the study type (HL7 table 0074), e.g. CUS for an echo |
study.isUrgent | Whether the study is flagged as urgent. See below. |
{{ study.clinicalLocation }} | The study's clinical location |
Study type variables are empty when the study type is not specified.
study.isUrgent can be used in a condition to select specific content:
{%- if study.isUrgent -%}S^STAT - Critical/Urgent^HL70280{%- else -%}R^Routine^HL70280{%- endif -%}
Report
| Variable | Description |
|---|---|
{{ report.id }} | Unique ID of the report in HeartLab |
{{ report.type }} | Report type: preliminary, final or amendment |
{{ report.hl7ResultStatus }} | Result status for the report type: P, F or C |
{{ report.completedAt }} | Timestamp when the report was completed, in your organization's timezone |
{{ report.completedBy }} | Name of the user who completed the report |
{{ report.completedById }} | HeartLab user ID of the user who completed the report |
{{ report.templateName }} | Name of the report template used, empty for reports ingested from an external system |
{{ report.pdf }} | Encoded report PDF |
{{ report.text }} | Report PDF converted to plain text |
{{ report.rtf }} | Encoded RTF document containing an image of each report page (not available for Agent deliveries) |
Measurements
The measurement filter outputs the value of one of the study's measurements, which allows measurements to be sent in their own OBX segments:
OBX|2|NM|LVIDd^LV Internal Diameter Diastole^L||{{ 'leftVentricleInternalEndDiastolicDimension' | measurement: 'cm', decimalPlaces: 1 }}|cm|||||F
The filter is applied to a measurement name. Its first argument is the unit to output the value in, which is required and can be given as a unit name such as 'centimeters' or its abbreviation such as 'cm'. The unit must be one that the measurement can be converted to, e.g. a distance can't be output in 'mL'.
The following options can then be given by name, in any order:
| Option | Description |
|---|---|
decimalPlaces | The number of decimal places to output. Defaults to the number of decimal places HeartLab displays for the measurement. |
indexing | 'bodySurfaceArea' divides the value by the patient's body surface area, giving a value in the unit per m², e.g. {{ 'leftVentricleMass' | measurement: 'g', indexing: 'bodySurfaceArea' }}. Defaults to 'none'. |
The unit is not included in the output, so it should be placed in the HL7 field for units, such as OBX-6. An indexed value's unit is the unit per m², e.g. g/m2.
Body surface area is calculated with the Du Bois formula from the height and weight recorded on the study. When either is unknown an indexed value is empty.
When a measurement can be acquired in more than one way, pass several measurement names separated by commas through the split filter. The first measurement that has a value in the study is used:
{{ 'leftVentricleInternalEndDiastolicDimension,leftVentricleInternalEndDiastolicDimensionMMode' | split: ',' | measurement: 'cm', decimalPlaces: 1 }}
The output is empty when the study has no value for the measurement. To omit a segment entirely when there is no value, assign the result to a variable and test it:
{%- assign lvef = 'leftVentricleEjectionFractionBiplane' | measurement: '%' -%}
{%- if lvef %}
OBX|3|NM|LVEF^LV Ejection Fraction^L||{{ lvef }}|%|||||F
{%- endif %}
Measurement names are the same as those used in report calculations, and are listed under Settings > Reports > Calculations.
Example Output
The Example Output section displays a rendered preview of the generated HL7 message using example data.
This can be used to:
- Validate HL7 formatting
- Verify variable replacement
- Confirm segment structure
- Review message output before deployment
Downloading HL7 Output
Select HL7 Download to export the generated HL7 example output for:
- Testing
- Validation
- EMR onboarding
- Integration troubleshooting
Best Practices
- Keep a backup of working templates before making changes
- Validate template changes with your receiving system
- Test changes in a non-production environment where possible
- Confirm receiving systems support the configured HL7 version and message structure
Troubleshooting
Common causes of HL7 formatting issues include:
- Invalid HL7 segment structure
- Incorrect separator characters
- Unsupported receiving system requirements
- Invalid or incomplete template variables
- Incorrect encoding expectations
If generated HL7 output is rejected:
- Review the Example Output section
- Verify all required segments exist
- Confirm formatting requirements with the receiving system
- Compare output against vendor-provided HL7 specifications
- Contact your HeartLab representative for assistance if required
MFR