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
• Directories
• Configuration
• Preparation
  • Backup
  • Upgrade Time
  • MySQL connector
  • Disk space
  • Replication
• Database Upgrade
• Web application
• Customisation
• Document Templates

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>/bin
change to:
  <OPENVPMS_HOME>\bin

Release Notes

Release Notes are provided for sub-releases (e.g. 2.2.1, 2.2.2 etc). If you are upgrading to a sub-release then you should consult the release notes on the download page at https://www.openvpms.org/download

Requirements

The software required to run OpenVPMS may change between releases.

Check Requirements to ensure you have the necessary software.

Directories

These instructions assume that:

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

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

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

 

Configuration

Starting with OpenVPMS 2.2, there is an openvpms.properties configuration file located in the <OPENVPMS_HOME>/conf directory.

This contains:

• database connection details
• password decryption information

This is created or updated using:

> cd <OPENVPMS_HOME>/bin
> toolbox configure

 

 

Preparation

Backup

 

Backup be done using the mysqldump tool. e.g.:

> mysqldump -u <admin-user> -p openvpms --result-file openvpms.sql

Replace <admin-user> with a user that has administrator privileges in MySQL.

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.

 

Upgrade Time

Allow time for the database upgrade to take place. On large databases, this may take several hours.

In practices with limited windows for downtime, do a trial upgrade on a different host to estimate how long will be needed to perform the real migration.

The upgrade time may be reduced by making innodb_buffer_pool_size as large as possible for the duration of the upgrade.

MySQL connector

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

Disk Space

Database migration can require as much disk space as the largest table in the database. As a rule of thumb, ensure there is at least as much disk free as the database currently occupies, on the disk where the database resides.

The current database size can be determined by running:

> cd <OPENVPMS_HOME>/bin
> toolbox database --size
openvpms 100.05 GB

Replication

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

Database Upgrade

Upgrading from 1.9 or later

If you are upgrading from OpenVPMS 1.9 or a later release, then database migration is accomplished using the toolbox utility:

> cd <OPENVPMS_HOME>/bin
> toolbox database --update -u <admin-user> -p
Enter value for -p (Database administrator password):

37 changes need to be applied to update the database to the latest release.

WARNING: Updating the database can take a long time.
See https://openvpms.org/documentation/csh/2.4/topics/installing-openvpms/up...
for instructions on:
. backing up the database
. determining disk space requirements
. speeding up the update

DO NOT continue if the database is not backed up.

Proceed with the update? [Y/n] Y

Replace <admin-user> with a user that has administrator privileges in MySQL.

If you are upgrading from OpenVPMS 2.3, two MySQL users are required, a read/write user (default 'openvpms'), and a read-only user (default 'openvpmsreport').
These can be configured by running:

> cd <OPENVPMS_HOME>/bin
> toolbox configure
> toolbox database --setup-users -u <admin-user> -p

Upgrading from 1.8 or earlier

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

The scripts are located in the <OPENVPMS_HOME>/legacy-migration 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 reassure yourself that something is happening.

 

Web application

 

The web application needs to be created with the properties from <OPENVPMS_HOME>/conf/openvpms.properties.

This is done using the toolbox war command i.e.:

> cd <OPENVPMS_HOME>/bin
> toolbox war

Created ../webapps/openvpms.war

The file ../webapps/openvpms.war should have restrictive permissions to protect passwords

 

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 toolbox archetype --load 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 & 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 name
3. by creating a templates file that only loads the desired files
4. 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
  > toolbox template --load --size <size> documents

where size is one of A4, A5, or Letter.

Report templates can be loaded using:

  > cd <OPENVPMS_HOME>/bin
  > toolbox template --load --size <size> reports

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.

Loading templates by name

To load a subset of the available templates, specify them by name e.g.:

 

  > cd <OPENVPMS_HOME>/bin
  > toolbox template --load --size A4 'Invoice' 'Invoice Items' 'Invoice Items-PT'
  Loaded 'Invoice'
  Loaded 'Invoice Items'
  Loaded 'Invoice Items-PT'

 

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
> toolbox template --load --file  ../reports/mydocuments.xml --all

Restart Tomcat after loading templates to ensure that its caches do not contain obsolete information.

See also Obsolete Document Templates.