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 Manage users plugin Manage 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 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 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: 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/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.
Configure Default
Configure openvpms.properties using default values, without prompting.
This assumes MySQL is running on localhost and listening on port 3306.
E.g.:
> toolbox configure --default 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.
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
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>
Update
Updates the database to the latest version.
This:
- 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
E.g:
> 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. See https://openvpms.org/documentation/csh/2.3/topics/installing-openvpms/up... 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 2.2.0.9 - OVPMS-2462 ... 00:00.005s Updating to 2.2.0.10 - OBF-275 ... 00:00.139s Updating to 2.2.0.11 - OVPMS-2468 ... 00:00.005s Updating to 2.2.0.12 - OVPMS-2505 ... 00:00.001s Updating to 2.2.0.13 - OBF-279 ... 00:00.010s Updating to 2.2.0.14 - OBF 279 ... 00:00.013s Updating to 2.2.0.15 - OVPMS-2538 ... 00:00.022s Updating to 2.2.0.16 - OVPMS-2541 ... 00:00.009s Updating to 2.2.0.17 - OVPMS-2525 ... 00:00.024s Running ArchetypeLoader ... 00:12.565s Running PluginLoader ... 00:00.024s Database 'openvpms_dev' updated from version 2.2.0.8 to 2.2.0.17 in 00:00:13.983
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.
List
Lists users.
E.g.:
> toolbox user --list
id username name active roles
--------------------------------------------------------------------------------
1153 admin Admin true Administration
1155 vet Vet true Base Role, ClinicianSet 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.
Add Role
Adds one or more roles to a user.
E.g.:
> toolbox user --add-role avet Clinician Administration User updated
Remove Role
Removes one or more roles from a user.
E.g.:
> toolbox user --remove-role avet Administration User updated
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.
List
List plugins. This displays the keys of user-installed plugins.
> toolbox plugin --list org.openvpms.openvpms-clickatell-plugin
Install
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
Uninstall
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.
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%)
