Installing OpenVPMS

Complete

This section describes how to install OpenVPMS.

The required software is documented in Requirements.

There are three installation procedures:

  1. New Installation - to install for the first time
  2. Upgrading an existing system
  3. You have an existing system, but want to upgrade to a new machine

If you are doing a new install, you should also read:

Other useful information can be found in the following:

Browser Compatibility

Complete

OpenVPMS is designed to be used with Firefox, Chrome, or Safari.

The Context Sensitive Help facility provides help when you press Alt-F1 on most screens.

By default, the help is displayed in a separate browser window. If you want it displayed in a tab rather than a new window, try the following:

  • Firefox: install the 'Open Link in New Tab' add-on
  • Chrome: install the 'One Window' extension
  • Safari: select Preferences|Tabs|Open pages in tabs instead of windows: Always

Note that both Context Sensitive Help and Print Previews are treated as pop-ups by browsers and may be blocked. You will need to enable pop-ups for your OpenVPMS site.

 

Data Migration

Complete

OpenVPMS doesn't directly support data migration from other veterinary practice systems.

It does however provide a plugin for Pentaho Data Integration (PDI, aka Kettle) that can be used to get data into OpenVPMS.

At this stage, only PDI 3.2 is supported. This can be obtained from here.

Extract this zip file to a directory. This will be referred to as <PDI_HOME>.

To install the OpenVPMSLoader plugin:

  1. Extract <OPENVPMS_HOME>/import/plugin/OpenVPMSLoader.zip to     <PDI_HOME>/plugins/steps/OpenVPMSLoader
  2. Remove <PDI_HOME>/libext/spring/spring-core.jar
  3. Copy <PDI_HOME>/plugins/steps/OpenVPMSLoader/spring-asm-3.0.5.RELEASE.jar to <PDI_HOME>/libext/spring
  4. Copy <PDI_HOME>/plugins/steps/OpenVPMSLoader/spring-core-3.0.5.RELEASE.jar to <PDI_HOME>/libext/spring

See also Implementors Forum|Data Migration

Note that PDI 3.2 needs to use the 32-bit Java JVM.  If you have previously installed the 64-bit version for Tomcat to use then you will also need to install the 32-bit version for PDI.

New Installation

Complete

The following describes how to install OpenVPMS from scratch and assumes that you have downloaded it and unpacked its zip file.

If you have not installed the other required software, see Requirements.

The headings below are:

Note that in the following the directory or folder separator character is shown as /, following unix conventions. On Windows, replace / with \. e.g. given:
  <OPENVPMS_HOME>/lib
change to:
  <OPENVPMS_HOME>\lib

Directory structure

The OpenVPMS installation has a single top-level directory named:
   openvpms-release-XXX
where XXX indicates the version.

This will be referred to as <OPENVPMS_HOME> in the remainder of this document. This directory has the following sub-directories:

Name Contents
bin a number of tools used to load data into OpenVPMS
conf configuration files for the tools in ../bin
db MySQL SQL scripts to create the initial database
import data to import into OpenVPMS
lib jars used by the tools in ../bin
reports document templates for reporting
update data and scripts to migrate from earlier versions of OpenVPMS
webapps  the OpenVPMS web applications

 

 

 

 

MySQL connector

The MySQL Connector/J JDBC driver needs to be downloaded from:
    http://dev.mysql.com/downloads/connector/j/5.1.html
   
It is typically named mysql-connector-java-5.1.<x>.zip or mysql-connector-java-5.1.<x>.tar.gz where <x> represents the minor version number.

The JDBC driver in the archive is named:
    mysql-connector-java-5.1.<x>-bin.jar.

This needs to be copied to:

  • the Apache Tomcat library directory: <TOMCAT_HOME>/lib
  • the OpenVPMS library directory:  <OPENVPMS_HOME>/lib

In the above, <TOMCAT_HOME> refers to the directory where Apache Tomcat is   installed. On Windows, this will be something like:
    C:\Program Files\Apache Software Foundation\Tomcat 7.0

Database setup

To create the OpenVPMS MySQL database, run the following in a shell prompt
  > cd <OPENVPMS_HOME>/db
  > mysql -u admin -p < createdb.sql
  > mysql -u admin -p openvpms < db.sql

