Browser Compatibility

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

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. Remove any existing OpenVPMSLoader plugin from <PDI_HOME>/plugin/steps
2. Extract <OPENVPMS_HOME>/import/plugin/OpenVPMSLoader.zip to     <PDI_HOME>/plugins/steps/OpenVPMSLoader
3. Remove <PDI_HOME>/libext/spring/spring-*.jar
4. Copy <PDI_HOME>/plugins/steps/OpenVPMSLoader/spring-core-3.2.14.RELEASE.jar to <PDI_HOME>/libext/spring
5. Update the spoon script to include:
          -Djava.util.Arrays.useLegacyMergeSort=true
   This is required when using Java 7 or higher, to work around a bug in PDI 3.2

For Windows, modify spoon.bat and change:

set OPT=-Xmx256m...

to:

set OPT=-Xmx256m... -Djava.util.Arrays.useLegacyMergeSort=true

For Unix, modify spoon.bat and change:

OPT="-Xmx256m...."

to:

OPT="-Xmx256m.... -Djava.util.Arrays.useLegacyMergeSort=true"

 

See also Implementors Forum|Data Migration

Java Requirements

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.

To migrate data from Microsoft Access Databases (.mdb), Java 7 is required, as support for ODBC drivers was dropped in Java 8.

MySQL connector

PDI includes mysql-connector-java-3.1.14-bin.jar in the <PDI_HOME>/libext/JDBC/ directory. Whilst this is much older than the 5.1 version recommended for OpenVPMS, it should be retained to avoid a bug in the later version of the MySQL connector. The bug is activated by the inclusion of the useCursorFetch in Database Connection - Options, and prevents loading of archetype descriptor assertions. These are used to define lookups and constraints in archetypes, and thus no longer work.

 

 

Locale and Fonts - Unix

Locale

The reports and documents in the release package make use of the system's locale to get the appropriate date and currency formats and to select the appropriate resource bundle. Many unix systems use the standard en_US.UTF-8 locale. To change the locale on a ubuntu system you can use:

sudo apt-get install language-pack-en-base
sudo nano /etc/default/locale   to set the required locale

then log out and in again (and restart Tomcat if necessary using sudo service tomcat7 restart).

The locale being used is shown on the Help screen.

Fonts

NOTE: the following discussion applies ONLY to reports and documents that use jrxml content. For Forms and Letters that use Open Office odt (and Microsoft Word .doc) based content, you can happily use any font installed on the system. However, if you are creating odt/doc content on a Windows system but your OpenVPMS server is running on a unix system, then the fonts you use may get remapped. For example 'Bradley Hand ITC' will be mapped to 'URW Chancery L'. If you need specific fonts installed on your unbuntu server, see here.

***UPDATE for 1.9.1***

In the 1.9.1 release all standard reports have been converted to use the DejaVu fonts. Because these are built into JasperSoft Reports, all will work with no problems. If you build or use custom reports you should ensure that these use the DejaVu fonts rather than the default San Serif. (Look at the Style|Base section with JaspersoftStudio in any standard report to see how this is done.)

***End 1.9.1 - keep reading for 1.9 and prior ***

The reports and documents in the release package have all been developed in a Windows system. The fonts are almost without exception set to Sans Serif.  In a Windows system this maps to the Arial font.

However on unix systems it normally maps to the DejaVu fonts. Although these look like Arial, they have slightly bigger font width metrics, and as a result sometimes the text does not fit in the allowed space.

That is, you get effects like the following where the words 'From Date' and 'Method' have been truncated - and also 'Report' is missing from the title.

instead of:

The fix is to replace the DejaVu fonts with the Liberation fonts. These are a set of Sans Serif, Serif and Monospaced fonts designed to have the same font metrics as the Microsoft Arial, Time Roman and Courier New fonts.

Since JasperReports uses the Java fonts we need to do two things:

1. install the Liberation fonts
2. change Java's fontconfig to map the Sans Serif, Serif and Monospaced fonts to the Liberation ones rather than the DejaVu ones

On a Ubuntu systems you can install the Liberation fonts using:
  sudo apt-get install fonts-liberation

To change the font mapping, you need to edit the appropriate fontconfig file. In the <JAVA_HOME>/jre/lib directory you will find the following fontconfig files:

