This project will add a Location filter to Reporting - Work In Progress, to query charges according to the practice location where they were done.

The Location filter will:

• display all locations for the specified user, or those for the practice if the user doesn't define any
• default to the current Practice Location
• include an All, indicating to query charges for all locations

JIRA: OVPMS-1522

The Generate Orders facility generates orders for products that have a preferred supplier.

For multi-location practices that order the same product via different suppliers, this is insufficient. The preferred supplier needs to be configurable per product and stock location.

This project will allow individual product-stock location relationships to specify the preferred supplier.

When generating orders, the preferred supplier will be selected from the:

1. product-stock location relationship; or

2. product's preferred supplier

If no preferred supplier is found, no order will be created.

JIRA: OVPMS-1526

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.

 

JIRA: OVPMS-1523

This project adds support for exporting and importing stock quantities as CSV files.

This enables practices to use external stock management tools to determine stock quantities, and import the changes to OpenVPMS.

It adds two buttons to the Products|Stock Managment workspace, namely "Export" and "Import".

Export

The Export button launches a Stock Export dialog. This displays:

• filter criteria, used to select the stock to export
• a Find button, used to display the stock matching the criteria
• a Zero Negative Quantities checkbox, used to determine how negative quantities should be handled. It is selected by default
• an Export button, used to download the matches as a CSV

The stock may be filtered on:

• Stock Location - a dropdown listing all active stock locations, in alphabetical order. The stock location linked to the current practice location is selected by default
• Type- a dropdown listing All, Medication, Merchandise. All is selected by default indicating that both Medication and Merchandise products should be listed
• Name - the product name. Empty by default. Supports wildcards e.g. Acepromazine*
• Income Type - a dropdown listing product income type classifications e.g. Merchandise. All is selected by default, indicating that all income types should be listed.
• Product Group - a dropdown listing product group classifications e.g. "Vaccination". All is selected by default, indicating that all product groups should be listed.

Of these, only the Stock Location is required.

Stock Display

When Find is pressed, matches will be displayed in a table including:

• Product Identifier
• Product Name
• Selling Units
• Quantity

File Format

The export CSV file will include the following details:

• Stock Location Identifier
• Stock Location Name
• Product Identifier
• Product Name
• Selling Units
• Quantity - the current stock on hand at the stock location
• New Quantity - the new stock on hand at the stock location

If Quantity is positive or Zero Negative Quantities is unselected, New Quantity will be the same as Quantity.

If Quantity is negative and Zero Negative Quantities is selected, New Quantity will be set to zero.

The export file will be named stock-<location name>-<todays date>.csv to help differentiate it from prior exports.

Import

• When importing the file, only the quantities may be changed. All of the other values must correspond to existing stock location and product data.
• The file may only contain data for a single stock location.
• If there are any errors, they will be reported with the line number of the input file, and the import aborted.
• If the imported file is valid:
  • a single Stock Adjustment transaction will be created, containing a  Stock Adjustment Item per imported record where the Quantity and New Quantity are different
  • The Stock Adjustment Item Adjust Quantity By field will be calculated as the difference between Quantity and New Quantity. This may be negative
  • The transaction will have In Progress status, to allow the user to review it
  • The new Stock Adjustment transaction will be selected in the Stock Management workspace, to allow users to Edit or Finalise it.

Configuration

The existing Practice configuration option "Reminder Export Format" that determines if reminder export files are exported tab or comma separated will be renamed to "File Export Format" and used to configure the format for both reminder and stock export files.

JIRA: OVPMS-1511

Support to order visits is now included in OpenVPMS 2.1

 

---

The original project:

 

In Patients - Medical Records - Summary, and in the Summary tab of the Visit editor, patient visits are displayed from newest to oldest.

Within these visits, medical records can be ordered, as per Medical Records display order
 

This project will allow a practice wide option to specify the visit sort order.

This will be configured by extending the options available in the Medical Records Sort Order field of the practice.

Currently, this supports:

• Descending  (i.e. newest items first)
• Ascending    (i.e. newest items last)

This will be changed to:

• Visit Descending, Items Descending
• Visit Descending, Items Ascending
• Visit Ascending, Items Descending
• Visit Ascending, Items Ascending

Or, if any clearer...:

• Newest Visit First, Newest Item First
• Newest Visit First, Newest Item Last
• Newest Visit Last, Newest Item First
• Newest Visit Last, Newest Item Last

TODO:

• does there need to be another button to override Visit order?
• In 1.8, the Problems tab has the same L&F as Summary. Does the sort order apply here?

 

Customer transactions occasionally need to be reversed as a result of user error e.g.:

