Import GIS coordinates (OrgUnits) - LogicalOutcomes/DHIS2-FAQ GitHub Wiki

• Covert .SHP files and Importing GML files

• Click Here to see a walkthrough video from the Online Curriculum that is related to this task.   Instructions: 

---

Step 1: Download a shape file

a. You need to have shape files for the org units. Open the link http://www.gadm.org

b. Scroll down to find the raw “You can download the data by country or for the whole whole world”, click on “country

c. Select the country of your choice. From “File format” choose “shape file” and then click OK. The newly open window shows the picture of selected country.

d. Click 'download' found below the map.

You will get a zip file which contains layers containing polygons of country’s boundary, regions, provinces, districts, municipalities, etc. Digits at the end of each layer name shows the layer number starting with 0 (the country’s boundary layer). Each layer is formed up by a few files with extensions as shown below. Usually layer names starts with the abbreviation of the country (for example: CAN for Canada, BGR for Bulgaria), followed by “adm” – abbreviation from administration and ends with the layer number – 0, 1, 2, 3…

   

Step 2: Simplification of layers in the shape file with Mapshaper program (Optional)

a. Open Mapshaper program available at http://www.mapshaper.org. The program allows online adjustment of shape files. It simplifies them, making them smaller files for faster upload to DHIS2.

b. Click on the link above to open the program. You will see the following window:

c. Select your zipped shape file which you downloaded from http://www.gadm.org, drag and drop it onto the area above. Alternatively, you can click on “select” button and from your windows explorer will open, then find the directory your file has been saved.

Once you upload the file you will find it as it is shown below:

d. Click on the blue button “Import”. On the upper side of your screen you will see Layer 0 – the first layer of your shape file which contains the boundary of your country. Clicking on the white arrow you will open all files contained in the uploaded zip file. By clicking on the “name” you can open any layer you want to explore (shown below).

Information about the opened layer can be displayed by clicking on the symbol “i” as shown below. If you open the district layer, it will display a map with all districts that the country comprises. By clicking on any district, a detailed information will appear on the left side of your screen. You can also explore each of the .csv files that accompanies the layer in order to see the org units it comprises.

Program menu is allocated on the upper right side. You can choose Simplify, Console or Export. Simplify allows you to determine the per cent of simplification; Console allows inserting of commands (help is available); Export provides export of the selected simplified layer.

a. To simplify a layer. Click on the menu Simplify and on the pop-down menu click 'Apply'.

  b. Slide the bullet to a per cent you want to simplify the geometries.

c. Once you finish, click 'Export' and select the layer you would like to export.

IMPORTANT: Each layer must be exported separately in order to add each layer in Step #3. If all layers are exported at the same time, it will be downloaded as one folder and selecting individual layers to add later on will not be possible. Remember to also extract your files to unzip them and get access to the individual .shp files.

Export command allows you to choose the file format of exported files – shape file, csv, GeoJSON. For the purpose of our task, we will choose a shape file type. Exported layers are zipped files containing 4 files types - .dbf, .prj, .shp, and .shx. The new .shp file of each layer has lesser detailed GIS data which will make a smaller GML file.

 

Step 3: Exporting shape files and creating GML files

Note: DHIS2 supports only one coordinate projection system that is EPSG:4326, with geographic latitude and longitude. There are many open source programs that convert shape files into EPSG:4326. You can use FWtools; Proj4js; OpenLayers; QGIS.

In this example QGIS is applied. If you do not already have this program installed, you can DOWNLOAD IT HERE.

  a. Open QGIS program, Open menu Layer, hover over 'Add Layer' and select 'Add Vector Layer'. This will open a window allowing you to browse and choose the .shp file you will re-project (see below).  

  b. Open the directory of the first layer (this is the boundary layer 0) and select the shape file. Its name is …adm0.shp. Click Open. A new window may appear at this point, showing you the available Coordinate Reference System. If it does not, don't be alarmed. This same step can be manually completed by right clicking on the layer (under Layers Panel on the left side) and selecting 'Save As'. 

c. Make sure it is WSG84 / Authority ID EPSG: 4326 and click OK as shown below:

d. Open menu Layer and select Save as. In the opened window, click Browse to choose the directory where your GML file will be stored (shown below).

 

Make the same steps with all available shape files which contains the layers with geometries of the regions, districts, municipalities of your chosen country. Do not forget to save your project files upon closing QGIS program. They might be necessary in case you occasionally delete your GML files.