NOTES:

  • replace 'admin' with a user that has administrator privileges in MySQL.
  • the createdb.sql script creates an 'openvpms' user that only has privileges to connect from localhost. If the MySQL database is a different host to that running Tomcat, change the createdb.sql script to uncomment:

    # GRANT ALL PRIVILEGES ON openvpms.* TO 'openvpms'@'%'
    #     IDENTIFIED BY 'openvpms' WITH GRANT OPTION;

To improve security, the '%' can be limited to the host that Tomcat will connect from.

Next, run the 'dataload' script. This provides two options, 'base' and 'setup'. The former loads a base database setup in preparation for data migration. The latter contains a default setup suitable for a new installation.

e.g:
  > cd <OPENVPMS_HOME>/bin
  > dataload setup

Web application installation

To install the OpenVPMS web application:

  1. Copy <OPENVPMS_HOME>/webapps/openvpms.war to the <TOMCAT_HOME>/webapps  directory.
  2. Start Apache Tomcat if it is not running

OpenOffice installation

OpenVPMS uses OpenOffice to perform reporting, printing and document conversion.
Install it as per your platform's requirements and then:

  1. Add it to the PATH of the user that runs Apache Tomcat.
    The installation path differs by platform and OpenOffice version. For OpenOffice 4 on Windows, the default installation path is:

           C:\Program Files (x86)\OpenOffice 4\program

    Windows users can find instructions for changing the PATH here.      

  2. Verify it can be run as that user. From a command prompt, enter:
          soffice
    This should start OpenOffice.

Document Templates

Document templates used for invoices, payments etc., are located in:
      <OPENVPMS_HOME>/reports

These need to be loaded prior to use. This can be done using the 'templateload' script. e.g:

  > cd <OPENVPMS_HOME>/bin
  > templateload ../reports/templates-X.xml

Where X is:
       A4 to load the A4 template set
       A5 to load the A5 template set
       Letter to load the Letter (ie US) template set

NOTES:

  • If a template with the same name has been already loaded, it will be replaced. More precisely, templates with the same name AND same content name will be replaced. Hence, if you have a template named Invoice, with content invoice-BE.jrxml, this will not be replaced but a new template named Invoice with content invoice.jrxml will be created.
  • Not all templates are available in all formats, however a complete set is loaded. Thus if you load the A5 set you will find that some templates are in A4 format. To clarify the situation, the description field indicates the paper size if it is not A4. eg " Medical Records (A5)"
  • Three drug label formats are available, Dymo, Epson, and 1.8x3.1.  If you load the Letter set you will get the latter, if you load A4 or A5 you will get Dymo.
  • Not everything is loaded. For example the Samples and the Patient Reminder Post Cards are not.

After installation, templates can be updated using via Administration|Templates.

The templates need to be customised to add practice logos etc. Templates with a:

  • .doc or .odt extension can be customised in OpenOffice Writer or Microsoft Word
  • .jrxml extension can be customised in Jaspersoft Studio

See also Introduction|Reporting, Reference|Reports and Forms, and Administration|Templates.

Testing the installation

To test the installation, open up your Internet Browser and enter the address:

      http://localhost:8080/openvpms/app

Login to OpenVPMS using user admin and password admin

 

Optional steps

OpenVPMS ships with optional data that can be loaded as required. This includes:

  • Security roles

The basic installation grants all functionality to all users. To restrict this, load the roles.xml file

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/roles.xml

  • VeNom presenting complaint and diagnosis codes

These are standardised codes that can be used to classify patient Problems. These can be loaded using:

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/VeNom-lookups.xml

  • Australian states and suburbs

These can be loaded using:

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/postcodesAU.xml

 

Requirements

Complete

OpenVPMS can be installed on either a unix system (most commonly a Ubuntu server), or a Windows system.  For Windows, for small practices you can install on a desktop or laptop running Windows 7 or 8; for larger practices it may be better to use a Windows Server operating system.

OpenVPMS requires the following to be installed:

    This may be included in the MySQL server installation.

    If you have installed Java 8, you must use Tomcat 7.0.53 or higher.

  • OpenOffice 4.0.x
    See http://www.openoffice.org/download/

     

  • Jaspersoft Studio 6.0.3 or higher
    This is only required to customise document templates.
    See https://community.jaspersoft.com/project/jaspersoft-studio/releases

    NOTE: this replaces iReport Designer which is no longer under active development, and does not work with Java 8. Sites running Java 7* can continue to use iReport Designer, but should use 5.0.4 or higher.

  • MySQL:
    • should be on the same host as Tomcat
    • should accept connections on port 3306
    • include the following lines in my.ini
      max_allowed_packet=16M
      innodb_file_per_table

 

