A system to migrate from SQL-based databases into OpenMRS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


The OpenMRS Data Import Tool Guide

This project eases data migration for production settings by improving upon eSaude Data Migration Tool making it more user friendly. The Data Import Tool integrates the eSaude Data Migration Tool (eSaude DMT) in order to migrate data from SQL-based data sources into OpenMRS. This module provides a WUI to configure migration settings and perform migration.


This document describes how to use the Data Import Tool to migrate data from a dummy database into OpenMRS.

Step 1. Build The Data Import Tool

Clone the DIT repo and build it.

  $ git clone https://github.com/openmrs/openmrs-module-dataimporttool.git
  $ cd openmrs-module-dataimporttool
  $ mvn clean install

The last command above generates an omod file for the openmrs-module-data-importtool.

Step 2. Install OpenMRS 1.11.3

Download the OpenMRS WAR file and deploy it to Tomcat.

Step 3. Prepare Dummy Database

Refer to the DMT-Guide for test Database and instructions on data migration.

I.) Create a dummy database, populated with data.

Clone dmt-guide

  $ git clone https://github.com/esaude/dmt-guide
  cd dmt-guide
  $ mysql -uroot -p
  mysql> create database dummy;
  mysql> use dummy;
  mysql> \. resources/source_medical_dummy.sql

II.) Create a dummy OpenMRS database

  $ mysql -uroot -p
  mysql> create database openmrs2;
  mysql> use openmrs2;
  mysql> \. resources/openmrs-1.11.3-clean.sql

There is a required change that must be done in OpenMRS database in order to run the migration, in OpenMRS 11, the PATIENT.patient_id column is not AUTO_INCREMENT, this way JDBC will not return the generated key. Use the script(alter_patient_id.sql) to alter the patient_id, after the migration you can change it back to normal.

  mysql> \. resources/alter_patient_id.sql

Step 4. Complete The Mapping Spreadsheet

The mapping sheet we are using can be download from Mapping Sheet.

I) Linux Users only

Install the MySQL/Mariadb Java connector or driver MariaDB Connector. Alternatively you could copy the MariaDB connector.jar files to the appropriate /usr/lib/java*/jre/lib/ext/ directory.

II) Windows User and Mac OSX Users only

Refer to the DMT README document for specific configuration settings.

Step 5. Run The DIT from OpenMRS

1.) Upload the module from the OpenMRS Manage modules link.

2.) Click on the Start Migration link under the Data Import Tool.

3.) Verify the migration settings and click 'Start Migration'.


1.) Matching File

2.) MariaDB Connector

3.) Sample Linux Config

The Docs can be downloaded from the OpenMRS DMT wiki page. OpenMRS mailing list OpenMRS talk.

If you have any further questions reach out on OpenMRS Talk.

Authors and Contributors

1.) Nyah Check(Ch3ck)

2.) Valerio Joao(vjoao)

3.) Pascal Brandt(psbrandt)