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:

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