Toolbox

Complete

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]
Commands:
  configure        Configure openvpms.properties
  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:

Configure

Configure openvpms.properties.

This:

  • 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 openvpms.properties configuration file in <OPENVPMS_HOME>/conf

E.g.:

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

Database

Create
 

Create the database.

This:

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

E.g:

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

Created openvpms
Archetypes successfully loaded

Update

Updates the database to the latest version.

E.g:

> toolbox database --update
Has the database been backed up? [Y/n] Y
Updating to 2.1.0.6 - OVPMS-2223 ... 00:00.077s
Updating to 2.1.0.7 - OBF-257 ... 00:00.015s
Updating to 2.1.0.8 - OBF-258 ... 00:00.004s
Updating to 2.1.0.9 - OVPMS-2082 ... 00:00.084s
Updating to 2.1.0.10 - OVPMS 2233 ... 00:00.025s
Updating to 2.1.0.11 - OVPMS-428 ... 00:00.085s
Updating to 2.1.0.12 - OVPMS 428 ... 00:00.836s
Updating to 2.1.0.13 - OVPMS-2241 ... 00:02.175s
Updating to 2.1.0.14 - OVPMS-2194 ... 00:00.007s
Updating to 2.1.0.15 - OBF-266 ... 00:00.073s
Updating to 2.1.0.16 - OBF-264 ... 00:00.032s
Updating to 2.1.0.17 - OVPMS-2292 ... 00:00.003s
Updating to 2.1.0.18 - OVPMS-2048 ... 00:00.004s
Updating to 2.1.0.19 - OVPMS-2346 ... 00:00.006s
Updating to 2.1.0.20 - OBF-269 ... 00:00.004s
Updating to 2.1.0.21 - OVPMS-2354 ... 00:00.004s
Database 'openvpms' updated from version 2.1.0.5 to 2.1.0.21 in 00:00:05.108

Version

Displays the database version.
E.g.:

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

Info

Displays database migration information.

E.g.

> toolbox database --info
+----------+-------------+---------------------+---------+
| Version  | Description | Installed on        | State   |
+----------+-------------+---------------------+---------+
| 2.0.0.1  | OVPMS-2045  |                     | <Baseln |
| 2.0.0.2  | OVPMS-2114  | 2019-07-25 14:18:45 | Success |
| 2.0.0.3  | OVPMS-2121  | 2019-07-25 14:18:45 | Success |
| 2.0.0.4  | OVPMS-2128  | 2019-07-25 14:18:45 | Success |
| 2.0.0.5  | OVPMS-2134  | 2019-07-25 14:18:45 | Success |
| 2.0.0.6  | OVPMS-2151  | 2019-07-25 14:18:45 | Success |
| 2.1.0.1  | OVPMS-2159  |                     | Pending |
| 2.1.0.2  | OVPMS-2188  |                     | Pending |
+----------+-------------+---------------------+---------+

The above indicates that:

  • the first database version to be installed was 2.0.0.1.
  • 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.

Archetype

Load

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

E.g.:

> toolbox archetype --load

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

List

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

 

Diff

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

War

Create the web archive.

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

E.g.:

> 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

Template

Load

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.

E.g.:

> 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

A4

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

A5

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

US-Letter

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

Load all document templates

A4

> toolbox template --load documents --size A4

A5

> toolbox template --load documents --size A5

US-Letter

> toolbox template --load documents --size Letter

Load all report templates

A4

> toolbox template --load reports --size A4

US-Letter

> toolbox template --load reports --size Letter

Load individual templates

A4

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

A5

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

US-Letter

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

User

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.

E.g.:

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.

Enable

Enables the specified user.

E.g.:

> toolbox user --enable vet
User enabled

Disable

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.

Plugin

Enable

Enable plugins. E.g.:

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

Disable

Disable plugins. E.g.:

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

SSL

Check

 Check SSL connectivity.

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

E.g.:

> toolbox ssl --check smtp.gmail.com 465
Connecting to smtp.gmail.com port 465
Successfully connected

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

> toolbox ssl --check smtp.gmail.com 465 -n 5
Connecting to smtp.gmail.com 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%)