Upgrade an existing system

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

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

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

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

Notes:

  1. 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.
  2. The above 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
  3. If you want to 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

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.

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.

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

Hence there are two situations:

  1. Your customised versions have the standard content names:
    Then loading the new set will overwrite your customised versions
     
  2. Your customised versions have different content names:
    Then loading the new set will not overwrite your customised versions.  However, you will be left with duplicate template names - ie two templates named Invoice, each with different contents.

In both cases, 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.

There is also the other case where you have your own customised version of a system document (eg the invoice) with a different name and/or content name. Here there are also two situations:

  1. You want to keep your customised version. In this case you need to edit the templateload xml file to delete the lines for the template(s) that you do not want loaded.
  2. You want to replace your customised version. In this case, you can load the new one, but then you will need to delete the old customised one using Administration|Templates|Document Templates|Delete.

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.

Syndicate content