Setting up for a new country
Geodata
Geodata (e.g. administrative borders as polygons, health facilities as points, roads and rivers as lines) are often available in the ESRI "shapefile" format, which consists of at least 3 files: .shp, .shx., and .dbf. The dBase (.dbf) can be opened with a normal spreadsheet program.
Mapping shapefiles to orgunits
There has to be a column in the .dbf file which acts as an identifier, a so called "geocode". With administrative boundaries, this is often also called "levelid" (LVLID).
In other words, one shapefile corresponds to one OrgUnit level (e.g. Country, Province, District, Facility).
To link each shapefile with the DHIS 2, the content of the geocode/LVLID column in the .dbf file must be entered in the corresponding orgunit's geocode field in the DHIS 2 organisationunit table. This can be a relatively cumbersome operation, which is best done by matching on name strings through linking the tables into database GUI tools such as MS Access or OpenOffice Base. Unfortunately, spellings often deviate quite dramatically, so quite extensive manual manipulations are needed.
Once you have aligned the names, you can update using a query, something like this:
UPDATE organisationunit SET geocode="<shapefile.geocode>" WHERE organsationunit.name=<shapefile.name>
However, the easiest way to achieve both the mapping and establishing the orgunit hierarchy is by importing everything from the WHO web service. This import functionality is an extension to the current orgunit module in DHIS2 and exists as a beta version in the following code repository location:
branches/dhis-web-shapefile-import. This module will be integrated into the main code shortly.
Geoserver
First, the shapefiles (all parts) must be put in a folder: tomcat\webapps\geoserver\data\data\<SHORT NAME OF YOUR COUNTRY>. Then, you must create the appropriate XML settings. This can be done manually, though many will prefer the Geoserver web interface.
Manual XML editing
Here's a Python script can do these things
In \tomcat\webapps\geoserver\data\catalog.xml, add an entry like this:
<datastore id = "sl_adm1" enabled = "true" namespace = "who" >
<connectionParams >
<parameter name = "charset" value = "ISO-8859-1" />
<parameter name = "url" value = "file:data/who/sl/admin1.shp" />
<parameter name = "namespace" value = "who" />
</connectionParams>
</datastore>
Here, you only need to substitute the ID to be unique and provide the URL of your shapefile.
In \tomcat\webapps\geoserver\data\featureTypes, make a new folder with the name <DATASTORE_ID>_<SHAPEFILE_NAME>
Inside this folder, create a file info.xml with the following content:
<featureType datastore = "sl_adm0" >
<name>admin0</name>
<!--
native wich EPGS code for the FeatureTypeInfoDTO
-->
<SRS>4326</SRS>
<SRSHandling>0</SRSHandling>
<title>admin0_Type</title>
<abstract>Generated from sl_adm0</abstract>
<wmspath>/</wmspath>
<numDecimals value = "8" />
<keywords>admin0, sl_adm0</keywords>
<latLonBoundingBox dynamic = "false" maxx = "-10.284239768981934" maxy = "10.0" minx = "-13.307629585266113" miny = "6.928689002990723" />
<nativeBBox dynamic = "false" maxx = "-10.284239768981934" maxy = "10.0" minx = "-13.307629585266113" miny = "6.928689002990723" />
<!--
the default style this FeatureTypeInfoDTO can be represented by.
at least must contain the "default" attribute
-->
<styles default = "adm_style" />
<cacheinfo enabled = "false" maxage = "" />
<maxFeatures>0</maxFeatures>
</featureType>
The tricky part here is the latLonBoundingBox and nativeBBox which have the same maxx, maxy, minx and miny. The values of these can be found with the Geoserver GUI, but also through most GIS desktop tools, such as in Envelope seen in the OpenJump menu Tools->QA->LayerStatistics.
You can find the right coordinate values on the Bounding box page.
Web GUI
After placing the geoserver.war in tomcat/webapps, go to:
You can see the currently registered shapefiles by clicking on Demo and then Map Preview, which will take you to
Click on Welcome, then Config. You must now log in. Click on config again, then Data > DataStores.
Click on New, and select Shapefile in the combobox. Give your new data a unique name (e.g. tz_adm2).
In the next screen, select a namespace (you can define your own). The important field here is the url, which should look like this:
[file:data/]<Name of your new folder>/<Name of your shapefile>.shp
In the next screen, click on Create new SLD (Styled Layer Descriptor). It doesn't matter what display selections you make for the SLD. Just select a name field, a text color, polygon color and outline color (assuming you are working with a polygon layer). Then click on Apply Style and then Finished, which will take you back to the previous screen. Select your new SLD in the combobox. In the SRS field, type "4326" (this is for lat/lon projection). Ignore the Lookup SRS button.
Click on Generate, and then scroll down to Submit at the bottom. After Submit, click on the Apply button in the upper left corner, and then on Save.
Now click on Welcome > Demo >Map Preview, and then click on your newly registered FeatureType to see the map.
In the application
At the bottom of the file tomcat\webapps\oh\WEB-INF\classes\application.xml, add an entry like the one below for each new layer you create:
<entry key="who:who:tz_adm2" value="http:/>
In tomcat\webapps\oh\WEB-INF\classes\application.xml\mapping.xml, change the follwing line to match the name of your new layer:
<entry key="[Location].[District]" value="who:tz_adm2"/>
After restarting tomcat, you should now be able to see your shapefile in the application (you may have to zoom out or pan). In order to see your new shapefile directly, adjust the center coordinate and zoom level. This is done in tomcat\webapps\oh\js\openhealth\mapping\MapController.js
Search for "lonlat". The values should be changed to a value near the center of what you see in the ideal positioning of your map in the application (the coordinates are displayed in the lower left corner when move your mouse over the map). You may also want to adjust the zoom parameter one or two notches (depending on the size of your shapefile/country).
Import metadata from online data dictionary
(data elements, datasets, indicator definitions etc from the online demo/repository)
BIRT
OpenHealth
Rename indicators and data element shortnames to not include characters like '<' and '-'
These characters are not supported in the prototype version of openhealth.
Populate the data mart tables (NOT UPDATED)
- datasources.xml must point to the appropriate database
- Use the DHIS 2 datamart module export GUI to populate three tables:
- aggregateddatavalue
- aggregatedindicatorvalue
In the export GUI, select data elements and indicators (as well as orgunits and periods)
Create database views
Your cubes will need a few views to fetch meta data names (and not IDs) from the data mart tables.
Insert views for each orgunit level you need reports from, and for data elements, indicators and periods. Copy and paste these openhealth views.
One troubleshooting tip when running into problems with your openhealth data is to check the contents of these views after populating the data mart. If they are empty the OLAP tables will also be empty....
Cubes
A cube defines dimensions based on the available data in the fact tables and defined in a file called cubes.xml
The cubes.xml file must be located in WEB-INF/classes and must be referenced in the datasources.xml file located in the root of the exploaded war file.
Copy and paste cube definitions from this page to your cubes.xml file.
NOTE:The indicator measure field should be specified as a calculated field Factor / *(numerator/denominator)
You can inspect your cube like this:
http:http:
[All%20Locations].[SLP000000000000000000],[Disease].[Disease].Members,[Time].[All%20Times]&aggregate=[Age+Group].[Age+Group],[Location].[District],[Time].[Month]&filter=
[Indicator].[Number%20Of%20Cases]&mapType=chloropleth&layer=axis0:[Indicator].[Number%20of%20Cases],[Age%20Group].[All%20Age%20Groups],[Gender].[All%20Genders].
[Female],axis1:[Location].[District],[Disease].[All%20Diseases].[AFP],[Time].[All%20Times]&mapType=chloropleth&flavor=png
You can also inspect it by opening DataEntry and click on any form. Then you can modify the url to point to one of your cubes and list your dimensions. If the dimensions are listed with the possible values your cube is ok, if not you should look for exeptions/errors in the tomcat log/console and in the firebug plugin.
Openhealth views (URLs)
To view the data defined in your cubes you need to specify URLS that are "pseudu-MDX" queries. These URLS are called views in the DHIS2+OH module called Data Analysis.
Copy and paste views from this page. Remember to replace the geocode that references a specific orgunit as in [Location].[SL00000000000].
Checking where there is data in a DHIS database
Some queries which give a good indication:
Periods with data (not listing OnChange)
select startdate, periodtype.name, count(*)
from (datavalue natural join period) natural join periodtype
group by startdate, periodtype.name
having periodtype.name not like 'OnChange'
order by count(*) desc;
Dataelementgroups with more than 100 observations
select deg.name, count(*)
from ((datavalue inner join dataelement AS de on datavalue.dataelementid=de.dataelementid)
inner join dataelementgroupmembers as degm on de.dataelementid=degm.dataelementid)
inner join dataelementgroup deg on deg.dataelementgroupid=degm.dataelementgroupid
group by deg.name
having count(*) > 100
order by count(*) desc;
OU3 (Districts) with more than 100 observations
select ou3.shortname, count(*)
from (datavalue inner join organisationunit AS ou4 on datavalue.sourceid=ou4.organisationunitid)
inner join organisationunit AS ou3 on ou4.parentid=ou3.organisationunitid
group by ou3.shortname
having count(*) > 100
order by count(*) desc;
Several instances on the same server
First, you need to compile several versions of DHIS 2 with different names for the DHIS2_HOME and OPENHEALTH_HOME environment variables. You set the names of these variables in these two beans.xml files:
trunk\dhis-2\dhis-support\dhis-support-external\src\main\resources\META-INF\dhis\beans.xml
trunk\dhis-2\dhis-services\dhis-service-reporting\src\main\resources\META-INF\dhis\beans.xml
