4.2.1. DHIS2
Last updated
Last updated
The process for registering a DHIS2 instance in GeoPrism Registry is as follows:
Navigate to the Settings page using the burger menu.\
Scroll down to the 'External Systems' section and click on the + button to open the Registration modal.\
Select DHIS2 from the Type dropdown and fill out the other fields (details on each field are provided in the table below).\
| Field name | Description | Required? |
|---|---|---|
Type | The type of external system. | Yes |
Organization | The organization the user belongs to. An external system will only be available to data and users within this organization. | Yes |
ID | The identifier for this external system. | Yes |
Label | The label of the external system. | Yes |
Description | A description of the external system. | No |
Username | The username of the user from the DHIS2 instance to be used for authentication. | Yes |
Password | The password of the user from the DHIS2 instance to be used for authentication. | Yes |
URL | The URL of the DHIS2 instance. | Yes |
An OAuth client must first be created in the DHIS2 instance. See section 3.9 for more information.
At the bottom of the External System modal, you will see a section for OAuth. Click the Enable OAuth Integration button.\
A form for configuring the OAuth integration will expand. Client ID, Profile Location, Token Location and Authorization Location should be filled out automatically. It is not recommended to change these values.\
Enter the Secret Key from the DHIS2 OAuth Client in the OAuth Secret Key field. You will need to get this from the DHIS2 instance.\
Click Submit.
GeoPrism Registry's DHIS2 integration has not been tested on DHIS2 versions above 2.38 and below 2.31. It is not recommended to integrate with DHIS2 servers outside of this range, because GeoPrism Registry could throw unspecified errors during synchronization, or in the worst case scenario, it could corrupt your DHIS2 database..
Some GeoPrism Registry features may not work with some versions of DHIS2.
The following table lists the OAuth integration possibilities for each DHIS2 version, as tested by TerraFrame.
| DHIS2 version | Integration via OAuth possible? |
|---|---|
2.35.2 and later | Yes |
2.35.1 | No |
2.35.0 | No |
2.34.2 | Yes |
2.33.7 | Yes |
2.32.7 | Yes |
2.31.9 | Yes |
If Geo-Object data is already present as organization units in a DHIS2 instance, it must first be imported using the Import from an external system option in the Import module.
GeoPrism Registry supports using a DHIS2 external system synchronization to push data to a DHIS2 instance. The purpose of the external system synchronization is to define how Geo-Object Types in a specific hierarchy will map to organization units in a DHIS2 instance. The latest version of the Geo-Objects will be synchronized with DHIS2, as GeoPrism Registry currently does not support exporting at a specific date.
The following steps are to be followed to enable the synchronization:
Navigate to the Settings page.\
Find the External System Synchronizations section and click on the Register Synchronization button.\
Click the Create button on the Synchronization Configurations page.\
Fill out the fields in the Synchronization Configuration modal and click Submit.\
| Field | Description |
|---|---|
Label | Label of the synchronization configuration. |
Organization | The organization the synchronization configuration will be available to. |
Hierarchy | The hierarchy this synchronization will use to push data to an external system. |
External System | The registered external system that this synchronization will use to push data to an external system. |
Org Units | A mapping between the Geo-Object Types in the selected GeoPrism Registry hierarchy and the types in the DHIS2 instance. |
The Org Units section of the configuration modal allows you to map each organization unit level in DHIS2 to a Geo-Object Type in GeoPrism Registry. There is no limit to the number of levels that can be matched, however no more levels should be matched than exist in the DHIS2 instance being synchronized with. Additionally, the matched Geo-Object Type of each level should be a direct child of the level before it.
The Geo-Objects in GeoPrism Registry are matched to their DHIS2 counterparts using the external identifiers of the GeoPrism Registry Geo-Objects and the identifiers of the organization units in DHIS2. It is important to note that this matching does not use the Code properties from either system. If a Geo-Object does not have an external identifier, then it will be considered new and will be created as a new organization unit in DHIS2 if the synchronization type is set to ‘Org Units and Relationships’. GeoPrism Registry will then save the external identifier of that new organization unit in the database to be used for future updates. If the Geo-Object has an external identifier while DHIS2 does not have an organization unit with a matching identifier in their system, an error will be shown.
The DHIS2 Synchronization Type specifies what data will be synchronized to DHIS2.
| Synchronization Type | Description |
|---|---|
Org Units | Synchronizes attributes from Geo-Objects over to existing organization units in DHIS2. New Geo-Objects cannot be synchronized with this setting. |
Relationships | Synchronizes relationships between Geo-Objects with DHIS2. If an organization unit in DHIS2 has a different parent than what exists in GeoPrism Registry, the existing parent will be set to the one in GeoPrism Registry. If multiple parents in GeoPrism Registry are detected for a Geo-Object an error will be thrown and the relationship will not be exported. New Geo-Objects cannot be synchronized with this setting. |
Org Units and Relationships | Synchronizes both attributes and relationships over to DHIS2. If the organization unit does not exist in DHIS2 it will be created. |
Geo-Object Types (levels) can be matched to an organization unit group, so that only selected organization units within that group are synchronized. The ‘Org Unit Group’ dropdown lists all organization unit groups which currently exist in the DHIS2 instance. When a Geo-Object Type is matched to a group, all Geo-Objects that are of that Geo-Object Type will be assigned to the selected organization unit group the next time the system synchronizes with this configuration.
This behavior operates in an additive fashion only. Any organization units which are already assigned to the organization unit group will not be affected.
If a Geo-Object Type is matched which contains custom attributes, the custom attribute matcher will be displayed.
This attribute matching is specific to a Geo-Object Type and level. In order for a DHIS2 attribute to be a valid selection for the matching, it must be applied to organization units, and it must be close enough in Type to be a candidate. Here are the appropriate selection types:
| GeoPrism Registry data type | Appropriate DHIS2 value types |
|---|---|
Text | Text, Long Text, Letter, Phone Number, Email, Username, URL |
Boolean | Boolean, True Only |
Date | Date, Date Time, Time, Age |
Integer | Integer, Integer Positive, Integer Negative, Integer Zero |
Decimal | Number, Unit Interval, Percentage |
Term | Option Set |
The following DHIS2 value types cannot be mapped to attributes in GeoPrism Registry:
Tracker Associate
Coordinate
Organization Unit
File Resource
Image
If an attribute in GeoPrism Registry is not matched to one in DHIS2 (either because there were no valid selections, or the dropdown was intentionally left as ‘not matched’), then the data in that attribute will not be synchronized with DHIS2. It will not, however, prevent the rest of the attributes or relationships from being synchronized.
GeoPrism Registry Term-type attributes can be matched to DHIS2 option sets. When the Target Type is set to ‘Option Set’, the Target Attribute dropdown will populate with all DHIS2 attributes which contain an option set and are assigned to organization units. When a GeoPrism Registry Term-type attribute is matched to a valid option set in the DHIS2, then the user interface expands to allow matching between GeoPrism Registry terms and DHIS2 options.
If a Geo-Object does not have values for the Term-type attribute, then the attribute will not be set on the DHIS2 organization unit. Geo-Objects with terms which have not been matched (‘Not Mapped’) will not be exported and an error will occur.
Terms can also be mapped instead to organization unit groups. This can be done by selecting ‘Org Unit Group’ in the Target Type dropdown.
Geo-Objects will be assigned to the organization unit group as matched in the above screenshot. This provides some basic support for organization unit group synchronization.
Similar to option set matching, if a Geo-Object does not have a value for the Term-type attribute, then it will not be assigned to an organization unit group. Geo-Objects with terms which have not been matched (‘Not Mapped’) will not be exported and an error will occur.
This behavior operates in an additive fashion only. Any organization units which are already assigned to the organization unit group will not be affected.
If a level is matched to a DHIS2 organization unit group, and the Geo-Object Type also contains a term which is matched to DHIS2 organization unit groups, then the synchronized organization unit will be added to all organization unit groups which have been matched (in an additive fashion).
GeoPrism Registry provides a plugin which can be downloaded and installed onto a DHIS2 instance. When installed onto DHIS2, this plugin behaves as a standard DHIS2 app, which will redirect to the GeoPrism Registry instance configured in the external system.
To download the DHIS2 to GeoPrism Registry plugin:
Navigate to an existing DHIS2 external system configuration form from the GeoPrism Registry Settings page.
Click the Download DHIS2 Plugin button, which will download a zip file called “cgr-dhis2-app.zip” to your computer.\
Please refer to the official DHIS2 documentation to install the plugin.
Successful installation will display the link to GeoPrism Registry in DHIS2.
