This guide is intended to help set up a demonstration instance of the Neuron Health platform. While Neuron is capable of high-availability and high-volume implementations, following this guide will result in a small-scale version of the system. This smaller instance is not intended to be used to support any production applications.
Ready For Production?
If you are ready to spin up a production-caliber instance of Neuron, contact the team at Roberts-Hoffman (the main project sponsor). There are several additional configurations that need to be addressed in a production environment, and we would love to save you the pain of trial-and-error!
Under The Hood
The Neuron Health platform is an extension of the [Tolven Platform]. Consequently, this document is based heavily on the Tolven V2.1 Windows Quick Start Install Guide. We have leveraged our experience with Tolven to simplify and streamline this guide to get you up and running in Neuron as quickly as possible.
Using Medication Orders
The Neuron Health platform requires the Lexi-Data drug database from Lexicomp, Inc. for ordering medications. Trial access to the Lexi-Data database can be obtained by contacting Roberts-Hoffman Software at firstname.lastname@example.org.
c:\tolven\tolven-configand rename it
Download the following files, placing them in
A note about Java: This demonstration install uses Java 6. For any production environment, you will need to upgrade the stack to Java 7.
jdk.exe file downloaded in the last step. Use the default values provided during the installation. After installations completes, test the installation by running the
java -version command from the command prompt. The output should look like:
java version "1.6.0_45" Java(TM) SE Runtime Environment (build 1.6.0_45) Java HotSpot(TM) 64-Bit Server VM (build ??., mixed mode)
Install Apache Ant
apache-ant-1.8.2-bin.zip file to
Extract the OpenSSL zip file to
Note: These instructions are assuming that you are performing a new PostgreSQL install. If you already have PostgreSQL installed, you can use that instance, but be sure to check your database properties in the next step.
postgresql-9.0.4 exefile in the initial-tolven-components directory to start the PostgreSQL installer.
postgresand the locale to English, United States. Accept the default values for all other selections. You do not need to install any extra utilities.
c:\tolven, you must change the
dev.example.com. To install to a different domain, add a
passwordmatch the corresponding properties.
127.0.0.1 dev.example.comOr substitute your host/domain here
C:\Progra~1\Java\jdk1.6.0_45– For Program Files.
C:\Progra~2\Java\jdk1.6.0_45– For Program Files(x86).
PATHvariable and double click it to bring up the editor.
Summary of Environmental Variables and Values
|Variable Name||Default Value|
Copy the file
JAVA_HOME\jre\lib\security\cacerts to your
Open a command line window as administrator and execute the following two commands. These will generate most of the required keystores/truststores in the initial-tolven-components directory and leave the command window open when you are done:
cd C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-installer ant generate-keystores
Confirm that the following files were created in the
cacerts.jks cert.cer keystore.jks keystore.p12 tolvendev-mdbuser.p12
1. Create Key
From the initial-install-components directory create keys for PostgreSQL, using tolven as the default password, as follows:
cd C:\tolven\initial-tolven-components keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -srcstorepass tolven -deststorepass tolven -noprompt
2. Export Key and Cert
Export the postgresql SSL
server.key from the
keystore.p12 (when prompted for Import Password and PEM pass phrase, enter
openssl pkcs12 -in keystore.p12 -out server.key -nocerts openssl pkcs12 -in keystore.p12 -out server.crt -nokeys
3. Copy Cert
Make a copy of
server.crt and call it
copy server.crt root.crt
4. Move Files
Copy the files
root.crt to your PostgreSQL data sub-folder:
copy server.key "%PGDATA%" copy server.crt "%PGDATA%" copy root.crt "%PGDATA%"
5. Modify Key
Execute the following from the command line using
tolven as the pass phrase:
cd "%PGDATA%" openssl dsa -in server.key -out server-nopasswd.key
Remove or rename
Set the permissions on
server.key to read-only.
6. Server Properties
postgresql.conf file in the data sub-folder of your PostgreSQL installation folder, and open it in a text editor like Notepad. Set the following:
ssl = on (Uncomment this line and set it to on.)
listen_addresses = ‘*’
max_prepared_transactions = 10 (Uncomment this line and ensure that the value is 10 or the installation process will fail.)
7. Network Access
To allow network access to the database, locate the
pg_hba.conf file in the PostgreSQL data sub-folder. JDBC, even from localhost, requires network access to the database. Documentation is included in that file. Open the file in a text editor like Notepad. The uncommented line should look something like this:
# TYPE DATABASE USER CIDR-ADDRESS METHOD hostssl postgres postgres 127.0.0.1/32 md5
You are done with the pg_hba.conf file, although remember to change this file if you need to access postgreSQL from clients not on localhost. You can also change the TYPE from hostssl to host, which will allow connections via non-ssl clients, but this is not recommended.
8. Restart to Apply
Stop and restart the PostgreSQL service. You can either use the service manager or use the following commands from the command prompt run as administrator. The PostgreSQL service name is either postgresql-9.0 or postgresql-x64-9.0:
sc stop postgresql-x64-9.0 sc start postgresql-x64-9.0
At this point in the install procedure, it is advisable to make a backup copy of the
tolven folder, including its sub-folders, before you execute the install command. If you are installing Tolven on a virtual machine, you can take a snapshot of the machine.
Open a command prompt window as administrator and navigate to
Execute the following command:
You should get a
BUILD SUCCESSFUL message after a successful install. It is advisable to capture the details of the install script for troubleshooting by piping the output to a file, like this:
ant install-config-tolven > ant.log
This facilitates much easier debugging of the install process should things not go smoothly.
This process can take a while to complete. On a Windows 7 VM with 1 GB and 1 CPU it can run for 15 to 20 minutes before completing. Also note that when OpenDS and the JBoss server start up, the Windows firewall will ask if you want to grant these programs access to the network; please do so.
After the install completes, you should now have the following sub-folders in the tolven folder:
initial-tolven-components snapshots tolven-config tolven-jboss6 tolvenOpenDS
If you are going to have trouble with the install, it will likely happen here. See Troubleshooting below for troubleshooting tips.
Note: Some of the vocabularies are quite large, and loading them can take some time. For a development environment, you can limit the vocabulary loading to 100 entries per vocabulary. This will significantly shorten the time required to load the vocabularies. If you don’t want to limit the download, skip over these steps
To Limit the Vocabulary Upload
C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-V2.1\bin\tpf.batfile with a text editor.
Activate Vocabulary Plugins
These commands must be executed one at a time, in sequence from
tpf -plugin org.tolven.growthchart tpf -plugin org.tolven.orders.imageorders tpf -plugin org.tolven.orders.laborders tpf -plugin org.tolven.deploy.problems tpf -plugin org.tolven.deploy.rxnorm tpf -plugin org.tolven.deploy.cvximmunization tpf -plugin org.tolven.deploy.substancemanufacturer tpf -plugin org.tolven.deploy.icd9procedures tpf -plugin org.tolven.deploy.reportablediagnosisLoader tpf -plugin org.r-hsoftware.lab tpf -plugin org.r-hsoftware.radiology tpf -plugin org.r-hsoftware.diagnoses.ICD9 tpf -plugin org.r-hsoftware.notes.Therapy tpf -plugin org.r-hsoftware.occupationalTherapyProcedure tpf -plugin org.r-hsoftware.respiratoryTherapyProcedure tpf -plugin org.r-hsoftware.speechTherapyProcedure
For demonstration purposes, trial access to the Lexi-Data drug database can be obtained by contacting Roberts-Hoffman Software at email@example.com. Roberts-Hoffman will provide instructions on how to configure the Neuron Health platform to access the trial database. You can also find information in the [System Administration Guide].
This step will load a set of default server properties. To view and change properties before loading them, see
In the same location as the previous step (
C:\tolven\snapshots\V21_yyyymmdd_snapshot\tolven-V2.1\bin), execute the following command to load default server properties.
tpf -plugin org.tolven.appserverproperties -load
Required User Attributes
|Realm||Select the tolven realm.|
|First Name||The first name of the user.|
|Last Name||The last name of the user.|
|A unique user id||A unique user ID to be used for Neuron login|
|Email Address||The user’s email address.|
|Organization Unit Name||A higher-level organizational group name to which the user belongs.|
|Organization Name||The name of the organization to which the user belongs.|
|State or Province||The state or province where the user works.|
adminas the user and
sysadminas the password.
adminas the user and
sysadminas the password.
You can also find more detailed information about users, roles, permissions, and security in the [System Administration Guide].
Important Files for Troubleshooting
Installation Log -
Ant script output (see Step 9) -
JBoss Boot log -
JBoss Server log -
The issues listed here include those that can occur during the installation or the configuration.
Install fails right away
If your install fails at the very beginning and does not recognize the
ant command, you may have not specified the ant installation variable and listed it in your path, or you specified it incorrectly. See Step 6.
During the install and configuration, certain processes can fail if the transactions take too long to complete. You may find that
ant install-config-tolven returns
BUILD SUCCESSFUL as the output, but that you are unable to load vocabularies or create an account (the account type selection is empty). If you observe these symptoms, you may need to take special installation steps to increase the system performance or increase the transaction timeout.
If you install Neuron on a demonstration machine with limited resources, you may encounter the Session/Transaction Timeout problem. On a server-caliber Linux Operating System, you will be able to install the Neuron demo with 1 CPU and 1 GB of memory. However, a Windows OS will require more resources for a successful install. If you have the symptoms of the transaction timeout, consider adding resources to the system.
Increasing the Transaction Timeout
Note: This troubleshooting step only applies to systems that demonstrate the characteristics described in the Session/Transaction Timeout section. If you are getting the message
BUILD FAILED, you are not ready to try this step.
c:\tolven\tolven-jboss6\server\tolven\deploy\transaction-jboss-beans.xmland open it in a text editor.
This batch file is the final step of
ant install-config-tolven, and is the step that fails when the transactions take too long to complete. Re-running this step should complete the install process and you can resume loading vocabularies in step 10.
Can't find the host in the browser
If you see errors saying that there are problems with finding
dev.example.com (or your name of choice), make sure that you made the proper entry in your HOSTS file. If you use something other than
dev.example.com, you also have to specify that in
plugins.xml file. Be absolutely sure you make no typographic errors in
HOSTS or in
Database connection errors
If there are errors that indicate trouble connecting to the database, make sure the database service is started. If you are using PostgreSQL, be sure that you followed the steps in the Configure PostgreSQL step above. If you have to make changes to the PostgreSQL configuration files, you will need to stop and restart the PostgreSQL service for those changes to take effect.
If you encounter Java errors that indicate that it can’t find the Java resources required, you may not have specified the
JDK_HOME variables and listed them in your path, or you specified them incorrectly. See Step 6.
If you get the following warning message:
WARN [loggerI18N] [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa]
Could not find new XAResource to use for recovering non-serializable XAResource...
postgres.conf file in a text editor and change the
max_prepared_transactions property to be greater than zero. 10 is recommended. Uncomment and change the following:
max_prepared_transactions = 10 # zero disables the feature
Stop and restart the PostgreSQL service.
Make sure that all of the versions of the components you placed in the initial-tolven-components folder match the versions as listed in this guide.
JVM Memory Settings
The out-of-the-box configuration of the JVM is restricted to 1 GB of working memory. To adjust this setting, modify
c:\tolven\tolven-jboss6\bin\startTolvenJBoss.bat. This batch file has the following memory configuration property on the first line:
-Xmx1024m. Adjust this property up to increase total memory available to the JVM; adjust this property down to lower the memory limit and reduce the impact of the JVM on the system resources.
After making any adjustments to your settings or files, do the steps below to re-start the install.
If your install failed during the config-tolven step, you will have to re-do the install as well. Follow the same steps below.
tolvenOpenDSfolders. Open the
tolven-configfolder. Delete the
repositoryRuntimefolders. Delete the
Servers -> PostgreSQL X -> Databases ->postgres.
Schemas to drop
drop schema app cascade; drop schema core cascade; drop schema doc cascade; drop schema gen cascade; drop schema provider cascade; drop schema public cascade;
The schemas will be automatically created again when you run the install.
Re-start the install process again.