Healthcare Solution: HL7 Connector 2.1.6 — Qmatic Platform

Healthcare Solution: HL7 Connector 2.1.6

Qmatic Platform — User and Installation Guide

Revision History

Version	Date	Author	Remarks
001	2020-06-11	Jose Armenteros	First Draft
002	2020-06-16	M.D. de Winter	Textual changes, styling, and ordering
003	2020-06-16	Jose Armenteros	Review of the document; added introduction
004	2020-07-30	Jose Armenteros	Added multi listener feature
005	2022-01-20	Jose Armenteros	Added new features for the new release
006	2022-05-25	Jose Armenteros	Added new features for release 2.1.1
007	2023-05-05	Jose Armenteros	Added new features for release 2.1.2
008	2024-02-16	Jose Armenteros	Added new features for release 2.1.4
009	2024-09-23	Jose Armenteros	Bug fixing for release 2.1.5
010	2025-03-24	Jose Armenteros	Bug fixing for release 2.1.6

1. What’s New

Changes in version 2.1.6: Fixed the issue where the conditional path could not work handling multiline. See section 12.4.4.

2. Glossary

Abbreviation	Description
HIS	Hospital Information System
PAS	Patient Appointment System

3. Introduction

The Orchestra HL7 Module is a middleware product that greatly reduces the effort and time required to integrate Qmatic Orchestra with a hospital information system. This document covers all aspects of the module including supported use cases, a typical implementation process, and configuration.

3.1 What is HL7?

HL7 specifies flexible standards allowing healthcare systems to communicate with each other. HL7 version 2 defines electronic messages for administrative, logistical, financial, and clinical processes. Versions 2.1 through 2.6 are backward compatible.

HL7 v2.x messages use human-readable ASCII encoding with one-character delimiters:

Field separator: | (pipe)
Component separator: ^ (caret)
Subcomponent separator: & (ampersand)
Repetition separator: ~ (tilde)
Every message begins with the MSH segment (message header)

Example admission record:

MSH|^~\&|MegaReg|XYZHospC|SuperOE|XYZImgCtr|20060529090131-0500||ADT^A01^ADT_A01|01052901|P|2.5|
EVN||200605290901||||200605290900|
PID|||56782445^^^UAReg^PI||KLEINSAMPLE^BARRY^Q^JR||19620910|M||...

ACK acknowledgment codes:

Value	Description
AA	Application Accept
AE	Application Error
AR	Application Reject

3.2 HL7 Issues

Issue	Description
1 — Missing Fields	Some vendors omit fields instead of leaving them empty, shifting all subsequent field numbers.
2 — Same Data in Different Fields	The same information may appear in different fields or segments across implementations.
3 — Same Data in Different Formats	Timestamps and other data may be formatted differently (e.g. `19991231100000.000` vs. `19991231^100000.000`).
4 — Different Versions	Data can only be exchanged between applications supporting the same HL7 version.
5 — Missing Values	Some vendors omit even mandatory fields.
6 — Invalid Segment Grammar	Expected segments may be missing; unexpected segments may appear.

3.3 HL7 Messages

Messages are the atomic unit of data transfer, identified by a three-character message type code (e.g. ADT).

Segments are logical groupings of data fields, each identified by a unique three-character Segment ID. IDs starting with Z are reserved for local definitions.

Fields are character strings. Example: the HL7 version field at position 12 in MSH (e.g. 2.5).

4. HIS Integration Scenarios

4.1 At PRE-ARRIVAL

Orchestra appointments are synchronised with HIS appointments. Appointments must include custom parameters: integrationId (unique HIS appointment ID) and optionally ticketId.

Synchronisation of Appointments — HIS sends new/updated/deleted appointment and customer events. Included.
Daily Import of Appointments — Qmatic fetches appointments from HIS (via HL7 QBP). Included. See the public API section.

4.2 At ARRIVAL

Fetching appointments from Qmatic — Appointments pre-synchronised; patient identifies at kiosk; visit created; check-in reported to HIS. Included.
Fetching appointments from HIS — Qmatic fetches patient data from HIS in real time at arrival. Included.
HIS sends Qmatic a Check-In message — Patient identifies to HIS staff; HIS sends check-in message; Qmatic creates visit and reports back. Included.