1. wrong payment type used (ie cheque instead of EFT, etc)
2. wrong amount entered
3. wrong customer used

These reversals appear in the customer's statement.

This project will provide the facility to:

1. Suppress the reversing and reversed transactions in the customer's statement

• This will be done by adding a 'hide' flag to the transaction archetypes.
• The statement items report will suppress transactions where 'hide' = true.
• The 'hide' flag will be set at the time of reversal, for those transactions that appear in the latest statement period (i.e. it will not be possible to hide the reversal of a transaction done in an earlier statement period).
• The 'hide' flag will be prompted for at reversal. It will default to 'false'.

2. Prompt for the Notes field at reversal

• Currently, the Notes field defaults to 'Reversal of <transaction> <id>'. This should be the default, but should also be editable.
• If no text is entered, ''Reversal of <transaction> <id>' should continue to be used.

3. Set the Reference field at reversal

• The Reference field of the reversing transaction should be set to the Id of the reversed transaction, but may be edited

4. 'Unhide' suppressed transactions

• This may be used if a reversal was erroneouly flagged to be hidden.
• This will be available to administrators only
• Both the reversing and reversed transactions will be unhidden. A relationship must be added between them at the time of reversal to support this.

 

JIRA: OVPMS-1510

When adding patient referrals, the referring vet must be known by name.

If a customer doesn't know the name of the vet, it can only be determined by going to Suppliers|Information, and seeing which vets work at the clinic.

If the vet is not known, and a clinic has multiple vets, then being able to select the principal vet, or one relevant to the referral becomes important.

This project will improve this by:

1. extending the search facility to

• allow searches on vet name or clinic name
• display all matching vets belonging to a clinic if a clinic name is entered
• display the clinic name in the list of matches

2. displaying the clinic name in the list of a patient's referrals

3. including any categories a vet has in their description, to aid selection E.g:

• Dr J Smith (Principal Vet)
• Dr K Jones (Opthamology)

JIRA: OVPMS-1487

Currently, when customer, patient and supplier documents are generated,  file names are assigned from the template file they are generated from.

This project will enable the file name assigned to customer and patient documents to be generated using an expression.

The expression used to generate file names will be :

• be selectable via a dropdown in the Document Template

• configured as lookups

If no expression is selected, then the template name will be used.

The expression will be provided with:

• a $file variable - representing the file name of the original template, minus the extension
• the document act (e.g. act.patientDocumentLetter, act.customerDocumentForm, act.supplierDocumentAttachment)
• a $patient variable, if a patient is linked to the act
• a $customer variable, if a customer is linked to the act, or the owner of the patient, if a there is only a patient present
• a $supplier variable, if a supplier is linked to the act

 

This will enable expressions like:

• concat($file, '  - ', $patient.name, ' ', $customer.lastName) - e.g. "Admission Consent Form - Fluffy Connor"

File name generation will occur when the document is created.

For letters, this occurs once. Forms are created on-demand, so the file name generation will occur each time the form is downloaded.

To ensure that generated file names are valid, any illegal characters such as '\', '/', ':', '*', '?', '<', '>', and '|' will be replaced with underscores.

JIRA: OVPMS-1483

OpenVPMS currently supports plain-text email. This project will replace the plain-text email support with HTML, to provide rich-text emails.

It will support email templates, to enable rapid generation of standard emails. Email templates may be created in Word, OpenOffice or JasperReports. They will be converted to HTML.

User Interface Changes

Editing

The Mail editor will be changed to replace the plain-text editor with a rich-text editor. This provides support limited support for editing HTML. In particular it supports:

• font style (normal, headings 1-6, preformatted, address)
• font name
• font size
• bold
• italic
• underline
• superscript
• subscript
• text alignment (left, centre, right, justify)
• indenting
• bullets
• numbering

Limitations

The rich text editor has the following limitations:

• It doesn't support editing images or links, but it can view them, when the mail is generated from a template.
• It also provides a button to perform spell checking, but this requires additional development work, outside of the scope of this project.

Template Selection

A Template button will be added to the Mail editor that:

• lists available email templates for selection
• enables the user to filter templates based on name

When a template is selected, it will replace the subject and body of the current email.

If the Template button is pressed and there is existing content, a warning will be displayed:

Selecting an email template will replace existing content. Do you wish to proceed?

Macro Expansion

Macro expansion will be supported when editing HTML emails. The only restriction is that macros may only generate plain text.

Any html will be escaped.

Templates

A new document template type, entity.documentTemplateEmail will be created to hold email templates. This will have the following nodes:

• name - the template name
• subject - an optional email subject
• contentType - identifies the type of the template content. One of:
  • TEXT
  • DOCUMENT