* Java 7 will no longer be updated by Oracle as of April 2015. OpenVPMS 1.8 will continue to work with Java 7, but users are encouraged to update to Java 8 to receive bug fixes and security enhancements. Java 8 will be required by OpenVPMS 1.9.

Security

Complete

This page addresses various security related matters.

Database passwords
The default installation creates a MySQL database user named 'openvpms' with password 'openvpms'.

This password should be changed. This can be done with the mysql utility with the command:
    set password for 'openvpms'@'localhost' = password('3f6iNF7m46w9vjc');

This should be done for each host that the openvpms user has been granted access from.

For more information see:
  https://dev.mysql.com/doc/refman/5.5/en/set-password.html

The password is stored in configuration files that will also need to be updated:

  • <OPENVPMS_HOME>/conf/hibernate.properties
  • <TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/hibernate.properties

Administrator password
The default installation creates an OpenVPMS user named 'admin', with password 'admin'.

This should be changed when installation is complete, via Administration|Users.

User passwords
User passwords are configured via Administration|Users. There is little restriction on what passwords may be entered, but it is recommended that strong passwords are used.

File permissions
The OpenVPMS and Tomcat installation directories should only be accessible to a single user with a strong password.

These directories contain files that could enable an attacker to gain access to the OpenVPMS web application, or the MySQL database.

 

Subscription

Complete

OpenVPMS relies on user subscriptions to fund development.

Your subscription status is displayed on the OpenVPMS login screen. If you have not paid, a link to a payment page is displayed. On payment, a subscription key will be mailed to you.

If you have a current subscription, you can request a subscription key by emailing a copy of your receipt to subscription[at]openvpms[dot]org.

To update your subscription status, edit the Practice in the Administration|Organisation workspace and upload the new subscription key.

Upgrade an existing system

Complete

This section details the procedure to be used when upgrading to a new release of OpenVPMS.

The headings below are:

Having installed the new release, you may want to look at the Implementation Checklist page.

Note that in the following the directory or folder separator character is shown as /, following unix conventions. On Windows, replace / with \. e.g. given:
  <OPENVPMS_HOME>/lib
change to:
  <OPENVPMS_HOME>\lib

Requirements

The software required to run OpenVPMS may change between releases.

Check Requirements to ensure you have the necessary software.

Preparation

 

Back up your database prior to performing the upgrade.

This can be done using the mysqldump tool. e.g.:

        mysqldump -u openvpms -p openvpms > openvpms.sql

NOTE: It is good practice to ensure that the backup can be restored to a different server, prior to performing any upgrade.

See also How To|Administration|Backup.

Directories

These instructions assume that:

  1. The previous OpenVPMS installation is available in <OPENVPMS_PREV>.
     e.g. on Windows:
        c:\OpenVPMS\openvpms-release-1.7

  2. The new installation will be located in <OPENVPMS_HOME>.
     e.g. on Windows:
        c:\OpenVPMS\openvpms-release-1.8

NOTE: the OpenVPMS version can be excluded from the path name, for example c:\OpenVPMS-Current Release - when upgrading you can rename this to say 'Current Release prev' . This can simplify upgrades by removing the need to change custom scripts that contain the installation path.

The previous installation should be retained until:

  •   settings have been migrated to the new installation
  •   the migration has been verified to be successful

Database migration

Upgrading from an earlier version of OpenVPMS requires data migration scripts to be run.

The scripts are located in the <OPENVPMS_HOME>/update/db directory. With the exception of the 1.5 to 1.6 release (where there was no change to the database structure), there is one sql script per release.

The sql scripts are:
     migrate-1.0-to-1.1.sql
     migrate-1.1-to-1.2.sql
     migrate-1.2-to-1.3.sql
     migrate-1.3-to-1.4.sql
     migrate-1.4-to-1.5.sql
     migrate-1.6-to-1.7.sql
     migrate-1.7-to-1.8.sql

You need to run each relevant one in turn using the mysql utility.

Hence if you are upgrading from OpenVPMS 1.7, run:
     > mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql

If you are upgrading from OpenVPMS 1.5 or 1.6, run:
     > mysql -u openvpms -p openvpms < migrate-1.6-to-1.7.sql
     > mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql

If you are upgrading from OpenVPMS 1.0 - you need the lot, so run:
     > mysql -u openvpms -p openvpms < migrate-1.0-to-1.1.sql
     > mysql -u openvpms -p openvpms < migrate-1.1-to-1.2.sql
     > mysql -u openvpms -p openvpms < migrate-1.2-to-1.3.sql
     > mysql -u openvpms -p openvpms < migrate-1.3-to-1.4.sql
     > mysql -u openvpms -p openvpms < migrate-1.4-to-1.5.sql
     > mysql -u openvpms -p openvpms < migrate-1.6-to-1.7.sql
     > mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql

Note that if you are helping test a new release, you will be getting 'snapshot' releases. It this case it is sensible to re-run the migration script for the new version. The scripts are written so that they are re-runnable.

Replication

If you are replicating your OpenVPMS database, you must ensure that row-based replication is used. The migration scripts are not compatible with statement-based replication.

MySQL connector

Copy the MySQL JDBC driver mysql-connector-java-5.1.<x>-bin.jar from <OPENVPMS_PREV>/lib to <OPENVPMS_HOME>/lib

Load archetypes

Load the latest archetypes by running the appropriate archload script for your platform.

   Windows:
   > cd <OPENVPMS_HOME>\bin
   > archload

   Unix:
   > cd <OPENVPMS_HOME>/bin
   > archload.sh

Web application

The existing web application should be removed before installing the new version.

To do this:

  1. Shut down Apache Tomcat if it is already running.
  2. Delete or move directory: <TOMCAT_HOME>/webapps/openvpms
    Do not move it to another directory under <TOMCAT_HOME>/webapps/ as Tomcat will continue to launch it.
  3. Delete the file:      <TOMCAT_HOME>/webapps/openvpms.war
  4. Delete the directory: <TOMCAT_HOME>/work/Catalina/localhost/openvpms
  5. Copy <OPENVPMS_HOME>/webapps/openvpms.war to the directory <TOMCAT_HOME>/webapps
  6. Start Apache Tomcat - this will extract <TOMCAT_HOME>/webapps/openvpms.war and build <TOMCAT_HOME>/webapps/openvpms

Customisation

If you use customised versions of the standard archetypes, or have added archetypes, these will need to be loaded.

For modified versions of the standard archetypes, be sure to incorporate any changes that have been made.

You should then use archload to load these archetypes - or if you have only a few, use Administration|Archetypes|Import.

If you have customised versions of propercase.properties, help.properties, or messages.properties you need to install these in
  <TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/localisation

You can simply overwrite the default propercase.properties with your own version.

However, help.properties and messages.properties will need to be edited to bring your adjustments into the current versions.
 
If you have a customised default.stylesheet, then the version in
  <TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/style
will need to be edited to incorporate your changes.
 
Now restart Apache Tomcat so the above customisations get picked up and login and see that things are as they should be.

Document Templates

In order to take advantage of new and revised document templates, you will need to load these - see here. Note that you will almost certainly have tailored versions of the system documents (like invoices, credits, etc). Before loading the templates, you will need to check that your customised version have different names - as the notes say:

"If a template with the same name has been already loaded, it will be replaced. More precisely, templates with the same name AND same content name will be replaced. Hence, if you have a template named Invoice, with content invoice-BE.jrxml, this will not be replaced but a new template named Invoice with content invoice.jrxml will be created."

Hence, if your customised versions have the standard content names, loading the new set will overwrite your customised versions.  In this case, the best approach is probably to edit the templateload xml file (ie <OPENVPMS-HOME>/reports/templates-X.xml where X is A4, A5 or Letter) to delete the lines for the templates that you do not want loaded.

Kettle

If you use Pentaho Data Integration (see here) then you need perform its steps 1,2 and 3 to upgrade the OpenVPMS components.

Upgrade to a new machine

Complete

If you have an existing system but you are installing OpenVPMS on a new machine, you essentially go through the steps for a new install, but instead of creating a new openpms database, you restore your existing one, and then upgrade that to the new release.

 

First you need to use mysqldump to take a backup of the database on the old machine (see Upgrade|Preparation).

Now you can follow the New Installation steps until you get to the dataload step. Instead of using the dataload utility, you use the mysql utility to restore your backup onto the new machine.  This is done using the command:

  > mysql -u admin -p openvpms < openvpms.sql

where admin is the name of your root user and openvpms.sql is the dump from the old machine.

You should continue with the Web Application and Open Office installation steps.

To complete the process, we need to upgrade the installation on the new machine, so we simply use the steps to Upgrade an Existing Installation.