Skip to content

Latest commit

 

History

History
99 lines (62 loc) · 6.43 KB

README.md

File metadata and controls

99 lines (62 loc) · 6.43 KB
Raw

OpenMRS

DHIS Connector Module

This module posts OpenMRS Period Indicator Report data to DHIS2 using the Reporting Rest module. Mappings between Period Indicator Reports and DHIS2 Data Sets can be generated via the UI. The DHIS2 API is backed up for offline operation and DXF files can be downloaded instead of posting to DHIS2 directly.

Setup

Before you use the DHIS Connector Module, you will need to configure both a Period Indicator Report in OpenMRS (instructions) and the corresponding DHIS2 Data Set in DHIS2 (instructions).

Installation

First install the Reporting Rest Module† (you will also need the Rest Module and the Reporting Module). Then download and install the DHIS Connector Module.

† You will actually need to download this build of the Reporting Rest Module until this change is merged and released.

Configuration

The first step is to configure the link to your DHIS2 server. This is done by clicking the Configure DHIS Server link under the DHIS Connector Module heading on the OpenMRS Administration page. You will need to know the URL of your target DHIS2 instance as well the details of a user that has access to the API. To test with the DHIS2 demo server, use the following details:

Field Value
URL https://play.dhis2.org/demo
Username admin
Password district

⚠️ NB: Since DHIS API pagination isn't handled yet, you will have to change the Rest Max Results Absolute Webservices Module global property to 2000. Do this by clicking the Settings link on the OpenMRS Administration page, then click Webservices on the bottom left. Change the value of the Rest Max Results Absolute property to 2000 and click save. Ensure to build your reports in OpenMRS but making sure each indicator id is uniquely named

Mappings

Before you can send Period Indicator Report data to DHIS2, a mapping must exist between the report and a DHIS2 Data Set. Mappings can either be generated via the UI or placed in the correct location. Mappings are stored as JSON on the file system at OPENMRS_DIR/dhisconnector/mappings/. On Ubuntu, this usually corresponds to /usr/share/tomcat7/.OpenMRS/dhisconnector/mappings/.

Create Mapping

To generate a mapping via the UI, click 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 follows:

Finally, click save and give your mapping a unique name.

Exporting Existing Mapping

This module provides a way of exporting existing mappings which basically archives them into one download that can thereafter be imported/uploaded into the current or another OpenMRS instance.

Uploading Existing Mapping

The module provides an option to import or upload mappings previously exported from the current or other instances, this feature is available and will be released as part of 0.1.2

Posting Data

To post data to the DHIS2 server or download the data in DXF format, 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.

The date selector will changed based on the period type of the DHIS2 Data Set.

Once you have selected a value for all the fields, click Send Data to post data directly to the DHIS2 server, or Download JSON to download the data in DXF format.

To post backedup DHIS2 API, run; bash postDHIS2API.sh and enter required details

DHIS2 Backup

Every time a request is sent to the DHIS2 server, the resulting JSON is stored on the file system at OPENMRS_DIR/dhisconnector/dhis2Backup/. On Ubuntu, this usually corresponds to /usr/share/tomcat7/.OpenMRS/dhisconnector/dhis2Backup/. If the DHIS2 server is no longer reachable, these backed up API values will be used by the DHIS Connector Module.

For OpenMRS implementations that should operate offline, it is possible to pre-populate this dhis2Backup by using both the DHIS API Import and export pages. Assuming all the required resources have been backed up by the online implementation, the offline implementation should be able to function correctly without ever being able to reach the DHIS2 server.

Module Status

Jira Issues

Implemented

  • Configure DHIS2 Server
  • Drag and drop mapping generator
  • Post data or download DXF
  • Backup DHIS2 API for offline use
  • Interface for uploading mappings
  • Interface for exporting mappings
  • Fix mapping creation UI to support multi-line DataElement names
  • Interface for prepopulating DHIS2 API backup
  • Error handling
  • Managing/editing mappings
  • Scroll page when dragging mapping to top and bottom of page if necessary
  • Generation, Downloading & Posting of ADX
  • Automated reporting and posting to DHIS2 using configured mapping

TODO

  • Support other types of OpenMRS reports
  • DHIS2 API pagination
  • Upgrade all dhis endpoints or api to work after 2.20
  • Support Quaterly, SixMonthly, SixMonthlyApril, BiMonthly, FinancialApril, FinancialJuly, FinancialOct period types

License

MPL 2.0 w/ HD © OpenMRS Inc.