Template Tool - Experimental

Overview

Templates turns the active HL7 v2 message into a readable preview using Liquid templates. It is an Enterprise feature.

• HTML packs render a compact clinical-style page (message header, patient, observations) with HL7Spy’s built-in Liquid HTML templates.

• FHIR packs convert the message with Microsoft’s Liquid FHIR conversion templates (from the FHIR Converter project) and show the result as JSON with a navigable tree.

The preview follows the message selected in your current HL7 message tab.

At a glance

• Open from Tools → Templates (Show/Hide Tools)

• Left: Packs list — choose and manage template packs (HTML and FHIR share one store)

• Right: preview tabs based on pack output (WebView / Html / Text / Xml, or Tree / Json)

• Built-in packs are read-only — Clone to create an editable copy

• Opening the pack editor shows the pack README.md overview first (Markdown preview)

• Pack zoom and grid text follow the HL7Spy font zoom on the status bar

Opening Templates

1. Open an HL7 v2 message tab and select a message.

2. Show the Templates tool from the Tools menu (Show/Hide Tools).

3. Templates docks like other tools. The left panel lists packs; the right side shows the preview.

HL7Spy remembers the last pack you used and restores it the next time you open Templates.

Tip

Preview tabs stay hidden until Templates has something to show for the current message and pack. After a successful render, the tabs appropriate to that pack appear automatically.

Packs

HTML and FHIR packs live in the same HL7Spy settings Templates folder and appear together in the Packs list. They share one pack store; only the pack kind changes how preview and editing work.

Packs are grouped by kind:

Each row shows the pack Name and Version. Hover a row to see its description.

Built-in vs editable packs

Built-in packs ship with HL7Spy and cannot be overwritten. Use Clone to create a writable copy under your HL7Spy Templates folder.

Toolbar

The same commands are available from the packs list right-click menu.

Actions menu

HTML preview (Templates packs)

When an HTML pack is active and the template produces HTML, Templates shows:

HL7Spy remembers whether you last preferred WebView or Html while you stay on HTML packs.

Built-in HTML layout

The built-in HTML pack is meant for a quick scan of the selected message. It also ships two sample rules so you can see how conditioned templates vary the preview:

Message

• Type, Time, Control ID, From, To, Version (from MSH)

Patient

• MRN, Name, Sex, DOB, Age (from PID)

• Admit (when present), Class, Location, Attending / Referring (when present), Visit # (from PV1). Empty Attending, Referring, or Admit fields are omitted. Missing visit numbers show as ???.

Observations

