How to migrate data from OpenMRS to DHIS2 using DCM Module
What is OpenMRS?
OpenMRS is a software platform and a reference application which enables the design of a customized medical records system to support the delivery of health care in developing countries.
What is DHIS2?
DHIS2 is a tool for collection, validation, analysis, and presentation of aggregate and patient-based statistical data, tailored (but not limited) to integrated health information management activities.
Purpose of OpenMRS-DHIS2 Connector Module
In many countries where OpenMRS is used alongside DHIS 2, it has been a trouble to maintain two databases to operate both the products simultaneously. So, this module will help the users to import analyzed OpenMRS report data which can be used in DHIS 2 for analytics. This module provides the implementers a User Interface for an easier-to-set-up OMRS to DHIS2 pipeline, that doesn’t need manual code fixes every time there’s a change to reporting indicators.
How the OpenMRS-DHIS2 Connector Module (DCM) Works?
The DHIS Connector module is used to extract/aggregate data from the OpenMRS system. Data is aggregated according to the user specification (CD4 COUNT < 200). Then the OpenMRS feature, the cohort builder, is used to query the database as specified by the user.
After getting the required aggregated data an HL7 message is created and sent to DHIS. The Mirth Messaging module is used to send the message to DHIS.
Technologies Used
HL7 API (HAPI)
Mirth
Mirth Messaging Module
Steps to Implement the integration process:
Install DHIS2 - For more information refer - https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html
Once DHIS2 is installed following activities should be performed:
Define Organizations in DHIS2. This should map to the locations to be defined in OpenMRS.
Define periods depending upon how granular data aggregation you want to perform based on time period.
Define Data sets & data elements - All data entry in DHIS2 is organized through the use of data sets. A data set is a collection of data elements grouped together for data collection.
Install OpenMRS - For more information refer - https://wiki.openmrs.org/display/docs/Installing+OpenMRS
Installing DHIS Integration Module (under OpenMRS)
To install the DHIS Integration Module (DIM), the global property module.allow_web_admin must be set to true. The global properties are found under Administration/Manage Global Properties. The Global Properties must be saved after any change.
For DIM to be installed, the Mirth Messaging module must be installed and running (Mirth Messaging Module). To install any module, you navigate to Administration>Manage Modules. Under the Manage Modules page, there is an Add Module sub-menu. Browse to the .omod file (OpenMRS module), and click on Add Module. OpenMRS will do the necessary checks to ensure that the module is up and running.
For DIM to run, certain Global Properties need to be defined:
dhismodule.dataSetFile - This specifies the file that has the datasets that need to be sent to the DHIS system. The directory of the file is needed (the file must also be created/exist in that directory).
dhismodule.dhisInput - This specifies the directory where all the inputs for the module are. The directory contains things like the Dataset file.
dhismodule.HL7Archive - This specifies the directory that will be used to save all HL7 messages sent to DHIS saved by date.
Remember to SAVE the global properties after every change.
Before you can use DIM, Mirth must be installed and a Mirth channel must be set up. Mirth is used to allow communication between the 2 systems.
Using DHIS2 Connector Module
After installing DIM, the DCM menu appears on the Administration page of OpenMRS. Use following steps to use the DCM:
Configuration - Here you will configure the link to the DHIS2 server. This is done by clicking the Configure DHIS2 Server link under the DHIS Connector Module heading on the OpenMRS Administration page.
Field | Value |
URL | |
Username | admin |
Password | district |
Mapping - Before you can send Period Indicator Report data to DHIS2, a mapping must exist between the report and a DHIS2 Data Set. This mapping can be done in the UI by clicking the Create Mapping link under the DHIS Connector Module heading on the OpenMRS Administration page. Then select the Period Indicator Report from the left menu and the corresponding DHIS2 Data Set from the right menu. Drag the Data Elements and Category Option Combos from the right to the matching row on the left as shown in below image. Once the mapping is complete, click save and give your mapping a unique name.
Location Mapping
Before you can send Period Indicator Report data to DHIS2, a mapping must exist between the OpenMRS Location and a DHIS2 Organization Unit. So when pushing data, the respective DHIS Organization Unit and OpenMRS Location of the Dataset will be automatically mapped. Location Mappings can be saved via the Location Mapping UI. Mappings are stored in the database at dhisconnector_location_to_orgunit table.
Posting Data
To post data to the DHIS2 server, click the Run Reports link under the DHIS Connector Module heading on the OpenMRS Administration page. Select the Period Indicator Report and the corresponding mapping to use.
Since Period Indicator Reports are always run for a specific location, you will also need to select the OpenMRS Location as well as the corresponding DHIS2 Organisation Unit. But with the automated location mapping feature, it will show the available location mappings when the mapping is selected. You can select the required location-org unit mappings from the available mappings.
The date selector will be changed based on the period type of the DHIS2 Data Set.
It is also possible to schedule/automate the process of pushing the data, by clicking the Automation link under the DHIS Connector Module heading on the OpenMRS Administration page.
To add mappings, choose the mapping from the dropdown list and click Add.
You need to map the relevant OpenMRS Location and DHIS2 Organisation Unit using the Location Mapping UI before scheduling the mappings.
To push data manually, select the mappings and click Run Selected. Available OpenMRS locations and DHIS2 organization units will be mapped automatically. Automated reports will be ran and pushed automatically by the end of the relevant period.
You can toggle the automation by checking/unchecking the tick box and clicking save.
Data synchronization in DHIS2
Once the data is posted to DHIS2 from OpenMRS, it is necessary to run the data synchronization script in dhis2. Only after data synchronization, it is possible to create visualizations in DHIS2 as the synchronization process is responsible for pull & push of metadata in DHIS2