Connectivity

HL7 Templates

Create and customize HL7 message templates used to send HL7 to other systems.

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.

If you are unsure how your HL7 message should be structured, please contact your integration provider or HeartLab support before modifying templates.

Create an HL7 Template

If you do not see these settings, your role may not include Integrations: HL7 permissions. Contact your HeartLab administrator if required.

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.
`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

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)

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

HeartBox

Set up and validate a HeartBox appliance for DICOM transfer into HeartLab.

Kosmos

Connect a Kosmos device to HeartLab via IPSec VPN and DICOM profile configuration.