HL7 Pharmacy Orders

Donate to this project

Development Project Status: Completed

Total cost estimate (ex-Tax): 
Due date for completion of this stage: 
Current Percentage Funded: 
Project description: 

1. Overview

This project will add support for HL7 messaging related to pharmacy orders and billing.

It will enable OpenVPMS to:

  • submit pharmacy orders to external providers during invoicing
  • receive billing information for those orders
  • update invoices to incorporate any changes between what was ordered, and what was delivered

2. Messages

The following messages will be supported:


Message Type Message Event Description Direction
ADT A01 Admit/visit notification Outbound
ADT A03 Discharge/end visit. Outbound
ADT A08 Update patient information Outbound
ADT A011 Cancel admit/visit notification Outbound
RDE O11 Pharmacy order message Outbound
DFT P11 Financial Inbound

Note that outbound messages are those generated via OpenVPMS, and inbound messages are those generated by an external provider.

2.1. Admit/Discharge/Transfer (ADT) messsages

ADT messages are sent to via outbound connectors as follows:

Message Type Message Event Description Triggered
ADT A01 Admit/visit notification
  • When an appointment changes status from Pending to In Progress, Admitted, or Checked In
  • When a patient is invoiced without being checked-in
ADT A03 Discharge/end visit
  • When an appointment changes status to Completed.
  • When an invoice is finalised without the patient being checked-in
ADT A08 Update patient information When a patient is updated
ADT A011 Cancel admit/visit notification Triggered on appointment going to Cancel status after being In Progress, Admitted, or Checked In

2.2. Pharmacy Order Messages

Pharmacy Order messages are sent when an invoice is saved and one or more charged products is classified as having an external provider.

A Pharmacy Order message will be sent:

  • for new charge items
  • if a quantity of an existing order is updated. This amends the order
  • if a charge item is deleted. This cancels the order
  • if a charge item product is changed. This cancels the original order, and issues a new one, if required.

If multiple products are to be ordered from the one provider, a separate RDE O11 message will be created per order.

In all cases, the ORC segment Placer Order Number will be that of the charge item identifier. The external provider must populate the Filler Order Number, and use this in DFT messages.


2.2.1. Pharmacy Orders without Check-In

Order messages are sent in the context of a patient visit. If a patient is not checked in, then an ADT A01 message will be sent prior to any order message.

When an invoice is finalised and a patient is not checked in, an ADT A03 message will be generated.

A patient is considered  not checked in, if they don't have an Visit in progress.

2.3. Financial Messages

Financial messages are received from external providers.

As OpenVPMS is responsible for determining pricing and billing, the objective is to correlate what was invoiced with what the provider dispensed.

Where there are differences, the customer invoice needs to be adjusted.

This is done by creating an intermediate "Customer Order" that represents the provider financial message, instead of updating the invoice directly. This ensures that invoices are not updated while users are editing them, resulting in "Failed to save Invoice. It may have been modified by another user" errors.


2.3.1. Message correlation


To correlate DFT messages with their original order, the message must have an ORC segment containing the Placer Order Number. The Placer Order Number is the identifier of the original charge item in OpenVPMS.

If a DFT message is received that:

  • doesn't correspond to any charge item; or
  • has a different patient to the patient on the charge item; or
  • the patient is unknown

an incomplete Customer Order will be created, populated with as many details as possible from the DFT message.

For incomplete orders, a message will be sent to the user that generated the original order, if known, or the person identified in the FT1 segment. If no user can be identified, a fallback user configured on the Practice will be notified.

3. Customer Order Workspace

Customer Orders may be reviewed and processed within a new Customer Order workspace, under Workflow.

Here, they may be:

  • Queried
  • Edited
  • Invoiced
  • Cancelled
  • Printed

3.1. Querying Orders

A filter will be provided to filter customer orders by status, date range, customer and patient. It will default to displaying all Pending orders.

3.2. Editing Orders

Orders may be edited. Any order that has incomplete details will need to be edited before it is invoiced.

3.3. Invoicing Orders

There are a number of cases that need to be supported when invoicing Customer Orders:

1. Order matches invoice

Invoicing the order changes the order status to Finalised

2. Order has one or more items that weren't invoiced

Invoicing the order copies the ordered products and quantities to the invoice, and changes the order status to Finalised

3. Order has a different quantity to that invoiced

Invoicing the order updates the quantity on the invoice

4. Order has a different product to that invoiced

For this release, an error will be raised, and it must be handled manually.

5. Order doesn't match invoice and invoice has been finalised

For this release, an error will be raised, and it must be handled manually.

3.4. Cancelling Orders

Orders may be cancelled by selecting them and clicking Cancel. A prompt will be displayed warning that this operation cannot be undone before proceeding with the cancel.

4. Workflow Integration

4.1. Visit Editor

The Visit Editor will be extended to include the following on the Invoice tab:

  • a prompt that will be displayed above the invoice if there are any pending Customer Orders. Pending orders will be checked each time the Invoice tab is selected.
  • an "Invoice Orders" button. This will list the available orders, if any.

Invoicing an order will:

  • copy the order items to the invoice
  • set the order status to Finalised
  • save both the order and invoice

