Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
The module OXDImporter is designed and built for use by Partners In Health (PIH), Peru. It facilitates the study in Lima by importing cell-phone collected in OpenXData from the OpenMRS system. OpenMRS is the primary data source of the study and contains all the CRFs
The module runs on Windows environment and has been tested with extensively with Windows XP and Ubuntu Linux. The module requires OpenMRS 1.6 and is not backward compatible with older versions due to irreversible changes in the OpenMRS API post 1.5 version of OpenMRS. The environment can be summarized as follows:
Operating system: Windows / Linux
Web server: Tomcat 6
Java Version: 1.6
Database: MySQL 5.1
The module runs as a task that runs repeatedly and checks for any new data submitted in by cell phones to OpenXData. The module does not have a user interface as such but uses the Global Properties page in OpenMRS for setting required parameters for its functionality.
The module needs the following before it can start importing successfully:
Following tasks need to be running. These can be checked by going to Manage Scheduler in Admin section.
The study database should have been created in OpenXData with the all the required study forms under it. It should be insured that the cell phones can connect to OpenXData server and download studies and submit filled forms.
For each OpenXData form (except FILI) a corresponding CRF must be in place in OpenMRS which contain the questions present in the cell-phone forms. Eg. A PPDA form in OXD must have its counterpart PPDA CRF in OpenMRS.
Settings (formerly Global Properties from 1.8 downwards) are used to store data that is used by the module to carry out its functionality. These can be accessed on the following page
Used for setting the database version by reading the sqldiff.xml file in the module. Should not be changed. (Only when this might need to be changed is when someone removes or modifier the module’s tables from the database purposely. In such an extraordinary situation, the value of the database version should be set to 0.0.1 and the module be reloaded by removing and installing again.)
Used for setting the location of the folder where logs for the module are generated. Can be changed to a convenient location using the default value as a sample.
The folder where mapping files for the CRFs are contained. The path is set to the module’s folder in the AppData directory of the environment.
All mapping files should be named according to the value of this Global property. E.g. , a value of
“-mapping.xls” would mean “crf1 -mapping.xls”, “crf2-mapping.xls”, etc where the ‘crf1’ & ‘crf2’ refer to the names of the CRF’s for which mapping exists and followed by the naming convention.
the address of openXdata database server where oxd forms reside. Could be IP Address like: 184.108.40.206 or 127.0.0.1. Default value is ‘localhost’.
The name of the openXdata database residing on the database server.
The port of openXdata database server where oxd forms reside. Default is 3306
The username of a valid user of the database server with rights of openXdata database.
The password of a valid user of the database server with rights of openXdata database.
Pipe-separated list of names of forms as they occur in OpenXData and need to be imported. Following value is set by default:
Any new form would need a same single letter form name in both systems ie OXD and OpenMRS and would need to be added to the list above after a ‘|’ sign.
Mappings refers to the linking of OpenXData forms with those in OpenMRS. This is done in two stages:
The following section deals with the proper way of creating the mappings
This mapping is used for linking names of forms from both systems. This information is stored in
This table has 4 columns of which 3 store information from OXD database and are populated automatically by the module using the code and the above global property while the 4th column is for storing ‘form_id’ of each corresponding OpenMRS form.
This columns needs to be filled hand by an implementer who has access to the database. It can be done by a tool such as MySQL Query Browser or SQL queries at MySQL command line.
Eg. For OXD form ELIN with VersionID 35 a CRF in OpenMRS exists in ‘form’ table. If the form_id is 100, then the row in ‘oxdimporter_oxdomrs_form_mapping’ for ELIN mapping should have value of 100 for the form_id column.
This requires Excel sheets in the following naming format:
The files would need to be put in UserHome/AppData/OpenMRS/oxdimporter/mapping folder on the system
The file would contain TWO columns. The FIRST column would contain OpenXData node name (question). This can be obtained from the ‘data’ column of the table ‘form_data’ in OpenXData database.
For eg for ELIN,
Following node names or questions can be retrieved:
The second column of the mapping file is obtained from the template.xml of the OpenMRS form. This comes from the column ‘template’. The tags should be selected from obs section:
<participant_had_a_positive_smear_on_a_sputum_specimen multiple="0" openmrs_concept="2092^PARTICIPANT HAD A POSITIVE SMEAR ON A SPUTUM SPECIMEN^99DCT" openmrs_datatype="CWE">
<the_participant_is_greater_or_equal_than_16_years_old multiple="0" openmrs_concept="2095^THE PARTICIPANT IS GREATER OR EQUAL THAN 16 YEARS OLD^99DCT" openmrs_datatype="CWE">
Two questions can be selected from the above snippet:
Now using, these two columns, the mapping excel sheet can be created for each form using the methods described.
Answer mapping is done to insure that the response from cell phones is interpreted the right way in OpenMRS. Following table needs to be populated in OpenMRS: oxdimporter_answer_mapping
The table has the following columns:
oxd_value :contains the string in OXD’s answer
concept_name: the name of the concept that corresponds to the above string in OpenMRS
locale: stores two locales from the module: ‘es’ for Spanish and ‘en’ for English.
This table needs to be populated by script by the user.
The module is in the process of being open-sourced. We hope to post it to the openMRS repository soon.
This module was authored by Omar Ahmed in collaboration with implementation and technical support from: Socios en Salud, InterActive Research & Development, Partners in Health, the research team at Brigham Women's, Sarah Bird, David Thomas, Evan Waters and Brent Atkinson.