Installation of the Distribution (Windows Edition)

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). For installation onto a Windows box it is usually easier to use the distribution with the .zip extension. The software can be downloaded from the http://www.openempi.org/openempi-downloads/index.html site. Once you have registered (only need to do this the first time you visit the site) you can select the version of interest from the list, as shown in the example below, and click on the red download link.

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 C:\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. You can then extract the contents of the distribution file in the selected directory using the Windows Explorer as shown below.

If you followed the steps above successfully, at this point the contents of the archive should reside under the directory C:\sysnet\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 C:\sysnet\openempi\openempi-entity-3.x.y (Note that the x and y refer to the major and minor numbers of the distribution you are installing; for the example above the directory would be openempi-entity-3.1.0).

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.x.y 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, test-person-5k.csv are sample datasets for testing OpenEMPI and getting started. The test-person-5k.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 the example distribution shown in the example above, set OPENEMPI_HOME=C:/sysnet/openempi/openempi-entity-3.1.0). 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=c:/sysnet/openempi/openempi-entity-3.1.0). This can be used if you use a script to start your application server and you can easily modify that startup script.