1. Overview

At present, OpenVPMS uses a mixture of HL7 and document imports to support laboratory systems.

This project will:

• provide an API to enable 3rd parties develop plugins to integrate laboratory services with OpenVPMS
• provide support to submit orders to laboratories as part of invoicing, as is the case with the existing HL7 support
• extend the Investigation Type, to allow the tests to be included to be specified
• provide user interface support to configure the plugins

2. Laboratory API

The API will:

• provide support to place and cancel orders
• provide support to add results to patient history
• enable laboratory services to be discovered
• enable the tests that a service provides to be discovered
  This will allow Investigation Types to list which tests to order
• enable laboratory services to cancel orders

2.1 Order API

The Order API will enable OpenVPMS to:

• submit orders to laboratory services during invoicing
  This will occur automatically, when charging products that have an Investigation Type linked to a laboratory
• cancel orders during invoicing
  This will occur automatically, when a line-item associated with an order is changed or deleted

2.2 Results API

The Results API will be provided to enable laboratory services to add results to patient history. This will attach results to an existing Investigation, versioning it if there is prior results.

2.3 Services API

The Services API will provide methods to discover and synchronise laboratories and their available tests, in OpenVPMS.
For services that don't support laboratory discovery, it will provide a method to preconfigure a laboratory to use the service.

3. Data Requirements

3.1 Laboratory

OpenVPMS already has two objects to support HL7 laboratories:

• Laboratory - sent orders for patient Investigations, for a single Practice Location
• Laboratory Group - groups multiple Laboratory services so they can be treated in the same way for the purposes of invoicing

These are used by Investigation Types to determine where orders are sent.

The existing Laboratory will be renamed HL7 Laboratory to better reflect its function.

The Laboratory Group will be repurposed to allow both HL7 Laboratory objects and a new Laboratory type.

This will contain:

• location - the practice location where the laboratory may be accessed.
  This may be configured after plugin deployment.
• user - the user to use when submitting orders. Optional
  This will be configured after plugin deployment
• service - a link to the laboratory service
• tests - a lists of tests supported by the laboratory

3.2. Plugin Archetype Requirements

Laboratory Service

Plugins will be required to define and install an archetype with the prefix entity.laboratoryService. E.g. entity.laboratoryServiceAbaxis

This must contain the following fields:

• name - the laboratory service name
• description - optional description
• active - determines if the service is active or not.

The archetype may contain additional fields to determine how the service is configured.

Species and Breeds

Each laboratory typically has its own species and breeds, which need to be mapped to the OpenVPMS equivalents.

It is envisaged that laboratories will provide archetypes to map these i.e.:

• lookup.species<Laboratory>
• lookupRelationship.speciesMapping<Laboratory>

and if breeds are supported:

• lookup.breed<Laboratory>
• lookupRelationship.breedMapping<Laboratory>

Typically, OpenVPMS users are free to add their own species and breeds so the mapping will likely be a manual integration step.

4. Integration

The following changes are required to integrate the Laboratory API:

• invoicing needs to use laboratory service plugins to submit and cancel orders, when there is laboratory service linked to an investigation type
• the Administration - Organisation (or Types?) workspace needs to be updated:
  • to support configuration of entity.laboratoryService* instances
  • synchronise services
• the Investigation Type will be updated to list the tests to order
  If an Investigation Type is linked to a Laboratory Group, each Laboratory in the group must support the same tests

5. Exclusions

• If an investigation is cancelled outside of OpenVPMS, any changes to the customer invoice must be done manually (see OVPMS-2178)
• The existing HL7 Laboratory support could be re-implemented as a plugin, using this API. That is out of the scope of this project.

JIRA: OVPMS-2082