fontconfig.RedHat.5.bfc
fontconfig.RedHat.5.properties.src
fontconfig.RedHat.6.bfc
fontconfig.RedHat.6.properties.src
fontconfig.SuSE.10.bfc
fontconfig.SuSE.10.properties.src
fontconfig.SuSE.11.bfc
fontconfig.SuSE.11.properties.src
fontconfig.Turbo.bfc
fontconfig.Turbo.properties.src
fontconfig.Ubuntu.properties
fontconfig.bfc
fontconfig.properties.src

For a Ubuntu system, the one to edit is fontconfig.Ubuntu.properties.

To make things easier, the modified file is attached to this post named fontconfig.Ubuntu.properties.txt

After you modify the file, you will need to restart Tomcat to have it take effect.

Locale and Fonts - Windows

Locale

The reports and documents in the release package make use of the system's locale to get the appropriate date and currency formats and to select the appropriate resource bundle. 

Note that the locale used by OpenVPMS is that seen by the Java environment used by Tomcat and that this can be different from that you see when you log on as a Windows user. The locale being used is displayed on the Help screen. For how to set/check the Java locale see here.

If you run Tomcat under a user account, then you need to check the locale set for that account.

However, if you run Tomcat under the system account (the normal setup) then you need to ensure that the locale set for the 'Welcome Screen and System accounts' is as required. If not, on the Copy Settings window, click the 'Welcome screen and system account' box and press OK. Note also that it is the 'Format:' setting that determines the date and currency formats.

If you change the region settings, then you MUST restart Tomcat for the change to take affect.

Fonts

***UPDATE for 1.9.1***

In the 1.9.1 release all standard reports have been converted to use the DejaVu fonts. Because these are built into JasperSoft Reports, all will work with no problems. If you build or use custom reports you should ensure that these use the DejaVu fonts rather than the default San Serif. (Look at the Style|Base section with JaspersoftStudio in any standard report to see how this is done.)

***End 1.9.1 update ***

The reports and documents in the release package have all been developed in a Windows system, and thus in general you do not have to worry about fonts. The Sans Serif font set in all the standard reports and documents will map to Arial.

NOTE: the following discussion applies ONLY to reports and documents that use jrxml content. For Forms and Letters that use Open Office odt (and Microsoft Word .doc) based content, you can happily use any font installed on the system.

However, if you do want to use another font (for example if you need to support Chinese characters when printing drug labels) then you need to understand that the fonts available to Jaspersoft Studio that you can choose from when creating or editing jrxml content are NOT necessarily available to OpenVPMS when it is generating the report/document. This is because when generating the jrxml based report/document, OpenVPMS only has access to a) the fonts mapped by <JAVA-HOME>\lib\fontconfig.properties; and b) those held in jar files in the <TOMCAT-HOME>\lib folder.

Hence if you need a non-standard font you will need to create a jar file containing it and place this in <TOMCAT-HOME>\lib.

To do this, first using Windows Explorer, copy the fonts you want to a new folder, say c:\temp\fonts - in the following I copied Comic Sans MS (which includes 4 files) and Arial Unicode MS Regular and you should have:  

Now start JasperSoft Studio and use Window|Preferences|Jaspersoft Studio|Fonts to get:

Click the 'Add From Path' button and specify the folder in which you saved the fonts, then click Finish to get:

Now click on both the fonts to select them and then press the Export button. Specify the file name you want (say MyOpenVPMSfonts) and press Save. You can then Cancel the above window to dismiss it.

In your c:\temp\fonts folder there will now be MyOpenVPMSfonts.jar which you can copy to <TOMCAT-HOME>\lib  (eg C:\Program Files\Apache Software Foundation\Tomcat 7.0\lib). After you restart Tomcat, your new fonts will be used when you generate reports and documents that use them.

New Installation

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:

• Directory structure
• MySQL connector
• Database setup
• Document Templates
• Web application installation
• OpenOffice installation
• Testing the installation
• Optional steps
  • Security roles
  • VeNom codes
  • Australian states and suburbs

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>/bin
  > dbtool --create install -u admin -p apasswd

NOTES:

• replace 'admin' with a user that has administrator privileges in MySQL and 'apasswd' with their password
• the --create install option creates a user 'openvpms' with password 'openvpms' that only has privileges to connect from localhost.
• If the MySQL database is a different host to that running Tomcat, then you will need to:
  1. Edit the <OPENVPMS_HOME>/conf/hibernate.properties file to replace 'localhost' in the line

     hibernate.connection.url=jdbc:mysql://localhost:3306/openvpms
     by the IP address or host name of the database server.
     This MUST be done before running dbtool.

  2. After running dbtool, use the mysql utility to grant access using the command:

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