4.3 Reporting Appointment Check-In to HIS

Qmatic reports check-in data to HIS if the visit contains all required data to build the HL7 check-in messages.

4.4 At SERVING

HIS can request the following Qmatic actions via HL7: call/recycle/end/transfer a visit by integrationId; add custom parameters; add a service to a visit. Included.

5. Sector

Healthcare, due to the nature of HL7.

6. Components

Hl7Connector application (war file) — Bridge between HIS and Orchestra; HL7 translator.
ServicePoint_WebServicePoint_Hl7 unit type — Service point unit type.
managementInformationServicePoints unit type — Provides service point visit status for improved performance.
notifyHl7VisitEvents unit type — Catches Orchestra events and POSTs to the hl7Connector outgoing message endpoint.

6.2 Notify Events to HIS Unit Type Parameters

Parameter	Description
Unit id	Identification code of the unit.
Notify visits for these queues	Select queues for visit event handling (marked blue).
Write data in QAgent log (debug)	If enabled, logs to agent log files.
Url to notify the event	Endpoint for sending HL7 messages. Example: `http://localhost:8080/hl7Connector/service/outgoingMessagesEngine.groovy`
Logger Name	Logger name for `orchestra backlog.xml` settings.

6.3 Management Information Service Points Unit Type Parameters

Parameter	Description
Unit id	Identification code of the unit.
Logging enabled	If enabled, logs to agent log files.

7. Service Points Unit Type (UTT)

Handles service points without requiring an assigned user. Included type: ServicePoint_WebServicePoint_Hl7.utt.

Parameter	Description
Unit id	Identification code of the unit.
Media Application	Media Application Surface name from Surface Editor.
Write data in QAgent log (debug)	If enabled, logs to agent log files.
Work Profile	Default work profile name.
Logger Name	Logger name for `orchestra backlog.xml` settings.

8. Installation

Orchestra version must be above Orchestra 7.0 [4.0.0.697]. Deploy unit type templates via System Administration; war files to /custdeploy.

Default hl7Connector connection: http://localhost:8080. A valid Orchestra user with access to the Central branch is required.

8.1 Settings via ApplicationContext.xml

Open the file inside the war at WEB-INF/CONFIG/applicationContext.xml and replace yourUser and yourPassword with valid Orchestra credentials.

8.2 Settings via External File

Place a file named hl7-connector.conf in the Orchestra conf folder (overrides ApplicationContext.xml):

username= user
password= password
server= localhost:8080
protocol= http

9. Settings

Basic configuration steps:

Configure a branch with at least one entry point and ServicePoint_WebServicePoint_Hl7 service points.
Configure calendar settings: Appointment Profile, calendar services, calendar resources.
Configure a log files folder.
Configuration > Orchestra Central Settings — Central Orchestra connection and credentials (appointments and customers).
Configuration > Orchestra Agent Settings — Orchestra Agent connection and credentials (entry points and service points).

9.1 Log Files

Proposed log files (added as appenders/loggers in conf/logback.xml):

hl7Connector.log — Incoming messages monitor.
Hl7Connector_Events_handling.log — Outgoing messages monitor.
Hl7Connector_Unattended_servicepoints.log — Unattended service points monitor.
integrationSummary.log — Summary of incoming HL7 messages and responses.
transactionErrorLog.log — Incoming HL7 messages that result in errors.

In production environments, set logging level to INFO.

Each appender uses a QPRollingFileAppender with 10 MB max file size, 10 days history, and 120 MB total cap.

10. HL7 Connector User Interface (Version 2.1.0)

The application menu provides access to: Configuration, Incoming Journeys, Outgoing Journeys, Templates, Mappings, Custom Ticket ID Templates, and Connector Tester. Configuration settings can be imported/exported as JSON files.

11. Configuration

11.1 HL7 Listener

Parameter	Description
Port	Local ports for receiving messages. Multiple ports separated by `;`.
TLS	Enable TLS/SSL. Certificates must be imported in most cases.

11.2 Listener Performance

