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             Manage users
  plugin           Manage 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 a password for the database user
  • generates openvpms.key, if not present
    This is used to encrypt and decrypt 3rd-party passwords.
  • creates or updates the configuration file in <OPENVPMS_HOME>/conf


> toolbox configure

Database URL [jdbc:mysql://localhost:3306/openvpms?useSSL=false]:
Database user [openvpms]:
Database password: v3@20XlIl.2R=
Reporting database URL [jdbc:mysql://localhost:3306/openvpms?useSSL=false]:
Reporting database user [openvpms]:
Reporting database password [v3@20XlIl.2R=]:

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.


Configure Default

Configure using default values, without prompting.
This assumes MySQL is running on localhost and listening on port 3306.


> toolbox configure --default

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.



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

MySQL, Tomcat on the same host

When MySQL and Tomcat are on the same hosts, the command just needs the MySQL administrator user name and password. For security, the password will be prompted for if it is not specified on the command line. E.g.:

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

Created openvpms
Archetypes successfully loaded

MySQL, Tomcat on different hosts

When MySQL and Tomcat are on different hosts, the --host argument needs to be supplied to indicate the host the user will be connecting from. This should be the host running Tomcat. This argument must conform to the host_name supported by MySQL.

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


Updates the database to the latest version.


  • performs database migration
  • loads updated archetypes
  • loads updated plugins
    • Only those plugins that have been installed previously will be loaded
    • Plugins must include an Atlassian-Plugin-Key in MANIFEST.MF for this to be successful


> toolbox database --update

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

WARNING: Updating the database can take a long time.
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
Updating to - OVPMS-2462 ... 00:00.005s
Updating to - OBF-275 ... 00:00.139s
Updating to - OVPMS-2468 ... 00:00.005s
Updating to - OVPMS-2505 ... 00:00.001s
Updating to - OBF-279 ... 00:00.010s
Updating to - OBF 279 ... 00:00.013s
Updating to - OVPMS-2538 ... 00:00.022s
Updating to - OVPMS-2541 ... 00:00.009s
Updating to - OVPMS-2525 ... 00:00.024s
Running ArchetypeLoader ... 00:12.565s
Running PluginLoader ... 00:00.024s
Database 'openvpms_dev' updated from version to in 00:00:13.983


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.



Lists users.


> toolbox user --list
        id username         name                     active roles
      1153 admin            Admin                    true   Administration
      1155 vet              Vet                      true   Base Role, Clinician

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.

Add Role

Adds one or more roles to a user.


> toolbox user --add-role avet Clinician Administration
User updated

Remove Role

Removes one or more roles from a user.


> toolbox user --remove-role avet Administration
User updated



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.


List plugins. This displays the keys of user-installed plugins.

> toolbox plugin --list


Installs a plugin. If OpenVPMS is already running, click the Refresh button in Administration - System - Plugins to deploy it.

> toolbox plugin --install ../plugins/openvpms-deputy-plugin-2.3.jar
Installed plugin with key org.openvpms.openvpms-deputy-plugin


Uninstalls a plugin. The plugin is not undeployed until OpenVPMS is restarted.

> toolbox plugin --uninstall org.openvpms.openvpms-clickatell-plugin
Plugin removed. 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