• content - stores text content, used for migrating existing templates
• expression - an optional xpath expression used to supply an object to the template. See http://www.openvpms.org/documentation/csh/1.7/admin/lookup/macroReport

For templates with contentType = DOCUMENT, the template content will be stored by an act.documentTemplate.

The existing entity.documentTemplate emailSubject and emailBody nodes will be removed. These will be replaced by a relationship to an entity.documentTemplateEmail.

By default, templates will be processed using JasperReports or OpenOffice, depending on the mime-type. If a template has a text/plain mime-type, it will be converted to html. This is to support migration of existing entity.documentTemplate.

Statements and Reminders

Currently statements and reminders are sent with the subject and body coming from the entity.documentTemplate emailSubject and emailText nodes respectively.

This will be changed to use the entity.documentTemplateEmail linked to the entity.documentTemplate. If a statement or reminder template doesn't have a linked entity.documentTemplateEmail, an exception will be thrown.

Migration

The existing entity.documentTemplate archetype has emailSubject and emailText nodes. These will be removed.

For each entity.documentTemplate that has content for these, the following will be created:

• entity.documentTemplateEmail - the subject node will contain the emailSubject, the content node will contain the emailText, and the name will be copied from the entity.documentTemplate
• an entityLink.documentTemplateEmail linking the entity.documentTemplate to entity.documentTemplateEmail

 

JIRA: OVPMS-1729

This project will add support to query available appointment slots:

• for a schedule view or schedule
• on a particular day, after a date, or between two dates
• at a particular time, after a time, or between two times
• optionally for a duration (e.g. 15 mins, or 5 days)

This will enable users to issue queries like:

• find a free surgery slot for Thursday next week
• find the next free 30 minute slot
• find a boarding cage for 5 days in July

It will be initiated by clicking a "Find Free Slot" button in the Workflow|Scheduling screen.

The Find Free Slot button will display a dialog with filters for:

• Schedule View - defaults to the current Schedule View in Workflow|Scheduling. If unset, Schedule is used
• Schedule - defaults to all schedules in the Schedule View
• Start Date - defaults to the current date in Workflow|Scheduling
• End Date - empty by default, indicating all dates after Start Date. If set, specifies to find all slots up to <End Date> 23:59:59
• Start Time - empty by default, indicating all times
• End Time - empty by default, indicating all times
• Duration - the slot duration. Defaults to the minimum slot size of the schedules in the Schedule View
• Duration Units - the slot duration units. One of Minutes, Hours, or Days. Defaults to Minutes

Clicking the dialog's Find button will list the available free slots matching the criteria, including the:

• Schedule
• Date
• Time

If a match is selected, two buttons are enabled:

• New Appointment - selecting this opens an Appointment editor populated with the schedule, date, time and duration. The appointment type will be set to the first one found with a similar duration.
• View Schedule - selecting this closes the dialog, and displays the appropriate schedule with the slot highlighted

The dialog's OK button may be used to close the dialog.

JIRA: OVPMS-1463

Sample Queries

Query: Find the next available slot for the current View

 

Filter

Schedule View	Default value
Schedule	Unset - means all Schedules in the Schedule View
Start Date	Default - today's date
End Date	Unset
Start Time	Unset
End Time	Unset
Duration	Default. The minimum duration for all schedules in the View. E.g. "15"
Duration Units	Default - minutes

 

Sample Results

Schedule	Date	Time
Dr Smith	17/3	10:00
Dr Smith	17/3	1:15
Dr Jones	17/3	10:30
Dr Smith	18/3	9:00
Dr Jones	18/3	11:45

Query: Find a surgery slot next Thursday or Friday, between 11am and 3pm

 

Filter

Schedule View	Unset
Schedule	"Surgery"
Start Date	Next Thursday's date
End Date	Next Fridays's date
Start Time	11:00
End Time	15:00
Duration	Default minimum duration for "Surgery" schedule. E.g. "30"

 

Sample Results

Schedule	Date	Time
Surgery	20/3	11:30
Surgery	20/3	13:30
Surgery	21/3	14:30

Query: Find a cage for 5 days after the 21/3.

 

Filter

Filter
Schedule View	"Cages"
Schedule	Unset - all cages in "Cages" view
Clinician	Unset
Start Date	21/3
End Date	Unset
Start Time	Unset
End Time	Unset
Duration	5
Duration Units	Days

 

Sample Results

Schedule	Date	Time
Cage 1	21/3	9:00
Cage 3	21/3	9:00
Cage 4	22/3	9:00
Cage 4	23/3	9:00
Cage 4	24/3	9:00