dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #16864
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 491: Updated installation and gis chapters
------------------------------------------------------------
revno: 491
committer: Lars Helge Overland <larshelge@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Tue 2012-04-10 19:02:54 +0200
message:
Updated installation and gis chapters
modified:
src/docbkx/en/dhis2_implementation_guide_installation.xml
src/docbkx/en/dhis2_user_man_creating_gis.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/docbkx/en/dhis2_implementation_guide_installation.xml'
--- src/docbkx/en/dhis2_implementation_guide_installation.xml 2012-03-27 12:59:43 +0000
+++ src/docbkx/en/dhis2_implementation_guide_installation.xml 2012-04-10 17:02:54 +0000
@@ -8,12 +8,12 @@
<para>This chapter provides a guide for setting up the above technology stack. It should however be read as a guide for getting up and running and not as an exhaustive documentation for the mentioned environment. We refer to the offical Ubuntu, PostgreSQL and Tomcat documentation for in-depth reading.</para>
<section>
<title>Server setup</title>
- <para>This section describes how to set up a server instance of DHIS 2 on Ubuntu 10.04 64 bit with PostgreSQL as database system and Tomcat as Servlet container. The term <emphasis role="italic">invoke</emphasis> refers to executing a given command in a terminal. You can find the terminal in <emphasis role="italic">Applications</emphasis> - <emphasis role="italic">Accessories</emphasis> - <emphasis role="italic">Terminal</emphasis>.</para>
+ <para>This section describes how to set up a server instance of DHIS 2 on Ubuntu 10.04 64 bit with PostgreSQL as database system and Tomcat as Servlet container. The term <emphasis role="italic">invoke</emphasis> refers to executing a given command in a terminal. </para>
<para>For a national server the recommended configuration is a quad-core 2 Ghz processor or higher and 12 Gb RAM or higher. Note that a 64 bit operating system is required for utilizing more than 4 Gb of RAM, the Ubuntu 10.04 64 bit edition is thus recommended. </para>
- <para>For this guide we assume that 4 Gb RAM is allocated for PostgreSQL and 7 GB RAM is allocated for Tomcat. <emphasis role="italic">If you are running a different configuration please adjust the suggested values accordingly!</emphasis> The steps related to performance tuning are optional and can be done at a later stage.</para>
+ <para>For this guide we assume that 4 Gb RAM is allocated for PostgreSQL and 7 GB RAM is allocated for Tomcat. <emphasis role="italic">If you are running a different configuration please adjust the suggested values accordingly!</emphasis> The steps marked as <emphasis role="italic">optional</emphasis>, like the step for performance tuning, can be done at a later stage.</para>
<para><emphasis role="bold">Create new user (optional)</emphasis></para>
- <para>You might want to create a dedicated user for running DHIS - it is not recommended to run as the root user. Create a new user called dhis by invoking <code>useradd -d /home/dhis -m dhis -s /bin/bash</code> Then make the user able to perform operations temporarily as root user by invoking <code>adduser dhis admin</code> Then invoke <code>passwd dhis</code> to set the password for your account. Make sure you set a strong password with at least 15 random characters. You might want to disable remote login for the root account for improved security by invoking<emphasis role="italic"> sudo passwd -l root</emphasis></para>
- <para><emphasis role="bold">Operating system kernel tuning (optional)</emphasis></para>
+ <para>You might want to create a dedicated user for running DHIS - it is not recommended to run as the root user. Create a new user called dhis by invoking <code>useradd -d /home/dhis -m dhis -s /bin/bash</code> Then make the user able to perform operations temporarily as root user by invoking <code>adduser dhis admin</code> If there is no admin group you must create it first by invoking <code>groupadd admin</code> Then invoke <code>passwd dhis</code> to set the password for your account. Make sure you set a strong password with at least 15 random characters. You might want to disable remote login for the root account for improved security by invoking<emphasis role="italic"> sudo passwd -l root</emphasis></para>
+ <para><emphasis role="bold">Operating system kernel tuning</emphasis></para>
<para>These settings are optional except for the shared memory setting which is required for PostgreSQL memory allocation. Open the kernel configuration file by invoking <code>sudo nano /etc/sysctl.conf</code> At the end of the file add the following lines and save.</para>
<screen>kernel.shmmax = 1073741824
net.core.rmem_max = 8388608
@@ -22,10 +22,15 @@
<para><emphasis role="bold">Install Java</emphasis></para>
<para>Install Java by invoking <code>sudo apt-get install openjdk-7-jdk</code></para>
<para><emphasis role="bold">Install PostgreSQL</emphasis></para>
- <para>Install PostgreSQL by invoking <code>sudo apt-get install postgresql-9.1</code></para>
- <para>Set the password for the postgres Unix user by invoking <code>sudo passwd postgres</code> and following the instructions. Switch to the postgres user by invoking <code>su postgres</code> and entering the password when prompted.</para>
- <para>Log into psql by invoking <code>psql</code> Create a user called <emphasis role="italic">dhis</emphasis> by invoking <code>create user dhis with password '<dhis>'</code> Replace the password <emphasis role="italic"><dhis></emphasis> with something secure. Create a database by invoking <code>create database dhis2 with owner dhis encoding 'utf8'</code> Exit psql by invoking <code>\q</code> Return to your session by invoking <code>exit</code> You now have a PostgreSQL user called <emphasis role="italic">dhis</emphasis> and a database called <emphasis role="italic">dhis2</emphasis>.</para>
- <para>Do basic performance tuning by increasing the operating system kernel shared memory by opening file /etc/sysctl.conf and adding the line <emphasis role="italic">kernel.shmmax = 1073741824</emphasis> at the end of it. Make the change take effect by invoking <code>sysctl -p</code> Then open file <emphasis role="italic">/etc/postgresql/8.4/main/postgresql.conf</emphasis> and set the following properties: </para>
+ <para>Install PostgreSQL by invoking <code>sudo apt-get install postgresql-8.4</code></para>
+ <para>First configure client authentication by opening the following file by invoking</para>
+ <para><code>sudo nano /etc/postgresql/8.4/main/pg_hba.conf</code></para>
+ <para>Scroll down towards the end of the file and replace the word <emphasis role="italic">peer</emphasis> with <emphasis role="italic">md5</emphasis> so that it reads</para>
+ <screen>local all all md5</screen>
+ <para>Switch to the postgres user by invoking <code>sudo su postgres</code> Log into psql by invoking <code>psql</code> Create a user called <emphasis role="italic">dhis</emphasis> by invoking <code>create user dhis with password '<dhis>';</code> Replace the password <emphasis role="italic"><dhis></emphasis> with something secure. Create a database by invoking <code>create database dhis2 with owner dhis encoding 'utf8';</code> Exit psql by invoking <code>\q</code> Return to your session by invoking <code>exit</code> You now have a PostgreSQL user called <emphasis role="italic">dhis</emphasis> and a database called <emphasis role="italic">dhis2</emphasis>.</para>
+ <para>Do performance tuning by opening the following file by invoking </para>
+ <para><code>sudo nano /etc/postgresql/8.4/main/postgresql.conf</code></para>
+ <para>and set the following properties:</para>
<para><code>shared_buffers = 512MB</code></para>
<para>Determines how much memory PostgreSQL can use for caching of query data. Is set too low by default since it depends on kernel shared memory which is low on some operating systems.</para>
<para><code>effective_cache_size = 3500MB</code></para>
=== modified file 'src/docbkx/en/dhis2_user_man_creating_gis.xml'
--- src/docbkx/en/dhis2_user_man_creating_gis.xml 2011-12-12 10:02:05 +0000
+++ src/docbkx/en/dhis2_user_man_creating_gis.xml 2012-04-10 17:02:54 +0000
@@ -1,99 +1,97 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
-<chapter>
- <title>Setting up GIS</title>
- <section>
- <title>Context</title>
- <para>Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are often distributed in proprietary formats and will need to be converted to a format which DHIS2 uses. ESRI shapefiles are the most common geospatial vector data format for desktop applications. You might find shapefiles for your country <ulink url="http://www.diva-gis.org/gdata";>here</ulink> or in many other geospatial data repositories on the web. Some amount of work needs to be done in order to use these coordinates in DHIS 2 GIS, namely transforming the data into a suitable format and ensuring the name which are contained in the geospatial data match exactly with the names of the organization units which they should be matched to. </para>
- <para>If you go to the organisation unit module and edit one of the units, you can see a text field called Coordinates. Here you may fill in its coordinates directly (geojson format) which is useful if you just want to update a couple of units.</para>
- <para>An example point/facility coordinate:</para>
- <para><programlisting><userinput>[29.341,-11.154]</userinput></programlisting></para>
- <para>An example polygon/area coordinates string:</para>
- <para><programlisting><userinput>[[[[29.343,-11.154],[28.329,-11.342],[28.481,-10.239],[29.833,-10.412]]]]</userinput></programlisting></para>
- <para>However, if you are going to e.g. add coordinates for all units at a certain level you don't want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.<important>
- <para>The only co-ordinate reference system supported by DHIS2 is EPSG:4326, also known as geographic longitude/latitude. Coordinates must be stored with the longitude (east/west position) proceeding the latitude (north/south position). If your vector data is in a different CRS than EPSG 4326, you will need to reproject the data first before importing into DHIS2. </para>
- </important></para>
- </section>
- <section id="gisSetup">
- <title>Importing coordinates</title>
- <para>Step 1 - Simplify/generalize your geographical data</para>
- <para>The boundaries in geographical data files are usually very accurate, too much so for the needs of a web-based GIS. This usually does not affect the performance when using GIS files on a a local system, but it is usually necessary to optimize the geographical data for the web-based GIS system of DHIS2. All geographical data needs to be downloaded from the server and rendered in a browser, so if the data is overly complex, the performance of the DHIS2 GIS will be negatively impacted. This optimization process can be described as follows:</para>
- <para><simplelist>
- <member>Coordinates: The number of significant decimal digits (e.g. 23.02937874993774) should be shortened to fewer digits (e.g. 23.03). Although this will result in some inaccuracies on the map, given the usual scale at which maps in DHIS2 are produced (> 1:50,000), the loss of precision should not be noticeable. Normally, no more than four significant digits after the decimal point should be necessary.</member>
- <member>Polygons: In addition to shortening the number of significant digits, the actual number of points should also be reduced to an optimal level. Finding this optimal level may take a bit of experimentation. Decreasing the precision of the points as well as the number of points through generalization, will lead to degradation of the polygon. However, after a bit of experimentation, an optimal level of generalization can be found, where the accuracy of the polygon is visually acceptable, and the performance of the GIS is optimal. </member>
- </simplelist></para>
- <para>For polygons, we need to make the boundary lines less detailed by removing some of the line points. One possible method is the use of <ulink url="http://www.mapshaper.com/test/demo.html";>MapShaper</ulink> which is an online tool which can be used to generalize geographical data. To use MapShaper, simply upload your shapefile to the site. Then, at the center bottom you see a slider that starts at 0%. It is usually acceptable to drag it up to about 80%. In the left menu you can check "show original lines" to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click "export" in the top right corner. Then check the first of the four options called "Shapefile - polygons", click "create" and wait for the download buttons to appear. Now, download the two files to your local computer (being sure to rename the file so that you do not overwrite your existing, original data). Move on to the next step with your new simplified shapefile.
- </para>
- <para>Step 2 - Convert the shapefile to GML</para>
- <para>
- The recommended tool for geographical format conversions is called "ogr2ogr". This should be available for most Linux distributions ("<command>sudo apt-get install gdal-bin"</command>). For Windows, go to <ulink url="http://fwtools.maptools.org/";>http://fwtools.maptools.org/ </ulink>and download "FWTools", install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this <ulink url="http://www.epsg-registry.org/";>site</ulink>. If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that <command>ogr2ogr</command> can determine the input spatial reference system. You can determine the spatial reference system by executing the following command.</para>
- <para><programlisting><userinput>ogrinfo -al -so filename.shp</userinput></programlisting></para>
- <para>Assuming that the projection is reported to be EPSG:27700 by <command>ogrinfo</command>, we can transform it to EPSG:4326 by executing the following command.<programlisting><userinput> ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp </userinput></programlisting></para>
- <para>If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by executing the following command. </para>
- <para><programlisting><userinput>ogr2ogr -f GML filename.gml filename.shp</userinput></programlisting></para>
- <para> You will find the created GML file in the same folder as the shapefile.
- </para>
- <para>Step 3 - Prepare the GML file</para>
- <para>
- Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a <gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are just going to import their coordinates. In order to do this DHIS 2 will match the name of the feature members to the organisation unit names in the database. To get the name of the feature members in the GML file the importer will look for a property called "ogr:Name". Figure out what property that is holding the name of the feature members (could be "ogr:DISTRICT_NAME", "ogr:NAME_1" or whatever, this differs from shapefile to shapefile) and rename it to "ogr:Name". Ensure that both the start and the end tags are renamed properly. They are supposed to look like e.g.: <ogr:Name>Moyamba District</ogr:Name>
- </para>
- <para>
- Note that the name of the feature members in the GML file must be spelled exactly the same as the organisation units in the database. Otherwise the importer will not recognize it and thus not transfer any coordinates. E.g. "Moyamba" in the GML file might be called "Moyamba District" in the database. Creative use of the "rename all" function in the text editor is usually of great help in these situations, as you do not want to edit numerous feature members manually. Have a brief look at the names and compare them to the names in the database. If they seem to match fairly good, it is about time to do a preview in the import-export module.
- </para>
- <para>
- Go to Services -> Import-Export, select "Preview", select the GML file and click "Import". Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the "discard all" button below the list and then the "Import all" button above the list.
- </para>
- <para>
- If the import process completes successfully, you should now be able to utilize the geographical data in the DHIS2 GIS. If not, check the log for hints and look for common errors such as:
- </para>
- <para>- Name duplicates in the GML file. The name column in the database is unique and does not accept two organisation units with the same name.</para>
- <para>- The "shortname" column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.</para>
- <para>- Special name characters in the GML file. Be sure to convert these to appropirate XML equivalents or escape sequences.</para>
- </section>
- <section>
- <title>Administering the GIS module</title>
- <section id="gisOverlay">
- <title>Register overlays</title>
- <para>Overlays are geographical layers that do not have any direct linkage
- to data in the database. Examples include roads, rivers, airports, ports,
- and other geographical information that you may want to display on your
- map, but that is not necessarily linked to data contained in the DHIS
- database. The <guimenu>Register Overlay</guimenu> panel will allow you to
- add new layers and determine how they will be represented visually on the
- map. </para>
- <itemizedlist>
- <listitem>
- <para><guilabel>Display name: </guilabel>Represents your overlay in
- the layer tree in the upper right corner.</para>
- </listitem>
- <listitem>
- <para><guilabel>Map source file: </guilabel>The GeoJSON file
- name.</para>
- </listitem>
- <listitem>
- <para><guilabel>Fill color: </guilabel>Decides the fill color if the
- layer is a polygon layer. </para>
- </listitem>
- <listitem>
- <para><guilabel>Fill opacity: </guilabel>Select an opacity level
- between 0 (invisible) and 1 (solid).</para>
- </listitem>
- <listitem>
- <para><guilabel>Stroke color: </guilabel>The stroke color over lines
- and polygon borders.</para>
- </listitem>
- <listitem>
- <para><guilabel>Stroke width: </guilabel>Select a stroke width between
- 0 and 4.</para>
- </listitem>
- </itemizedlist>
- <section>
- <title>Copying files to the DHIS application</title>
- <para>Currently, your GeoJSON files should be placed in the
- DHIS2_HOME/geojson of your DHIS application to be accessible to the GIS
- module. If the GeoJSON directory does not exist, you will need to create
- it manually and copy your GeoJSON files there.</para>
- </section>
- </section>
- </section>
-</chapter>
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<chapter>
+ <title>Setting up GIS</title>
+ <section>
+ <title>Context</title>
+ <para>Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are often distributed in proprietary formats and will need to be converted to a format which DHIS2 uses. ESRI shapefiles are the most common geospatial vector data format for desktop applications. You might find shapefiles for your country <ulink url="http://www.diva-gis.org/gdata";>here</ulink> or in many other geospatial data repositories on the web. Some amount of work needs to be done in order to use these coordinates in DHIS 2 GIS, namely transforming the data into a suitable format and ensuring the name which are contained in the geospatial data match exactly with the names of the organization units which they should be matched to. </para>
+ <para>If you go to the organisation unit module and edit one of the units, you can see a text field called Coordinates. Here you may fill in its coordinates directly (geojson format) which is useful if you just want to update a couple of units.</para>
+ <para>An example point/facility coordinate:</para>
+ <para><programlisting><userinput>[29.341,-11.154]</userinput></programlisting></para>
+ <para>An example polygon/area coordinates string:</para>
+ <para><programlisting><userinput>[[[[29.343,-11.154],[28.329,-11.342],[28.481,-10.239],[29.833,-10.412]]]]</userinput></programlisting></para>
+ <para>However, if you are going to e.g. add coordinates for all units at a certain level you don't want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.<important>
+ <para>The only co-ordinate reference system supported by DHIS2 is EPSG:4326, also known as geographic longitude/latitude. Coordinates must be stored with the longitude (east/west position) proceeding the latitude (north/south position). If your vector data is in a different CRS than EPSG 4326, you will need to reproject the data first before importing into DHIS2. </para>
+ </important></para>
+ </section>
+ <section id="gisSetup">
+ <title>Importing coordinates</title>
+ <para>Step 1 - Simplify/generalize your geographical data</para>
+ <para>The boundaries in geographical data files are usually very accurate, too much so for the needs of a web-based GIS. This usually does not affect the performance when using GIS files on a a local system, but it is usually necessary to optimize the geographical data for the web-based GIS system of DHIS2. All geographical data needs to be downloaded from the server and rendered in a browser, so if the data is overly complex, the performance of the DHIS2 GIS will be negatively impacted. This optimization process can be described as follows:</para>
+ <para><simplelist>
+ <member>Coordinates: The number of significant decimal digits (e.g. 23.02937874993774) should be shortened to fewer digits (e.g. 23.03). Although this will result in some inaccuracies on the map, given the usual scale at which maps in DHIS2 are produced (> 1:50,000), the loss of precision should not be noticeable. Normally, no more than four significant digits after the decimal point should be necessary.</member>
+ <member>Polygons: In addition to shortening the number of significant digits, the actual number of points should also be reduced to an optimal level. Finding this optimal level may take a bit of experimentation. Decreasing the precision of the points as well as the number of points through generalization, will lead to degradation of the polygon. However, after a bit of experimentation, an optimal level of generalization can be found, where the accuracy of the polygon is visually acceptable, and the performance of the GIS is optimal. </member>
+ </simplelist></para>
+ <para>For polygons, we need to make the boundary lines less detailed by removing some of the line points. One possible method is the use of <ulink url="http://mapshaper.com/test/MapShaper.swf";>MapShaper</ulink> which is an online tool which can be used to generalize geographical data. To use MapShaper, simply upload your shapefile to the site. Then, at the center bottom you see a slider that starts at 0%. It is usually acceptable to drag it up to about 80%. In the left menu you can check "show original lines" to compare the result and you may want to give a different simplification method a try. When you are happy with the result, click "export" in the top right corner. Then check the first of the four options called "Shapefile - polygons", click "create" and wait for the download buttons to appear. Now, download the two files to your local computer (being sure to rename the file so that you do not overwrite your existing, original data). Move on to the next step with your new simplified shapefile.
+ </para>
+ <para>Step 2 - Convert the shapefile to GML</para>
+ <para>
+ The recommended tool for geographical format conversions is called "ogr2ogr". This should be available for most Linux distributions <command>sudo apt-get install gdal-bin</command>. For Windows, go to <ulink url="http://fwtools.maptools.org/";>http://fwtools.maptools.org/ </ulink>and download "FWTools", install it and open up the FWTools command shell. During the format conversion we also want to ensure that the output has the correct coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more detailed reference of geographic coordinates, please refer to this <ulink url="http://www.epsg-registry.org/";>site</ulink>. If you have already reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there is no need to explicitly define the output coordinate system, assuming that <command>ogr2ogr</command> can determine the input spatial reference system. Note that most shapefiles are using the EPSG:4326 system. You can determine the spatial reference system by executing the following command.</para>
+ <para><programlisting><userinput>ogrinfo -al -so filename.shp</userinput></programlisting></para>
+ <para>Assuming that the projection is reported to be EPSG:27700 by <command>ogrinfo</command>, we can transform it to EPSG:4326 by executing the following command.<programlisting><userinput>ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp </userinput></programlisting></para>
+ <para>If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by executing the following command. </para>
+ <para><programlisting><userinput>ogr2ogr -f GML filename.gml filename.shp</userinput></programlisting></para>
+ <para> You will find the created GML file in the same folder as the shapefile.
+ </para>
+ <para>Step 3 - Prepare the GML file</para>
+ <para>Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a <gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are just going to import their coordinates. In order to do this DHIS 2 will match the name of the feature members to the organisation unit names in the database. To get the name of the feature members in the GML file the importer will look for a property called "ogr:Name". Figure out what property that is holding the name of the feature members (could be "ogr:DISTRICT_NAME", "ogr:NAME_1" or whatever, this differs from shapefile to shapefile) and rename it to "ogr:Name". Ensure that both the start and the end tags are renamed properly. They are supposed to look like e.g.: <ogr:Name>Moyamba District</ogr:Name>
+ </para>
+ <para>Note that the name of the feature members in the GML file must be spelled exactly the same as the organisation units in the database. Otherwise the importer will not recognize it and thus not transfer any coordinates. E.g. "Moyamba" in the GML file might be called "Moyamba District" in the database. Creative use of the "rename all" function in the text editor is usually of great help in these situations, as you do not want to edit numerous feature members manually. Have a brief look at the names and compare them to the names in the database. If they seem to match fairly good, it is about time to do a preview in the import-export module.
+ </para>
+ <para>
+ Go to Services -> Import-Export, select "Preview", select the GML file and click "Import". Look for new/updated organisation units. Our intention is to add coordinates to already existing organisation units in the database, so we want as many updates as possible and 0 new. Those listed as new will be created as root units and mess up the organisation unit trees in DHIS 2. If any listed as new, click the number and the organisation units in question will appear in the list below. If there are any slight misspellings compared to the organisation unit names in the database - fix them and do the preview again. Otherwise, click the "discard all" button below the list and then the "Import all" button above the list.
+ </para>
+ <para>
+ If the import process completes successfully, you should now be able to utilize the geographical data in the DHIS2 GIS. If not, check the log for hints and look for common errors such as:
+ </para>
+ <para>- Name duplicates in the GML file. The name column in the database is unique and does not accept two organisation units with the same name.</para>
+ <para>- The "shortname" column in the organisationunit table in your database has a too small varchar definition. Increase it to 100.</para>
+ <para>- Special name characters in the GML file. Be sure to convert these to appropirate XML equivalents or escape sequences.</para>
+ </section>
+ <section>
+ <title>Administering the GIS module</title>
+ <section id="gisOverlay">
+ <title>Register overlays</title>
+ <para>Overlays are geographical layers that do not have any direct linkage
+ to data in the database. Examples include roads, rivers, airports, ports,
+ and other geographical information that you may want to display on your
+ map, but that is not necessarily linked to data contained in the DHIS
+ database. The <guimenu>Register Overlay</guimenu> panel will allow you to
+ add new layers and determine how they will be represented visually on the
+ map. </para>
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Display name: </guilabel>Represents your overlay in
+ the layer tree in the upper right corner.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Map source file: </guilabel>The GeoJSON file
+ name.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Fill color: </guilabel>Decides the fill color if the
+ layer is a polygon layer. </para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Fill opacity: </guilabel>Select an opacity level
+ between 0 (invisible) and 1 (solid).</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Stroke color: </guilabel>The stroke color over lines
+ and polygon borders.</para>
+ </listitem>
+ <listitem>
+ <para><guilabel>Stroke width: </guilabel>Select a stroke width between
+ 0 and 4.</para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Copying files to the DHIS application</title>
+ <para>Currently, your GeoJSON files should be placed in the
+ DHIS2_HOME/geojson of your DHIS application to be accessible to the GIS
+ module. If the GeoJSON directory does not exist, you will need to create
+ it manually and copy your GeoJSON files there.</para>
+ </section>
+ </section>
+ </section>
+</chapter>