Step 4: Adjustment of GML files for their recognition by DHIS2 importer

The next steps are of a prime importance because they will prepare your GML files for the import into DHIS2. GML files are of XML file format and can be edited with any text processing program, such as Notepad.

Each GML file contains coordinates and names of organization units existing in a certain layer (regions, districts, municipalities). Coordinates of org units contained in the GML file will be imported and recognized by DHIS2 only if they are already created in DHIS 2. For example, a GML file of a country X contains 50 districts, but in DHIS2 the user has created 4 districts. Therefore, upon the import of the GML, DHIS2 will recognize and import the coordinates of 4 districts only.

In addition, if you have created a certain number of org units in DHIS2 as districts, but in GML file same names are determined as regions, the import of their coordinates might not be successful. Therefore, you must pay attention to the exact level of the org units listed in the GML file and their levels in DHIS 2.

The names in the GML file should match the names created in DHIS2 Orgunit hierarchy.

Very important: The importer of DHIS2 looks in the GLM file for the tag “ogr:NAME” in order to access the name of an organization unit. However, the GML file you have created from QGIS program contains many tags that determine an org unit and they all contain additional symbols that practically prevents DHIS 2 importer to access the orgunit. Therefore, you have to find where the organization unit name that is stored in the GML file and rename it to “ogr:NAME”. As it was mentioned above, the name should be exactly the name as in DHIS2 database, so pay attention to the spelling as well.

The following examples will describe the way such revisions can be made with all layers, starting with Layer 0 (boundary of a country), then Layer 1 (Country Provinces) and Layer 2, etc. One GML file must be uploaded corresponding to each OrgUnit Level in DHIS2

Let’s open the GML file, Layer 0 - the country’s boundary which in this example is Canada (see below). You will find a description of the polygon outlining the country’s boundary. There are a few tags that determine the name of Canada as an Org unit. However, you see that all the tags have additional abbreviations (_ISO, _FAO, _LOCAL, etc.). These abbreviations will prevent the importer of DHIS 2 to recognize the name of the Org unit. Therefore, choose one of the tags, for example <ogr:NAME_ENGLI>Canada</ogr:NAME_ENGLI> and revise it to <ogr:NAME>Canada</ogr:NAME>. You must edit only one of all the tags. Otherwise there will be duplication of the name.

Once you edit the above raw, save and close the file. This layer 0 is ready for import into DHIS 2.

Next: level 1 (a part of the GML file is shown below) defines all provinces in Canada. Do not forget that each country has unique administrative hierarchy. In this example layer 1 comprises Provinces. They are 13 in total.

Steps:

In the example below you will see NAME tags of Org units which belongs to Layer 0 and to Layer 1:

PARTS OF LAYER 1 GML FILE

Proceed with all tags of Org units that belong to Layer 1. In this example they are 27. This means that you have to make 27 changes as it is shown above.

All remaining tags, such as ogr:HASC_1; ogr:CCN_1; or what so ever remain unchanged.

When you finish, save and close the file. Your Layer 1 GML file is ready for import into DHIS 2. 

Additional Layers/OrgUnit Levels:

In case your chosen country has got additional SHAPE FILE layers, you have to follow these same logical steps: 

FOR LAYER 2 CHANGE THE NAME TAGS OF THE ORG UNITS THAT BELONG TO LAYER 2 ONLY. IT WILL LOOK LIKE:

<ogr:NAME_3>XYZ</ogr:NAME_3>

CHANGE IT TO

<ogr:NAME>XYZ</ogr:NAME>

 

Step 5: Import of GML files into DHIS2

a. Open Import – Export Application

b. Choose GML Import

  c. Click on “Choose file”. Select the first GML (layer 0) containing your country’s boundary. Select “Yes” as a Dry run.

d. Click Import. Wait until you get the following message:

Click on Display import summary. If the import is successful, you will get the following message:

e. Repeat this step for the import of all other layers. Depending on the existing Org units in your DHIS 2 same number of imported units should be recognized by DHIS 2.

Troubleshooting :

In case you get an error message of the type:

Look at the Report description to see the reason of rejection.

Then:

1. check again if the names of org units in your DHIS2 match the names in your GML

2. check the tags that define the types of your org units

3. In case the error message appears again, try to re-project your shape files by repeating the steps described in "Exporting shape files and creating GML files”.

4. Consult with DHIS2 expert.