HAPI uses java.util.concurrent.ExecutorService. Default ThreadPoolExecutor values: Core Pool Size = 10, Maximum Pool Size = 100, Keep Alive Time = 30, Max Threads = 100.

11.3 HL7 Monitoring

Parameter	Description
Monitor Thread Enabled	Enable the thread monitor.
Monitor Service Interval	Monitoring interval in seconds. Default: 10.

11.4 HL7 Settings

Parameter	Description
Charset	Character set (e.g. UTF-8).
Message type	Filter by message type. Use `*` for all (e.g. `SIU`, `ADT`).
Trigger event	Filter by event. Use `*` for all (e.g. `S12`, `A01`).
HL7 Version	Version for incoming messages: 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, or 2.6.
ER7 option	If enabled, messages use pipe & caret format. Otherwise XML format.

11.5 Remote Server (HIS) Configuration

Parameter	Description
Remote Server Enabled	Enable/disable sending messages to HIS.
IP Address	Remote server IP address.
Port	Remote server port.
Server Timeout (ms)	Connection timeout in milliseconds.
TLS	Enable TLS/SSL for remote server. Certificates must be imported.
Http Context	Enable HTTP servlet connection (e.g. `/hl7list`).
Enable Http Credentials	Enable/disable credential usage.
User / Password	HTTP credentials.

11.6 Logging & Monitoring

Parameter	Description
Logging Enabled	Enable per-transaction logging.
Logging Folder Path	Folder for per-transaction log files (must be created manually).
Number of days to keep logs	Days to retain log files (e.g. 30).
Save all incoming HL7 messages	Save each raw incoming HL7 message as `in_YYYYMMDD_HHMMSS.sss_Hl7_message.log`.

11.7 Orchestra Central Settings

Parameter	Description
Central Orchestra Enabled	Enable/disable Orchestra Central connection.
Username / Password	Credentials for central connector functions.
Protocol	HTTP or HTTPS.
Server (host:port)	Orchestra server and port (e.g. `localhost:8080`).

11.8 Orchestra Agent Settings

Parameter	Description
Orchestra Agent Enabled	Enable/disable Orchestra Agent connection.
Username / Password	Credentials for agent connector functions.
Protocol	HTTP or HTTPS.
Server (host:port)	Orchestra server and port.

11.9 Date Settings

Parameter	Example
HL7 Date Format	`yyyyMMddHHmmss` or `yyyyMMddHHmm`
Orchestra Date Format	`yyyy-MM-dd'T'HH:mm:ss.000+0000`

11.10 Customer

Configure the string template to build the customer externalId. Defaults: {customer.externalId} (calendar), {customer.cardNumber} (central). Available values: customer.phone, customer.identificationNumber, customer.externalId, customer.firstName, customer.lastName, customer.publicId, customer.email, customer.name.

11.11 Branches

Select the branches integrated by HL7 for searching visits by custom parameter.

12. Incoming Journeys

Triggered by incoming HL7 messages. Each journey checks rules then executes all defined actions. Journeys can be imported/exported as JSON; imported journeys are disabled by default.

12.3 Message

Each journey requires a Message Code (e.g. SIUS12, ADTA14) and a Message Template. The summary tab shows rules and actions for quick review.

12.4 Rules

All rules must be fulfilled for actions to execute. Each rule has: Name & description, HL7 path(s), and accepted values. If the value at any HL7 path matches at least one accepted value, the rule is fulfilled. Accepted values support REGEX. Use null for paths that return no value.

12.4.1 Simple Path

A single HL7 path and a collection of accepted values.

12.4.2 Conditional Path

Defined by: a value to check, an HL7 path to get the check value, an HL7 path for the final value, and a Find in segment flag.

12.4.3 Not Finding in Segment

If the check path value equals the value to find, the final value is read from the overall value path.

12.4.4 Finding in Segment

Iterates through items in the segment. Use (i{N}) syntax for iteration count. Examples:

/PID-3(i5)-5 — Iterates 5 times through PID-3 repetitions.
/PID(i10)-3-5 — Iterates 10 times through PID segments.
/PID(i10)-3(i5)-5 — Nested: 10 PID × 5 PID-3 iterations.

Fix in 2.1.6: Conditional path now correctly handles multiline scenarios.

