Administering OpenVPMS

This section includes things that are not done using the OpenVPMS web application.

mysqldump -u <username> --password=<password> --single-transaction --quick --extended-insert --add-locks --result-file=<dumpfile> openvpms

mysqldump -u <username> --password=<password> ... openvpms > E:\backups\opvdump.sql

mysql -u <username> -p openvpms < <dumpfile>

set DSTAMP=%date:~6,4%-%date:~3,2%-%date:~0,2%

net stop "Apache Tomcat 6.0 Tomcat6"
net stop "MySQL55"

sleep 10

ren C:\openvpms\data\mysql-slow.log %DSTAMP%-mysql-slow.log
ren C:\openvpms\data\mysql-slow.log %DSTAMP%-mysql-error.log
ren "C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs\openvpms.log" %DSTAMP%-openvpms.log
ren "C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs\openvpms-full.log" %DSTAMP%-openvpms-full.log

..... other stuff to backup database etc

net start "MySQL55"
net start "Apache Tomcat 6.0 Tomcat6"

exit

Account Reminders

OpenVPMS can send SMS reminders for unpaid invoices and counter sales.
For example, if an invoice is still unpaid 4 weeks after it was finalised, an SMS reminder can be sent out with the text:

Reminder: your invoice from Vets R Us on Tuesday 24/08/21 has an outstanding balance of $100.25. Contact us on (03) 12345678 if you have any issues. Please ignore this if you have recently made a payment.

This is fully configurable.

To do this:

1. The Practice must have SMS configured

2. Invoices and Counter Sales must have their Send Reminder flag ticked.  

This is enabled by default for new charges; historical charges must have this flag selected manually using the Enable Reminders button in Customers - Charges and Customers - Account

3. Customers must be able to receive SMS messages

This is done by selecting Allow SMS on their phone contact. If the customer has multiple phone contacts with Allow SMS set, then the preferred one will be used, and if none are preferred, then the first one created.

4. The Account Reminder Sender must be configured.

This automatically sends account reminders.

Reminders can be monitored in Reporting - Debtors - Reminders.

Appointment Reminders

OpenVPMS can send SMS reminders for upcoming appointments, automatically or manually.

To do this:

1. The Practice must have a Mail Server configured

The SMS gateways supported by OpenVPMS use email, so a Mail Server must be configured on the Practice.

2. The Practice must have SMS configured

3. An Appointment Reminder SMS Template must be configured

Reminder templates can be linked to the Practice and/or Practice Location. If a template is linked to a Practice Location, it will be used in preference to any linked to the Practice.

4. Schedules must be configured to send appointment reminders

This is done be selecting the Send Appointment Reminders flags for each Schedule that may send appointment reminders

5. Appointment Types must be configured to send appointment reminders

This is done be selecting the Send Appointment Reminders flags for each Appointment Type that may send appointment reminders

6. Customers must be able to receive SMS messages

This is done by selecting Allow SMS on their phone contact. If the customer has multiple phone contacts with Allow SMS set, then the preferred one will be used, and if none are preferred, then the first one created.

7. The Appointment Reminder Sender can be configured

This is required to send reminders automatically.

If you do not configure this (or create the sender job, but deactivate it) then appointment reminders will not be sent automatically, but can still be sent manually via the Remind button in Workflow - Scheduling. Doing things this way allows you the convenience of automatically generating the SMS text, but because the text is generated and then displayed, and allows you to personalise the reminder if required. The date and time of sending the reminder will also be recorded against the appointment.

8. The Appointment itself must have its 'Send Reminder' box ticked

This will be automatically ticked for new appointments provided that the previous conditions are satisfied. However, if you have appointments created before the Appointment Reminders system was activated, then in order to enable the automatic sending of reminders for these, you will have to edit each appointment to tick the 'Send Reminder' box.

Correct 'patient added to wrong customer'

If you have a situation is which a patient was mistakenly added to the wrong customer some time ago and you need to currect the situation and keep the patient's medical history but move all financial transations involving the patient to the correct owner, then do as follows:

1. Reverse any transactions on the OLD Customer that involved the patient to be transferred....even if they included another pet from that customer's file.

2.  Reverse any payments associated with those invoices. If payments cannot be reversed that match the invoice total - create a REFUND of the correct payment type.

3. At this point the OLD customer balance should be the same before you started.

4. Transfer the Patient to the NEW(Correct) Customer.

5. At this point you have the history, patient and customer correct - you just need to fix the transaction history.

6.  If invoices that you reversed contained transactions that were still relevant to the OLD Customer, recreate these invoices and pay them using the same payment type you reversed.

7.  In the new Customer recreate the relevant invoice items you reversed from the old customer and pay them using the same payment method you either created the refund for OR reversed in step 2.  Adjust line item costs to be the same (if prices have risen).

8. Make notes on each new invoice about the actual date the transaction took place on - do the same for payments.

9. At this point both client Balances would be in theory either zero or reflect the balance before you started the process.

10. Run a balance check over each customer.

11. The TILL for this day will have a lot of transactions that don't really exist - but the reversals and payments should balance each other out, so the nett effect on the daily total should be zero.

Deputy Integration

OpenVPMS supports integrating Workflow - Rostering with Deputy:

• Two-way shift synchronisation is supported.
• Synchronisation is performed for OpenVPMS Roster Areas that have been mapped to a corresponding Area in Deputy.
• Synchronisation is performed for shifts starting today, and 30 days (by default) into the future. Historical shifts are not synchronised
• OpenVPMS shifts that cannot be synchronised will be flagged as an error in Workflow - Rostering

This requires:

1. a Deputy account
2. rostering to be configured
3. a Permanent Token for plugin authorisation
4. the Deputy plugin to be installed
5. the Deputy plugin to be configured

1. Deputy Account

Deputy accounts can be obtained at https://www.deputy.com.

This includes free trial accounts.

2. Configuring Rostering

See How To - Rostering.

3. Plugin authorisation token

In order for OpenVPMS to connect to Deputy, a Permanent Token must be generated.

There is an animated GIF showing this under the Permanent Token section of Deputy's API Authentication page.

