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
- Adding users
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
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 |
---|---|
archetypes | archetype definitions |
bin | tools used to configure and load data into OpenVPMS |
conf | configuration files for the tools in ../bin |
import | data to import into OpenVPMS |
legacy-migration | scripts used to migrate from releases prior to OpenVPMS 1.9. |
lib | jars used by the tools in ../bin |
reports | document templates for reporting |
plugins | plugin support |
webapps | the OpenVPMS web applications |
NOTE: the OpenVPMS installation directory should be secured to prevent unauthorised user access.
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 toolbox configure to configure the database connection properties
- run toolbox database --create to create the database
- run dataload to import data into the database
1. Run 'toolbox configure'
The toolbox configure command:
- is run from the <OPENVPMS_HOME>/bin directory
- prompts for database connection properties:
- If there is a default value, it will be surround by square brackets.
- To keep the default value, press enter.
- updates the openvpms.properties configuration file in <OPENVPMS_HOME>/conf
E.g.:
> cd <OPENVPMS_HOME>/bin > toolbox configure Database URL [jdbc:mysql://localhost:3306/openvpms?useSSL=false]: Database user [openvpms]: Database password: apasswd Reporting database URL [jdbc:mysql://localhost:3306/openvpms?useSSL=false]: Reporting database user [openvpms]: Reporting database password [apasswd]: The file ../conf/openvpms.properties should have restrictive permissions to protect passwords Take a secure backup of the file ../conf/openvpms.properties This needs to be kept for subsequent updates.
If the MySQL database is on a different host to that running Tomcat, replace localhost in the Database URL with the correct host name or IP address.
2. Run 'toolbox database --create'
The toolbox database --create command:
- is run from the <OPENVPMS_HOME>/bin directory
- creates the database corresponding to the Database URL specified
- creates the user corresponding to the Database user and password specified
- loads archetypes
> cd <OPENVPMS_HOME>/bin > toolbox database --create -u <admin-user> -p <admin-password> Created openvpms Archetypes successfully loaded
NOTES:
- replace <admin-user> with a user that has administrator privileges in MySQL and <admin-password> with their password
- If the MySQL database is a different host to that running Tomcat,use the mysql utility to grant access using the command:
GRANT ALL PRIVILEGES ON <database-name>.* TO '<user-name>'@'%' IDENTIFIED BY '<user-password>' WITH GRANT OPTION;
Replace <database-name>, <user-name> and <user-password> with the corresponding values entered during toolbox configure.
To improve security, the '%' should be replaced with the host that Tomcat will connect from.
3. Run dataload
The dataload command provides two options:
- base - loads a base database in preparation for data migration
- setup - contains a default setup suitable for a new installation
> cd <OPENVPMS_HOME>/bin > dataload setup
4. Set administrator password
The dataload command creates a default administration user named admin with password admin.
This should be secured by providing a new password e.g.:
> cd <OPENVPMS_HOME>/bin > toolbox user --setpassword admin -p somestrongpassword
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 toolbox template --load command.
There are 3 sizes of templates supported: A4, A5 and Letter (i.e. US-Letter).
To load all A4 templates:
> cd <OPENVPMS_HOME>/bin > toolbox template --load --size A4 --all Loaded 'Counter Sale' Loaded 'Credit' Loaded 'Credit Adjustment' Loaded 'Debit Adjustment' Loaded 'Estimate' Loaded 'Estimate Items' Loaded 'Estimate Items-PT' Loaded 'Invoice' Loaded 'Invoice Items' Loaded 'Invoice Items-P ... Loaded 'Stock Movement Report' Loaded 'Stock Reorder Report' Loaded 'Stock Valuation Report' Loaded 'Stocktake Export Report' Loaded 'Stocktake List Report' Loaded 'HL7 Messages Report' Loaded 'Insurance Claims Report'
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:
- change the paper size from A4 to Letter if you loaded the Letter template set
- 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:
- Generate the web archive (war) using:
> cd <OPENVPMS_HOME>/bin > ./toolbox war Created ../webapps/openvpms.war The file ../webapps/openvpms.war should have restrictive permissions to protect passwords
- Copy <OPENVPMS_HOME>/webapps/openvpms.war to the <TOMCAT_HOME>/webapps directory.
- 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:
- 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.
- 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 a web browser and enter the address:
http://localhost:8080/openvpms/login
Login to OpenVPMS using user admin and the password set above.
Optional steps
OpenVPMS ships with optional data that can be loaded as required. This includes:
- VeNom codes
- Australian states and suburbs
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.
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
Adding users
The installation includes a single administrator user named 'admin' that has authorities to perform all operations.
New users can be added in the web application at Administration - Users by clicking the New button.
Users have categories and roles that determine what they can do.
E.g., clinicians should be assigned:
- the Clinician category
- the Clinician, Insurance Claims and Base Role roles
See Concepts - Users for more details.