12.5 Actions

Executed in configured order after all rules pass. If one action fails, remaining actions are not executed.

12.6 Parameters

Each parameter has fields with: Name, Action Type, Mandatory flag, HL7 Path, Default value (now = current date), Is Date flag. Multiple HL7 paths can be concatenated.

Key Parameter Reference

Parameter	Mandatory	Default HL7 Path	Notes
Integration Id	Yes	`/.PV1-19-1`	Shared unique ID between HIS and Orchestra.
Entry point	Yes	`/.PV1-39-1`	Requires entry point mapping.
Service	Yes	`/.PV1-39-1`	Requires standard service mapping.
Ticket Parameter Name	Yes	—	Field name to store the calculated ticketId.
Appointment Public Id	Yes	`/.PV1-19-1`	Appointment public ID.
Service point	Yes	`/.PV1-3-4-1`	Requires service point mapping.
Calendar service	Yes	`/.PV1-39-1`	Requires calendar service mapping.
Calendar resource	Yes	`/.PV1-39-1`	Requires calendar resource mapping.
Transfer (Queue + Delay)	Yes / No	`/.PV1-39-1`	Queue requires mapping; Delay is optional seconds.

Calendar Appointment fields: Start date (/.SCH-11-4), End date (/.SCH-11-5), Title (/.SCH-7-2), Notes, Public Id (/.SCH-1-1), Number of Customers, Slot length, All day (bool), Block (bool), Duration. Custom parameters can be added.

Calendar Customer fields: Name (/.PID-5-3), First/Last name (/.PID-5-2), Phone (/.PID-14-1), Address fields (/.PID-11-x), Identification Number, External Id, Public Id, Email (/.PID-13-4), Date of birth (/.PID-7-1, format yyyy-MM-dd). Custom parameters can be added.

Central Customer fields: First/Last name (/.PID-5-2), External customer id (/.PID-14-1). Additional fields (country, address, city, email, phone) must be added as custom fields.

12.7 Actions Reference

Action	Description
Create a visit (12.7.3)	Creates a visit with `integrationId` for the given entry point and service. Maps entry point/service; calculates custom ticket ID if configured.
Create a visit — check In appointment (12.7.4)	Checks in appointment via public ID. Finds/creates customer; verifies branch match; gets service; calculates ticket ID.
Create a visit linked to a customer (12.7.5)	Creates a visit linked to a customer found/created by external ID. Gets service mapping and calculates ticket ID.
Call a visit (12.7.6)	Calls a visit by `integrationId` at a given service point. Recalls if already being served there; calls/transfers otherwise.
Recycle a visit (12.7.7)	Recycles a visit by `integrationId` at a given service point.
End a visit (12.7.8)	Ends a visit by `integrationId` if being served at a service point.
Merge visits (12.7.9)	Merges two visits identified by patient IDs; removes one.
Remove a visit (12.7.10)	Removes a visit by `integrationId`.
Transfer a visit (12.7.11)	Transfers a visit by `integrationId` to a queue (from mapping). Works for waiting visits or visits being served at the requested SP.
Add Parameters to a Visit (12.7.12)	Adds custom parameters to a visit by `integrationId`.
Add service to a visit (12.7.13)	Adds a service to a visit’s unserved services by `integrationId`.
Create appointment by integration Id (12.7.14)	Creates a calendar appointment. Maps service/resource; finds/creates customer; creates appointment with `integrationId` if not found.
Update appointment by integration Id (12.7.15)	Updates a calendar appointment. Finds/creates customer; finds appointment by integration ID; creates if not found.
Delete appointment by integration Id (12.7.16)	Finds customer by external ID, then finds and deletes appointment by integration ID.
Create CENTRAL appointment (12.7.17)	Creates a central (appointment connector) appointment. Sets publicId to HIS value if not found.
Update CENTRAL appointment (12.7.18)	Updates a central appointment by public ID.
Delete CENTRAL appointment (12.7.19)	Finds and deletes a central appointment by appointment public ID.
Create / Update / Delete customer (12.7.20-22)	Manage customers via the calendar-backend connector.
No action (12.7.23)	No action executed. Useful for HIS messages that cannot be filtered but require no Orchestra action.
Fetch appointment data (12.7.24)	Fetches appointment data from an HL7 message. Returns array of Orchestra calendar appointment objects.
Create or update a customer (12.7.25)	Finds customer by external ID; updates if found, creates if not.
Fetch a customer (12.7.26)	Returns an Orchestra calendar customer object from the HL7 message.
Fetch a customer from central (12.7.27)	Returns a central appointment customer object from the HL7 message.
Fetch visit data with multi-service & customer (12.7.28)	Returns JSON with customer, parameters, and services from an HL7 message.
Fetch data from HL7 message (12.7.29)	Returns JSON array of parameter sets from an HL7 message.
Create/Update/Delete customer from central (12.7.30-32)	Manage customers via the appointment connector (central database).
Transfer current visit at service point (12.7.33)	Transfers the currently-served visit at a given service point to a queue.
Recycle current visit (12.7.34)	Recycles the currently-served visit at a given service point.
Custom local action (12.7.35)	Executes a custom Groovy class from `web-inf/classes/custom/actions`.
Multi-appointment check-out (12.7.36)	Handles patients with multiple appointments: ends current visit and arrives next appointment (sorted by date), or recycles if last.
Check In + end existing visit (12.7.37)	Finds customer/appointment by `integrationId`, deletes existing visit, arrives appointment, adds custom parameters.
End visit with multi-appointment check-out (12.7.38)	Implements multi-appointment check-out for a visit by `integrationId`.
End current visit at SP with multi-appointment check-out (12.7.39)	Implements multi-appointment check-out for the current visit at a given service point.
Send visit data by HL7 (12.7.40)	Finds a visit by `integrationId` and redirects to an outgoing journey for sending to HIS.