To improve security, the '%' should be replaced with the host that Tomcat will connect from.

Next, run the 'archload' script to load archetypes:

  > cd <OPENVPMS_HOME>/bin
  > archload

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

Document and Report Templates

The templates used for document (ie invoices, payments etc.) and reports, are located in:
      <OPENVPMS_HOME>/reports

These need to be loaded prior to use. This can be done using the 'templateload' script. If you invoke this with no arguments you will get the following:

Loads OpenVPMS document and report templates

usage: templateload [type size]|[file]
   type - the template type. One of: documents, reports
   size - the page size. One of: A4, A5, Letter
   file - templates.xml file path

NOTE: existing templates with the same name and content file name will be replaced

E.g.:
   templateload documents A4
   templateload reports Letter
   templateload c:\myreports\my-custom-A4.xml

As indicated the templates are grouped by type and paper size. For new installations, you MUST load both the reports and the documents. However, when upgrading, if you have your own customised version of invoices etc, it may be beneficial to load all the reports but a restricted subset of the documents - see here for more information.

For new installations you need to do:

  > cd <OPENVPMS_HOME>/bin
  > templateload reports RS
  > templateload documents DS

Where RS is the paper size for the reports and must be either A4 or Letter (ie US)
and DS is the paper size for the documents and must be one or A4, A5 or Letter

NOTES:

• If a template with the same name has been already loaded, it will be replaced. More precisely, templates with the same ORIGINAL 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. However, a template named Invoice with content Invoice.jrxml which has been renamed to 'My Invoice' will be overwritten with the original name and new content.
• Not all templates are available in all formats, however a complete set is loaded. Thus if you load the A5 document set you will find that a few templates are in A4 format.
• If you plan to use A5 for only a restricted set of documents (eg only invoices and receipts) then you should load the A4 set, and then update the content of those templates that you want to use A5 stationary. See here.
• Three drug label sizes are available, Diskette, Shipping, and Video Top. All the document template sets (A4, A5, Letter) load the Diskette sized label. If you need one of the others, then you can load it from <OPENVPMS-HOME>\reports\Patient\Labels\Shipping or ...\Video Top.  These folders contain a readme.txt file specifying  the label dimensions.
• 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.

Templates may be customised if necessary - those that have content with a:

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

Customising of the .odt template content will be required to:

1. change the paper size from A4 to Letter if you loaded the Letter template set
2. insert your logo etc

Customising of the .jrxml template content is not generally required - the localisation is done using the Letterhead facility.

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

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.

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
• VeNom codes
• Australian states and suburb

Note that having loaded these (as with any external changes to the database) you should restart Tomcat to ensure that its caches do not hold obsolete information.

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 codes

The VeNom codes are standardised codes for classifying veterinary data. OpenVPMS can use VeNom:

• presenting complaint and diagnosis codes to classify patient Problems.
• visit reason codes for Appointments and Visits.

VeNom codes can all be loaded using:

> cd <OPENVPMS_HOME>/bin
> dataload -d ../import/data/VeNom

To load specific codes, see below.

Loading VeNom presenting complaints

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

Loading VeNom diagnoses

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

Loading VeNom visit reasons

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

Australian states and suburbs

These can be loaded using:

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

 

Requirements

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, 8 or 10; for larger practices it may be better to use a Windows Server operating system.

*NOTE: OpenVPMS requires MySQL 5.5, which is included in Ubuntu 14.04. Later releases include MySQL 5.6 or MySQL 5.7 which are only supported via configuration changes.

32 or 64 bit version? Both Java and MySQL are available in 32 and 64 bit versions. For larger systems (where you will want to run MySQL and Tomcat with large memory allocations) you should use the 64 bit versions. Otherwise the 32 bit versions are adequate.

Server Software

• Java Platform, Standard Edition 8
  The Java Runtime Environment (JRE) is the minimum requirement. That is, neither the SDK or Server JRE packages are needed.
  See http://www.oracle.com/technetwork/java/javase/downloads/index.html
   
• Tomcat 8.x
  See https://tomcat.apache.org/download-80.cgi
  On Windows, select the 32-bit/64-bit Windows Service Installer
  • Tomcat minimum 1024M of memory.  Recommended 2048M.
