Toolbox
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.
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%)
