Configure Tolven Plugin Framework
From DOC
On-line Installation
In an on-line installation, plugins are downloaded from http://tolven.org/download by default.
If you need to change the plugin Library Repository, edit <config-dir>/plugins.xml file, and change the following property:
<property name="repositoryLibraryURL" value="http://tolven.org/download,file:///#{globalProperty['config.dir']}/repositoryLocal" />
There is no need to edit this property under most circumstances. The first represents the main tolven download site for Tolven plugins, while the second is a local repository, which by default is <config-dir>/repositoryLocal.
Additional libraries can be added to this property separating each with a comma. Multiple repositories will be treated as one large, combined repository from which to draw plugins.
Plugin Properties
The default plugins.xml file is located in the tolven-config directory. It is identical to the file called jboss-legacypostgresql-ldap-plugins.xml located in the <install-dir>/examples/rootPlugins directory. If you are configuring for Oracle, then you should copy the jboss-oracle-ldap-plugins.xml from that directory, rename it plugins.xml and place that in <config-dir> directory before proceeding.
This file is important since it determines which plugins will be downloaded from the Library Repositories, and allows the user to configure plugins. Each plugin named in this XML file may have the optional one <root/> tag. The presence of a <root> tag guarantees that the plugin and all its dependencies will be downloaded. A given plugin can have any number of <property> tags specific to that plugin. The <property> tags can also exist outside of any particular plugin, making them global <property> tags.
The plugins.xml file contains a list of plugins, some of which contain a <root> tag. Those are the ones which will be downloaded under all circumstances if found in the library repository. They are deemed required for the most part. Other plugins may be downloaded if there is a direct or indirect dependency.
Now we will cover the minimum changes required when using a default installation. There are many other properties in the plugins.xml which you may wish to change.
LDAP Configuration
When these properties are changed, it is necessary to run configPhase1 for them to take effect. Only the basic of the LDAP properties are shown below:
<plugin id="org.tolven.config.ldap">
<root />
<property name="ldap.hostname" value="localhost" />
<property name="ldap.port" value="636" />
</plugin>
Database Configuration
When these properties are changed, it is necessary to run configPhase1 for them to take effect. The hostname, port and databaseName can be set here:
PostgreSQL
<plugin id="org.tolven.config.database">
<root />
<property name="database.hostname" value="localhost" />
<property name="database.port" value="5432" />
<property name="database.databaseName" value="postgres" />
<property name="database.user" value="postgres" />
</plugin>
Oracle
Oracle has two possible formats:
<plugin id="org.tolven.config.database"> <root /> <property name="database.hostname" value="localhost" /> <property name="database.port" value="1521" /> <property name="database.databaseName" value="ORCL" /> <property name="database.user" value="tolven" /> </plugin>
or:
<plugin id="org.tolven.config.database"> <root /> <property name="database.user" value="tolven" /> <property name="database.url" value="jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ORCL)))" /> </plugin>
JDBC Driver
The value "your-jdbcDriver.jar" below needs to be the absolute path to the driver suggested by your database installation. The application server also needs this jdbc driver, which in the case of JBoss means placing it in the application server's lib directory (i.e. the full path to server/tolven/lib for tolven-jboss-4.x).
<plugin id="org.tolven.library.jdbcdriver">
<root />
<property name="jdbcDriver" value="your-jdbcDriver.jar" />
</plugin>
You can either use the explicit absolute path or combine both the requirements above by using one of the global properties ending with the name of your jdbc driver, to refer to the driver from the appservers' lib directory e.g.
<plugin id="org.tolven.library.jdbcdriver">
<root />
<property name="jdbcDriver" value="#{globalProperty['appserver.home']}/server/tolven/lib/your-jdbcDriver.jar" />
</plugin>
- If you do not have that jdbc driver, download it and enter an absolute path to it now.
- Copy the jdbc driver to the server/tolven/lib directory of the JBoss server.
Tomcat Configuration
When these properties are changed, it is necessary to run configPhase1 for them to take effect. Only the basic properties of the Tomcat server are shown below....there are many more in the plugins.xml (see org.tolven.config.tomcatserver).
<plugin id="org.tolven.config.tomcatserver">
<root />
<property name="http.port" value="8080" />
<property name="http.address" value="#{globalProperty['webBindAddress']}" />
<property name="http.redirectPort" value="8443" />
<property name="https.port" value="8443" />
<property name="ajp.port" value="8009" />
<property name="ajp.redirectPort" value="8443" />
</plugin>
Note here the use of a plugin property called http.address. The plugin developer indicates that this plugin requires an http.address, so this file could provide it right here as a string literal, but this example shows that since the hostname is more global than just this plugin, the value should be search for in a global property called 'webBindAdress', which would be located in a <property> tag outside any particular plugin.
Note: The default configuration will only work for HTTP requests on localhost. To specify a specific host adapter to listen on, edit your <config-dir>/plugins.xml file:
<property name="webBindAddress" value="X.X.X.X" />
or to listen on all host adapters:
<property name="webBindAddress" value="0.0.0.0" />
Application Server Configuration
When these properties are changed, it is necessary to run configPhase1 for them to take effect. You can configure the application to not require a password on startup, with the disadvantage that the password for startup will be in plain text on the file system. To select this option, set the prompt for password to false:
<plugin id="org.tolven.assembler"> <root /> <property name="promptFor.appserver.password" value="false" /> </plugin>
The previous method for doing this is below, and is now deprecated. You can remove the entire plugin entry from you <config-dir>/plugins.xml in favor of the one above:
<plugin id="org.tolven.config.appserverpasswordpromptoff"> <root /> <property name="promptFor.appserver.password" value="false" /> </plugin>
Global Properties
Three important properties will be mentioned here:
<property name="installation.dir" value="your-installationDir" /> <property name="config.dir" value="your-tolven-configDir" /> <property name="appserver.home" value="your-appserver-homeDir" />
All three of these locations were chosen by the user during installation and configuration up to this point. Those locations must now be entered here.
Note on Windows: You must use forward slashes when specifying directory paths in these Java-based properties files (backslash is taken as an escape character).
Setup Environment Variables
When executing commands in the plugin framework, you may be required to enter the admin Id ("admin" by default), admin password (sysadmin by default) and the location of the configuration directory. The following command will set the admin Id and configuration directory location as environment variables (TOLVEN_USER and TOLVEN_CONFIG_DIR):
Execute the following command in the installation bin directory.
On Windows:
cd <install-dir>\bin tpfenv
On Linux (please note the extra dot followed by a space):
cd <install-dir>/bin . ./tpfenv.sh
The script is quite straight forward, and although it is not recommended for security reasons due to password visibility, the password can also be set using TOLVEN_PASSWORD. Please note that TOLVEN_CONFIG_DIR should not contain backslashes unless you have escaped them.
Initialize the Runtime Repository
The Runtime Repository normally starts out empty and valid. It will contain the plugins that will be downloaded, selected, and used to configure Tolven. Once the root plugins have been selected for addition to the Runtime Repository, all the dependent plugins can be determined from those root plugins.
On Windows:
cd <install-dir>\bin repositoryInit
On Linux:
cd <install-dir>/bin ./repositoryInit.sh
Tolven will then contact each of the Library Repositories and download the root plugins by default, followed by all the dependent plugins. If all plugins are accounted for, then the Runtime Repository will be consistent, which can be determined by executing the command:
Phase 1 Configuration
Phase 1 usually happens before the application server is running. It's primary function is to assemble the Tolven "ear" file and deploy it to the application server.
If there has been any misconfiguration, it will show up when you attempt your first configPhase1. Execute:
configPhase1
Credentials Configuration
During configPhase1, credentials will have been placed in the tolven-config/credentials directory (by default). This directory is configurable from within the plugins.xml file for plugins which manage credentials. Tolven no longer deploys credentials directly to the LDAP, database or JBoss servers, since it's normally a one time act anyway.
For previous users who are upgrading, the current credentials located in your database and ldap servers should be fine, so long as you also copy your previous credentials (indicated below) from your previous JBoss directory to the new JBoss directory. There are a few additional steps indicated here: Tolven RC1
If this is your first installation, then you need to manually copy the following credentials to the servers:
LDAP
Copy the following to your LDAP directory:
tolven-config/credentials/ldap/tolvendev-ldap-key.pem tolven-config/credentials/ldap/tolvendev-ldap-cert.pem tolven-config/credentials/ldap/tolvendev-ldap-cacerts.pem
During the configuration phase of LDAP, you may recall that LDAP was waiting for these credentials in order to be able to start up in secure mode on port 636. The default password for tolvendev-ldap-key.pem is tolven, which you will be prompted for when you start LDAP. Ensure that LDAP is now accessible using e.g. JXplorer or that it is listening on port 636 (e.g. using the 'netstat -a' command). On Linux it is recommended that these certificates are owned by the ldap user, and that the permissions have the unix convention 400.
Start openLDAP
If you are using openLDAP, it can be started with a command such as the following:
C:\OpenLDAP\slapd.exe -f slapd.conf -d 256 -h ldaps://
Notice that the port is now defined as ldaps (which is port 636).
The default password that protects the password store is tolven.
PostgreSQL
Copy the following to your database directory (e.g. the data directory in the of PostgreSQL):
tolven-config/credentials/postgresql/server.key tolven-config/credentials/postgresql/server.crt tolven-config/credentials/postgresql/root.crt
On Linux ensure that these certificates are owned by the database user (postgres by default), and that the permissions have the unix convention 400.
JBoss
Copy the following to the tolven-jboss-4.2.2.GA/server/tolven/conf directory
tolven-config/credentials/jboss/tolvendev-jboss.jks tolven-config/credentials/jboss/tolvendev-jboss-cacerts.jks tolven-config/credentials/tolven/tolvendev-tolven.jks tolven-config/credentials/tolven/passwordStore.properties tolven-config/credentials/webserver/tolvendev-webserver.p12
If you are using pgadmin, it too requires credentials, which for conveniece are included with the PostgreSQL configuration. These need to be copied to a directory called postgres (for linux prefix this with a dot) in the user's home directory:
tolven-config/credentials/pgadmin/postgresql.key tolven-config/credentials/pgadmin/postgresql.crt
Oracle
Tolven does not provide instructions for how to configure Oracle for SSL connections or how to use Oracle Wallet. Consult the Oracle documentation for instructions.
The Tolven-generated credentials can be copied to Oracle Wallet from tolven-config/credentials/oracle.
Tolven has found that if no special SSL configuration is applied to Oracle, then Tolven will talk to Oracle over a non-encrypted connection. In that case, this step can be skipped completely. This is reasonable if the connection between Tolven and Oracle occurs within a secure environment.
Test Database And LDAP Connections After ConfigPhase1
The database and LDAP servers should be running for the following tests, although the application server is not yet ready to be started. If these tests fail, there is no point moving on until, the issues are resolved.
This test attempts to connect to the PostgreSQL database using the database superuser and the admin keystore for SSL. If using Oracle, substitute org.tolven.postgresqlmgr with org.tolven.oraclemgr
tpf -plugin org.tolven.postgresqlmgr -testAdminDB
This test attempts to connect to the database using the database superuser and the application server keystore for SSL.
tpf -plugin org.tolven.postgresqlmgr -testAppServerDB
This test attempts to connect to LDAP using the root DN in LDAP and the admin keystore for SSL.
tpf -plugin org.tolven.ldapmgr -testRootDNLDAP
Phase 2 Configuration
For phase 2 (re)start both the database and ldap servers. The GUI Plugins contain a number of manager plugins (suffixed with mgr), which provide both command line and GUI tests for the connections to the database and LDAP servers. Use these to ensure that you have working connections.
The following command will activate any plugins that may need to initialize the ldap and database servers before the application server is started. This extra step is required because the application won't start correctly if there are no schemas in either the database or the ldap servers.
Once the database has been initialized, you do not need to repeat this step although there is no harm if you do.
configPhase2
Update MDBUser
Execute the following in order to create an mdbuser in LDAP (see org.tolven.mdbuser).
On Windows:
tpf -plugin org.tolven.mdbuser -update
On Linux:
./tpf.sh -plugin org.tolven.mdbuser -update
Test LDAP Connection Prior To Starting Application Server
The tests executed after configPhase1 should not be affected by configPhase2, but you can double check them if you wish: Test Database And LDAP Connections After ConfigPhase1.
This test attempts to connect to LDAP using the admin DN in LDAP, which was placed there during configPhase2, and uses the admin keystore for SSL.
tpf -plugin org.tolven.ldapmgr -testAdminLDAP
This test attempts to connect to LDAP using the admin DN in LDAP, which was placed there during configPhase2, and uses the application keystore for SSL.
tpf -plugin org.tolven.ldapmgr -testAppServerLDAP
Startup Application Server
Start the application server by navigating to the Tolven JBoss bin directory and executing the command:
On Windows:
startTolvenJBoss
On Linux:
./startTolvenJBoss.sh
On Linux there is a startJBossNohup version which starts JBoss in the background, but it is not recommended to use this command until you have ensured that you have configured and can start JBoss successfully. You will also have to configure JBoss to not require a password, as described above.
It is recommended that you watch the JBoss server.log carefully as it starts (server/tolven/log/server.log), to ensure that you see no ERRORs.
Test Application Server Connection After Start
This test will connect to the application server as admin and is only a simple test to check whether a context can be retrieved.
tpf -plugin org.tolven.jbossmgr -testAdminAppServer
Update Database Indexes
Once JBoss has started, execute the following commands to create the database indexes for the tables, which were created during the start up process. This step is normally carried out during a first installation, and might only need to be re-run if new indexes are announced in Tolven. This process can take a few minutes to run for a large database.
On Windows:
cd <install-dir>\bin updateDBIndexes.bat
On Linux:
cd <install-dir>/bin ./updateDBIndexes.sh
Update Server Properties
This step will configure the Tolven runtime server properties. An initial set of properties will be created which you can deploy to the database. Thereafter, you can change these properties when needed, even while the application server is running. The properties are managed by the following entry in the plugins.xml file:
<plugin id="org.tolven.appserverproperties"> <root /> <property name="appserver.default.propertiesFile" value="server-default-config.properties.xml" /> <property name="guiComponentParentId" value="org.tolven.appservermgr" /> </plugin>
The filename value of the appserver.default.propertiesFile, is by default a relative path to the file within the plugin itself. These default properties are currently a part of the plugin. If you wish to edit these properties, then place all of those properties in your own file, and use an absolute path to that file e.g:
On Windows:
<property name="appserver.default.propertiesFile" value="c:/tolven-config/server-default-config.properties.xml" />
Please note the forward slashes for the path which appears in the plugins.xml.
On Linux:
<property name="appserver.default.propertiesFile" value="/usr/local/tolven-config/server-default-config.properties.xml" />
You can use the example file provided in the <config-dir> or unzip the one in the plugin itself, and then place that externally wherever you choose, and then edit it. If you already have properties in the database from a previous installation, then there is no need to run this command, otherwise:
tpf -plugin org.tolven.appserverproperties -load
If you wish to use the GUI for appserver properties, then you can execute:
tpf -plugin org.tolven.appserverproperties -gui
Phase 3 Configuration
This phase provides the application configuration to the server. Prior to this step, the application server will have no applications defined and therefore a user would be able to do little beyond logging in.
If you are installing Tolven for the first time, you should probably add the prototype applications provided by Tolven prior to running this step. See the following section for details.
The application server must be started before executing the following command
On Windows:
configPhase3
On LInux:
./configPhase3.sh
This command will activate those plugins that have account types, rules, trims, vocab etc to upload to the database via the application server. In other words, the Tolven runtime configuration.
This is likely to be the most commonly repeated configuration command once the above installation and configuration process has been completed.
The actions taken by this command affect the database, not the tolven.ear file. For example, if changes are made that affect the tolven.ear file, then configPhase1 will need to be run before running configPhase3. If only a trim changes, then only configPhase3 is needed to upload it to the running database and application server.
At this point, you may want to connect to the web application, which by default is:
log in, create a demo account, and perhaps generate some test patients. In order to generate test patients, you must have the org.tolven.ccr plugin included in your tolven-config/plugins.xml file (which in turn requires that you rerun configPhase1).
Application Metadata
Tolven requires metadata that defines the basic application behavior. Metadata, in the form of plugins, is uploaded to the database where it is used a runtime. In order for these plugins to be available to your repositoryRuntime, you need to first add the following snippets to your tolven-config/plugins.xml file in order to make them root plugins.
Metadata Supplied By Tolven
Note that these are prototypes (examples), which Tolven updates regularly on the download site. Add the following to your <tolven-config>/plugins.xml:
<plugin id="org.tolven.prototype.applications"> <root /> </plugin> <plugin id="org.tolven.prototype.application.trim"> <root /> </plugin>
These plugins will automatically be downloaded to your <config-dir>/repositoryRuntime/plugins directory the next time you execute repositoryInit, and as newer versions appear, they too will be downloaded.
Custom Metadata
If you do not want to use the Tolven supplied custom metadata above, and wish to use you own custom metadata, you can execute the following to create a snapshot, or starting place, from the current prototypes. You will then maintain these from that point forwards.
Execute one the following in order to download copies of plugins containing application metadata. Make sure that you substitute the location of your <config-dir> directory for the defaults below. In addition, each of the commands below needs to be executed individually to allow you to enter the admin password.
On Windows:
copyplugin -src http://tolven.org/download -srcId org.tolven.prototype.applications -dest <config-dir>/repositoryLocal/plugins -destId com.myorg.applications copyplugin -src http://tolven.org/download -srcId org.tolven.prototype.application.trim -dest <config-dir>/repositoryLocal/plugins -destId com.myorg.trims genMetadata -plugins <config-dir>/repositoryLocal/plugins -liburl file:///<config-dir>/repositoryLocal -outdir <config-dir>/repositoryLocal
On Linux:
./copyplugin.sh -src http://tolven.org/download -srcId org.tolven.prototype.applications -dest <config-dir>/repositoryLocal/plugins -destId com.myorg.applications ./copyplugin.sh -src http://tolven.org/download -srcId org.tolven.prototype.application.trim -dest <config-dir>/repositoryLocal/plugins -destId com.myorg.trims ./genMetadata.sh -plugins <config-dir>/repositoryLocal/plugins -liburl file:///<config-dir>/repositoryLocal -outdir <config-dir>/repositoryLocal
The above commands will result in two plugins being copied to your local repository directory <config-dir>/repositoryLocal/plugins.
In order for these plugins to then be transferred to your <config-dir>/repositoryRuntime/plugins directory, you need to first add the following plugin requests to your tolven-config/plugins.xml file.
<plugin id="com.myorg.applications"> <root /> </plugin> <plugin id="com.myorg.trims"> <root /> </plugin>
Vocabulary
Applications will need some standard vocabulary. Tolven provides several vocabularies via plugins which can also be included by pasting some or all of the following in the plugins.xml.
<plugin id="org.tolven.deploy.allergies"> <root /> </plugin> <plugin id="org.tolven.deploy.breastproblems"> <root /> </plugin> <plugin id="org.tolven.deploy.diagnoses"> <root /> </plugin> <plugin id="org.tolven.deploy.immunization"> <root /> </plugin> <plugin id="org.tolven.deploy.problems"> <root /> </plugin> <plugin id="org.tolven.deploy.procedures"> <root /> </plugin> <plugin id="org.tolven.deploy.rxnorm"> <root /> </plugin>
To download the above plugins to your repositoryRuntime, execute repositoryInit.
On Windows:
cd <install-dir>\bin repositoryInit
On Linux:
cd <install-dir>/bin ./repositoryInit.sh
Once downloaded, The applications and trims plugins operate in phase 3 of the configuration, so execute the configPhase3 command to upload the applications to the application server.
On Windows:
configPhase3
On LInux:
./configPhase3.sh
The vocabulary plugins are not automatically activated during configPhase3, and so have their own commands. You may be prompted for userId, password and <config-dir> unless you have taken the appropriate configuration steps given earlier in the configuration process, so these commands must be executed individually. If your userId, password and <config-dir> are set up you can simply execute them all, and they will simply execute sequencially:
On Windows:
tpf -plugin org.tolven.deploy.allergies tpf -plugin org.tolven.deploy.breastproblems tpf -plugin org.tolven.deploy.diagnoses tpf -plugin org.tolven.deploy.immunization tpf -plugin org.tolven.deploy.problems tpf -plugin org.tolven.deploy.procedures tpf -plugin org.tolven.deploy.rxnorm
On Linux:
./tpf.sh -plugin org.tolven.deploy.allergies ./tpf.sh -plugin org.tolven.deploy.breastproblems ./tpf.sh -plugin org.tolven.deploy.diagnoses ./tpf.sh -plugin org.tolven.deploy.immunization ./tpf.sh -plugin org.tolven.deploy.problems ./tpf.sh -plugin org.tolven.deploy.procedures ./tpf.sh -plugin org.tolven.deploy.rxnorm