• MySQL
  MySQL 5.5 is supported natively. MySQL 5.7 may be used with configuration changes.
   
  • MySQL 5.5
    See http://dev.mysql.com/downloads/mysql/5.5.html#downloads

    Download the MySQL Community Server 'Generally Available (GA) Release'.
     

  • MySQL 5.7
    See https://dev.mysql.com/downloads/mysql/5.7.html#downloads
    Download the MySQL Community Server 'Generally Available (GA) Release'.

    The sql_mode must be changed to remove ONLY_FULL_GROUP_BY. This is done by configuring the server options file, or via MySQL Workbench.

On Windows, the MySQL installer may require that the Microsoft .Net Framework 4 be installed. This is available from:
http://www.microsoft.com/en-au/download/details.aspx?id=17851
 

NOTE: if you are upgrading from an earlier MySQL release, see the relevant MySQL manual for migrating the MySQL data e.g.:

• MySQL 5.5 Reference Manual - Updating MySQL

• MySQL 5.7 Reference Manual - Updating MySQL
   

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
  character-set-server = utf8
• Minimum Innodb buffer size set to 512M.  

NOTE: If character-set-server is not set to utf8, some characters may not be stored correctly. E.g, μ may be replaced with ?

• MySQL Connector/J JDBC driver
  See http://dev.mysql.com/downloads/connector/j/5.1.html

    This may be included in the MySQL server installation.

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

  NOTE: several users have indicated that LibreOffice 5 is not 100% compatible with OpenOffice. Fields may not merge correctly, and documents created in LibreOffice may look different when printed via OpenVPMS.
   

• Locale and Fonts
  For unix systems see Unix Locale and Fonts
  For windows systems see Windows Locale and Fonts

Workstation Software

If you wish to use the External Edit facility then the following software is required on all workstations that will edit documents in OpenVPMS:

• Java Platform, Standard Edition 8
  The Java Runtime Environment (JRE) is the minimum requirement. That is, neither the SDK or Server JRE packages are needed.
  See http://www.oracle.com/technetwork/java/javase/downloads/index.html
   
• OpenOffice 4.1.2 or higher

See http://www.openoffice.org/download/

Optional Software

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

   

• MySQL Workbench
  This is not required by OpenVPMS itself, but if you are going to do any report development, then you will find that the Workbench’s ability to build and test SQL queries is very useful. You can download it from http://dev.mysql.com/downloads/workbench.
   

Security

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

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

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

The headings below are:

• Release Notes
• Requirements
• Preparation
• Directories
• MySQL connector
• Database migration
• Load archetypes
• Web application
• Customisation
• HL7
• Document Templates
• Kettle

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

Release Notes

Release Notes are provided for sub-releases (eg 1.8.1, 1.9.1 etc). If you are upgrading to a sub-release then you should consult the release notes on the download page at http://www.openvpms.org/download

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-2.0

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

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

 

MySQL connector

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

Database migration

Migrating from 1.9 or later

If you are upgrading from OpenVPMS 1.9 or a later release, then database migration is accomplished using the dbtool utility. Run the following in a shell prompt

  > cd <OPENVPMS_HOME>/bin
  > dbtool --update

Migrating from 1.8 or earlier

Upgrading from a version of OpenVPMS earlier than 1.9 requires that data migration scripts first be run to bring the database up to 1.9, and then you can use the dbtool utility as above. 

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
     migrate-1.8-to-1.9.sql

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

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

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

If you are upgrading from OpenVPMS 1.5 or 1.6, run:
I    > mysql -u openvpms -p openvpms < migrate-1.6-to-1.7.sql
     > mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql
     > mysql -u openvpms -p openvpms < migrate-1.8-to-1.9.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
     > mysql -u openvpms -p openvpms < migrate-1.8-to-1.9.sql

Migration Notes

1. The mysql command will prompt for a password. You can enter the password by including it directly following the '-p' - so if the password is say 'Opv1234' then you can use:
     > mysql -u openvpms -pOpv1234 openvpms < migrate-1.8-to-1.9.sql
2. If you want re-assurance that something is happening you can add the -v (verbose) option, ie:
     > mysql -v -u openvpms -pOpv1234 openvpms < migrate-1.8-to-1.9.sql
   If you want all the details, use -v -v -v, ie:
     > mysql -v -v -v -u openvpms -pOpv1234 openvpms < migrate-1.8-to-1.9.sql
3. If you are 're-migrating', i.e. you have an existing database that you are restoring a backup into, see Upgrade to a new machine for instructions to recreate and restore the database. This is necessary to avoid data corruption.

