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

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

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

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

If you are upgrading from 1.9 to 2.0, 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 to 2.0

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, i.e.:
      > mysql -v -u openvpms -pOpv1234 openvpms < migrate-1.8-to-1.9.sql
    If you want all the details, use -v -v -v, i.e.:
      > 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 OpenVPMS 2.0 system that you are restoring a 1.9 database 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.

Obsolete Document Templates

Complete

Some document templates have been either renamed, had their content name changed, or are no longer used.

Changes from 1.9 to 2.0

If you have upgraded from 1.9 and you have used the templateload utility to load the 2.0 template set, then no action is required as no templates became obsolete.

Changes from 1.8 to 1.9

If you have upgraded from 1.8 and you have used the templateload utility to load the 1.9 template set, then the following templates can be deleted as they are no longer used:

Name Content
Counter Sale Items Counter Sale Items.jrxml
Credit Items Credit Items.jrxml
Debtors - Current - SubReport2 Debtors - Current - SubReport2.jrxml
Supplier Credit Items Supplier Credit Items.jrxml
Pharmacy Return Items Pharmacy Return Items.jrxml
Refund Items Refund Items.jrxml

Changes from 1.7 to 1.8

If you have upgraded from 1.7 and you used the templateload utility to load the 1.8 or 1.9 template set, then, unless you have manually deleted them, you will have obsolete 1.7 document templates in your system. The table below lists those templates that can be deleted.

NOTE:

  1. If you have customised versions of some templates and when customising them you did NOT change the content name (eg your Invoice template still uses content named "invoice A4.jrxml") then obviously you should not delete the template.
  2. The list below includes both the A5 and A4 template sets, and if you loaded the A4 set, then you will not have the A5 versions of some templates (eg, Counter Sale, Credit, Invoice, etc), and vice versa if you loaded the A5 set.


Name Content
Appointment Appointment A5.jrxml
Bank Deposit Bank Deposit A4.jrxml
Counter Sale countersale a4.jrxml
Counter Sale countersale a5.jrxml
Counter Sale Items countersaleItems.jrxml
Counter Sale Items countersaleItemsA5.jrxml
Credit credit a4.jrxml
Credit credit a5.jrxml
Credit Adjustment Credit Adjustment A5.jrxml
Credit Items creditItems.jrxml
Credit Items creditItemsA5.jrxml
Customer Account Balance Report customerAccountBalance.jrxml
Debit Adjustment Debit Adjustment A5.jrxml
Desexing Certificate desexing certificate a4.odt
Desexing Certificate desexing certificate a5.odt
Drug Label label Dymo.jrxml
Estimate Estimate A4.jrxml
Estimate Estimate A5.jrxml
Estimate Items Estimate Items A4.jrxml
Estimate Items Estimate Items A5.jrxml
Grouped Reminders Report grouped reminders a4.jrxml
Invoice invoice a4.jrxml
Invoice invoice a5.jrxml
Invoice Items invoiceitems.jrxml
Invoice Items invoiceitemsa5.jrxml
Invoice Reminders invoiceRemindersA4.jrxml
Invoice Reminders invoiceRemindersA5.jrxml
Message message a4.jrxml
Order Items orderItems.jrxml
Patient Clinical Event patientClinicalEvent a4.jrxml
Patient Clinical Event patientClinicalEvent a5.jrxml
Patient Image patientDocumentImage.jrxml
Patient Reminders Report patientReminders.jrxml
Receipt receipt a4.jrxml
Receipt receipt a5.jrxml
Receipt Items receiptItems.jrxml
Receipt Items receiptItemsA5.jrxml
Refund Refund A5.jrxml
Refund Items Refund Items A5.jrxml
Reminder Cartrophen First cartrophen first reminder.odt
Reminder Desexing First desex first reminder.odt
Reminder Vaccination First vaccination first reminder.odt
Reminder Vaccination Puppy and Kitten First vaccination puppy kitten first reminder.odt
Reminder Vaccination Second vaccination second reminder.odt
Statement statement A4.jrxml
Statement statement A5.jrxml
Statement Items statementItems A5.jrxml
Statement Items statementItems.jrxml
Stock Adjustment Stock Adjustment A4.jrxml
Stock Adjustment Items Stock Adjustment Items A4.jrxml
Stock Take List Report stock take list.jrxml
Stock Transfer Stock Transfer A4.jrxml
Stock Transfer Items Stock Transfer Items A4.jrxml
Supplier Credit Supplier Credit A5.jrxml
Supplier Credit Items Supplier Credit Items A5.jrxml
Supplier Invoice Supplier Invoice A5.jrxml
Supplier Invoice Items Supplier Invoice Items A5.jrxml
Supplier Refund Supplier Refund A5.jrxml
Supplier Refund Items Supplier Refund Items A5.jrxml
Supplier Remittance Supplier Remittance A5.jrxml
Supplier Remittance Items Supplier Remittance Items A5.jrxml
Task Task A5.jrxml
Till Balance TillBalance.jrxml
Vaccination Certificate vaccination certificate a4.odt
Vaccination Certificate vaccination certificate a5.odt
Work In Progress Report workInProgress.jrxml