HL7 General Orders


From http://www.openvpms.org/project/hl7-general-orders

1. Overview

This project will add support for HL7 general order messages.

It will enable OpenVPMS to:

  • submit and cancel orders to external providers during invoicing

  • submit orders when creating Investigations

  • cancel orders when deleting Investigations or setting their status to Cancelled

  • receive order cancellation notifications from providers to amend invoices

Orders will be submitted whenever an investigation is created that has an investigation type that specifies:

  • an Investigation Service or Investigation Service Group; and

  • a Universal Service Identifier

2. Messages

The following messages will be supported:

Message Type

Message Event






General Order Message


Used to place and cancel orders with an external provider



Used by the provider to cancel orders



General Order Message Reponse


Used to acknowledge an ORM^O01 cancellation sent by a provider



Used to acknowledge an ORM^O01 message sent from OpenVPMS

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

2.1 Orders

New orders are submitted for:

  • products with appropriately configured investigation types, when an invoice is saved

  • investigations

Order cancellations are submitted for prior orders when:

  • an invoice item is deleted

  • an invoice is deleted

  • an investigation is cancelled

  • an investigation is deleted

2.2. Provider Order Cancellation

A provider can cancel an order issued from OpenVPMS, by sending an ORM^O01 message with:

  • ORC-1 Order Control set to CA

  • ORC-2 Placer Order Number set to that of the original order

In order to tie these messages into invoicing, a new Investigation Order archetype will be created, similar to the Pharmacy Order archetype. As with Pharmacy Orders, these may be:

  • invoiced

  • created, viewed, and deleted via Workflow - Customer Orders.

To support order cancellation, these may have a Cancellation status.

3. Investigation Services

Two new HL7 services will be supported:

  • Investigation Service

  • Investigation Service Group

Both will be configured via the Administration - HL7 - Services tab.

3.1 Investigation Service

An Investigation Service has a:

  • name

  • description

  • connector used to submit orders

  • connector used to receive order cancellations

  • location, indicating the Practice Location that the service applies to

  • list of patient admission events the service will receive

3.2 Investigation Service Group

An Investigation Service Group is used to group Investigation Services by Practice Location. When submitting orders, the current Practice Location is used to select the Investigation Service to use.

4. Configuration

4.1 Mapping

The following fields require mapping from OpenVPMS to their provider-specific values.





Administrative Sex

Requires a mapping between party.patientpet sex and desexed nodes and the provider values for these. E.g.:

* sex = MALE, desexed = false => "M"

  • sex = MALE, desexed = true => "C"

  • sex = FEMALE, desexed = false => "F"

  • sex = FEMALE, desexed = true => "S" |


Species code

Requires a mapping between lookup.species and a provider specific species lookup.


Universal Service Identifier

Requires a mapping between OpenVPMS investigation type, and the provider service identifier.

The PID-8 and PID-35 fields will be supported via a new archetype entity.HL7MappingConfiguration:

  • for PID-8, all of the possible combinations for administrative sex will be enumerated as fields, to allow a value for each e.g:

    • male => "M"

    • maleDesexed => "C"

    • female => "F"

    • femaleDesexed => "S"

    • unknownSex => "U"

  • for PID-35, the archetype name of the provider species will be used e.g. lookup.speciesIDEXX

  • this configuration will be an optional field of Connectors.

  • it will include the Include Milliseconds and Include Time Zone fields, currently held on the entity.HL7ReceiverMLLP and entity.HL7SenderMLLP archetypes

Pre-defined provider configurations may be supported by creating an entity.HL7MappingConfiguration<Provider> archetype (e.g. entity.HL7MappingConfigurationIDEXX), that provides the appropriate mappings for each field as default values.

5. User Interface

The new entity.HL7MappingConfiguration archetype will be viewed and edited via a new tab in Administration - HL7, named Mappings. This will also support editing provider specific mappings.

6. Exclusions

This project will not support:

  • receipt of results (e.g. ORU messages). These can be handled as documents and loaded via the Document Loader

  • OMG, OML, OMD, OMS, OMN, OMI, or OMP messages (these are the preferred order messages in HL7 2.5)





Tim Anderson


Tim Anderson



Fix versions