• One block per order group: accession / order fields from OBR, then a table of OBX results (#, ID, Value, Units, Status)

FHIR preview (Fhir packs)

When a FHIR pack is active, Templates converts the selected v2 message using Liquid templates based on Microsoft’s open-source FHIR Converter catalog, then shows:

The built-in FHIR pack starts from those Microsoft HL7 v2 → FHIR Liquid templates. By default, HL7Spy picks the entry template from MSH-9 (prefer MSH-9.3, otherwise MSH-9.1 + MSH-9.2). Clone the pack when you need to customize mappings for your site. See How template selection works and the pack README in the editor.

Tree find toolbar

• Type in the find box to locate nodes.

• Toggle Filter / Search:

  • Filter — hide non-matching nodes

  • Search — highlight matches; use Previous / Next to move between hits

• Sync (on by default) — selecting a tree node jumps the Json tab to that line

Tip

Keep Sync on when inspecting large FHIR output: click a node in the Tree, then switch to Json to read the surrounding text at that location.

Editing templates

1. Select a writable pack (clone a built-in first if needed).

2. Click Edit (or Clone on a built-in pack, which creates a writable copy and opens the editor).

Pack overview (README)

When the editor opens, HL7Spy shows the pack’s root README.md (if present) as a formatted Markdown preview. Built-in HTML and FHIR packs include a README that describes pack layout and how a template is chosen for the current message.

Select any other .md file in the files tree to preview it the same way. Liquid, JSON, HTML, and other text files open in the code editor.

Tip

Use the README as the first place to look when learning a pack or onboarding a colleague to your customized clone.

Editor layout

FHIR packs hide the Rules pane: conversion usually picks a template from MSH-9 (see below). You still browse and edit files in the Files tree.

File badges in the tree call out special roles (for example (fallback) for _default, or (rule) when a file is already listed in Rules).

How template selection works

HTML (Templates) packs

1. Rules in the Rules grid are evaluated in order.

2. The first enabled rule whose Condition matches the current message is used as the root template.

3. If no rule matches, Default (_default) is used.

4. Other files under templates/ can still be {% include %} targets (for example shared CSS or segment partials).

The built-in Default row is a fallback and cannot be renamed or deleted. Add conditioned Rules for specific message types (for example MSH-9.1 = 'ADT' AND MSH-9.2 = 'A18').

FHIR packs

Conversion picks one message entry template for the current HL7 v2 message:

1. Explicit rules (if present in the pack) — conditions are evaluated in order; the first enabled match wins.

2. Default MSH-9 mapping — if no explicit rule matches:

   • Prefer MSH-9.3 (message structure) when present (for example ADT_A01).

   • Otherwise combine MSH-9.1 (message type) + MSH-9.2 (trigger event) as {MSH-9.1}_{MSH-9.2} (for example ADT + A01 → ADT_A01).

3. That name is matched to a template file such as templates/ADT_A01.liquid.

Example MSH segment:

• MSH-9.1 = ADT

• MSH-9.2 = A01

• MSH-9.3 = ADT_A01 → template ADT_A01

Helper templates under folders such as Resource/, Reference/, DataType/, and ID/ are included by entry templates; they are not selected directly from MSH-9.

Editor toolbar and save

Save buttons enable only when there are unsaved changes. Closing with unsaved changes prompts you to save, discard, or cancel.

Built-in packs are read-only

You cannot edit or save into Built-in HTML or Built-in FHIR. Click Clone, then edit the clone.

Root HTML templates should be complete HTML documents (including <html> … </html>). Include partials (MSH, PID, PV1, and so on) can be fragments.

Liquid syntax and Microsoft FHIR templates

Templates are written in Liquid. Use these references when authoring or customizing packs:

Note

HTML preview packs use Liquid for presentation (HTML output). FHIR packs use Liquid for conversion (JSON FHIR output), aligned with the Microsoft FHIR Converter template model. HL7Spy may expose additional filters for HTML preview (for example path helpers); core Liquid syntax remains as documented on the Liquid site.

Font size

• The packs grid follows the application font zoom (status-bar zoom control).

• The WebView HTML preview scales with the message editor font size.

• The Html / Json / Text / Xml editors use the message editor font.

Typical workflows

Preview a message with the built-in HTML pack

1. Open a v2 message tab and select a message.

2. Open Templates.

3. Select Built-in HTML.

4. Review the rendered page on the WebView tab (use Html to inspect the generated markup).

Customize the HTML preview

1. Select Built-in HTML → Clone.

2. Read the pack README that opens in the editor (layout and selection rules).

3. Edit Name / Description if you like.

4. Adjust _default / Default, add conditioned Rules, or edit MSH / PID / PV1 / OBR includes from the Files tree.

5. Save. The preview updates for the selected message.

Inspect a FHIR conversion

1. Select Built-in FHIR (or a cloned FHIR pack).

2. Use the Tree to browse the structure; with Sync on, the Json tab follows the selected node.

3. Optionally Clone the pack. The editor opens on the pack README (including how MSH-9.1 / MSH-9.2 / MSH-9.3 choose the entry template).

4. Edit conversion templates from the Files tree (see Liquid syntax and Microsoft FHIR templates), then Save to refine the output.

Share a pack with a colleague

1. Select your writable pack.

2. Actions → Export Pack and save the .nupkg.

3. On the other machine: Actions → Import Pack and select the file.

Troubleshooting

Related

• HTML and FHIR template packs are stored together under your HL7Spy settings Templates folder.

• Each pack can include a root README.md overview shown when you open the pack editor.

• Liquid language reference: https://shopify.github.io/liquid/