Page Comparison

Installation of the Distribution

The OpenEMPI software is released using two different distribution formats:

1. The new distribution format starting with release 3.4.0 uses a distribution that is named using the following convention: openempi-entity-${version}-release.tar.gz (for example the version 3.4.0 release has the name openempi-entity-3.4.0-release.tar.gz). The new distribution format is easier to install in that it requires fewer manual steps.
2. The legacy distribution format that is named using the following convention: openempi-entity-${version}.tar.gz.

Please follow the distribution-specific installation instructions for the format of the distribution that you are trying to install.

Installation of New Distribution Format

The installation of a distribution of OpenEMPI using this release format is fairly straightforward. Make sure that the JAVA_HOME environment variable points to an installation of JDK 1.8. Keep in mind that with the new distribution format there is no need to install an instance of the Tomcat application server. An instance of the Tomcat server is included in the distribution and is configured nominally to operate properly with OpenEMPI.

1. Extract the contents of the distribution into the root of directory into the directory that will become the parent of the installation directory. In the following example we install the distribution under the /sysnet/openempi directory and assume that the distribution file resides in the /tmp directory.

mkdir /sysnet/openempi
cd /sysnet/openempi
tar xf /tmp/openempi-entity-3.5.0-release.tar.gz

2. Configure the distribution based on the directory in which it was installed. You first change into the directory in which the distribution was extracted and run the post-install script. The post-install.sh script takes two parameters: the first is the directory in which the distribution was extracted (/sysnet/openempi/openempi-3.5.0 for the example shown here) and the second one is the version of the distribution that you are customizing (in this case it is 3.5.0).

cd /sysnet/openempi/openempi-3.5.0
./post-install.sh /sysnet/openempi/openempi-3.5.0 3.5.0

3. The next step is to configure the database instance for the release. The release assumes that you are using the standard Postgres database and it is pre-configured for that database. If you are using an alternate database please follow the appropriate instructions.

4. You can now start the instance using the startup command.

cd /sysnet/openempi/openempi-3.5.0
bin/startup.sh

You can stop the server using the shutdown command in a similar manner.

cd /sysnet/openempi/openempi-3.5.0
bin/shutdown.sh

You are done with the installation and should now be able to access the administrative application by pointing your browser to: http://localhost:8080/openempi-admin (default account uses username: admin and password: admin).in the form of an archived tar file as well as in the form of an installer. This page describes the installation process using an archived tar file as the distribution format. The installation steps are described in separate pages listed below based on the version of the distribution that you are trying to install. For installation instructions for an older and unsupported distribution format, please follow the installation instructions below on this page.

Installation of Legacy Distribution Format

NOTE: You should no longer be installing OpenEMPI using this approach. Installations made using this approach are no longer supported.

The first step in installing OpenEMPI is to download the software distribution. There are always two versions of the release made available: one targeted towards Unix machines (.tar.gz extension) and one targeted towards Windows machines (.zip extension). You can pick the version of the distribution that is most appropriate for your  environment but the contents of both versions of the distribution are the same.

You then need to select a directory where you would like to install the software. We make the assumption that the software is extracted under /sysnet/openempi but you can pick any directory. The name of the archive may vary some depending on the version of the software that you are downloading. Try to always use the latest version of the software for a given major release number. If the version digresses considerably from this documentation space, a new space will be created to match the new release. In place of the x and y in the instructions below, substitute the values for the latest version of the Entity edition of OpenEMPI available.

$ cd /sysnet
$ tar xvfz /tmp/openempi-3.x.y-openempi.tar.gz

If you followed the steps above successfully, at this point the contents of the archive should reside under the directory /opt/openempi/openempi-entity-3.x.y. In a later step you will need to set the OPENEMPI_HOME environment variable to point to this location. To confirm that you have correctly extracted the contents of the archive, make sure that there is a directory named conf in the directory /opt/openempi/openempi-entity-3.x.y.

