View source for Synchronizing iHRIS against a Master Facility List

This page is outdated.  Please see:
 [[iHRIS and DHIS2 Interoperability]]

This page looks at strategies and concerns when synchronizing the iHRIS facility list with hose
==What Is A Health Facility==
Before we can begin synchronizing iHRIS facilities against another system, we need to be sure that both systems agree on the definition of a health facility.  There are several places where the answer to this question is not clear.  For example:
*Are we looking at both public sector and private sector facilities?  
*Are we looking a facilities that are only places that provide clinical care?  This may sometimes (though not always) the case when, for example, you are trying to link to DHIS2 or other system that is interested in reporting clinical data only.  iHRIS tends to have a larger set of facilities under it, for example the MOH Headquarters.

If you are asking this question and getting different answers, than you can propose the following questions and answers:
*What is a health facility?  Well, it is a place where a health worker works.
*So what is a health worker?  According to the [http://www.who.int/hrh/documents/counting_health_workers.pdf definition adopted by the WHO] it is anyone "engaged in the promotion, protection or improvement of the health of the population." 
Notice that a health worker is not just someone providing clinical care, so this includes the Minister of Health, ambulance drivers, cleaning staff, and probably you if you are reading this.

Now that we know who the health workers are, then we can advocate to the keepers of the Master Facility List that they should include the non-clinical facilities in their Master Facility List.


===Who is the Authority on Facility Data===
Sometimes the remote system you wish to synchronize with has both public and private sector facilities listed in it.  However, they may not be mandated to cover register both facilities. In this case, you will end up with conflicts when the true authority for one of these sectors starts managing their facility data.  Although this is largely a governance issue within the Facility Registry community, it is a good time to ask this question.  

For example, in some countries there are two departments at the MOH -- one is in charge of all public sector facilities and one in charge of all private sector facilities.

One good place to look for an authority of facility data is DHIS2.  Even if it does not necessarily have the mandate, DHIS2 does tend to have a comprehensive list of facilities. 

==Linking or Replacing Facilities==
Depending on the answers to the questions the questions:
*Is there any existing facility data in iHRIS?
*Are all of the facilities that are needed in iHRIS already in the remote service
*How are the geographic data elements (the location of the facility) going to be mapped into iHRIS
You may choose to either link the existing iHRIS facilities to list from the the remote service, or you may want to replace the existing facilities in iHRIS with those from the remote service. 

 
In an existing iHRIS deployment, perhaps the easiest route to take is the “Liberia” approach in which iHRIS and DHIS2 facilities are considered separate but need to be linked.  Here, one can import the DHIS2 facility list as a separate list into iHRIS as a separate “DHIS Facility List” using the [[#SVS | SVS]] standard.    The existing iHRIS facilities will need to be matched against the DHIS2 facilities if we want to report them.  

The “DRC” approach, is for when there are no existing facilities or geographic data in iHRIS and DHIS2 will be the authority for all of this data.   In particular, you will  not be editing facilities in iHRIS directly.   In this case, we can pull the full organizational hierarchy from DHIS2 into iHRIS.

The third approach, the “Ghana” and "Kenya" approach, is if there is existing iHRIS facility data, but we want to move to using the remote service (DHIS2 and the Kenya MFL) as an authority.  In many ways, this is like the DRC approach, except that we will need to match existing facilities against the DHIS facilities and then “remap” all data that points to the old facilities, districts, etc. into the new versions we got from DHIS2.

==Extract, Transform, Load==
When interfacing with a remote service or external source of data for obtaining the master facility list, have one generic software design pattern you should think of, ETL:
*Extract: extract the data from the remote system
*Transform: transform the facility data into a format usable by iHRIS.  There are two good candidates here:
**A module containing magic data for the facility under /I2CE/formsData/forms/facility.  This is good for the DRC, Kenya or Ghana approach when you want to treat the other system as an authority for all facilities
**A [[#SVS | SVS]] file containing a simple list of facilities and a code.  This is useful for the Liberia approach when there is a large gap between the iHRIS facilities and those that are being maintained in the remote system. 
**The iHRIS XML representation of a form.  This is used in particular for XML service form storage mechanisms.  It is out-of-scope of this wiki article.   
*Load: after successful transformation, load the data into iHRIS. 

===Direct Load===
If the external facility data is an XML file, there is a [[Technical Overview: Form Storage -- XML | XML form storage mechanism]] for reading the data directly in from the file.   This can be used in cases where the external data is organized in a simple way and if you don't need to perform any real manipulation of the data.


==Linking Facilities (Liberia)==
In this case we extracted the facility list from the organization units in DHIS2 via the magic data export.  We performed a [http://www.w3schools.com/xsl/ XSL] transform on the DHIS2 meta data to produce an [[#SVS | SVS]] file.  The SVS file can be loaded directly into iHRIS using a new (in 4.2) form storage mechanism.

The files are here:
https://code.launchpad.net/~his-interop/liberia-academy-interop/trunk
*DHIS Meta Data Source: dhis_metaData_may_13_2014.xml
*XSL Transform: dhis_metaData_org_units_to_svs.xsl
*Resulting SVS file: dhis_org_units_as_svs.xml

==Replacing Facilities (Kenya)==
See [[Kenya Master Facility List]] for some notes on the full process and considerations for 

==Replacing Facilities (Ghana)==
In this case, the transformation process was from a CSV file to a iHRIS Module using a PHP script:
*The PHP script and source data http://bazaar.launchpad.net/~ihris+ghana/ihris-manage-ghana/4.1/files/head:/DHIS_SourceData/
*Resulting Facility Data Module http://bazaar.launchpad.net/~ihris+ghana/ihris-manage-ghana/4.1/files/head:/modules/Ghana-data-facility/
*Resulting County Data Module http://bazaar.launchpad.net/~ihris+ghana/ihris-manage-ghana/4.1/files/head:/modules/Ghana-data-county/

==Remap Existing Facilities in iHRIS==
If there are existing facilities in iHRIS, then we will need to do some additional work to:
*Associate one of the "old" facilities to one of the "new" facilities.  This is called "setting remapping data".  This can can be done either automatically through the use of a script, or [https://www.youtube.com/watch?v=Gfj3Cui9JnU manually] through the web-interface. 
*Update any of the positions or other forms pointing to an old facility to point to the new facility data identified by the remapping data.

===Matching with a Script===
Here are two commented examples of automatic matching:
*[[Kenya_Master_Facility_List#Script_to_get_all_the_facilties_and_match_duplicate_names | Kenya MLF]]: create a list of facilities with duplicate names.  If there is one which comes from the MFL, then the others should remap to that
*[http://bazaar.launchpad.net/~his-interop/liberia-academy-interop/trunk/view/head:/link_ihris_facility_to_dhis_svs.php Liberia automatic link] Goes through the list of iHRIS facilities and tries to match against the imported DHIS facilities and set the remapping data


==Automating the Process==
This is where the work still remains to be done.  A few things:
*DHIS2 will soon have new apps to expose their organization units as an SVS file
*You can have a cron-job to perform the ELT to load the iHRIS data

==Other Resources==
* DHIS2: [[Linking iHRIS Facilities and DHIS Organizational Units]] This shows you how to load the full metadata export from DHIS2 into iHRIS and then link the iHRIS facilities to these organizational units.  There is not as streamlined as the SVS methodology discussed above.
* Kenya MFL: [[Kenya Master Facility List]]

==Standards==
There are a few international standards for representing facility data in the health system:
*CSD ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/ITInfrastructure/IHE_ITI_Suppl_CSD.pdf has an XML representation for facility data and an API to access that data.
*HL7 FIHR also has an organization concept http://www.hl7.org/implement/standards/fhir/organization.html as well as a location (e.g building) http://www.hl7.org/implement/standards/fhir/location.html.  It includes a RESTful API 
*HPD ftp://ftp.ihe.net/DocumentPublication/CurrentPublished/ITInfrastructure/IHE_ITI_Suppl_HPD.pdf has an organization which can be used to represent a facility.  It is based on LDAP

===SVS===
[http://www.ihe.net/Technical_Framework/upload/IHE_ITI_Suppl_SVS_Rev2-1_TI_2010-08-10.pdf Sharing Value Sets] is an international standard in the health information systems community for sharing simple lists as XML files.