1. Go to https://<your deputy host>.deputy.com/exec/devapp/oauth_clients
2. Click 'New OAuth Client'
3. Fill out the fields:
   Name: OpenVPMS
   Redirect Uri: http://localhost
4. Click 'Save This OAuth Client'
5. Click 'Get An Access Token'
   This will display a prompt:

   Access Token is 9878a0425d4b6287131501751a407e19. This is a long life token that will last 10 years.
    

6. Record your Access Token.

4. Plugin Installation

To install the Deputy plugin:

1. Go to Administration - System - Plugins
2. Click 'Install Plugin'
3. Upload the Deputy plugin from <OPENVPMS_HOME>/plugins/deputy-openvpms-plugin.jar
   For OpenVPMS 2.3, the plugin is named deputy-openvpms-plugin-2.3.jar
4. Log-out/in. This is required as the plugin archetypes aren't visible

5. Plugin Configuration

To configure the Deputy plugin:

1. Go to Administration - Organisation
2. Click New - Deputy Service
   Fill out the fields: 

• URL - the URL of your Deputy host. e.g.: https://3ec09100736332.au.deputy.com
• Access Token - the access token you generated in 3.5 above

3. Click Apply
4. If no Mappings are displayed, click Refresh
5. Map Roster Areas and Employees

• Only those Roster Areas that are mapped will be synchronised.
• If a Roster Area is synchronised that has users that aren't mapped to Deputy Employees, affected shifts will be highlighted in the Workflow - Rostering

6. Configure the synchronisation frequency
   By default, synchronisation happens every 30 minutes.
   This can be set to 5 minutes. Any lower frequency setting will be treated as 5 minutes.

Email Template Tips - Open Office

The following are tips and tricks to make Email Templates that generate impressive looking emails using Open Office.

Set the Content Type to Document, and if possible use an Open Office document for the Content. Avoid RTF and HTML content as these do not allow merging, and use Jasper Report (jrxml) content only if you need Jasper Reports abilities to run sub-reports. Avoid Microsoft Office content if possible, because although it does allow merging, it does not provide some of the Open Office facilities (such as conditional content).

When preparing the Open Office document, you need to be careful when you insert images.  You cannot simply inset the image, and you MUST use an image that resides on a publicly accessible website (so that the person who receives the email can access the images), and you MUST link to the image.

Thus, you insert the image, use Insert|Picture|From File... and enter the URL of the image, and ensure that the Link box is ticked - as follows:

Note that the easiest way of getting the image's URL is to open the web page where it is displayed and then right click on the image, then:

In Firefox, use Copy Image Location

In Chrome, use Copy Image Address

Having inserted your image, if you want to centre or right-align it then you must do as follows:

First right-click on the image and select Anchor|As Character:

Click just after the image - by default it is left aligned:

To centre or right-align, click the appropriate icon.

Finally, in normal use, it is quite common to use empty paragraphs to space between items (as has been done above). However, you will find that doing this leads to big gaps in the email text.  Just letting the paragraphs follow one after the other provides perfectly adequate spacing.

Hence, with an invoice cover-note like the following:

the generated email looks like:

Using spaces for spacing
If you have not played with HTML, you may not realise that if text in HTML documents contains multiple consecutive spaces, then these are replaced by a single space. More strictly, multiple whitespace characters are replaced by a single space.  Hence if you wish to space say two graphics apart by 3 spaces, then you cannot use space characters - instead you must use 'non-breaking space' characters.  In Open Office Writer and Microsoft Word you inject these using Ctrl-Shift-Space on a Windows machine or Option-Space on a Mac).

No gaps between paragraphs
The paragraph spacing used in Open Office Writer will be ignored. Hence if your text in Writer looks like:

then the email text will look like:

To bring the lines together, use 'New Lines' (Ctrl-Shift-Enter) instead, so that in Writer you have:

then the email text will look like:

Wrong font
There is a bug in Open Office 4.1.2 that results in a user field at the beginning of a paragraph being given no font specification and thus shows up as (the default) Times.

That is, if in Writer you have:

then the email text will look like:

Looking closely you will see that although the 'Regards' has font Arial, that for Dr Crossling has font Times.

If you change the paragraph mark after the Regards, to a new line, ie like:

then the email text will look like:

Email template Tips - Jaspersoft Studio

The following are tips and tricks to make Email Templates that generate impressive looking emails using Jaspersoft Studio.

Studio is designed to generate pixel-accurate documents.  This works well when generating PDF format output, but for HTML format output one needs top take into account the fact that HTML is designed to handle different screen formats.

In order to make a best effort at generating HTML output that is pixel-acurate, Studio generates the HTML using tables to position items.

To quote https://community.jaspersoft.com/wiki/making-html-xls-or-csv-friendly-re..., the guidelines are:

1. Minimizing the number of rows and columns in the grid oriented formats (minimizing the number of "cuts").

   To do that, you have to make sure you align your report elements as often as you can, both on the horizontal and the vertical axis and that you eliminate the space between elements.

   1. Inefficient Layout:

      

   2. Grid friendly layout:
      

2. Avoiding overlapping report elements.

   Make sure report element will not overlap when the report will be generated. This is because if you have two elements that share some region, it will be impossible for them to share the same cell in the resulting grid structure. You might obtain some unexpected results if elements overlap.

3. Give up using page headers and page footers.

   Especially when you want to obtain documents in which the page breaks are not relevant (CSV for example), make sure that you suppress the page header and page footer sections in your report design. You could also minimize the top and bottom margins for your report, so that when exported to HTML, XLS or CSV, your documents will be made of a single chunk, without page separators.

We also want the email to look good in the email clients that are commonly used. It is suggested that you test with Microsoft Outlook, Gmail using a browser on a workstation or laptop, and Gmail on a smartphone.

To achieve this:

1. use a Page Format with the height and width set to 500px, and zero for all margins
2. in the Report Properties, check the 'Ignore Pagination' option

Image guidlines:

1. Images look best if centered
2. Microsoft Outlook renders images at their original size ignoring any height or width set in the HTML.  Hence having designed the layout with an image height of say 60px and width say 200px, and having set the image property 'Scale Image' to 'Retain Shape', you then need to ensure that the images you are using have a height or 60px and a width not exceeding 200px.

