HL7
The Administration - HL7 screen enables HL7 support to be configured.
This includes:
- Services - the HL7 services that OpenVPMS connects to
- Connectors - these determine how OpenVPMS connects to the services
- Mappings - these determine how HL7 messages are constructed
Connectors
The Connectors screen supports viewing and editing HL7 connectors.
Connectors may be:
- Senders - used to send HL7 messages from OpenVPMS to an external system
- Receivers - used to receive HL7 messages from an external system
The buttons are as follows:
| New | create a new Connector |
| Edit | edit the selected Connector |
| Delete | delete the selected Connector - a confirmation window will appear |
| Messages | displays HL7 messages sent or received via the selected Connector |
| Stop | stops messaging for a Sender. Messages will be queued until the Sender is started. |
| Start | starts messaging for a Sender |
Creating a new HL7 Connector
The New button is used to create a new HL7 Connector:
The available Connectors are:
| HL7 MLLP Receiver | used to receive HL7 messages from an external application |
|---|---|
| HL7 MLLP Sender | used to send HL7 messages to an external application |
HL7 MLLP Receiver
This is the create/edit/view screen for HL7 MLLP Receivers. These are responsible for receiving HL7 messages using the MLLP protocol over TCP/IP, from external applications.
The fields are as follows:
| Id | the receiver identifier |
| Name | the receiver name |
| Active | uncheck this box to deactivate the receiver. Deactivating the receiver prevents HL7 messages being received. |
| Port | The TCP/IP port to listen on |
| Sending Application | Uniquely identifies the sending application among all other applications within the network. |
| Sending Facility | Identifies the sending application facility. |
| Receiving Application | Uniquely identifies the receiving application among all other applications within the network. |
| Receiving Facility | Identifies the receiving application facility. |
| Mapping | The HL7 Mapping to use when creating messages. |
HL7 MLLP Sender
This is the create/edit/view screen for HL7 MLLP Senders. These are responsible for sending HL7 messages using the MLLP protocol over TCP/IP, to external applications.
The fields are as follows:
| Id | the sender identifier |
| Name | the sender name |
| Active | uncheck this box to deactivate the sender. Deactivating the sender prevents HL7 messages being sent. |
| Host | The host to connect to |
| Port | The port to connect to |
| Sending Application | Uniquely identifies the sending application among all other applications within the network. |
| Sending Facility | Identifies the sending application facility. |
| Receiving Application | Uniquely identifies the receiving application among all other applications within the network. |
| Receiving Facility | Identifies the receiving application facility. |
| Response Timeout | The maximum time to wait for responses, in seconds. |
| Retry Interval | The time to wait after an error occurs, before resubmitting a message. |
| Mapping | The HL7 Mapping to use when creating messages. |
Messages
The Messages window displays HL7 messages sent or received via a HL7 Connector.
The buttons are as follows:
| Find | Find all messages matching the criteria. Also press this to refresh the display. |
| OK | Closes the window |
| Resubmit |
Resubmits a message to an external application. Only applies to:
|
| Dequeue |
This is used to prevent a message from being sent. Once dequeued, the message cannot be re-queued. Only applies to Sender connectors. |
Mappings
The Mappings screen supports viewing and editing HL7 mappings.
These determine how HL7 messages are populated, and the messages that are sent.
The buttons are as follows:
| New | create a new HL7 Mapping |
| Edit | edit the selected HL7 Mapping |
| Delete | delete the selected HL7 Mapping - a confirmation window will appear |
| Export Lookup Mapping | export mappings between lookups |
| Import Lookup Mapping | import mappings between lookups |
Creating a Mapping
The New button is used to create a new HL7 Mapping:
The Cubex HL7 Mapping and IDEXX HL7 Mapping are pre-configured mappings for the Cubex pharmacy service and IDEXX laboratory service, respectively.
The HL7 Mapping is a generic mapping.
Select OK to create the selected mapping.
Lookup Mappings
Some HL7 applications require OpenVPMS lookups to be mapped to their format. This is supported by creating a relationship between the OpenVPMS lookup and the application specific version.
From OpenVPMS 1.9, mapping of Species is supported. For convenience, these mappings can be exported to CSV (comma-separated values), edited in a spreadsheet, and then re-imported.
Exporting Mappings
The Export Lookup Mapping button is used to export mappings to CSV. This displays a popup window:
Clicking OK generates a CSV containing the current mapping between the selected lookup archetypes.
If no mapping has been established, the file will look like:
| Map From Type | Map From Code | Map From Name | Map To Type | Map To Code | Map To Name |
|---|---|---|---|---|---|
| lookup.species | AVIAN | Avian | lookup.speciesIDEXX | ||
| lookup.species | BOVINE | Bovine | lookup.speciesIDEXX | ||
| lookup.species | CAMELID | Camelid | lookup.speciesIDEXX | ||
| lookup.species | CANINE | Canine | lookup.speciesIDEXX | ||
| lookup.species | CAPRINE | Caprine | lookup.speciesIDEXX | ||
| lookup.species | CAVIES | Cavies | lookup.speciesIDEXX | ||
| lookup.species | CERVIDAE | Cervidae | lookup.speciesIDEXX | ||
| lookup.species | EQUINE | Equine | lookup.speciesIDEXX | ||
| lookup.species | FELINE | Feline | lookup.speciesIDEXX | ||
| lookup.species | LAPINE | Lapine | lookup.speciesIDEXX | ||
| lookup.species | MURINE | Murine | lookup.speciesIDEXX | ||
| lookup.species | OTHER | Other | lookup.speciesIDEXX | ||
| lookup.species | OVINE | Ovine | lookup.speciesIDEXX | ||
| lookup.species | PISCINE | Piscine | lookup.speciesIDEXX | ||
| lookup.species | PORCINE | Porcine | lookup.speciesIDEXX |
Each column with blanks needs to be filled out. If no mapping exists, the row should be deleted.
Importing Mappings
The Import Lookup Mapping button is used to import mappings from CSV. This displays a popup window to upload the CSV file:
Click Browse to select the CSV file.
Click Send to upload the file and import it.
A message will be displayed if the file was imported successfully.
Lookup Mapping Import Errors
If errors were detected in the import, a summary will be displayed:
Correct these, and re-import until no errors are reported.
Cubex HL7 Mapping
This is the screen used to create and edit HL7 mappings for the Cubex HL7 pharmacy service.
The Cubex mapping is pre-configured, with most fields read-only. The editable fields are:
| Name | The mapping name. |
|---|---|
| Description | The mapping description. |
| Active | Determines if the mapping is active. |
HL7 Mapping
This is the screen used to create and edit generic HL7 mappings.
The fields are as follows:
| Id | Uniquely identifies the mapping, or -1 if the mapping is unsaved. |
|---|---|
| Name | The mapping name. |
| Description | The mapping description. |
| Active | Determines if the mapping is active. |
| Send Admit/Discharge/Transfer | Determines if HL7 ADT (Admit/Discharge/Transfer) messages should be sent. If unticked, the Send Update Patient and Send Cancel Admit options are ignored. |
| Send Update Patient (ADT A08) | Determines if ADT A08 messages are sent when a patient is updated, or its weight changes. |
| Send Cancel Admit (ADT A11) | Determines if ADT A11 messages are sent. If unticked, ADT A03 (Patient Discharge) messages will be sent instead. |
| Set PID-3 | If ticked, the patient identifier will be populated in the PID-3 field. |
| Set PID-2 | If ticked, the patient identifier will be populated in the PID-2 field. |
| Sex: Male | The code to use for male patients. |
| Sex: Male - desexed | The code to use for desexed male patients. |
| Sex: Female | The code to use for female patients. |
| Sex: Female - desexed | The code to use for desexed female patients. |
| Sex: Unkown | The code to use if the patient sex is unknown. |
| Species Mapping |
The species mapping lookup. If unset, no mapping is performed. Note that if set, then the patient breed will not be supplied in the PID-36 as breed mapping is not supported. |
| Unmapped Species | The code to use if no species mapping exists. |
| Include Milliseconds | If ticked, date/time fields will include milliseconds. |
| Include Timezone | If ticked, date/time fields will include timezones. |
IDEXX HL7 Mapping
This is the screen used to create and edit HL7 mappings for the IDEXX HL7 laboratory service.
The IDEXX mapping is pre-configured, with most fields read-only. The editable fields are:
| Name | The mapping name. |
|---|---|
| Description | The mapping description. |
| Active | Determines if the mapping is active. |
| Send Admit/Discharge/Transfer | Determines if HL7 ADT (Admit/Discharge/Transfer) messages should be sent. These are not required to submit orders to IDEXX, but update the Census List when patients are checked in and out. |
Note that a mapping between the OpenVPMS lookup.species and IDEXX lookup.speciesIDEXX will need to be established in order for species codes to be sent correctly. This can be done via Administration - Lookups, or using the Lookup Mappings support
Services
The Services screen supports viewing and editing HL7 services.
The buttons are as follows:
|
create a new HL7 Service or test |
|
edit the selected service |
|
delete the selected service - a confirmation window will appear |
Creating a new HL7 Service
The New button is used to create a new HL7 Service or Test:
| sent orders for patient Investigations, for a single Practice Location | |
| groups multiple HL7 Laboratory services | |
| describes a test that can be submitted to an HL7 Laboratory | |
| sent patient admission, discharge and update events | |
| sent pharmacy orders, for a single Practice Location | |
| groups multiple Pharmacy services |
HL7 Laboratory
This is the create/edit/view screen for HL7 Laboratory services.
These are responsible for:
- submitting orders for patient Investigations to an external HL7 laboratory, during invoicing
- generating Laboratory Returns and when the laboratory cancels an order.
The fields are as follows:
| Id | the Laboratory identifier |
| Name | the Laboratory name |
| Description | the Laboratory description |
| Active | uncheck this box to deactivate the Laboratory. Deactivating the Laboratory prevents orders being placed and cancellation messages received. |
| Order Connector | the connector used to submit orders to the Laboratory. |
| Cancel Connector | the connector used to receive cancellation messages from the Laboratory. |
| Location | specifies the Practice Location that this Laboratory is used for. |
| User | specifies the user that Laboratory Returns will be created with. |
HL7 Messages
For the messages supported by an HL7 Laboratory see:
HL7 Laboratory Test
An HL7 Laboratory Test is used to order tests via an HL7 Laboratory.
The fields are as follows:
|
the name of the test |
|---|---|
|
an optional description of the test |
|
the identifier for the test, issued by the laboratory |
|
uncheck the box to deactivate the Laboratory Test |
|
the Investigation Type that determines which HL7 Laboratory to use. |
Laboratory Service Group
A Laboratory Group is used to group multiple HL7 Laboratory services in multi-location practices. An Investigation Type uses the Laboratory Group.
When invoicing a investigation linked to a Laboratory Group, the current practice location determines which Laboratory is selected to order the investigation.
Patient Event Service
A Patient Event Service is an HL7 service that notifies an external application of patient events using HL7 messages.
The fields are as follows:
| Id | the service identifier |
| Name | the service name |
| Description | the service description |
| Active | uncheck this box to deactivate the service. Deactivating the service prevents HL7 messages being sent. |
| Connector | the HL7 connector used to send messages to the external application |
| Location | the practice location that this service will send messages for |
HL7 Messages
For a list of messages and their triggers, see the HL7 Patient Administration Messages.
Pharmacy
This is the create/edit/view screen for HL7 Pharmacy services.
These are responsible for:
- submitting orders for Medication and Merchandise products to an external pharmacy, during invoicing
- generating Pharmacy Orders and Returns when the pharmacy dispenses products.
The fields are as follows:
| Id | the Pharmacy identifier |
| Name | the Pharmacy name |
| Description | the Pharmacy description |
| Active | uncheck this box to deactivate the Pharmacy. Deactivating the Pharmacy prevents orders being placed and dispense messages received. |
| Order Connector | the connector used to submit orders to the Pharmacy. |
| Dispense Connector | the connector used to receive dispense messages from the Pharmacy. |
| Location | specifies the Practice Location that this Pharmacy is used for. |
| User | specifies the user that Customer Orders and Returns will be created with. |
HL7 Messages
For the messages supported by a Pharmacy see:
Pharmacy Group
A Pharmacy Group is used to group multiple HL7 Pharmacy services in multi-location practices. A Medication or Merchandise product uses the Pharmacy Group.
When invoicing a product linked to a Pharmacy Group, the current practice location determines which Pharmacy is selected to order the product.
