Installation of Legacy Distribution Format

Owned by Sophia
Sept 05, 2023
4 min read

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