HL7 Laboratories

Overview

This page describes how to configure OpenVPMS to interface with an HL7 laboratory such as IDEXX LabLink. For an overview of HL7 in OpenVPMS, see Concepts - HL7.

Configuration

To configure OpenVPMS to interface with an HL7 laboratory the following steps must be performed:

1. Configure an HL7 MLLP Sender, to send HL7 messages to the laboratory

2. Configure an HL7 MLLP Receiver, to receive HL7 messages from the laboratory

3. Configure an HL7 Laboratory with the Receiver and Sender

4. Configure an HL7 Laboratory Group (optional)

5. Configure investigations to be ordered via the Laboratory/Laboratory Group

1. Configuring an HL7 MLLP Sender

The HL7 MLLP Sender is used to send orders, and patient admission and discharge messages to the laboratory. It is configured via the Aministration - HL7 - Connectors page.

Select New - HL7 MLLP Sender and enter the laboratory connection information as per your laboratory provider's instructions.

2. Configuring an HL7 MLLP Receiver

The HL7 MLLP Receiver is used to receive order cancellation messages from the laboratory. It is configured via the Aministration - HL7 - Connectors page.

Select New - HL7 MLLP Receiver and enter the laboratory information as per your laboratory provider's instructions.

Note that Port is a TCP/IP port that OpenVPMS listens on. It must be accessible to the laboratory through any firewall. Appropriate security precautions should be taken to avoid other parties from accessing the port.

3. Configuring an HL7 Laboratory

The HL7 Laboratory is used to specify a pharmacy to send pharmacy orders to, and receive dispense messages from. It is configured via the Administration - HL7 - Services page.

Select New - HL7 Laboratory and enter the:

• HL7 MLLP Sender configured in step 1 for the Order Connector
• HL7 MLLP Receiver configured in step 2 for the Cancel Connector

4. Configuring an HL7 Laboratory Group

An HL7 Laboratory Group is used to group laboratories by Practice Location.

It is only required for multi-location practices that use different laboratories for each practice location.

It is configured via the Administration - HL7 - Services page.

Select New - HL7 Laboratory Group and enter the HL7 Laboratory or Laboratories configured in step 3.

5. Configuring Investigations

To configure investigations to be ordered by a Laboratory/Laboratory Group, edit the Investigation Types and set the appropriate Universal Service Identifier and Laboratory.

Testing the Connection

The simplest way to test the connection between OpenVPMS and the laboratory provider is to admit a patient. This will send an HL7 ADT A01 message via the Order Connector to the laboratory.

Its progress can be viewed on the OpenVPMS side by going to Administration - HL7 - Connectors, selecting the appropriate HL7 MLLP Sender, and clicking Messages.

To test the connection from the laboratory to OpenVPMS, charge an investigation, and then cancel the corresponding order at the laboratory. A corresponding:

• HL7 ORM O01 should appear in the Messages window for the HL7 MLLP Receiver
• Laboratory Return should appear in Customer - Orders

HL7 Pharmacies

Overview

This page describes how to configure OpenVPMS to interface with an HL7 pharmacy such as Cubex. For an overview of HL7 in OpenVPMS, see Concepts - HL7.

Configuration

To configure OpenVPMS to interface with an HL7 pharmacy the following steps must be performed:

1. Configure an HL7 MLLP Sender, to send HL7 messages to the pharmacy

2. Configure an HL7 MLLP Receiver, to receive HL7 messages from the pharmacy

3. Configure an HL7 Pharmacy with the Receiver and Sender

4. Configure an HL7 Pharmacy Group (optional)

5. Configure products to be dispensed via the Pharmacy/Pharmacy Group

1. Configuring an HL7 MLLP Sender

The HL7 MLLP Sender is used to send pharmacy orders, and patient admission and discharge messages to the pharmacy. It is configured via the Aministration - HL7 - Connectors page.

Select New - HL7 MLLP Sender and enter the pharmacy connection information as per your pharmacy provider's instructions.

2. Configuring an HL7 MLLP Receiver

The HL7 MLLP Receiver is used to receive pharmacy dispense messages from the pharmacy. It is configured via the Aministration - HL7 - Connectors page.

Select New - HL7 MLLP Receiver and enter the pharmacy information as per your pharmacy provider's instructions.

Note that Port is a TCP/IP port that OpenVPMS listens on. It must be accessible to the pharmacy through any firewall. Appropriate security precautions should be taken to avoid other parties from accessing the port.

3. Configuring an HL7 Pharmacy

The HL7 Pharmacy is used to specify a pharmacy to send pharmacy orders to, and receive dispense messages from. It is configured via the Administration - HL7 - Services page.

Select New - HL7 Pharmacy and enter the:

• HL7 MLLP Sender configured in step 1 for the Order Connector
• HL7 MLLP Receiver configured in step 2 for the Dispense Connector

4. Configuring an HL7 Pharmacy Group

An HL7 Pharmacy Group is used to group pharmacies by Practice Location.

It is only required for multi-location practices that use different pharmacies for each practice location.

It is configured via the Administration - HL7 - Services page.

Select New - HL7 Pharmacy Group and enter the HL7 Pharmacy or Pharmacies configured in step 3.

5. Configuring Products

To configure products to be dispensed by a Pharmacy/Pharmacy Group, set the Pharmacy on the appropriate Medication or Merchandise product, or the Product Type.

For large numbers of products, specifying the Pharmacy on the Product Type is the preferred approach, although all products with the Product Type must be dispensed this way.

Testing the Connection

The simplest way to test the connection between OpenVPMS and the pharmacy provider is to admit a patient. This will send an HL7 ADT A01 message via the Order Connector to the pharmacy.

Its progress can be viewed on the OpenVPMS side by going to Aministration - HL7 - Connectors, selecting the appropriate HL7 MLLP Sender, and clicking Messages.

To test the connection from the pharmacy to OpenVPMS, dispense a product. A corresponding:

• HL7 RDS O13 should appear in the Messages window for the HL7 MLLP Receiver
• Customer Order should appear in Customer - Orders

OAuth2