NOTE: With a large database, the 1.8 to 1.9 migration takes some time and using the -v or -v -v -v option is useful to re-assure yourself that something is happening.

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.

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.

HL7

Sites using HL7 in OpenVPMS 1.8 need to manually edit their HL7 Connectors to include a mapping. A mapping for Cubex is provided.

Document & Report Templates

To take advantage of the new and revised templates, they need to be loaded.

Templates are divided into two types:
•    document templates - Invoices, Receipts etc
•    report templates -  reports run from Reporting - Reports

It is strongly recommended that all sites run the latest versions of the standard reports.

If a site is using:

• standard document and report templates, then the latest versions can be loaded as per a new installation. This will replace existing templates, and add any new templates.
• custom document or report templates, then templates can be selectively loaded to avoid replacing customised ones

After loading, obsolete templates may need to be manually removed.

Selectively loading templates

Templates can be selectively loaded:

1. by type
2. by creating a templates file that only loads the desired files
3. manually, by editing the appropriate Document Template (via Administration|Templates|Document Templates), and uploading the appropriate content file from <OPENVPMS_HOME>/reports

Loading templates by type

Document and report templates can be loaded separately. This can be useful if a site has customised one and not the other.

Document templates can be loaded using:
  > cd <OPENVPMS_HOME>/bin
  > templateload documents SIZE
where size is one of A4, A5, or Letter.

Report templates can be loaded using:
  > cd <OPENVPMS_HOME>/bin
  > templateload reports SIZE
where size is one of A4, or Letter.

In both cases, these will:

 

• replace existing Document Templates with the same Content name
• create new Document Templates where there is no existing template E.g. an existing Document Template named:

1. My Invoice with Content named Invoice.jrxml will be replaced by the standard Invoice with Content named Invoice.jrxml
2. Invoice with Content named Custom Invoice.jrxml, will not be replaced.The standard Invoice with Content named Invoice.jrxml will be loaded, and one must be manually deleted using Administration|Templates|Document Templates|Delete.

Creating a templates file to load specific templates

To create a templates file that loads only the desired files, copy an existing templates xml file, and remove the lines that do not apply.

This will prevent standard templates replacing existing custom templates.
E.g., to exclude loading A4 invoices:

1. copy <OPENVPMS_HOME>/reports/documents-A4.xml to mydocuments.xml
2. remove or comment out the lines for the invoice templates that have been customised. (To aid this process you will find that the templates are grouped by sub-type in the xml file.) To comment them out, enclose the appropriate template lines by <!-- and --> - for example:

    <!--
    <template name="Invoice" archetype="act.customerAccountChargesInvoice" reportType="CUSTOMER"
              description="Invoice " path="Customer/Invoice/A5/Invoice.jrxml" mimeType="text/xml"
              docType="document.other"/>
    <template name="Invoice Items" archetype="SUBREPORT" reportType="CUSTOMER" description="Invoice Items "
              path="Customer/Invoice/A5/Invoice Items.jrxml" mimeType="text/xml" docType="document.other"/>
    -->

  3. load the templates

        cd <OPENVPMS_HOME>/bin
        templateload ../reports/mydocuments.xml

Restart Tomcat after running templateload to ensure that its caches do not contain obsolete information.

See also Obsolete Document Templates.

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

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).

You can then follow the New Installation steps until you get to the Database Setup step.

Then, to create the OpenVPMS MySQL database, run the following in a shell prompt
  > cd <OPENVPMS_HOME>/bin
  > dbtool --create restore -u admin -p apasswd

NOTES:

• replace 'admin' with a user that has administrator privileges in MySQL and 'apasswd' with their password
• the --create restore option creates a user 'openvpms' with password 'openvpms' that only has privileges to connect from localhost.
• If the MySQL database is a different host to that running Tomcat, then you will need to:
  1. Edit the <OPENVPMS_HOME>/conf/hibernate.properties file to replace 'localhost' in the line

     hibernate.connection.url=jdbc:mysql://localhost:3306/openvpms
     by the IP address or host name of the database server.
     This MUST be done before running dbtool.

  2. After running dbtool, use the mysql utility to grant access using the command:

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.

 

Having created the database, you can now 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. Note that if you are migrating from 1.9 or earlier, this describes the necessary database migration steps.

Dropping the database

If the database to restore a backup to already exists, it should be dropped first.

> mysql -u admin -p
> drop schema openvpms;
    Query OK, 46 rows affected (1.04 sec)
> quit