After you familiarize yourself with the operation of OpenEMPI, you are likely to make various changes to the main configuration file mpi-config.xml but before you start the server for the first time, it is important that you make one change to the file. There is a parameter in the file that specifies the directory where the data repository files are created. This parameter is <data-directory> and is set to the value "/mnt/sysnet/" by default. You need to modify this parameter so that it points to a valid directory on your server and one which the user on whose behalf the server process is running has permissions to write to that directory. Usually we set this parameter to a directory within the OPENEMPI_HOME directory.

The top level directory contains various jar archives for deployment of OpenEMPI and the corresponding PIX/PDQ adapter.

• openempi-core-${version}.jar contains all the core classes that comprise OpenEMPI and is the appropriate option if you want to deploy OpenEMPI embedded within another Java application.
• openempi-webapp-web-${version}.war is a J2EE Web Archive that can be deployed against any compliant web container. It includes the core OpenEMPI infrastructure and API, the web-based administration console, and support for the PIX/PDQ interface. This is the best way to deploy OpenEMPI and get going as quickly as possible.
• openempi-openpixpdq-adapter-${version}.jar is a jar file that comprises the adapter for deployment of OpenEMPI within the OpenPIXPDQ server. The adapter included in the distribution always matches the version of OpenEMPI that it is combined with. As OpenEMPI goes is improved over time, appropriate changes are needed to the OpenPIXPDQ adapter to take advantage of the enhancements made.
• create_new_database_schema-${version}.sql is the database script to use for creating the database instance for OpenEMPI. For the 3.0.x releases, this is the only script you need to run and there are no update scripts that need to be run.
• create_person_entity_model_definition.sql is a database script that creates an entity definition representing a person. It is important to load this script even if you end up eventually modifying this entity or dropping it altogether.
• drop_database_schema.sql is the database script to use to drop all the database objects from the OpenEMPI schema.
• update_database_schema-${version}.sql includes updates to the database schema. You use this sql script to update the base schema for the release and to bring it up to date with the latest minor release.
• mpi-config.xml the configuration file that controls the operation of OpenEMPI. There is an XML configuration file included with the ear file distribution but the configuration file is included here separately for reference purposes.
• mpi-config.xsd the schema file for validation of the OpenEMPI configuration file.
• jdbc.properties is a sample properties file for configuring access to the database repository for OpenEMPI. If you are not using the default instance name, database server, port number, etc for OpenEMPI, you can make the modifications in this file and then update the contents of the war or ear files using the jar command.
• pixpdq_connectathon_patients.csv, dataset_A_1000.csv are sample datasets for testing OpenEMPI and getting started. The dataset_A_1000.csv is a sample patient dataset we got from the excellent Febrl project. You can use these patients for testing alternative matching or blocking algorithms or just to populate the patient registry and see what OpenEMPI has to offer. The pixpdq_connectathon_patients.csv file, as the name implies, is a list of patients that you can use to run the PDQ suite of tests that were used for preparation of OpenEMPI in getting tested as part of the OpenPIXPDQ service at the 2009 Connectathon. There is a complete suite of tests for both the PIX and PDQ interfaces included in the distribution. Documentation on how to run these tests will follow.

The configuration files are stored in the conf directory below the defined home directory for the OpenEMPI application. The home directory for OpenEMPI can be set in one of two ways:

• You can set the environment variable OPENEMPI_HOME to point to the home directory for OpenEMPI. (for example under Unix sh you can use export OPENEMPI_HOME=/sysnet/openempi/openempi-entity-3.x.y or on Windows set OPENEMPI_HOME=d:/servers/openempi/openempi-entity-3.x.y). This is a better approach if you deploy OpenEMPI under multiple application servers or you don't want to modify the application server's startup script.
• You can set the java system parameter openempi.home to point to it (for example set -Dopenempi.home=/opt/openempi/openempi-entity-3.x.y). This can be used if you use a script to start your application server and you can easily modify that startup script.

You must next install the database and /wiki/spaces/openempi30/pages/295018.