Gmail OAuth2 configuration

Complete

The following instructions can be used to configure a Mail Server that connects to Gmail using OAuth2.
These instructions apply to the Email Document Loader Job as well, although the ports will be different.

1. In Administration - Organisation, create or edit a Mail Server

Enter the following details:

Name	Gmail
Description	Account settings for Gmail
Host	smtp.gmail.com
Port	587
Timeout	120
Connection Security	STARTTLS
Authentication Method	OAuth2  - Gmail

2. Click Authorise

The first time this is done, a New OAuth2 Client Registration window will be displayed.
This prompts for the following details:

• Client Id
• Client Secret

These are obtained in the following steps. Note the Redirect URI.

3. Log in to https://console.cloud.google.com

Create a new project: https://console.cloud.google.com/projectcreate

Project name: OpenVPMS

Click CREATE

 

4. Enable the GMail API

 

i. Select API & Services from the Dashboard
ii. Select Enabled API & services

 

 

iii. Click ENABLE APIS AND SERVICES

 

iv. In the API Library, enter gmail api in the search field.
     Select Gmail API from the results.
 

 

v. Click ENABLE

5. App Registration

i. Under the APIs & Services, click OAuth consent screen

ii. If you are part of an Organisation , select Internal, else select External.
iii. Click CREATE

 

 

iv. On the OAuth consent screen, enter:

• App name: OpenVPMS
• User support email: an email address for users to contact you with questions about their consent
• Under Developer contact information, enter:
  • Email addresses: support[at]openvpms[dot]com

 

 

v. Click SAVE AND CONTINUE

 

vi. On the Scopes screen, click ADD OR REMOVE SCOPES
vii. In the Updated selected scopes popup, under Manually add scopes, enter:
    https://mail.google.com

    and click ADD TO TABLE

viii. In the table, select:

• https://mail.google.com
• .../auth/userinfo.email
• .../auth/userinfo.profile
• openid

and click UPDATE

 

 

ix. On completion, Your non-sensitive scopes should display:

• .../auth/userinfo.email
• .../auth/userinfo.profile
• openid

while Your restricted scopes should display:

• https://mail.google.com

Click SAVE AND CONTINUE

 

6. Test users

i. Click ADD USERS

ii. In the Add users popup, enter the email addresses of the users whose accounts will be access by OpenVPMS

iii. Click ADD

 

 

iv. Click SAVE AND CONTINUE

7. Credentials

i. Under APIs & Services, select Credentials
ii. Click CREATE CREDENTIALS
iii. Click OAuth client ID

 

iv. Under Create OAuth client ID, enter

• Application type: Web application
• Name: OpenVPMS
• Authorized redirect URIs: enter the value displayed in the OAuth2 Client Registration e.g. http://localhost:8080/openvpms/oauth2/code/gmail

v. Click CREATE

A popup will display, containing the Client ID and Client Secret:

Gmail is now ready to accept authorisation.

8. Update OAuth2 Client Registration

Back in the OAuth2 Client Registration editor, enter the Client Id and Client Secret.

 

 

    Click OK. This should automatically start the Authorise flow. A new browser will be displayed.

    After logging in, follow the prompts, and select 'Read, compose, send and permantly delete all your mail from Gmail'

Click Continue.

 

9. Check Authorisation

In the Mail Server window, click Check Authorisation.

    If successful, the Gmail account will appear in the Username field. Click OK.

 

10. Troubleshooting

Authorisation will fail if details haven't been entered correctly. Google error messages can be range from the helpful "Access blocked: authorisation error. The OAuth client was deleted" (indicating that a OAuth 2.0 Client IDs has been deleted in the Google console), to the not so helpful "Sorry, something went wrong there. Try again". 

If authorisation fails, ensure that the:

1. The Client Id and Client Secret from step 7 v. have been correctly entered in the OAuth2 Client Registration window in step 8.

2. Authorized redirect URI in step 7 iv matches that shown in step 8.

3. Scopes match those in step 5 ix.

If the above all match, try performing authorisation in a different browser. The "Sorry, something went wrong there. Try again" error has been seen in Firefox (117.0), but was resolved by using Google Chrome (116.0). 

 

Online Bookings

Overview

OpenVPMS can accept online bookings from external providers, such as MyHealth1st's PetYeti Find A Vet portal.

To enable support for online booking, the following are required:

1. Each participating Practice Location, Schedule and Appointment Type must have Online Booking enabled
2. Each Schedule may specify Online Booking Times. These can be used to specify different times than the default for a schedule.
3. A dedicated OpenVPMS user account should be created that is used solely for online bookings. The provider will use this to submit bookings.

Online Bookings

Online booking appointments will appear in the Scheduling display with a computer icon. In the Appointment editor, the Online Booking flag will be ticked.

If the customer is new or unrecognised, the appointment will display:

No Customer

The customer details will be displayed in the Booking Notes when editing the appointment.

Check-In may not be performed on the appointment until a customer is entered.

If the patient is new or unrecognised, its name will appear in the Booking Notes.

Security

There are a number of security considerations to be aware of:

• an OpenVPMS user account is required to make online bookings. This should be a restricted account that only has the authorities required to make online bookings.
  This can be done by creating a user that only has the Online Booking role assigned.
• the OpenVPMS web application should not be exposed to the wider internet to allow external providers to connect. Restricted access can be provided through a VPN, IP filtering, and/or URL filtering. For the purposes of online booking, only the:
     /openvpms/ws/booking
  URL should be exposed.

Online Investigations with IDEXX VetConnect

OpenVPMS can submit online orders for patient Investigations, and automatically have the results attached and displayed in patient history.

To do this:

1. enable plugin support, if required
2. install the IDEXX VetConnect PLUS plugin
3. configure the IDEXX VetConnect plugin
4. synchronise data
5. link devices to Practice Locations
6. add tests to products

1. Enable Plugin Support

Plugin support is provided in Administration - System - Plugins.

See the corresponding help for instructions on enabling plugins.

2. Install the IDEXX VetConnect PLUS plugin

The IDEXX VetConnect plugin is a file with a .jar extension provided by IDEXX, and will be named something like vetconnect-openvpms-plugin-2.2.jar.

