Toolbox is a command line tool for performing administrative functions in OpenVPMS.

It is invoked using the toolbox command in the <OPENVPMS_HOME>/bin directory. e.g.:

> cd <OPENVPMS_HOME>/bin
> toolbox
Usage: toolbox [COMMAND]
  configure        Configure
  database         Create or update the database
  archetype        Load or compare archetypes
  war              Create the web archive
  template         Load report templates
  user             Set passwords, enable/disable users
  plugin           Enable/disable plugins
  ssl              Check SSL connectivity

The options are as follows:




  • prompts for database connection properties:
    • If there is a default value, it will be surrounded by square brackets.
    • To keep the default value, press enter.
  • generates openvpms.key, if not present
    This is used to encrypt and decrypt 3rd-party passwords.
  • updates the configuration file in <OPENVPMS_HOME>/conf


> 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/ should have restrictive permissions to protect passwords

Take a secure backup of the file ../conf/
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.



Create the database.


  • creates the database specified by db.url in the <OPENVPMS_HOME>/conf/ file
  • creates the user corresponding to the db.username and db.password
  • loads archetypes


> toolbox database --create -u <admin-user> -p <admin-password>

Created openvpms
Archetypes successfully loaded


Updates the database to the latest version.


> toolbox database --update
Has the database been backed up? [Y/n] Y
Updating to - OVPMS-2223 ... 00:00.077s
Updating to - OBF-257 ... 00:00.015s
Updating to - OBF-258 ... 00:00.004s
Updating to - OVPMS-2082 ... 00:00.084s
Updating to - OVPMS 2233 ... 00:00.025s
Updating to - OVPMS-428 ... 00:00.085s
Updating to - OVPMS 428 ... 00:00.836s
Updating to - OVPMS-2241 ... 00:02.175s
Updating to - OVPMS-2194 ... 00:00.007s
Updating to - OBF-266 ... 00:00.073s
Updating to - OBF-264 ... 00:00.032s
Updating to - OVPMS-2292 ... 00:00.003s
Updating to - OVPMS-2048 ... 00:00.004s
Updating to - OVPMS-2346 ... 00:00.006s
Updating to - OBF-269 ... 00:00.004s
Updating to - OVPMS-2354 ... 00:00.004s
Database 'openvpms' updated from version to in 00:00:05.108


Displays the database version.

> toolbox database --version
Database 'openvpms' is at version


Displays database migration information.


> toolbox database --info
| Version  | Description | Installed on        | State   |
|  | OVPMS-2045  |                     | <Baseln |
|  | OVPMS-2114  | 2019-07-25 14:18:45 | Success |
|  | OVPMS-2121  | 2019-07-25 14:18:45 | Success |
|  | OVPMS-2128  | 2019-07-25 14:18:45 | Success |
|  | OVPMS-2134  | 2019-07-25 14:18:45 | Success |
|  | OVPMS-2151  | 2019-07-25 14:18:45 | Success |
|  | OVPMS-2159  |                     | Pending |
|  | OVPMS-2188  |                     | Pending |

The above indicates that:

  • the first database version to be installed was
  • five subsequent migration scripts have been successfully applied.
  • there are two migration scripts that need to be applied to update to the latest OpenVPMS version.

By convention, the Description column refers to the JIRA related to the migration.



The toolbox archetype --load command loads archetypes from the <OPENVPMS_HOME>/archetypes directory.


> toolbox archetype --load

The OpenVPMS web application must be restarted after running this command.


List archetypes.

List archetypes in the database

> toolbox archetype --list

This is the same as running:

> toolbox archetype --list db

List archetypes in a directory

> toolbox archetype --list ../archetypes

By default, this will recurse subdirectories. Recursion can be disabled by specifying --no-recurse

Verbose output

To get more information, add the --verbose flag:

> toolbox archetype --list --verbose
Retrieving archetype descriptors from: database
Found 564 descriptors



Compare archetypes.

Compare a directory with archetypes in the database

> toolbox archetype --diff ../archetypes db

Compare an archetype file with a prior version in the database

> toolbox archetype --diff --verbose db ../archetype/org/openvpms/archetype/contact/contact.location.adl

Compare two directories containing archetypes

> toolbox archetype --diff  2.1/archetypes 2.2/archetypes


Create the web archive.

This generates openvpms.war using the located in <OPENVPMS_HOME>/conf/


> toolbox war

Created ..\webapps\openvpms.war

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

Changing the name

By default, the war will be named openvpms.war. This can be changed using the --name argument. E.g.:

> toolbox war --name demo
Created ..\webapps\demo.war

Logging output will be directed to files based on the specified name. Given the name "demo", logging output will be written to:

  • <TOMCAT_HOME>/logs/demo.log
  • <TOMCAT_HOME>/logs/demo-full.log



Load templates.

Templates are divided into two types:
•    document templates - Invoices, Receipts etc
•    report templates -  reports run from Reporting - Reports

These are located in the <OPENVPMS_HOME>/reports directory.

There are 3 sizes of templates supported: A4, A5 and Letter (i.e. US-Letter).
Reports are only available in A4 and Letter size.


> 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 'Stocktake List Report'
Loaded 'HL7 Messages Report'
Loaded 'Insurance Claims Report'

Load all templates


> toolbox template --load --all --size A4


Reports aren't available in A5 format, so reports must be loaded in A4 or Letter format.

> toolbox template --load documents --size A5
> toolbox template --load reports --size A4


> toolbox template --load --all --size Letter

Load all document templates


> toolbox template --load documents --size A4


> toolbox template --load documents --size A5


> toolbox template --load documents --size Letter

Load all report templates


> toolbox template --load reports --size A4


> toolbox template --load reports --size Letter

Load individual templates


> toolbox template --load 'Invoice' 'Invoice Items' 'Invoice Items-PT' --size A4


> toolbox template --load 'Invoice' 'Invoice Items' 'Invoice Items-PT' --size A5


> toolbox template --load 'Invoice' 'Invoice Items' 'Invoice Items-PT' --size Letter


User operations.

NOTE: changes made using these commands may not be seen immediately in the application, due to caching.
This can be avoided by making changes when Tomcat is not running.

Set Password

Sets the password for the specified user.


toolbox user --setpassword admin -p
Enter value for -p (password):
Password updated

The password can be specified on the command line after the -p option, but for security should be input at the prompt.


Enables the specified user.


> toolbox user --enable vet
User enabled


Disables a user.

This prevents login. E.g.:

> toolbox user --disable vet
User disabled

Note that disabling users that are required for background jobs (i.e. the Practice Service User), can prevent OpenVPMS from starting up.



Enable plugins. E.g.:

> toolbox plugin --enable
Plugins enabled. If OpenVPMS is already running it needs to be restarted.


Disable plugins. E.g.:

> toolbox plugin --disable
Plugins disabled. If OpenVPMS is already running it needs to be restarted.



 Check SSL connectivity.

This can be used to diagnose SSL certificate issues for external services.


> toolbox ssl --check 465
Connecting to port 465
Successfully connected

To run the check multiple times, use the -n argument. E.g.:

> toolbox ssl --check 465 -n 5
Connecting to port 465
1... Successfully connected
2... Successfully connected
3... Successfully connected
4... Successfully connected
5... Successfully connected
5 of 5 calls were successful (100.0%)


Syndicate content