IHRIS and DHIS2 Interoperability
From IHRIS Wiki
This article describes OpenHIE standards based data exchange and interoperability between iHRIS and DHIS2.
This article assumes that you are running:
- iHRIS version 4.2 (or above)
- DHIS2 version 2.19 (or above)
The assumptions are:
- DHIS2 has the list of facilities and the geographic hierarchy
- iHRIS wants to load in the DHIS2 facilities and geographic hierarchy
- iHRIS wants to export the number of health workers for each facility to DHIS2. This may be disaggregated, for example, by:
- Sex/Gender (Male vs Female)
- Cadre (Nurse, Doctor, Midwife,... )
We will be making use of an InterLinked Registry of Health workers and Health facilities to achieve this interoperability. This software that will help us do this is OpenInfoMan.
- 1 Care Services Discovery (CSD)
- 2 DHIS2 and OpenInfoMan
- 3 What is a health facility in DHIS2?
- 4 DHIS2 Meta Data Export
- 5 iHRIS CSD Facilities
- 6 Sending Number of Health Workers
Care Services Discovery (CSD)
CSD is the main means for exporting (and importing) facility lists and organizational unit hierarchy from DHIS2 in a standards based way and compliant with the OpenHIE architecture. This data exchange is documented in more detailed here:
In the sequence diagram in the above link, you should think of:
- FR = Facility Registry = DHIS2
- HWR = Health Worker Registry = iHRIS
- ILR = InterLinked Registry = OpenInfoMan
DHIS2 and OpenInfoMan
We are going to export meta-data from DHIS2 to OpenInfoMan. OpenInfoMan will take the exported meta-data and transform it into the CSD standard. OpenInfoMan then shares that information out as an InterLinked
What is a health facility in DHIS2?
The most important question that needs to be answered is what is a health facility in the DHIS2 instance you are using. In DHIS2 there is no universal way of saying which of the Organisation Units is a health facilities. However, there are two typical ways:
- Every Organisation Unit at a fixed level (or below) is a health facility. Often this is at level 4 and below.
- There are one or more Organisation Unit Groups that have been created and the Organisation Units for health facilities are assigned to one of these Organisation Unit Groups
An example of Organisation Unit Groups for a Health Facility is:
- Medical Clinic
- Provincial Hospital
- District Hospital
- Nursing School
- Administrative Office
- TB HC Treatment Center (CT)
- Prison Clinic
DHIS2 Meta Data Export
Once we know which Organisation Units are health facilities, we can setup the export of DHIS2 metadata into the CSD format. There are existing transformations that can be used and we would just need to modify them based on the specifics on the health facilities in DHIS2.
What we will be doing is:
- In OpenInfoMan, create a new CSD document to hold the DHIS2 facility data
- In OpenInfoMan, copy and modify one of the transformation scripts to be used for our DHIS2 instance (See #OpenInfoMan DHIS2 Adapter Below)
- In DHIS2, Perform the DXF Meta-Data Export, available under the Import-Export app in DHIS2. See below for the details on what you need to export.
- In OpenInfoMan, we will upload the DXF MetaData export via the DHIS2 Adapter
Once done, the health facility data in DHIS2, including the organisation unit structure, from DHIS2 is available in the CSD directory.
If you would like to automate this process, for example with cronjob, you can:
- use the DHIS2 web api to download the meta-date export
- use an HTTP POST of a CSD Care Services Request for the stored function.
OpenInfoMan DHIS2 Adapter
There is an DHIS2 adapter for OpenInfoMan which can be found here with three line install instructions for Ubuntu 14.04 LTS:
If you install this adapter, you will have a web interface on your server to:
- create a new CSD document. For our examples below we will use DHIS2_DEMO as the name of the document
- upload a DHIS2 metadata export
- specify conditions on when an organization unit is a facility (by group code or level)
- let you select if you want DHIS2 users transformed to CSD health workers
You will need to include the following data in your meta-data export:
If you want to also transform users into health workers you will also need:
Automating DHI2 to InterLinked Registry (DXF->CSD)
If you want to automate this via a cronjob you will need to submit a valid Care Services Discovery HTTP POST (which is called the ITI-73 Query for Services transaction ).
There is a bash script that helps you do this:
An example posted message where we are selecting all organisation units with group codes for a mental health clinics and administrative buidings might look like this. The exact available group codes for your system can be found by browsing the DHIS2 web-api: <source lang='xml'>
<requestParams> <dxf></dxf> <groupCodes> <groupCode>MENTAL_HEALTH_CLINICS</groupCode> <groupCode>ADMINISTRATIVE_BLDG</groupCode> </groupCodes> <levels/> <URL>http://demo.dhis2.org</URL><--! THIS IS THE "NAME" OF YOUR DHIS2 INSTANCE--> <OID/> <usersAreHealthWorkers/> </requestParams>
If you want to import users as health workers, you can change the line:
The documented is submitted as:
- URL: http://localhost:8984/CSD/csr/DHIS2_DEMO/careServicesRequest/urn:dhis.org:extract_from_dxf:v2.19
- An HTTP POST
- Content-type: text/xml
If you need the error conditions, check out:
iHRIS CSD Facilities
Enabling the CSD Facility Map Module
There is now support for linking existing iHRIS facilities to the Inter-Linked Registry via a module. To enable this module, go to:
- Click "Configure System"
- Click "Configure Modules"
- Click "Sub-Modules" to the right of "iHRIS Common"
- Click "Sub-Modules" to the right of "Facility"
- Check the "CSD Facility Map" check-box
- Click update
This will add a new MAP field to iHRIS facility form called "csd_facility."
Once you have configured the connection details for the InterLinked video you can start mapping iHRIS facilities to CSD / Inter-Linked registry. To do so:
- Go to "Configure System"
- Click "InterLinked Health Worker Registry"
- You can then set the URL for the a Facility Registry by select "Define or configure additional InfoManagers"
There is youtube video that shows this configuration process (on a slightly different user interface)
TO DO: replace the drop-down list for select a CSD Facility with a report search.
Mapping iHRIS and CSD Facilities
The module only enables a new fields in the iHRIS facility form. It does not perform any mappings.
There are several strategies for linking iHRIS facilities to the Inter-Linked Registry csd_facility form. For example:
- You can write a PHP script to match on the facility name
- If you have already mapped data against DHIS2, you can write a php script to use a facility code or dhis_uid fields and lookup the corresponding InterLinked Registry facility by searching the csd_facility form.
Sending Number of Health Workers