13. Outgoing Journeys

Triggered by Orchestra events (visit creation, call, etc.); send HL7 messages to HIS. Journeys can be imported/exported.

13.1 Orchestra Event

Events contain standard fields (visitId, branchId, ticket, service, queueName, etc.) plus any custom parameters added to the visit (integrationId, CaseId, etc.).

13.2 Message Configuration

Configure: Name & Description, Remote server and port, Orchestra Event trigger, and HL7 Message Template. Available events: VISIT_CREATE, VISIT_REMOVE, VISIT_END, VISIT_NEXT, VISIT_CONFIRM, VISIT_CALL, VISIT_NOSHOW, VISIT_RECYCLE, VISIT_TRANSFER_TO_QUEUE, VISIT_TRANSFER_TO_SERVICE_POINT_POOL, VISIT_TRANSFER_TO_USER_POOL, CUSTOM.

13.3 Rules

Rules check event fields against accepted values. If all rules pass, the HL7 message is sent. Rule components: Name & description, Visit field name, Accepted values (matched against the event field value).

13.4 Fields

Fields in the HL7 template are replaced at runtime. Visit field value syntax:

random{N} — Appends a random value of N digits.
Any event field name (e.g. ticket, entryPointName) is replaced by the event value.
Literal strings remain unchanged.

Example: RX-ticket-random2-entryPointName → RX-D008-23-WebReception.

13.5 Send the Message to HIS

If all rules are fulfilled, the HL7 message is sent to HIS according to the remote server settings.

14. Templates

Reusable customer and appointment field mappings used across multiple journeys. Exportable/importable as JSON.

Calendar customer template — Maps HL7 fields to the calendar backend customer type.
Central customer template — Maps HL7 fields to the central (appointment connector) customer type.
Calendar appointment template — Maps HL7 fields to the calendar backend appointment type.
Central appointment template — Maps HL7 fields to the central appointment type.

15. Mappings Between HIS and Orchestra Values

HIS values must be translated to Qmatic IDs. From version 2.1.4, codes starting with ^ are evaluated as REGEX expressions:

XRay — Exact match only.
^XRay — Matches all values starting with “XRay”.
^XRay (\d){1} — Matches “XRay 1”, “XRay 99” but not “XRay xyz”.

All mapping types support import/export and duplication:

Standard services — Used for create visit, add service to visit.
Calendar services — Used for create/update/delete appointment.
Queues — Used for transfer a visit.
Entry points — Used for create a visit (with or without appointment).
Service points — Used for call/recycle/end a visit.
Calendar resources — Used for create/update/delete appointment.

16. Custom Ticket ID Templates

A collection of custom ticket ID templates used when creating a visit or appointment. When creating an appointment, the calculated ticket number is stored as a custom parameter.

17. Connector Tester

Test journeys by sending HL7 messages to a local listener port. Select a journey (pre-fills with local port and template) or use the empty form for custom testing. Enable the response message option when testing query/response scenarios (no HIS server required). Responses: OK (success) or KO (failure); raw HL7 ACK is displayed.

18. Public API

18.1 Send Data to HIS

POST /hl7Connector/service/outgoingMessageEngine.groovy

JSON payload. Requires eventName field matching an outgoing journey. Example (JavaScript):

var payload = {
  eventName: "VISIT_CREATE",
  customerId: customerId,
  integrationId: integrationId,
  branchId: visit.branchId.toString(),
  ticket: visit.ticketId,
  visitId: visit.id.toString()
};
$.ajax({
  url: "/hl7Connector/service/outgoingMessageEngine.groovy",
  type: "POST", contentType: "application/json",
  data: JSON.stringify(payload), dataType: "json",
  success: function(result) { /* handle result */ }
});

18.2 Collect Data from HIS

POST /hl7Connector/service/outgoingIncomingMessageEngine.groovy

Sends an outgoing journey to HIS; the HL7 response is redirected to the incoming journeys engine; the result is returned to the caller. Requires both an outgoing and an incoming journey to be configured.

Payload: eventName (selects outgoing journey), eventType (input for incoming journeys; replaces /.MSH-6-1 in the HIS response). Output: status (OK/KO), description, data (JSON string).

18.2.1 Use Case Example

Kiosk widget fetches laboratory services for a patient:

Widget POSTs to outgoingIncomingMessageEngine.groovy with eventName: "CUSTOM", eventType: "FETCH_DATA", and patient ID fields.
An outgoing journey sends a QBP message to HIS with patient identifiers in HL7 paths.
HIS responds with SQR^S25 containing appointment data.
The /MSH-6-1 field is replaced with the payload eventType (FETCH_DATA).
The modified message feeds the incoming engine. A journey with message code SQRS25 and rule /.MSH-6-1 = 'FETCH_DATA' processes it.
Widget receives: { "status": "OK", "data": "[...]", "description": "..." }.

19. Example Use Case

Patients are checked in by HIS staff at a reception desk. Hospital staff uses HIS to call, undo, end, and undo-end visits. A shared integrationId links records in both systems.

Step	HIS Action	HL7 Message	Orchestra Action
1a	Check In (integrationId)	ADT A01	Creates the visit
1b	Print ticket	ADT A08	Updates visit with ticketId
2	CALL VISIT (integrationId)	ADT A02	Calls visit; shows ticket on displays
3	UNDO Visit call (integrationId)	ADT A12	Recycles visit
4	End visit (integrationId)	ADT A03	Ends visit
5	UNDO visit end (integrationId)	ADT A13	Recycles visit

Key HL7 field mappings:

HIS Parameter	HL7 Field	Orchestra Parameter
Entry point code	PV1-39-1	Branch — entryPoint
Service code	PV1-39-1	Branch — service
Integration Id	PV1-19-1	integrationId
Location (service point)	PV1-3-4 + PV1-3-2	Branch — servicePoint

Implementation steps:

Incoming journey (ADT A01 — Create Visit): Message code ADTA01, add HIS HL7 template, add rule filtering on X-Ray department (Id=190 using HL7 path value), add “Create visit” action with HL7 paths for each parameter and required custom parameters.
Outgoing journey (VISIT_CREATE — ADT A08): Select VISIT_CREATE event, add HIS ADT A08 template, add rules filtering by branch name and integrationId presence (REGEX \d+), configure fields with HL7 paths and event field names.
Mappings: Create mappings for service and entry point.

Qmatic Platform — HL7 Connector 2.1.6 — Page 110 of 110

hl7-connector-user-installation-guide-2-1-6 (1).pdf
5 MB Download