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.
 

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.

 

List

Lists users.

E.g.:

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

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

 

Syndicate content