To install it:

• go to Administration - System - Plugins
• click Install Plugin
• in the Upload window, select Browse and enter the path to the plugin .jar
• click Send
• once uploaded it should appear in the list of plugins as IDEXX VetConnect PLUS OpenVPMS plugin, with a status of Active

3. Configure the IDEXX VetConnect PLUS plugin

The IDEXX VetConnect PLUS plugin needs to be configured to enter the user name and password to connect to IDEXX VetConnect PLUS.

To configure it for the first time:

• log out and back in again
  This is required as the plugin installs archetypes which won't be immediately visible, due to caching
• go to Administration - Laboratories and select New -> IDEXX VetConnect PLUS and enter the user name and password provided by IDEXX
• click Apply
• click Mappings - Species Mappings to map OpenVPMS species to their equivalents in IDEXX
  Select the Other species if there is no direct match.
• click OK

4. Synchronise data

With the IDEXX VetConnect PLUS laboratory created in step 3 selected, click the Synchronise Data button.

This will create Investigation Types, Laboratory Devices and Laboratory Tests for use with IDEXX VetConnect PLUS.

Two Investigation Types will be created:

• IDEXX VetLab Station - for tests that are performed by in-house IDEXX VetLab Station devices
• IDEXX Reference Laboratory - for tests that are performed by an IDEXX Reference Laboratory

All IDEXX VetConnect PLUS test will be linked to one of these two Investigation Types.

5. Link Laboratory Devices to Practice Locations

Practices with multiple Practice Locations should limit which Practice Locations can use which Laboratory Devices.

To do this:

• show the available Laboratory Devices in Administration - Laboratory; and
• edit them; and
• add the correct Practice Location to each device on the Locations tab

6. Add Laboratory Tests to products

Tests are ordered by attaching them to products. When the product is charged, the associated tests will be used to create an Investigation which will be submitted to IDEXX VetConnect PLUS.

The results will be automatically attached to the investigation as they become available.

To attach tests to a product:

• go to Products - Information
• select or create a new product
• on the Tests tab, add the test(s)

Online insurance claims with PetSure VetHub

OpenVPMS can submit insurance claims to insurers managed by PetSure VetHub.

To do this:

1. enable plugin support, if required
2. install the PetSure VetHub plugin
3. configure the PetSure VetHub Insurance Service
4. synchronise insurers
5. create a policy
6. submit a claim

1. Enable Plugin Support

Plugin support is provided in Administration - System - Plugins.

See the corresponding help for instructions on enabling plugins.

2. Install the PetSure VetHub plugin

The PetSure VetHub plugin is a file with a .jar extension provided by PetSure, and will be named something like vethub-openvpms-plugin-2.0.jar.

To install it:

• go to Administration - System - Plugins
• click Install Plugin
• in the Upload window, select Browse and enter the path to the plugin .jar
• click Send
• once uploaded it should appear in the list of plugins as PetSure VetHub OpenVPMS plugin, with a status of Active

3. Configure the PetSure VetHub Insurance Service

The PetSure VetHub Insurance Service needs to be configured to enter the user name and password to connect to VetHub.

To configure it for the first time:

• log out and back in again
  This is required as the plugin installs archetypes which won't be immediately visible, due to caching
• go to Administration - Organisation and select New -> PetSure VetHub Insurance Service
• enter the user name and pass word provided by PetSure
• click OK

4. Synchronise Insurers

The Synchronise Insurers button makes all insurers supported by PetSure VetHub available for use in OpenVPMS.

It:

• adds insurers not already present in OpenVPMS
• updates existing insurers
• deactivates insurers no longer supported by PetSure VetHub

Only insurers that have been added via Synchronise Insurers can be used to submit claims to PetSure VetHub.

5. Create a Policy

New insurance policies can be created via Patient - Medical Records - Insurance by clicking the New Policy button.

This will display a New Insurance Policy window.

In order for claims to be made via PetSure VetHub, the Insurer must be one of the insurers added via Synchronise Insurers.

6. Submit a Claim

New insurance policies can be created via Patient - Medical Records - Insurance by clicking the Claim button.

This will display a New Insurance Claim window.

Once the claim is filled out, click the Submit button to submit it to PetSure VetHub.

This will display a declaration an Accept and Decline option. For the claim to be submitted, click Accept.

Orders and Deliveries

This page covers how to run the Supplier's side of OpenVPMS - ie how to generate orders and receive deliveries.

Note that the ESCI system is not covered here.

The first thing to do is to ensure that you have things set up so that ordering system will work. ie

• the suppliers have been created using Suppliers|Information|New
• products from that supplier set to use it and the supplier is set as preferred, and the ordering information is set in the product's Supplier Tab
• products have their stock location data set with current, ideal and critical quantities set in the product's Stock Locations Tab

The basic flow is:

1. Use Suppliers|Orders to create an order to a given supplier for a given stock location, edit if necessary, and when satisfactory, finalise the order [and print and send off to the supplier]. You can either use the Generate Orders button to generate the order(s), or you can create the order by keying in the line items and quantities, or you can do both - ie use Generate Orders, and then edit the order to add more items.
    
2. When stuff arrives, use Suppliers|Deliveries to create the delivery record to tell the system that stuff has arrived, edit if necessary, and when satisfactory, finalise the delivery. Note that the system makes it easy for you to create the delivery record - it will bring up a list of what is on order and you just tick off the items (or if all got delivered, the complete order). If an item was short-shipped (eg you ordered 10 and got 7), then tick the item to get it listed as one of the delivered line items, and then edit the delivery line item to record the lower actual quantity. If an item was over-shipped (eg you ordered 10 and got 15) and you are going to accept the extras (and not send them back to the supplier) just record the quantity actually received.

   Note that when you press the Finalise button you are finalising THIS delivery - you are not necessarily indicating that the complete order has all been delivered - just the stuff that arrived today. The act of finalising the delivery updates the stock and and if you have Auto-Price update set, then the cost price (and hence your sell price) will be automatically updated.

   If this was a part delivery, when more stuff arrives, create the delivery, edit if required, and finalise this delivery.

   If you receive less than you ordered, and you know that there will be no more deliveries, then you need to edit the order (not the delivery) to indicate this.  There are two ways to do this: either you can change the order's status to Cancelled, or (more correctly), for those line items that short-shipped, set the Quantity Cancelled equal to (Quantity Ordered - Quantity Received). In this second case, the order's delivery status will change to Full when all the line items have (Ordered - Received - Cancelled) less than or equal to zero.

