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:

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:

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.

JIRA: OVPMS-1523