What this module does

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

Documentation / How-To

Environment

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

OpenMRS: 1.6

Java Version: 1.6

Database: MySQL 5.1

How it works?

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.

Pre-Requisites

The module needs the following before it can start importing successfully:

1. Dependent OpenMRS modules
2. Required OpenMRS tasks
3. OpenXData database with study and forms under the study
4. Corresponding OpenMRS Forms (CRFs) for the Study forms in OpenXData
5. Mapping spreadsheets

Dependent OpenMRS modules

• FormEntry module version 4.5.4
• Peru fitness study 1.4

Required OpenMRS tasks

Following tasks need to be running. These can be checked by going to Manage Scheduler in Admin section.

• ‘Process Form Entry Queue’ with 30 seconds interval and the class should be set to ‘org.openmrs.module.formentry.ProcessFormEntryQueueTask’
• ‘Process HL7 Task’ with 30 seconds interval the class should be set to ‘org.openmrs.scheduler.tasks.ProcessHL7InQueueTask’

OpenXData database with study and forms under the study

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.

Corresponding OpenMRS Forms (CRFs) for the Study forms in OpenXData

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.

Administering OXDImporter

Settings (formerly Global Properties from 1.8 downwards)

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

www.server-address-here/openmrs/admin/ maintenance/globalProps.form

oxdimporter.database_version

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.)

oxdimporter.pathToLoggingFolder

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.

oxdimporter.pathToMappingFile

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.

oxdimporter.mappingFileNameConvention

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.

oxdimporter.openxdataAddress

the address of openXdata database server where oxd forms reside. Could be IP Address like: 125.222.43.34 or 127.0.0.1. Default value is ‘localhost’.

oxdimporter.openxdataDatabaseName

The name of the openXdata database residing on the database server.

oxdimporter.openxdataPort

The port of openXdata database server where oxd forms reside. Default is 3306

oxdimporter.openxdataUsername

The username of a valid user of the database server with rights of openXdata database.

oxdimporter.openxdataPassword

The password of a valid user of the database server with rights of openXdata database.

oxdimporter.openxdataFormNameList

Pipe-separated list of names of forms as they occur in OpenXData and need to be imported. Following value is set by default:

TRAT|ESPU|RBKC|SINT|PPDA|FILI|CASE|PPDL|HTBC|ENUT|CAMB|CIER|DEMO|ELCO|ELIN|EMBA|RESQ|SANG|CICI|CICO|HMED

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.

Scheduler Task

1. Go to Manage Scheduler in Administration
2. Make sure that the pre-requisite processes are running.
3. Click on Add Task
4. Now add the following for Task Configuration:
   1. Name: Process OXD Importer
   2. Schedulable Class: org.openmrs.module.oxdimporter.scheduler.ProcessOXDImporterTask
   3. Description: task for importing data from a given OpenXData instance repeatedly.
   4. For Schedule: Repeat Interval : 30 seconds
5. Click 'Save'

Creating Mappings

Mappings refers to the linking of OpenXData forms with those in OpenMRS. This is done in two stages:

1. Excel sheets (for questions)
2. OpenMRS Database (for answers and form names)

The following section deals with the proper way of creating the mappings

OXD-OpenMRS Forms Mapping

This mapping is used for linking names of forms from both systems. This information is stored in

1. oxdimporter.openxdataFormNameList: used for containing OXD Form names which need to be imported
2. Table ‘oxdimporter_oxdomrs_form_mapping’

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 4^th 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.

Question Mapping

This requires Excel sheets in the following naming format:

<form_name>-mapping.xls

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,

<i_id_del_participante>1234567891</i_id_del_participante>

<ii_id_del_participante_2>1234567891</ii_id_del_participante_2>

<iii_fecha_de_entrada>2011-04-06</iii_fecha_de_entrada>

<elin1_el_potencial_participante_tiene_un_frotis_de_esputo_positivo>true</elin1_el_potencial_participante_tiene_un_frotis_de_esputo_positivo>

<elin2_el_potencial_participante_es_gt_16_aos_de_edad>false</elin2_el_potencial_participante_es_gt_16_aos_de_edad>

<elin3_fecha_de_nacimiento>2011-04-05</elin3_fecha_de_nacimiento>

Following node names or questions can be retrieved:

i_id_del_participante

ii_id_del_participante_2

iii_fecha_de_entrada

elin2_el_potencial_participante_es_gt_16_aos_de_edad

elin3_fecha_de_nacimiento

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">

<date xsi:nil="true"/>

<time xsi:nil="true"/>

<value xsi:nil="true"/>

</participant_had_a_positive_smear_on_a_sputum_specimen>

<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">

<date xsi:nil="true"/>

<time xsi:nil="true"/>

<value xsi:nil="true"/>

</the_participant_is_greater_or_equal_than_16_years_old>

Two questions can be selected from the above snippet:

-participant_had_a_positive_smear_on_a_sputum_specimen

-the_participant_is_greater_or_equal_than_16_years_old

Now using, these two columns, the mapping excel sheet can be created for each form using the methods described.

Answer Mapping

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:

Id(auto incremented)

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.

Downloads

The module is in the process of being open-sourced. We hope to post it to the openMRS repository soon.

About

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.