We have now done all that is really required. However, if you want OpenVPMS to track the supplier financials, then you need to generate the supplier invoices and enter the payments. Note that you do not need to do this, and many practices use their accounting system to handle the supplier finances.

Invoices and payments are handled as follows:

1. Select a finalised delivery on the Suppliers|Deliveries  screen and press the Invoice button.  The system will create the invoice to the supplier for all delivered items from that supplier. Hence if the order was delivered in three lots, then if you wait until you have three finalised deliveries, pressing Invoice will create just one invoice.
2. Now use Suppliers|Charges to process the invoice - edit it if necessary, and then finalise it.  Note that the Supplier will not want this invoice - he should have already sent you one.  Hopefully the two will agree - in fact you should delay finalising the invoice until the two do agree. [You may have set the supplier's list price wrongly, so your order shows the widgets at $10 each, but the supplier is actually charging $11.50 each.]
3. Having finalised the invoice, it will now appear in Suppliers|Accounts. After you pay the supplier, you can now use Supplier|Payments to tell the system that you have paid.

Given the above flow, when the system is running happily, you use the Generate Orders button on the Suppliers|Orders screen to generate the order (s).  See the above link for the algorithm used.

In a startup situation, you will have orders outstanding that the system does not know about. You could use Suppliers|Orders|New to enter the order.  However, this is not mandatory - you can simply create the delivery records as the stuff is delivered. Note that because you have not entered the order, when you press New on the Suppliers|Deliveries screen,  the system will not find any orders to be delivered. Just OK this and it will generate an empty delivery record for you and you can manually add it all the line items that have been delivered.  Finalising this delivery will cause the stock to be updated.

Over the Counter Refund

If you do an OTC sale to an anonymous customer, and then they return the goods and you want to do a refund, the procedure is as follows:

1. Call up the Customers|Account screen
2. Press the Select button and search for the OTC account and select it
3. Look through the transactions to find both the Invoice for the OTC sale you want to refund and its payment
4. Select each in turn and press the Reverse button to reverse the two transactions. This will create a credit to reverse the invoice and a refund to reverse the payment

Now do the physical reversal - ie put the item(s) back on the shelf, and give the customer back their money.

Note that the refund created by reversing the payment will have the same payment type as the original payment, and you will need to do the refund the same way.

Thus, if they paid by credit card, you will need to do a credit on their credit card. You should NOT just give them money from the till.

Patients and Customers - Adding

The fastest way to add a new customer and their patient(s) is to do as follows:

1. On Customers|Information screen, click New then fill in the name etc, and then press the Add button on the Patient tab, and then the binoculars after the Patient name slot - ie as follows:

Having pressed the Patient binoculars, you will get:

Press the New button, and fill in the patient details so it looks like the following (note the use of the relative date facility to quickly set the Date of Birth and hence Age):

And then press the OK button, which will bring you back to the new customer screen as follows:

If you want you can set the ownership date to the real ownership start date (ie ask Mr Smith when he acquired Rover) but it’s not necessary.

If there are more patients, press Apply to save what you have entered, and then click the Patient Add button to add the next patient.

Having added the patients, you can now click the Contacts tab so that you can add Mr Smith’s contact details.

Finally, press the OK button and you have a new customer with their patient(s).

Patients and Customers - Finding

If you have already found your customer, then you can either select the patient from the Customers|Information screen, or you can click Patients in the top menu and use the Select button (useful if the customer is a boarding kennel and has 300 patients recorded).

If you are looking for a patient and have not already found the customer, then Patients|Information|Select may be used.

As shown below, if you omit any customer information, but provide some or all of the patient name, you will be shown all the matching patients, irrespective of owner.

Print General Labels

The standard drug label templates include a facility to generate a general purpose label.  A general purpose label will be printed for any medication product with the Printe Name set to "LABEL-CSB". For example:

This will generate a label like:

(this is using the Diskette sized label). As you can see the 'Animal Use Only' gets suppressed and the product name is replaced by the patient's Colour/Species/Breed (hence the CSB).

Note that because you can do a New Medication on the Patients|Medical records screen, select this product, fill in the label text and print the label, and THEN cancel, you can generate a label and not leave an entry in the medical records.

Restrict what products are available at each location

If you have multiple locations, you may wish to limit which products are visible to each location in charges, estimates, reminders and patient documents.

By default, all products are available at all locations, and there is no block against invoicing an item for which there is no record of any stock at the current location. (You will get a no stock warning, but if you go ahead and finalise the invoice, a stock record for that item will be created with a negative quantity.)

If you want to limit what products are available then you need to set the 'Use Location Products' flag in the Practice. Having does this, then:

• Medication and merchandise products will only be available if they have a Stock Location relationship. That is, there is (or has previously been) stock at the location. To make the product available at that location you will either have to:

1. transfer stock to that location, or
2. finalise a delivery of the product to that location, or
3. edit the product and on the Stock Locations tab, create a Product Stock Location record for that location.

If there has been stock at the location, and you wish to make it unavailable at that location, then you simply edit the product and, on the Stock Locations tab, simply delete the Product Stock Location record for that location. (Obviously, if there is stock at that location, then you will want to transfer it elsewhere before deleting the record.)

• Service and template products will available UNLESS they have been excluded via their Locations tab.

In addition, templates can indicate what should happen if an included product isn't available at the location. It the the Skip If Missing option is checked then the product will be ignored if it isn't available at the current practice location. This allows a common template to be used that selectively includes products based on the location. The Skip If Missing is not checked (the default) then the template expansion will fail if the product isn't available at the location.

Rostering

Rostering enables employees to be scheduled to work, and identifies which clinicians can be scheduled for online booking.

To set up rostering:

1. Enable rostering at the Practice Location
2. Create Roster Areas
3. Assign users to Practice Locations
4. Enable Online Booking for clinicians
5. Configure Caching
6. Create Shifts

1. Enabling rostering at the Practice Location

In order to do rostering it needs to be enabled. This is done on a per-Practice Location  basis.

1. Go to Administration - Organisation
2. Edit the Practice Location that rostering is to be used at
3. tick the Rostering box
4. change the Roster Check Period, if required.
   This determines how far into the future to check the roster when scheduling clinicians to appointments. E.g., if the period of 4 weeks, the roster will be checked when assigning a clincian to an appointment created between the current date and 4 weeks in the future.
   If a clincian isn't rostered on, a warning will be displayed.

2. Creating Roster Areas

Roster Areas are areas within a Practice Location where employees work, e.g. Surgery, Reception, Grooming, or Boarding.
They can be assigned Schedules, indicating which schedules a clinician can work on.

1. Go to Administration - Organisation
2. New Roster Area
3. Enter the Name, optional Description, and practice Location, and add any Schedules.
4. click OK
5. repeat for each area in the practice

3. Assign users to Practice Locations

This step applies to multiple-locaction practices, where employees only work at one or several of the practices. It can be skipped for single-location practices.

In the Employees view of the Rostering workspace, all employees who can work at the current location are displayed.
To ensure that only those employees who work at the current location are displayed:

1. Go to Administration - Users
2. edit each User and on the Locations tab, add the practice locations that the user works at

4. Enable Online Booking for Clinicians

By default, online bookings aren't associated with any particular clinician. To allow customers make an online booking with specific clinicians:

1. Go to Administration - Users
2. edit each clinician User, and click the Online Booking flag

Notes:

• clinician availability is determined by the clincian's roster. A clinician will be unavailable if no roster has been set up for the period when a customer makes an appointment
• the booking provider must support v2 of the OpenVPMS Booking API

5. Configure Caching

Rostering data is cached for performance reasons. Two caches are used, Roster By Area, and Roster By Employee. The default sizes of these are determined by the number of Roster Areas and the number of Users respectively.

These only need to be changed if Roster Areas or Users are added or deleted or marked inactive.

To configure Rostering data caching:

1. Go to Administration - System
2. click Caches
3. select Roster By Area
4. click Edit
5. select Suggested, and click OK
6. select Roster By Employee
7. click Edit
8. select Suggested, and click OK
9. click Close

6. Create Shifts

Employees are rostered to areas by creating Shifts in Workflow - Rostering.
New shifts can be created by double-clicking in an empty cell on the Areas or Employees tab. Shifts can be copied using Ctrl-C and pasted into an empty cell using Ctrl-V.

To avoid scheduling warnings when assigning clincians to appointments, shifts should be created at least a week beyond the Roster Check Period.

Smart Flow Sheet integration

1. Overview

OpenVPMS can connect to Smart Flow Sheet to:

• create Flow Sheets for patients
  • during Check In
  • when transferring a task to a work list configured to create Flow Sheets
  • by pressing New Flow Sheet in Workflow - Scheduling or Workflow - Work Lists
• charge treatments given to a patient in Smart Flow Sheet
• add notes entered in Smart Flow Sheet to the corresponding patient's history
• import Medical Record, Billing, Notes, Flow Sheet and Anaesthetic reports, and add them to a patient's history
  • automatically, when the patient is discharged
  • by pressing Import Flow Sheet Records in Patients - Medical Records - Summary
• dicharge patients at check-out

To use Smart Flow Sheet:

1. Configure the Smart Flow Sheet Clinic API Key
2. Synchronise products
3. Synchronise clinicians
4. Configure work lists to create Flow Sheets (optional)
5. Configure Smart Flow Sheet

See Troubleshooting to diagnose Smart Flow Sheet related errors.

2. Configuring the Smart Flow Clinic API Key

Smart Flow Sheet needs to be enabled for each Practice Location where it will be used. This is done by:

1. Editing the Practice Location
2. Copying the API KEY displayed on the EMR Integration Settings page to the Smart Flow Sheet Clinic API Key

Multiple Smart Flow Sheet accounts are required if you have multiple Practice Locations, and:

• wish to receive billing information from Smart Flow Sheet; or
• limit products that are available for treatment, per location; or
• limit users that are available, per location

You will need to log out after making this change for it to take effect.

Once enabled:

• a New Flow Sheet button will be displayed in Workflow - Scheduling and Workflow - Work Lists. This can be used to create a Flow Sheet for the patient associated with an appointment or task
• an Import Flow Sheet Reports button will be displayed in Patients - Medical Records - Summary. This imports reports from Smart Flow Sheet for the selected patient Visit.
• a Synchronise with Smart Flow Sheet button will be displayed in Products - Information for administrator users
• a Synchronise with Smart Flow Sheet button will be displayed in Administration - Users for administrator users

3. Synchronising products

In order to see OpenVPMS products in Smart Flow Sheet, they need to be synchronised.

This:

• adds products to Smart Flow Sheet that aren't already present
  Only Medication, Merchandise and Service products are added, that are:
  • active, and;
  • available at the current Practice Location*, and;
  • don't have Use only in Templates set, and;
  • have no Product Type, or have a Product Type with Synchronise with Smart Flow Sheet ticked
• updates products in Smart Flow Sheet, that have changed since they were last synchronised. 
• removes products that are no longer active, or are no longer being synchronised 

* To be available at the current Practice Location:

• Medication and Merchandise products must have a Stock Location relationship with the current Practice Location's Stock Location
• Service products must have a Location relationship with the current Practice Location, if the Practice Use Location Products option is selected

Before synchronising products for the first time, log in as an administrator and go to Administration - Types. Edit each Product Type that should be synchronised, selecting Synchronise with Smart Flow Sheet.

To synchronise products, log in as an administrator user and go to Products - Information and click Synchronise with Smart Flow Sheet

Whenever products are updated, they should be synchronised.

Medication products

Medication products that have a Concentration must also specify the concentration units and Dispensing Units in order to fully synchronise.

Multiple Practice Locations

In multi-location practices, product synchronisation needs to be done for each practice location that has Smart Flow Sheet configured.

If the Practice Use Location Products option is selected, only the products linked to the current location will be synchronised. All other products will be removed.

4. Synchronising clinicians

In order to see OpenVPMS clinicians in Smart Flow Sheet, they need to be synchronised. This:

• adds clinicians to Smart Flow Sheet that aren't already present
  Only active clinicians that are available at the current Practice Location are added
• updates clinicians in Smart Flow Sheet, that have changed since they were last synchronised. 
• removes clinicians that are no longer active

To synchronise clinicians, log in as administrator user, and go to Administration - Users and click Synchronise with Smart Flow Sheet.

Whenever clinicians are updated, they should be synchronised.

Multiple Practice Locations

In multi-location practices, clinician synchronisation needs to be done for each practice location that has Smart Flow Sheet configured.

Only the clinicians that are available at the current practice location will be synchronised.

5. Configuring Work Lists to create Flow Sheets

Work Lists have a Create Flow Sheet option. When ticked, this will create a new Flow Sheet for a patient when the patient is:

• added to the Work List during Check In
• transferred to the Work List

Flow Sheets are linked to the patient Visit, so no new Flow Sheet will be created if one already exists for the Visit.

6. Configuring Smart Flow Sheet

Smart Flow Sheet provides an EMR Integration Settings page that determines the notifications that OpenVPMS receives.

6.1 Billing

To invoice treatments given in Smart Flow Sheet, set the following options to ON:

• Send Billing & Medical Records to EMR
• Send Anesthetic Billing & Medical Records to EMR

When OpenVPMS receives treatment notifications, it creates Customer Pharmacy Orders. If a treatment is amended or removed, it may create a Customer Pharmacy Return to reverse any invoiced amount.

Where possible, these will be automatically invoiced during the Check-In, Consult and Check-Out workflows.

NOTE: if you have multiple practice locations, you must use a separate Smart Flow Sheet account for each location when using these options to avoid charges being associated with the wrong location.

Cubex

If you connect Smart Flow Sheet and OpenVPMS to Cubex, you should set the options to OFF, to avoid double charging.

7. Troubleshooting

• SFS-0103: Failed to connect to Smart Flow Sheet. Check that the Smart Flow Sheet Clinic API Key is correct.

Check that the Smart Flow Sheet Clinic API Key matches that provided by Smart Flow Sheet.

• SFS-0118: Failed to download Smart Flow Sheet - Medical Records
  The manager turned off document on the Settings / Documents management page

The report needs to have its corresponding Files to Retain After Discharge option set to YES on the Documents Management page.

• Production/Test systems
  If you have both a production and test installation of OpenVPMS, you should either:

  • disable Smart Flow Sheet integration in the test system; or

  • discharge any patients that have had flow sheets created by the test system, before using it for production

This is because Smart Flow Sheet hospitalisations are linked to OpenVPMS by the patient's Visit identifier, and you cannot have two flow sheets for the same Visit identifier.
 

Test Reminders

If you are building or modifying reminder templates, then you will want to test them.

A convenient way to do so is as follows.

First set up the following:

1. a test practice location called say ZZ Test (this will enable you to process just reminders for customers whose practice location is set to ZZ Test)
2. a test customer say ZZ Test (whose practice location is set to ZZ Test) who has a patient say ZZ Dog. 
3. two test reminders called say ZZ Test1 and ZZ Test2 (you need 2 if you are want to test grouped reminders)

Now call up Patients|Medical Records|Reminders for ZZ Dog and use New to create two reminders, one for ZZ Test1 and the other for ZZ Test2. For each, add an item for each type of reminder (Print, Email, SMS, Export or List) that you want to test, eg:

Now go to Reporting|Reminders, set the Location to ZZ Test and you will see something like:

You can now press the Send All button and it will send these reminders.

Use Gmail to send mail

If you have a Gmail account, you can use Gmail's SMTP server to send out mail from OpenVPMS.  Setting up things this way is particularly useful if you are using your Gmail address as the From address in OpenVPMS - because some mail systems (Gmail in particular) check the From address against the SMTP server used to transmit the email and will generate warnings to the recipient if the SMTP server used does not match the from address.

To use your Gmail account as an SMTP server, you need to set up a Mail Server record (via Administration|Organisation) as follows:

The Name, Description, Username, and Password should be set to suit your setup.

You will then need to set this Mail Server in the Practice and/or Practice Location records as required.

Note that one idiosyncrasy of the Gmail SMTP server is that if the From address in the email differs from that being used then the From address will be updated to reflect the name of the account used to send the email.

Hence if the From address is set to "XYZ Vets Inc<xyzvets[at]gmail[dot]com>", and the above Mail Server is used, then the From address will be changed to "XYZ Vets Inc<dg12345[at]gmail[dot]com>".  Thus, in the above case, it would be better to use the xyzvets[at]gmail[dot]com account in the Mail Server record.

VetCheck Integration

OpenVPMS supports integration with VetCheck.

VetCheck can generate digital practice forms with e-signature, digital dental or GA monitoring charts, vaccination certifications, discharge instructions, home care videos, pet healthcare programs & handouts.

VetCheck emails generated forms to the customer, and these are also included as clickable links in patient history.

Set Up

To use VetCheck:

1. Sign up for an account at https://vetcheck.it/

2. Select the Enable VetCheck flag in the Practice.

Log out and back in for the changes to take effect.

This adds a VetCheck button in:

• the patient summary
• Administration - Templates

Patient VetCheck

To generate handouts etc for a patient:

1. Click the button in the patient summary.

The VetCheck website will be displayed in a popup window, with the following details submitted:

• the customer first name, last name, email address and phone
• the patient name, species, breed, sex, date of birth, colour and microchip

2. Enter your VetCheck credentials to log in

3. Search for a handout

4. Click SINGLE SHARE

5. Fill out the details and click SHARE A SINGLE HANDOUT

• VetCheck will send the handout to the customer
• OpenVPMS will add a link to it in patient history
• the link will be displayed beneath the button in the patient summary.
  The three most recent links will be displayed.

Template Administration

To administer VetCheck templates, click the VetCheck button in Administration - Templates.