Once you get your OpenEMPI instance up and running the first thing you will want to do is load some data into it so that you can then take OpenEMPI for a test run. In this blog post I will describe the easiest way to get some data into OpenEMPI.

OpenEMPI’s user interface offers a couple of options for loading data into the system. The first option expects the patient demographic data to be in a fixed data format while the second one allows the user to specify a mapping document that defines how fields from the file map into fields in the OpenEMPI data model. This post will describe the first and easier approach and a future article will talk about the more flexible data loading approach.

Since the easier approach for importing data into the system expects the data to be in a fixed format, let’s first talk about the format of the input file. The expected input format of the file is essentially a typical comma-delimited text file with one record of data per line. The table below describes the sequence of fields that make up a record and provide some details on how to format individual fields when they are expected to be specific format. For example, the phone number field should be formatted as a sequence of digits without any character separators like a ‘-‘ character. The file test-data-5k-openempi is formatted using the expected format and can be used to test the upload process.

[table caption=”Fixed data format table” width=”600px” colwidth=”20|80|500″ colalign=”left|left|left”]
,Field Name,Field Description

2.,Given Name, First name of the person
3.,Surname, Last name of the person
4.,Street Number, Street number and any other information that should preceed the address line
5.,Address 1,First line of the address of the person. The Street number field is prepended to this field before the record is imported into the database.
6.,City,The city portion of the address of the person
7.,Zip Code, The zip code portion of the address of the person
8.,State, The state portion of the address of the person
9.,Date of birth,The date of birth of the person formatted as yyyymmdd (e.g. 19870824)
10.,Age of the person, The age of the person as a natural number
11.,Phone number, The phone number of the person formatted as a sequence of digits (e.g. 8155364948)
12.,Social security number, The social security number of the person formatted as a sequence of digits (e.g. 692544254)
13.,Blocking number, This value is ignored during normal loading
14.,Gender, The gender of the person such as (M/F/O) (optional field)
15., Race, The race of the person (optional field)
16., Account, A medical account number associated with the person (optional field)
17.,Identifiers,A sequence of one or more identifiers. Each identifier may have an associated domain specified using the combination of namespace identifier/universal identifier domain/universal identifier domain type code. In the case of multiple identifiers each identifier is separated from the others using the  ‘^’ character. The identifier domain component are separated using the ‘&’ character (e.g. MRN-2148&2.16.840.1.113883.4.357&2.16.840.1.113883.4.357&hl7).

Once you have constructed your input data in the format expected by the loader you must first upload the file onto the server hosting OpenEMPI and then import the data into the system. To upload the file, login into the admin console at http://server/openempi-admin and select the File->File List option from the menu. You then need to point your browser to the file which should at this point be on the same host as the one your are running your browser on. Pressing the Browse button will allow you to locate the file on your local host and select it. In the Name edit box you can type in the logical name you want to assign to your file. This name can be anything at all but try to pick something that will remind you of which physical file the entry refers to and you also need to make sure that the name is unique. At this point you should be able to press the Upload button to upload the file onto the server.

File Upload

The next step is to load the data into the system. To do this select the file from the list that you want to load and click on the Import button. You should then be presented with a screen that gives you a number of choices as shown in the figure below.

Concurrent loader options

As I mentioned earlier, OpenEMPI provides a couple of file loaders out of the box and the one that is easier to use and expects the input in a fixed format is called the concurrentDataLoader. The other two check boxes are fairly self-explanatory. If you have a header line in your import file that you obviously don’t want to attempt to load onto the server, you should check the “Skip Header Line” option. The second check box relates to the two options that OpenEMPI offers regarding what should happen when a record is loaded onto the system. You may choose to only import the record in which case the data is loaded into the database and there is no further processing of the record. If you leave the “Is Import” check box unchecked, then after loading each record into the system, the system will invoke the currently configured matching algorithm to determine if the new record should be linked to any existing records in the system. As you have guessed the first option is the fastest one since invoking the matching algorithm is a fairly computationally intensive task. If your are setting up a new instance of OpenEMPI and you are trying to perform the initial load of data into the system, then the recommended approach is to simply do the “Import” and then once you have configured the matching algorithm, you can run then it once against all the data on the system. If on the other hand your instance of OpenEMPI is already in operation and you are uploading data from a new facility, then you should leave the “Is Import” option unchecked.

Once the system has finished loading the data, the screen will be updated to report on how many records were uploaded successfully and how many failed to load properly. If some of the records are not loaded successfully, you can get more information about what went wrong by looking at the log file for OpenEMPI which is typically called openempi.log and should reside in the OpenEMPI home directory.