If an order is incomplete, an error will be raised. The user will need to fix the order in Customer Orders Workspace before invoicing again.

4.2. Check Out Integration

A new step will be introduced at the start of Check Out that will prompt to invoice pending orders for the patient, if there are any.

5. Connectors

Outbound connectors are used to send messages and receive acknowledgements.

Inbound connectors are used to receive message and send acknowledgements.

In the initial version, HL7 version 2.5 messages will be supported, using the "pipe and hat" format over MLLP.

5.1 Inbound Connector

An Inbound Connector:

  • receives messages from external applications
  • is configured per application that OpenVPMS needs to receive messages from
  • processes messages and generates an acknowledgement
  • sends a nack for invalid messages
  • optionally logs messages, both accepted and rejected

Initially, an MLLP Inbound Connector will be provided that receives messages using MLLP. It is configured with the port to listen on.

5.2 Outbound Connector

An Outbound Connector:

  • sends messages to external applications and processes responses
  • is configured per application that needs to receive HL7 messages
  • has configuration options that indicates which messages an application is interested in

Initially, an MLLP Outbound Connector will be provided that sends messages using MLLP. It is configured with the host and port to send messages to.

5.3 Message Queuing

Messages sent via Outbound connectors are queued for delivery.

  • Messages in the queue are sent in FIFO order.
  • A message remains in the queue until:
    • the receiver processes it successfully (Message acknowlegement code AA received)
    • the receiver rejects it (Message acknowledgment code AR received). In this case, the message moves to an Error queue, and the next message is processed.
  • If a message cannot be sent due to network error, or a AE (application error) acknowledgment code is received, the message will be retried. The time between retries is configurable via the connector.

6. Configuration

6.1 Connectors

Two new archetypes will be defined to configure inbound and outbound connectors:

  • entity.connectorReceiverHL7MLLPType - configures a connector to receive HL7 messages over MLLP. This includes the:
    • port to listen for messages on
    • HL7 version
  • entity.connectorSenderHL7MLLPType - configures a connector to send messages over MLLP. This includes the:
    • host of the external application
    • port of the external application
    • interval between retries
    • HL7 version

Initially the HL7 version will be limited to 2.5.

If connectors are flagged as inactive, they will be disabled.

6.2 Pharmacy

An entity.pharmacyType will be used to classify products as being dispensed via an external pharmacy provider. This will include a link to an entity.connectorSender* to determine how pharmacy orders are sent.

6.3 Products and Product Types

Products and product types will be extended to include an optional reference to an entity.pharmacyType. If present, pharmacy orders will be generated when the product is charged.

The reference to a pharmacy on the product type may be used as a fallback, and to configure a pharmacy for related products.

7. Administration

A new administration workspace will be provided to monitor the:

  • outbound queues
  • error queue
  • logged messages

This will support:

  • browsing queued messages
  • browsing logged messages
  • message deletion from the error queue
  • message resubmit from the error queue

8. Exclusions

This project will not support:

  • Pharmacy orders for medication records added directly to patient history.
  • User notification of received orders. It is envisaged that this will generate too many notifications. The Visit Editor and Check-Out integration should be sufficient.
  • MLLP security
  • HL7 Enhanced acknowledgment
  • HL7 Z segments. These will be ignored
  • HL7 prescription information
  • Sending ADT A08 (Update patient information) when a patient owner is updated. This could mean that patient contact information is out of date, but can be worked around by saving the patient.




Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Re: HL7 Messaging

Just a few questions.

Invoicing orders

- Why can't orders (financial orders) simply be added to the invoice?

I guess what I don't want to happen is that medications are charged from Cubex or investigation started from external lab machine. Orders sit in a list that is not invoiced or forgotten about. These order charges then don't appear on the invoice (people report wrong balance to client) or are not charged because people forget to click the "Invoice Order" button. Or duplications appear because then someone charges that amoxyclav again.

Other questions:

- Sometimes visits are finalised but patient is still "checked in" or on our worklist. Will these patients be able to send/recieve orders?



Re: HL7 Messaging

We could update invoices automatically but this will increase the chances of "Failed to save Invoice. It may have been changed by another user" errors.

I've updated Visit Editor Integration and added a new Check Out Integration section to reduce the chances that orders will be overlooked.

A patient with a completed visit can send/receive HL7 messages. The appropriate visit will be selected using the same logic that is used to select visits when charging.

One issue may be for external providers that rely on ADT messages for patient information instead of using the patient information provided in the ORM message. They may not have enough information to submit a complete DFT message. In this case, they could:

  • submit an incomplete message (i.e. without patient information) - it must then be manually edited in OpenVPMS
  • raise an error
  • use an integration tool like Mirth Connect to generate ADT messages



Re: HL7 Messaging

Hi tim,

Thanks for explaining that. I think the prompt you describe to invoice pending orders is a very good solution.

With regards to the external providers issue I would ask that tony/cubex please comment on this and please let us know if this is an issue or not.



Re: HL7 Messaging

After discussing with Cubex, we will issue ADT messages if a patient isn't checked in when billing occurs i.e.

  • an ADT A01 will be sent when an invoice is saved, before sending any other messages
  • an ADT A03 will be sent when the invoice is finalised


Syndicate content