DHIS2 End-user Manual

2.24
© 2006-2016
DHIS2 Documentation Team

Revision 2594

2016-11-23 11:04:16
Version 2.24

Warranty: THIS DOCUMENT IS PROVIDED BY THE AUTHORS ''AS IS'' AND

ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS MANUAL AND PRODUCTS MENTIONED HEREIN, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

License: Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.3 or any
later version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is
included in the source of this documentation, and is available here online: http://
www.gnu.org/licenses/fdl.html.
-->

ii
DHIS2 End-user Manual Contents

Table of Contents
About this guide ................................................................................................................... vii
1. Getting started with DHIS2 ................................................................................................ 1
1.1. Using the DHIS2 demo server ................................................................................. 1
1.2. Using the DHIS2 live package ................................................................................. 1
1.2.1. Starting the DHIS2 Live package .................................................................. 1
1.2.1.1. Prerequisites for DHIS2 Live ............................................................... 1
1.2.1.2. Starting up with a blank database ..................................................... 1
1.2.2. Downloading and installing the server version ............................................. 2
1.3. Logging on to DHIS2 ............................................................................................... 2
1.4. Logging out of DHIS2 .............................................................................................. 2
1.5. Quick intro to designing a DHIS2 database ............................................................ 3
1.5.1. The organisational hierarchy ........................................................................ 3
1.5.2. Data Elements .............................................................................................. 4
1.5.3. Datasets and data entry forms ..................................................................... 5
1.5.3.1. Data entry forms ................................................................................ 5
1.5.4. Validation rules ............................................................................................. 6
1.5.5. Indicators ...................................................................................................... 6
1.5.6. Report tables and reports ............................................................................. 6
1.5.7. GIS ................................................................................................................. 7
1.5.8. Charts and dashboard ................................................................................... 7
2. Data entry .......................................................................................................................... 9
2.1. Data entry with DHIS2 ............................................................................................ 9
2.1.1. Selecting the data entry form ...................................................................... 9
2.1.2. Entering data .............................................................................................. 10
2.1.3. Editing and deleting data ........................................................................... 11
2.1.4. Validating data in the form ......................................................................... 11
2.1.5. Off-line data entry ...................................................................................... 11
2.1.6. Multi-organisation unit data entry .............................................................. 12
3. Using Data Quality functionality ...................................................................................... 13
3.1. Overview of data quality checks ........................................................................... 13
3.2. Data quality checks ............................................................................................... 13
3.3. Running Validation Rule Analysis .......................................................................... 13
3.4. Std Dev Outlier Analysis ........................................................................................ 15
3.5. Min-Max Outlier Analysis ....................................................................................... 16
3.6. Follow-Up Analysis ................................................................................................. 16
4. Using reporting functionality ............................................................................................ 17
4.1. Reporting functionality in DHIS2 ........................................................................... 17
4.2. Using standard reports .......................................................................................... 17
4.3. Using dataset reports ............................................................................................ 18
4.4. Using resources ..................................................................................................... 19
4.5. Using reporting rate summary .............................................................................. 19
4.6. Using organisation unit distribution reports .......................................................... 20
5. Using the Pivot Table app ............................................................................................... 21
5.1. About the Pivot table app ..................................................................................... 21
5.2. Create a pivot table .............................................................................................. 21
5.2.1. Select dimension items ............................................................................... 21
5.2.2. Modify pivot table layout ............................................................................ 24
5.3. Change the display of your table .......................................................................... 25
5.4. Manage pivot table favorites ................................................................................. 26
5.4.1. Save a pivot table as a favorite ................................................................. 26
5.4.2. Open a favorite ........................................................................................... 26
5.4.3. Rename a favorite ...................................................................................... 26
5.4.4. Share an interpretation of a favorite .......................................................... 26
5.4.5. Modify sharing settings for a favorite ......................................................... 27

iii
DHIS2 End-user Manual Contents

5.4.6. Create a link to a favorite .......................................................................... 27

5.4.7. Delete a favorite ......................................................................................... 27
5.5. Download data from a pivot table ........................................................................ 27
5.5.1. Download table layout data format ............................................................ 27
5.5.2. Download plain data source format ............................................................ 28
5.5.3. Download a CSV format without rendering data in the web browser .......... 28
5.6. Embed a pivot table in an external web page ...................................................... 29
5.7. Visualize a pivot table data as a chart or a map .................................................. 29
5.7.1. Open a pivot table as a chart ..................................................................... 29
5.7.2. Open a pivot table selection as a chart ...................................................... 29
5.7.3. Open a pivot table as a map ...................................................................... 30
5.7.4. Open a pivot table selection as a map ....................................................... 30
5.8. Constraints and tips .............................................................................................. 30
6. Using the Data Visualizer app ......................................................................................... 31
6.1. Data Visualizer overview ....................................................................................... 31
6.2. Create a chart ....................................................................................................... 31
6.3. Select a chart type ................................................................................................ 31
6.4. Select dimension items ......................................................................................... 32
6.4.1. Select indicators ......................................................................................... 33
6.4.2. Select data elements .................................................................................. 33
6.4.3. Select reporting rates ................................................................................. 33
6.4.4. Select fixed and relative periods ................................................................ 33
6.4.5. Select organisation units ............................................................................ 34
6.4.6. Select additional dimension items .............................................................. 34
6.5. Select series, category and filter .......................................................................... 35
6.6. Change the display of your chart .......................................................................... 37
6.7. Download a chart as an image or a PDF ............................................................... 38
6.8. Download chart data source ................................................................................. 38
6.9. Manage chart favorites ......................................................................................... 40
6.9.1. Save a chart as a favorite .......................................................................... 40
6.9.2. Open a favorite ........................................................................................... 40
6.9.3. Rename a favorite ...................................................................................... 40
6.9.4. Overwrite a favorite .................................................................................... 41
6.9.5. Share a chart interpretation ....................................................................... 41
6.9.6. Modify sharing settings for a favorite ......................................................... 41
6.9.7. Delete a favorite ......................................................................................... 42
6.10. Embed charts in any web page .......................................................................... 42
6.11. Visualize a chart as a pivot table or a map ........................................................ 42
6.11.1. Open a chart as a pivot table ................................................................... 42
6.11.2. Open a chart as a map ............................................................................. 42
7. Using the GIS app ............................................................................................................ 43
7.1. About the GIS app ................................................................................................. 43
7.2. Create a new thematic map ................................................................................. 43
7.3. Manage event layer ............................................................................................... 44
7.3.1. Create or modify event layer ...................................................................... 44
7.3.2. Turn off cluster ........................................................................................... 45
7.3.3. Modify cluster style ..................................................................................... 45
7.3.4. Modify information in event pop-up windows ............................................. 45
7.3.5. Clear event layer ........................................................................................ 46
7.4. Manage facility layer ............................................................................................. 46
7.4.1. Create or modify facility layer .................................................................... 46
7.4.2. Search for an organisation unit .................................................................. 46
7.4.3. Clear facility layer ....................................................................................... 47
7.5. Manage boundary layer ......................................................................................... 47
7.5.1. Create or modify boundary layer ................................................................ 47
7.5.2. Search for an organisation unit .................................................................. 47
7.5.3. Navigate between organisation hierarchies ................................................ 48

iv
DHIS2 End-user Manual Contents

7.5.4. Clear boundary layer .................................................................................. 48

7.6. Manage thematic layer 1- 4 .................................................................................. 48
7.6.1. Create or modify a thematic layer ............................................................. 49
7.6.2. Filter values in a thematic layer ................................................................. 49
7.6.3. Search for an organisation unit .................................................................. 49
7.6.4. Navigate between organisation hierarchies ................................................ 49
7.6.5. Clear thematic layer ................................................................................... 50
7.7. Manage facilities in a layer ................................................................................... 50
7.7.1. Relocate a facility ....................................................................................... 50
7.7.2. Swap longitude and latitude of a facility .................................................... 50
7.7.3. Display facility information ......................................................................... 50
7.8. Manage Earth Engine layer ................................................................................... 51
7.8.1. Create or modify an Earth Engine layer ..................................................... 51
7.9. Manage map favorites ........................................................................................... 52
7.9.1. Save a map as a favorite ........................................................................... 52
7.9.2. Open a favorite ........................................................................................... 52
7.9.3. Rename a favorite ...................................................................................... 52
7.9.4. Overwrite a favorite .................................................................................... 53
7.9.5. Share a map interpretation ........................................................................ 53
7.9.6. Modify sharing settings for a favorite ......................................................... 53
7.9.7. Delete a favorite ......................................................................................... 54
7.10. Manage map legend sets .................................................................................... 54
7.10.1. Create a new legend set .......................................................................... 54
7.10.2. Change a legend set ................................................................................. 55
7.10.3. Delete a legend set .................................................................................. 55
7.10.4. Assign a legend set to indicator or data element ..................................... 55
7.11. Download a map as image ................................................................................. 55
7.12. Embed a map in an external web page .............................................................. 55
7.13. Search for a location ........................................................................................... 56
7.14. Measure distance and area in a map .................................................................. 56
7.15. Visualize a map as a pivot table or a chart ........................................................ 56
7.15.1. Open a map as a chart ............................................................................. 56
7.15.2. Open a map as a pivot table .................................................................... 56
8. Dashboards ...................................................................................................................... 57
8.1. Setting up the dashboard ...................................................................................... 57
8.2. Managing the Dashboard ...................................................................................... 58
8.3. Dashboard Sharing ................................................................................................ 58
8.4. Manage messages and feedback messages ......................................................... 59
8.4.1. About messages and feedback messages .................................................. 59
8.4.2. Create a message ....................................................................................... 60
8.4.3. Read a message ......................................................................................... 60
8.4.4. Create a feedback message ....................................................................... 60
8.4.5. Configure feedback message function ........................................................ 60
8.4.6. Manage feedback messages ....................................................................... 61
9. User profiles ..................................................................................................................... 63
9.1. User settings ......................................................................................................... 63
9.2. User profile ............................................................................................................ 63

v
About this guide

About this guide

The DHIS2 documentation is a collective effort and has been developed by the development
team and users. While the guide strives to be complete, there may be certain functionalities
which have been omitted or which have yet to be documented. This section explains some of
the conventions which are used throughout the document.

DHIS2 is a browser-based application. In many cases, screenshots have been included for
enhanced clarity. Shortcuts to various functionalities are displayed such as "Maintenance-
>Data administration". The "->" character indicates that you should choose "Maintenance"
and then click on "Data administration" in the menu which appears through the browser.

Different styles of text have been used to highlight important parts of the text or particular
types of text, such as source code. Each of the conventions used in the document are explained
below.

Note
A note contains additional information which should be considered or a reference to
more information which may be helpful.

Tip
A tip can be a useful piece of advice, such as how to perform a particular task more
efficiently.

Important
Important information should not be ignored, and usually indicates something which is
required by the application.

Caution
Information contained in these sections should be carefully considered, and if not
heeded, could result in unexpected results in analysis, performance, or functionality.

Warning
Information contained in these sections, if not heeded, could result in permanent data
loss or affect the overall usability of the system.

Program listings usually contain some type of computer code.

They will be displayed with a shaded background and a different font.

Commands will be displayed in bold text, and represent a command which would need to be
executed on the operating system or database.

Links to external web sites or cross references will be displayed in blue text, and underlined
like this..

Bibliographic references will displayed in square brackets like this [Store2007]. A full reference
can be found in the bibliography contained at the end of this document.

vii
Getting started with DHIS2 Using the DHIS2 demo server

Chapter 1. Getting started with DHIS2

1.1. Using the DHIS2 demo server

The DHIS2 team maintains a demonstration server at https://play.dhis2.org/demo. This is by
far the easiest way to try out DHIS2. Simply open the link in your web browser and login with
username = admin and password = district.

Note
All changes on this server are deleted each night, so do not save any important work on
this server. It is strictly for demonstration purposes on only!

1.2. Using the DHIS2 live package

1.2.1. Starting the DHIS2 Live package

The DHIS2 Live package is the easiest way to get started with DHIS2 on your local computer.
DHIS2 Live is appropriate for a stand-alone installation and demos. Simply download the
application from here. Once the file is downloaded, you can simply double-click the downloaded
file, and get started using DHIS2.

1.2.1.1. Prerequisites for DHIS2 Live

You must be sure that you have a current version of the Java Runtime installed on your machine.
Depending on your operating system, there are different ways of installing Java. The reader is
referred to this website for detailed information on getting Java installed.

1.2.1.2. Starting up with a blank database

The live package comes with a demo database just like what you see on the online demo (which
is based on the national Sierra Leone HMIS), and if you want to start with a blank system/
database and build up your own system then you need to do the following:

1) Stop DHIS2 live if it is already running. Right click on the tray icon and select Exit. The tray
icon is the green symbol on the bottom right of your screen (on Windows) which should say'
DHIS2 Server running' when you hover your mouse pointer over the icon.

2) Open the folder where the DHIS2 live package is installed and locate the folder called "conf".

3) In conf/ open the file called 'hibernate.properties' in a text editor (notepad or similar) and do
the following modification: locate the string 'jdbc:h2:./database/dhis2' and replace the 'dhis2'
part with any name that you want to give to your database (e.g. dhis2_test).

4) Save and close the hibernate.properties file.

5) Start DHIS2 Live by double-clicking on the file dhis2-live.exe in the DHIS2 Live installation
folder or by using a desktop shortcut or menu link that you might have set up.

6) Wait for the browser window to open and the login screen to show, and then log in with
username: admin and password: district

7) Now you will see a completely empty DHIS2 system and you should start by adding your
users, organisational hierarchy, data elements, and datasets etc. Please refer to the other
sections of the user manual for instructions on how to do this.

1
Getting started with DHIS2 Downloading and installing the
server version

1.2.2. Downloading and installing the server version

The latest stable server version can be downloaded from this website. For detailed information
on how to install it please refer to the installation chapter in the implementation manual.

1.3. Logging on to DHIS2

Regardless of whether you have installed the server version of the desktop Live version, you
will use a web-browser to log on to the application. DHIS2 should be compatible with most
modern web-browsers, although you will need to ensure that Java Script is enabled.

To log on to the application just enter http://localhost:8080/dhis if you are using the DHIS2
live package, or replace localhost with the name or IP address of the server where the server
version is installed.

Once you have started DHIS2, either on-line or off-line, the displayed screen will prompt you to
enter your registered user-name and password. After entering the required information click
on log-in button to log into the application. The default user name and password are 'admin'
and 'district'. They should be changed immediately upon logging on the first time.

You can select the language which you wish to display DHIS2 in from the "Change language"
dialog box at the bottom of the screen. Not all languages may be available.

Should you have forgotten your password, you can click on the "Forgot password?" link. You
must have informed DHIS2 of your email address and the server must be properly configured
to send emails.

If you want to create your own account (and the server administrator allows this), simply click
"Create an account" and follow the directions provided.

Once you have logged into DHIS2, refer to the specific sections in this manual for the different
functionality which is available.

1.4. Logging out of DHIS2

Just click on the Profile and the click "Log out" the top-right corner of the DHIS2 menu.

2
Getting started with DHIS2 Quick intro to designing a DHIS2
database

1.5. Quick intro to designing a DHIS2 database

DHIS2 provides a powerful set of tools for data collection, validation, reporting and analysis,
but the contents of the database, e.g. what to collect, who should collect it and on what format
will depend on the context of use. However, in order to do anything with DHIS2, you must first
create meta-data. Meta-data, or data about the data, describes what should be collected (data
elements and categories), where it should be collected (organisation units) and how frequently
it should be collected (periods). This meta-data needs to be created in the DHIS2 database
before it can be used. This can be done through the user interface and requires no programming
or in-depth technical skills of the software, but does require a good understanding of the
processes which you are trying to collect data form.

This section will provide a very quick and brief introduction to DHIS2 database design and
mainly explain the various steps needed to prepare a new DHIS2 system for use. How to do
each step is explained in other chapters, and best practices on design choices will be explained
in the implementers manual. Here are the steps to follow:

1. Set up an organisational hierarchy

2. Define data elements

3. Define data sets and data entry forms

4. Define validation rules

5. Define indicators

6. Define report tables and design reports

7. Set up the GIS module

8. Design charts and customise the dashboard

1.5.1. The organisational hierarchy

The organisational hierarchy defines the organisation using the DHIS2, the health facilities,
administrative areas and other geographical areas used in data collection and data analysis.
This dimension to the data is defined as a hierarchy with one root unit (e.g. Ministry of
Health) and any number of levels and nodes below. Each node in this hierarchy is called an
organisational unit in DHIS2.

The design of this hierarchy will determine the geographical units of analysis available to the
users as data is collected and aggregated in this structure. There can only be one organisational
hierarchy at the same time so its structure needs careful consideration. Additional hierarchies
(e.g. parallel administrative groupings such as "Facility ownership") can be modelled using
organisational groups and group sets, however the organisational hierarchy is the main
vehicle for data aggregation on the geographical dimension. Typically national organisational
hierarchies in public health have 4-6 levels, but any number of levels is supported. The
hierarchy is built up of parent-child relations, e.g. a Country or MoH unit (the root) might have
e.g. 8 parent units (provinces), and each province again ( at level 2) might have 10-15 districts
as their children. Normally the health facilities will be located at the lowest level, but they can
also be located at higher levels, e.g. national or provincial hospitals, so skewed organisational
trees are supported (e.g. a leaf node can be positioned at level 2 while most other leaf nodes
are at level 5).

Typically there is a geographical hierarchy defined by the health system. e.g. where the
administrative offices are located (e.g. MoH, province, district), but often there are other
administrative boundaries in the country that might or might not be added, depending on how
its boundaries will improve data analysis. When designing the hierarchy the number of children
for any organisational unit may indicate the usefulness of the structure, e.g. having one or

3
Getting started with DHIS2 Data Elements

more 1-1 relationships between two levels is not very useful as the values will be the same
for the child and the parent level. On the other extreme a very high number of children in the
middle of the hierarchy (e.g. 50 districts in a province) might call for an extra level to be added
in between to increase the usefulness of data analysis. The lowest level, the health facilities will
often have a large number of children (10-60), but for other levels higher up in the hierarchy
approx. 5-20 children is recommended. Too few or too many children might indicate that a
level should be removed or added.

Note that it is quite easy to make changes to the upper levels of the hierarchy at a later
stage, the only problem is changing organisational units that collect data (the leaf nodes), e.g.
splitting or merging health facilities. Aggregation up the hierarchy is done based on the current
hierarchy at any time and will always reflect the most recent changes to the organisational
structure. Refer to the chapter on Organisation Units to learn how to create organisational
units and to build up the hierarchy.

1.5.2. Data Elements

The Data Element is perhaps the most important building block of a DHIS2 database. It
represents the "WHAT" dimension, it explains what is being collected or analysed. In some
contexts this is referred to an indicator, but in DHIS2 we call this unit of collection and analysis a
data element. The data element often represents a count of something, and its name describes
what is being counted, e.g. "BCG doses given" or "Malaria cases". When data is collected,
validated, analysed, reported or presented it is the data elements or expressions built upon
data elements that describes the WHAT of the data. As such the data elements become
important for all aspects of the system and they decide not only how data is collected, but
more importantly how the data values are represented in the database, which again decides
how data can be analysed and presented.

It is possible to add more details to this "WHAT" dimension through the disaggregation
dimension called data element categories. Some common categories are Age and Gender, but
any category can be added by the user and linked to specific data elements. The combination
of a data element's name and its assigned category defines the smallest unit of collection
and analysis available in the system, and hence describes the raw data in the database.
Aggregations can be done when zooming out of this dimension, but no further drill-down is
possible, so designing data elements and categories define the detail of the analysis available
to the system (on the WHAT dimension). Changes to data elements and categories at a later
stage in the process might be complicated as these will change the meaning of the data values
already captured in the database (if any). So this step is one of the more decisive and careful
steps in the database design process.

One best practice when designing data elements is to think of data elements as a unit of data
analysis and not just as a field in the data collection form. Each data element lives on its own
in the database, completely detached from the collection form, and reports and other outputs
are based on data elements and expressions/formulas composed of data elements and not the
data collection forms. So the data analysis needs should drive the process, and not the look an
feel of the data collection forms. A simple rule of thumb is that the name of the data element
must be able to stand on its own and describe the data value also outside the context of its
collection form. E.g. a data element name like "Total referrals" makes sense when looking at
it in either the "RCH" form or the "OPD" form, but on its own it does not uniquely describe
the phenomena (who are being referred?), and should in stead be called "Total referrals from
Maternity" or "Total referrals from OPD". Two different data elements with different meanings,
although the field on the paper form might only say "Total referrals" since the user of the
form will always know where these referrals come from. In a database or a repository of data
elements this context is no longer valid and therefore the names of the data elements become
so important in describing the data.

Common properties of data elements can be modelled through what is called data element
groups. The groups are completely flexible in the sense that they are defined by the user,

4
Getting started with DHIS2 Datasets and data entry forms

both their names and their memberships. Groups are useful both for browsing and presenting
related data, but can also be used to aggregate data elements together. Groups are loosely
coupled to data elements and not tied directly to the data values which means they can be
modified and added at any point in time without interfering with the raw data.

1.5.3. Datasets and data entry forms

All data entry in DHIS2 is organised through the use of Datasets. A Dataset is a collection
of data elements grouped together for data collection, and in the case of distributed installs
they also define chunks of data for export and import between instances of DHIS2 (e.g. from
a district office local installation to a national server). Datasets are not linked directly to the
data values, only through their data elements and frequencies, and as such a dataset can be
modified, deleted or added at any point in time without affecting the raw data already captured
in the system, but such changes will of course affect how new data will be collected.

A dataset has a period type which controls the data collection frequency, which can be daily,
weekly, monthly, quarterly, six-monthly, or yearly. Both which data elements to include in the
dataset and the period type is defined by the user, together with a name, short name, and code.

In order to use a dataset to collect data for a specific orgunit you must assign the orgunit to
the dataset, and this mechanism controls which orgunits that can use which datasets, and at
the same time defines the target values for data completeness (e.g. how many health facilities
in a district expected to submit RCH data every month).

A data element can belong to multiple datasets, but this requires careful thinking as it may
lead to overlapping and inconstant data being collected if e.g. the datasets are given different
frequencies and are used by the same orgunits.

1.5.3.1. Data entry forms

Once you have assigned a dataset to an orgunit that dataset will be made available in Data
Entry (under Services) for the orgunits you have assigned it to and for the valid periods
according to the dataset's period type. A default data entry form will then be shown, which is
simply a list of the data elements belonging to the dataset together with a column for inputting
the values. If your dataset contains data elements with categories such as age groups or
gender, then additional columns will be automatically generated in the default form based
on the categories. In addition to the default list-based data entry form there are two more
alternatives, the section-based form and the custom form.

1.5.3.1.1. Section forms

Section forms allow for a bit more flexibility when it comes to using tabular forms and are quick
and simple to design. Often your data entry form will need multiple tables with subheadings,
and sometimes you need to disable (grey out) a few fields in the table (e.g. some categories do
not apply to all data elements), both of these functions are supported in section forms. After
defining a dataset you can define it's sections with subsets of dataelements, a heading and
possible grey fields i the section's table. The order of sections in a dataset can also be defined.
In Data Entry you can now start using the Section form (should appear automatically when
sections are available for the selected dataset). You can switch between default and section
forms in the top right corner of the data entry screen. Most tabular data entry forms should be
possible to do with sections forms, and the more you can utilise the section forms (or default
forms) the easier it is for you. If these two types of forms are not meeting your requirements
then the third option is the completely flexible, although more time-consuming, custom data
entry forms.

1.5.3.1.2. Custom Forms

When the form you want to design is too complicated for the default or section forms then
your last option is to use a custom form. This takes more time, but gives you full flexibility in

5
Getting started with DHIS2 Validation rules

term of the design. In DHIS2 there is a built in HTML editor (FcK Editor) for the form designer
and you can either design the form in the UI or paste in your HTML directly using the Source
window in the editor. In the custom form you can insert static text or data fields (linked to data
elements + category) in any position on the form and you have complete freedom to design
the layout of the form. Once a custom form has been added to a dataset it will be available in
data entry and used automatically. You can switch back to default and section (if exists) forms
in the top right corner of the data entry screen.

1.5.4. Validation rules

Once you have set up the data entry part of the system and started to collect data then there is
time to define data quality checks that help to improve the quality of the data being collected.
You can add as many validation rules as you like and these are composed of left and right
side expressions that again are composed of data elements, with an operator between the two
sides. Typical rules are comparing subtotals to totals of something. E.g. if you have two data
elements "HIV tests taken" and "HIV test result positive" then you know that in the same form
(for the same period and organisational unit) the total number of tests must always be equal
or higher than the number of positive tests. These rules should be absolute rules meaning
that they are mathematically correct and not just assumptions or "most of the time correct".
The rules can be run in data entry, after filling each form, or as a more batch like process on
multiple forms at the same time, e.g. for all facilities for the previous reporting month. The
results of the tests will list all violations and the detailed values for each side of the expression
where the violation occurred to make it easy to go back to data entry and correct the values.

1.5.5. Indicators
Indicators represent perhaps the most powerful data analysis feature of the DHIS2. While data
elements represent the raw data (counts) being collected the indicators represent formulas
providing coverage rates, incidence rates, ratios and other formula-based units of analysis. An
indicator is made up of a factor (e.g. 1, 100, 100, 100 000), a numerator and a denominator,
the two latter are both expressions based on one or more data elements. E.g. the indicator
"BCG coverage <1 year" is defined a formula with a factor 100, a numerator ("BCG doses
given to children under 1 year") and a denominator ("Target population under 1 year"). The
indicator "DPT1 to DPT3 drop out rate" is a formula of 100 % x ("DPT1 doses given"- "DPT3
doses given") / ("DPT1 doses given").

Most report modules in DHIS2 support both data elements and indicators and you can also
combine these in custom reports, but the important difference and strength of indicators
versus raw data (data element's data values) is the ability to compare data across different
geographical areas (e.g. highly populated vs rural areas) as the target population can be used
in the denominator.

Indicators can be added, modified and deleted at any point in time without interfering with the
data values in the database.

1.5.6. Report tables and reports

Standard reports in DHIS2 are a very flexible way of presenting the data that has been
collected. Data can be aggregated by any organisational unit or orgunit level, by data element,
by indicators, as well as over time (e.g. monthly, quarterly, yearly). The report tables are
custom data sources for the standard reports and can be flexibly defined in the user interface
and later accessed in external report designers such as iReport or through custom HTML
reports. These report designs can then be set up as easily accessible one-click reports with
parameters so that the users can run the same reports e.g. every month when new data is
entered, and also be relevant to users at all levels as the organisational unit can be selected
at the time of running the report.

6
Getting started with DHIS2 GIS

1.5.7. GIS
In the integrated GIS module you can easily display your data on maps, both on polygons
(areas) and as points (health facilities), and either as data elements or indicators. By providing
the coordinates of your organisational units to the system you can quickly get up to speed with
this module. See the GIS section for details on how to get started.

1.5.8. Charts and dashboard

On of the easiest way to display your indicator data is through charts. An easy to use chart
dialogue will guide you through the creation of various types of charts with data on indicators,
organisational units and periods of your choice. These charts can easily be added to one of the
four chart sections on your dashboard and there be made easily available right after log in.
Make sure to set the dashboard module as the start module in user settings.

7
Data entry Data entry with DHIS2

Chapter 2. Data entry

2.1. Data entry with DHIS2

To open the data entry window hover over the Apps button. A drop down menu will appear
listing the apps provided by DHIS2. Click on the Data Entry option.

The data entry module is where aggregated data is manually registered in the DHIS2 database.
Data is registered for an organisation unit, a period, and a set of data elements (data set) at a
time. A data set often corresponds to a paper-based data collection tool.

2.1.1. Selecting the data entry form

To start entering data the first step is to open the correct form by following these steps:
1. Locate the orgunit you want to register data for in the tree menu to the left. Expand and
close branches by clicking on the +/- symbols. A quick way to find an orgunit is to use the
search box just above the tree (the green symbol), but you need to write in the full name
to get a match.
2. Select a data set from the dropdown list of data sets available to your selected orgunit.
3. Select a period to register data for. The available periods are controlled by the period type
of the data set (reporting frequency). You can jump a year back or forward by using the
arrows above the period.

By now you should see the data entry form. From a form design perspective, there are three
types for forms: default forms, section forms and custom forms. If a custom form exists, it will
be displayed, followed in order of precedence by a section form, and finally a default form.

Main data entry screen

9
Data entry Entering data

2.1.2. Entering data

Start entering data by clicking inside the first field and type in the value. Move to the next field
using the Tab button. Shift+Tab will take you back one step. You can also use the "up" and
"down" arrow keys, as well as the Enter key, to navigate between the form cells. The values
are saved immediately and do not require to be saved at a later stage. A green field indicates
that the value has been saved in the system (on the server).

Input validation: If you type in an invalid value, e.g. a character in a field that only accepts
numeric values you will get a pop-up that explains the problem and the field will be coloured
yellow (not saved) until you have corrected the value. If you have defined a min/max range
for the field (data element+organisation unit combination) a pop-up message will notify you
when the value is out of range, and the value will remain unsaved until you have changed the
value (or updated the range and then re-entered the value).

Disabled fields: If a field is disabled (grey) it means that the field can and should not be filled.
The cursor will automatically jump to the next open field.

Data history: By double-clicking on any input field in the form a data history window opens
showing the last 12 values registered for the current field (organisation unit+data element
+categoryoptioncombo) in a bar chart. This window also shows the min and max range and
allows for adjusting the range for the specific organisation unit and data element combination.

Data entry section form with history pop-up

Follow Up: In the data history window there is also a feature to tag or star a value. E.g. a
suspicious value that needs further investigation can be kept in the system, but marked for
Follow-Up. In the Data Quality module you can run a Follow-Up analysis and view all values
marked for Follow-Up, and then later edit the values if proved incorrect.

Audit trail: The audit trail allows you to view other data values which have been entered prior
to the current value. As an example, the following data element was changed from its original
value to 120. The audit trail shows when the data value was altered along with which user
made the changes.

10
Data entry Editing and deleting data

2.1.3. Editing and deleting data

If you wish to enter data which has already been entered, simply replace the data entry value
with the update values.

If you want to delete a data value completely, you should select the value of interest, and press
"Delete" on your keyboard. If you enter a zero and the data element has been configured to
not store zeros, the previous data value (i.e. the one you wish to modify) will not be overwritten
with the new value. Therefore, it is better practice to delete the data value completely (waiting
for the cell to turn green) and then to enter the new value.

2.1.4. Validating data in the form

When all the available values for the form has been filled in you can run a validation check on
the data in the form. Click on the "Run Validation" button in the top right (at the beginning of
the data entry page) or lower left (at the end of your data entry page) corner. All validation
rules which involves data elements in the current form (dataset) will be run against the new
data. Upon completion you will be presented with a list of violations or a simply a message
that says "The data entry screen successfully passed validation". See the Data Quality chapter
for information on how to define such validation rules.

When you have corrected any erroneous values and are done with the form the recommended
practice is to click on the Complete button below the form to register the form as complete.
This information is used when generating completeness reports for district, county, province
or the national level.

Data entry validation result

2.1.5. Off-line data entry

The data entry module will function even if during data entry the Internet connectivity is
not stable. In order to utilize this functionality, you must login to the server while Internet
connectivity is present, but if during data entry, the Internet link between your computer and
the server becomes unstable, data can still be entered into the data entry form, saved to
your local computer, and then pushed to the server once the Internet connectivity has been
restored. Data can be entered and stored locally while being off-line and uploaded to the central
server when on-line. This means that the on-line deployment strategy will be more viable in
areas with unstable Internet connectivity. The total bandwidth usage is greatly reduced since
forms no longer are retrieved from the server for each rendering.

When the server is able to be reached through the Internet connection, a message is displayed
at the top of the data entry screen below.

If the Internet connection should disconnect for some reason during the data entry process,
this will be detected by the application, and you will be informed that your data will be stored
locally.

11
Data entry Multi-organisation unit data entry

Data entry can proceed as normal. Once you have entered all of the necessary data, and the
application detects that the server is back on-line, you will be informed that you have data
which needs to be synchronized with the server.

Once the data has successfully synchronized with the server, you will receive a confirmation
message that the data has been successfully uploaded to the server.

2.1.6. Multi-organisation unit data entry

In some scenarios it is beneficial to enter data for multiple organisation units in the same data
entry form, for instance if there are few data elements in the form and a huge number of
organisation units in the hierarchy. In that case you can enable multi-organisation unit data
entry by going to "System settings" and tick the "Enable multi organisation unit forms" setting.
Then, in data entry, select the organisation unit immediately above the organisation unit you
want to enter for in the hierarchy. Note that this only work for the "section" based forms. You
should now see the data elements appearing as columns and the organisation units appearing
as rows in the form. Note that the data entry forms should still be assigned to the facilities that
you actually enter data for, i.e. the organisation units now appearing in the form.

12
Using Data Quality functionality Overview of data quality checks

Chapter 3. Using Data Quality

functionality
The data quality module provides means to improve the accuracy and reliability of the data
in the system. This can be done through validation rules and various statistical checks. All the
functionality described below can be accessed from the left side menu in the Services->Data
Quality module.

3.1. Overview of data quality checks

Ensuring data quality is a key concern in building an effective HMIS. Data quality has different
dimensions including:
• Correctness: Data should be within the normal range for data collected at that facility. There
should be no gross discrepancies when compared with data from related data elements.
• Completeness: Data for all data elements for all health facilities should have been submitted.
• Consistency: Data should be consistent with data entered during earlier months and years
while allowing for changes with reorganization, increased work load, etc. and consistent with
other similar facilities.
• Timeliness: All data from all reporting orgunits should be submitted at the appointed time.

3.2. Data quality checks

Data quality checking can be done through various means, including:
1. At point of data entry, the software can check the data entered to see if it falls within the
min-max ranges of that data element (based on all previous data registered).
2. Defining various validation rules, which can be run once the user has finished data entry.
The user can also check the entered data for a particular period and Organization Unit(s)
against the validation rules, and display the violations for these validation rules.
3. Analysis of data sets, i.e. examining gaps in data.
4. Data triangulation which is comparing the same data or indicator from different sources.

3.3. Running Validation Rule Analysis

You can access Validation Rule Analysis from the Apps->Data Quality menu.

A validation rule is based on an expression which defines a relationship between a number of

data elements. The expression has a left side and a right side and an operator which defines
whether the former must be less than, equal to or greater than the latter. The expression forms
a condition which should assert that certain logical criteria are met. For instance, a validation
rule could assert that the total number of vaccines given to infants is less than or equal to the
total number of infants.

The validation rule analysis function will test validation rules against the data registered in the
system. Validation violations will be reported in cases where the condition defined through the
validation rule expression is not met, i.e. the condition is false.

Selecting what data to validate:

First, enter a start date and an end date for which data should be included in the analysis. The
date picker widget may be used to select dates.

13
Using Data Quality functionality Running Validation Rule Analysis

Second, choose between including all validation rules or all validation rules from a single group.

Third, choose between including the selected organisation unit only or the selected
organisation unit with all children in the analysis. Fourth, select the organisation unit. Finally,
click validate.

Run validation rule selection

Validation results:

The analysis process will run for a while depending on the amount of data that is being
analysed. If there were no violations of the validation rules a message saying validation passed
successfully is displayed.

If validation violations were found, they will be presented in a list. The organisation unit, period,
left side description and value, operator, and right side value and description for each validation
violation are displayed.

The show details icon can be clicked in order to get more information about a validation
violation. This will open a popup screen that provides information about the data elements
included in the validation rules and their corresponding data values. This information can be
used in order to fix incorrect data.

The validation violations can be exported to a PDF document by clicking on the Download as
PDF button, and to a Microsoft Excel workbook by clicking on the Download as Excel button.

Run validation rule results

14
Using Data Quality functionality Std Dev Outlier Analysis

3.4. Std Dev Outlier Analysis

You can access Outlier analysis from the Apps->Data Quality menu.

The standard deviation based outlier analysis provides a mechanism for revealing values that
are numerically distant from the rest of the data. Outliers can occur by chance, but they often
indicate a measurement error or a heavy-tailed distribution (leading to very high numbers). In
the former case one wishes to discard them while in the latter case one should be cautious
in using tools or interpretations that assume a normal distribution. The analysis is based on
the standard normal distribution.

Select what data to analyse:

First, select the from and to date for the data to include in the analysis.

Second, select the data set from which to pick data elements from.

Third, select all or some of the data elements in the data set by double-clicking or marking
them and clicking the add/remove buttons.

Fourth, select the parent organisation unit to use. All children of the organisation unit will be
included.

Fifth, select the number of standard deviations. This refers to the number of standard
deviations the data is allowed to deviate from the mean before it is classified as an outlier.

Outlier analysis rule selection

Analysis result:

The potential outlier values discovered will be presented in a list after the analysis process
is finished. The data element, organisation unit, period, minimum value, actual value, and
maximum value will be displayed for each outlier. The minimum and maximum values refer to
the border values derived from the number of standard deviations selected for the analysis.

Each outlier value can be modified directly in the analysis result page. The value can be
modified by clicking inside the corresponding field in the value column, entering a value and
then navigate away from that field either by clicking tab or anywhere outside the field. The
system will provide an alert if the value is still outside the defined minimum and maximum
values, but the value will saved in any case. The field will have a red background color if the
value is outside the range, and a green if inside.

15
Using Data Quality functionality Min-Max Outlier Analysis

Each outlier value can be marked for further follow-up by clicking the star icon.

3.5. Min-Max Outlier Analysis

The min-max value based outlier analysis provides a mechanism for revealing values that are
outside the pre-defined minimum and maximum values. Minimum and maximum values can
be custom defined or automatically defined by the system in the data administration module.
See the section about Std dev outlier analysis for further details on usage.

3.6. Follow-Up Analysis

The follow-up analysis function will list all data values which are marked for follow-up. A
data value can be marked for follow-up in the data entry module and in the other validation
analysis variants in this module.As can be seen in the screen shot below, simply select an
organisation unit from the tree. All data values with a follow-up status will be displayed here
for the descendants of the selected organisation unit.

16
Using reporting functionality Reporting functionality in DHIS2

Chapter 4. Using reporting functionality

4.1. Reporting functionality in DHIS2

The reporting module in DHIS2 provides a range of reporting alternatives, and this section will
explain how to use them to view and analyse data. Another section explains how to configure
and set up the various reporting tools.

Standard reports: Standard reports are built on pivot tables, but are more advanced in its
design allowing for more cosmetics and styles. These reports can also combine multiple tables
and charts in the same report and be made available as one-click reports that are very easy
to use. These reports can be downloaded as PDF files which makes them ideal for printing as
well as sharing offline.

Dataset reports: Dataset reports are simply a printer friendly way to look at the data entry
forms with either raw or aggregated data (over time or place). The design used in data entry
will be used also in the data set reports. This will work only for data sets that has a custom
data entry form set up.

Dashboard: The fastest way to view your data. The dashboard can display up to four updated
charts as well as shortcuts to your favourite reports, report tables, and map views. Each user
can configure a personal dashboard.

Data Visualizer: Do flexible visualizations of your data as charts and data tables. Any number
of indicators and data elements can be included. Several chart types are available, such as
column, stacked column, line, area and pie charts. The charts can be saved in order to be easily
retrieved later and can also be put on your personal dashboard. Charts can be downloaded as
image and PDF files to your local computer.

Orgunit distribution reports: These reports are generated off the orgunit group set information
and can show what types (and how many of each type) of health facilities that are located in a
given area (any level in the hierarchy). These reports are automatically generated and display
the information in both tables and charts, and downloads in PDF, excel, and CSV are available.

Reporting rate summary: These reports provide a nice overview of how many facilities that
have submitted their data for a given dataset and period. Here you can get both the counts
and the percentages showing the reporting rate for all or single data sets.

Web-based pivot tables: The built in pivot table tool is a web-based tool to display indicator
data by orgunit and period in a typical pivot table view and allows for pivoting manipulations
of the tables. It allows for large amounts of data to be downloaded offline for analysis as well.

GIS: Present and analyse your data using thematic maps. You can view both data elements
and indicators and given that you have coordinates for all your orgunits you can drill down
the hierarchy and view maps for all levels from country polygons to facility points. See the
separate chapter on GIS for more details. All the map information is built into DHIS2 and all you
need to do is to register coordinates for your organisation units and the maps will be available.

4.2. Using standard reports

You access the available reports by navigating to Apps->Reports. In the report menu in the
left bar, click Standard Report. A list of all pre-defined reports will appear in the main window.

17
Using reporting functionality Using dataset reports

Standard reports

You run/view a report by clicking on the name of the report and then selecting "Create" from
the contextual menu. If there are any pre-defined paramaters, you will see a report parameter
window where you must fill in the values needed for orgunit and/or reporting month, depending
on what has been defined in the underlying report table(s). Click on "Get Report" when you
are ready. The report will either appear directly in your browser or be available as a PDF file
for download, depending on your browser settings for handling PDF files. You can save the file
and keep it locally on your computer for later use.

4.3. Using dataset reports

Dataset reports are printer friendly views of the data entry screen filled with either raw or
aggregated data. These are only available for data sets that have custom data entry forms
and not for default or section forms.

You can access data set reports from Apps->Reports.

A Criteria window will appear where you fill in the details for your report:

Dataset: The data set you want to display.

Reporting period: The actual period you want data for. This can be aggregated as well as raw
periods. This means that you can ask for a quarterly or annual report even though the data
set is collected monthly. A data set's period type (collection frequency) is defined in data set
maintenance. First select the period type (Monthly, Quarterly, Yearly etc.) in the drop down
next to Prev and Next buttons, and then select one of the available periods from the dropdown
list below. Use Prev and Next to jump one year back or forward.

Use data for selected unit only: Use this option if you want a report for an orgunit that has
children, but only want the data collected directly for this unit and not the data collected by
its children. If you want a typical aggregated report for an orgunit you do not want to tick this
option.

Reporting Organisation unit: Here you select the orgunit you want the report for. This can be
at any level in the hierarchy as the data will be aggregated up to this level automatically (if
you do not tick the option above).

When you are done filling in the report criteria you click on "Generate". The report will appear
as HTML in a printer-friendly format. Use the print and save as functions in the browser to print
or save (as HTML) the report.You can also export the data set report in Excel and PDF formats.

18
Using reporting functionality Using resources

4.4. Using resources

The resource tool allows you to upload both files from your local computer to the DHIS server
and to add links to other resources on the Internet through URLs. If you want to share a direct
link to the DHIS2 resources you can right click on the "view resource" button and copy the
link address.

To create a resource click on the "Add new" button. Enter a name for the resource, then choose
between uploading a file or external URL. If you chose file upload click "Choose file" and select
your file your local computer. If you chose URL enter the link to the resource on the Internet.
Then click "Save".

4.5. Using reporting rate summary

Access the reporting rate summary from the Apps->Reports menu. Reporting rate summaries
will show how many datasets (forms) that have been submitted by organisation unit and period.
There are two methods available to calculate reporting rates (completeness):

• Based on complete data set registrations. A complete data set registration refers to a user
marking a data entry form as complete, typically by clicking the complete button in the data
entry screen, hereby indicating to the system that she considers the form to be complete.
This is i.e. a subjective approach to calculating completeness.

• Based on compulsory data element: You can define any number of data elements in a data
set to be compulsory. This implies that data values must be captured for all data elements
which have been marked as compulsory in order for the data set to be considered complete.
This is i.e. an objective approach to calculating completeness.

The reporting rate summary will for each row show a range of measures:

• Actual reports: Indicates the number of data entry complete registrations for the relevant
data set.

• Expected reports: Indicates how many data entry complete registrations are expected. This
number is based on the number of organisation units the relevant data set has been assigned
to (enabled for data entry).

• Percent: The percentage of reports registered as complete based on the number expected.

• Reports on time: Same as actual reports, only reports registered as complete within the
maximum number of days after the end of the reporting period. This number of days after
reporting period can be defined per data set in the data set management.

• Percent on time: Same as percentage, only reports registered as complete on time used as
numerator.

To run the report you can follow these steps:

• Select an orgunit from the tree.

• Select one of the completeness methods to use to calculate the reporting rates.

Select all or one data set. All will give you a report with all data sets for the selected
organisation unit. A single data set will give you a report with completeness for all children
of the selected organisation unit.

• Select a period type and a period from the list of available periods for that period type. Move
back/forward one year by using the prev/next buttons.

• The report will then be rendered. Change any of the parameters above and the report will
be updated automatically.

19
Using reporting functionality Using organisation unit distribution
reports
Reporting rate summary

4.6. Using organisation unit distribution reports

You can access the Orgunit Distribution reports from the left side menu in the Apps->Reports.

Orgunit distribution reports are reports that show how the orgunits are distributed on various
properties like type and ownership, and by geographical areas.

The result can be presented in a table-based report or in a chart.

Running a report:

To run a report first select an orgunit in the upper left side orgunit tree. The report will be
based on orgunits located under the selected orgunit. The select the orgunit group set that you
want to use, typically these are Type, Ownership, Rural/Urban, but can be any user-defined
orgunit group set. The you can click on either Get Report to get the table-based presentation
or Get chart to get the same result in a chart. You can also download other format such as
PDF, Excel and CSV.

Orgunit distribution report

20
Using the Pivot Table app About the Pivot table app

Chapter 5. Using the Pivot Table app

5.1. About the Pivot table app

With the Pivot Table app, you can create pivot tables based on all available data dimensions in
DHIS2. A pivot table is a dynamic tool for data analysis which lets you summarize and arrange
data according to its dimensions. Examples of data dimensions in DHIS2 are:
• data dimension itself (for example data elements, indicators and events)
• periods (representing the time period for which the data represents)
• organisation hierarchy (representing the geographical location of the data)

From these dimensions you can freely select dimension items to include in the pivot table.
You can create additional dimensions in DHIS2 with the group set functionality. This allows for
different aggregation pathways, such as aggregation by "Partner" or facility type.

A pivot table can arrange data dimensions on columns, rows, and as filters. When you place
a data dimension on columns, the pivot table will display one column per dimension item. If
you place multiple data dimensions on columns, the pivot table displays one column for all
combinations of the items in the selected dimensions. When you place a data dimension on
rows, the pivot table displays one row per dimension item in a similar fashion. The dimensions
you select as filters will not be included in the pivot table, but will aggregate and filter the table
data based on the selected filter items.

5.2. Create a pivot table

1. In the Apps menu, click Pivot Table.
2. In the menu to the left, select the dimension items you want to analyse, for example data
elements or indicators.
3. Click Layout and arrange the data dimensions as columns, rows and filters.

You can keep the default selection if you want.

4. Click Update.

Example 5.1. Pivot table based on the demo database.

In this example, indicators are listed as columns and periods as rows.

Example pivot table with data elements on columns and periods as rows.

5.2.1. Select dimension items

The left menu lists sections for all available data dimensions. From each section you can select
any number of dimension items. As an example, you can open the section for data elements
and select any number of data elements from the available list. You can select an item by

21
Using the Pivot Table app Select dimension items

marking it and clicking on the arrow in the section header or simply double-clicking on the item.
Before you can use a data dimension in your pivot table you must at least select one dimension
item. If you arrange a dimension as columns or rows but do not select any dimension items,
the dimension is ignored.

You must choose at least one data dimension type to create a pivot table. The available types
are described in this table:

Table 5.1. Data dimension types

Data dimension type Definition Examples

Indicators An indicator is a calculated Coverage of immunization
formula based on data across a specific district.
elements.
Data elements Represents the phenomenon Number of malaria cases;
for which data has been number of BCG doses given.
captured.
Data sets A collection of data elements Reporting rates for
grouped for data collection. immunization and morbidity
You can select : forms.
• Reporting rates: the
percentage of actual
reports compared to
the expected number of
reports
• Reporting rates on time:
the reporting rates
based on timely form
submissions. A timely
submission must happen
within a number of days
after the reporting period.
• Actual reports: the actual
number of reports
• Actual reports on time:
the actual number of
reports based on timely
form submissions. A timely
submission must happen
within a number of days
after the reporting period.
• Expected reports: the
number of expected
reports based on
organisation units where
the data set and the
reporting frequency has
been assigned.
Event data items A data element that is part Average weight and height
of a program representing for children in a nutrition
events that have been program.
captured.
Program indicators A calculated formula based Average BMI score for
on data elements in children in a nutrition
program.

22
Using the Pivot Table app Select dimension items

Data dimension type Definition Examples

a program representing
events.

You can combine these dimensions to display for example aggregate data with reporting rates,
or event data items together with program indicators, all in the same pivot tables. For the "data
element" data dimension, you are also able to select "Totals" and "Details", which will allow
you to view different category combination options together on the same pivot table.

For the period dimension you can choose between using fixed periods or relative periods. An
example of a fixed period is "January 2012". To select fixed periods start by selecting a period
type from the period type list. You can then select periods from the list of available periods.

Relative periods are periods relative to the current date. Examples of relative periods are "Last
month", "Last 12 months", "Last 5 years". Relative periods can be selected by ticking the check-
boxes next to each period. The main advantage of using relative periods is that when you save
a pivot table favorite, it will stay updated with the latest data as time goes by without the need
for constantly updating it.

For the organisation unit dimension you can select any number of organisation units from the
hierarchy. To select all organisation units below a specific parent organisation unit, right click
and click "Select all children". To manually select multiple organisation units, click and hold
the Ctrl key while clicking on organisation units. You can tick "User org unit", "User sub-units"
or "User sub-x2-units" in order to dynamically insert the organisation unit or units associated
with your user account. This is useful when you save a pivot table favorite and want to share
it with other users, as the organisation units linked with the other user's account will be used
when viewing the favorite.

Selection of fixed and relative periods.

Dynamic dimensions can consist of organisation unit group sets, data element group sets, or
category option group sets which have been configured with the type of "Disaggregation".
Once the group sets have been configured, they will be come available in the pivot tables,
and can be used as additional analysis dimensions, for instance to analyse aggregate data

23
Using the Pivot Table app Modify pivot table layout

by Type of organisation unit or Implementing partner. Dynamic dimensions work the same as
fixed dimensions.

Tip
Some dynamic dimensions may contain many items. This can cause issues with certain
browsers due to the length of the URL when many dimension members are selected. A
special "All" check box is available for dynamic dimensions, which allows you to include
all available dimensions implicitly in your pivot table, without specifying each and every
dimension member.

5.2.2. Modify pivot table layout

After selecting data dimensions it is time to arrange your pivot table. Click "Layout" in the top
menu to open the layout screen. In this screen you can position your data dimensions as table
columns, rows or filters by clicking and dragging the dimensions from the dimensions list to the
respective column, row and filter lists. You can set any number of dimensions in any of the lists.
For instance, you can click on "Organisation units" and drag it to the row list in order to position
the organisation unit dimension as table rows. Note that indicators, data elements and data
set reporting rates are part of the common "Data" dimension and will be displayed together
in the pivot table. For instance, after selecting indicators and data elements in the left menu,
you can drag "Organisation Unit" from the available dimensions list to the row dimension list
in order to arrange them as rows in the pivot table.

The table layout screen.

After you have set up your pivot table you can click "Update" to render your pivot table, or click
"Hide" to hide the layout screen without any changes taking effect. Since we in our example

24
Using the Pivot Table app Change the display of your table

have selected both the period and organisation unit dimension as rows, the pivot table will
generate all combinations of the items in these dimensions and produce a table like this:

Pivot table where organisation units and periods are repeated on rows.

5.3. Change the display of your table

1. Click Options.

2. Set the options as required.

Table 5.2. Table options

Option Description
Show column totals Displays total values in the table for each row and
column, as well as a grand total for all values in the
Show row totals table.
Show column sub-totals Displays subtotals in the table for each dimension.
In the screenshot above, notice how subtotals
Show row sub-totals are generated for each of the periods in the
period dimension. If you only select one dimension,
subtotals will be hidden for those columns or rows.
This is because the values will be equal to the
subtotals.
Show dimension labels Shows the dimension names as part of the pivot
tables.
Hide empty rows Hides empty rows from the table, which is useful
when looking at large tables where a big part of the
dimension items do not have data in order to keep
the table more readable.
Skip rounding Skips the rounding of data values, offering the full
precision of data values. Can be useful for finance
data where the full dollar amount is required.
Aggregation type The default aggregation operator can be over-ridden
here, by selecting a different aggregation operator.
Some of the aggregation types are Count, Min and
Max.
Show hierarchy Shows the name of all ancestors for organisation
units, for example "Sierra Leone / Bombali /
Tamabaka / Sanya CHP" for Sanya CHP. The
organisation units are then sorted alphabetically

25
Using the Pivot Table app Manage pivot table favorites

Option Description
which will order the organisation units perfectly
according to the hierarchy.
Include only completed events Includes only completed events in the aggregation
process. This is useful for example to exclude partial
events in indicator calculations.
Display density Controls the size of the cells in the table. You can set
it to "comfortable", "normal" and "compact".

The "compact" option is handy in order to fit large

tables into the browser screen.
Font size Controls the size of the table text font. Can be set to
"large", "normal" and "small".
Digit group separator Controls which character to separate groups of digits
or "thousands". Can be set to "comma", "space" and
"none".
Legend set Shows a colour indicator next to the values. Currently
the GIS legend sets are being used.

3. Click Update.

5.4. Manage pivot table favorites

5.4.1. Save a pivot table as a favorite

To save a pivot table as a favorite:
1. Click Favorites > Save as.
2. In the text field, enter the name you want to give your pivot table.
3. Click Save.

5.4.2. Open a favorite

1. Click Favorites > Open.
2. Find and click the favorite you want to open. You can either use Prev and Next or the search
field to find a saved favorite.

5.4.3. Rename a favorite

1. Click Favorites > Rename.
2. In the text field, enter the new name you want to give your pivot table.
3. Click Rename.

5.4.4. Share an interpretation of a favorite

For certain analysis-related resources in DHIS2, you can share a data interpretation. An
interpretation is a link to the relevant resource with a description of the data.

To create an interpretation of a pivot table and share it with all users of the system:
1. Click Favorites > Write interpretation.

26
Using the Pivot Table app Modify sharing settings for a
favorite
2. In the text field, type a comment, question or interpretation.
3. Click Share.

You can see the interpretation on the Dashboard.

5.4.5. Modify sharing settings for a favorite

After you have created a pivot table and saved it as a favorite, you can share the favorite with
everyone or a user group:

1. Click Favorites > Share.

2. In the text field, enter the name of the user group you want to share your favorite with and
click the + icon.

The chosen user group is added to the list of recipients.

Repeat the step to add more user groups.

3. If you want to allow external access, select the corresponding box.
4. For each user group, choose an access setting. The options are:
• None
• Can view
• Can edit and view
5. Click Save.

5.4.6. Create a link to a favorite

1. Click Favorites > Get link.
2. Click the type of link you need.
• Open in this app: Provides a URL for the favorite. You can use this link to share the favorite
with other users or colleagues via email or chat.
• Open in web api: Provides a URL of the API resource. By default this is a HTML resource,
but you can modify the suffix of ".html" to ".json" or ".csv". Other data types are available.
This option is most useful when you need an API link to the pivot table resource. See the
DHIS2 developers guide for details about the different types which are available.

5.4.7. Delete a favorite

1. Click Favorites > Delete.
2. Click Delete to confirm your choice.

5.5. Download data from a pivot table

5.5.1. Download table layout data format

To download the data in the current pivot table:
1. Click Download.
2. Under Table layout, click the format you want to download: Microsoft Excel, CSV or HTML.

The data table will have one column per dimension and contain names of the dimension
items.
27
Using the Pivot Table app Download plain data source format

Tip
You can create a pivot table in Microsoft Excel from the downloaded Excel file.

5.5.2. Download plain data source format

You can download data in the current pivot table in JSON, XML, Excel, and CSV as plain data
formats with different identification schemes (ID, Code, and Name). The data document uses
identifiers of the dimension items and opens in a new browser window to display the URL of
the request to the Web API in the address bar. This is useful for developers of apps and other
client modules based on the DHIS2 Web API or for those who require a plan data source, for
instance for import into statistical packages.

To download plain data source formats:

1. Click Download.
2. Under Plain data source, click the format you want to download.

Table 5.3. Available formats

Format Action Description

JSON Click JSON Downloads JSON format based on ID
property.

You can also download JSON format based

on Code or Name property.
XML Click XML Downloads XML format based on ID
property.

You can also download XML format based

on Code or Name property.
Microsoft Click Microsoft Excel Downloads XML format based on ID
Excel property.

You can also download Microsoft Excel

format based on Code or Name property.
CSV Click CSV Downloads CSV format based on ID
property.

You can also download CSV format based

on Code or Name property.
JRXML Put the cursor on Advanced Produces a template of a Jasper Report
and click JRXML which can be further customized based on
your exact needs and used as the basis
for a standard report in DHIS2.
Raw data SQL Put the cursor on Advanced Provides the actual SQL statement used
and click Raw data SQL to generate the pivot table. You can use it
as a data source in a Jasper report, or as
the basis for an SQL view.

5.5.3. Download a CSV format without rendering data in the web browser
You can download data in CSV format directly without rendering the data in the web browser.
This helps to reduce any constraints in the system settings that has been set with regards to
the maximum number of analytic records. This lets you download much larger batches of data
that you can use for later offline analysis.

28
Using the Pivot Table app Embed a pivot table in an external
web page
To download data in CSV format without first rendering data in the web browser:
1. Click the arrow beside Update.

2. Click CSV to download the format based on ID property.

The file downloads to your computer.

Tip
You can also download CSV format based on Code or Name property.

5.6. Embed a pivot table in an external web page

Certain analysis-related resources in DHIS2, like pivot tables, charts and maps, can be
embedded in any web page by using a plug-in. You will find more information about the plug-
ins in the Web API chapter in the DHIS2 Developer Manual.

To generate a HTML fragment that you can use to display the pivot table in an external web
page:

1. Click Embed.
2. Click Select to highlight the HTML fragment.

5.7. Visualize a pivot table data as a chart or a map

When you have made a pivot table you can switch between pivot table, chart and map
visualization of your data.

5.7.1. Open a pivot table as a chart

1. Click Chart > Open this table as chart.

Your current pivot table opens as a chart.

5.7.2. Open a pivot table selection as a chart

If you want to visualize a small part of your pivot table as a chart you can click directly on a
value in the table instead opening the whole table.
1. In the pivot table, click a value.

29
Using the Pivot Table app Open a pivot table as a map

2. To verify the selection, hold the cursor over Open selection as chart. The highlighted
dimension headers in the table indicate what data will be visualized as a chart.
3. Click Open selection as chart.

5.7.3. Open a pivot table as a map

1. Click Chart > Open this table as map

Your current pivot table opens as a map.

5.7.4. Open a pivot table selection as a map

1. In the pivot table, click a value.

A menu displays.
2. Click Open selection as map.

Your selection opens as a map.

5.8. Constraints and tips

When selecting and arranging dimensions there are a few constraints that apply. All of these
constraints are validated and the pivot table module will provide feedback if any constraint
is violated.
• At least one dimension must be selected on columns or rows.
• At least one period must be included in the pivot table.
• Data element group sets and reporting rates cannot appear in the same pivot table.
• A table cannot contain more than the maximum number of analytic records which have
been specified through the system settings. The maximum number of records could also
be constrained by the maximum RAM which is available to your browser. Consider making
smaller tables instead of one table which displays all of your data elements and indicators
together.

Tip
Pivot tables in DHIS2 are limited to a system set parameter, which controls the number
of data values which can be returned. The reason for this is two fold. First, it would be
easy to overwhelm the server with a very complicated request for a large pivot table.
Second, the amount of data which is able to be rendered in a browser is fairly limited. If
you are having problems with very large or complex tables, consider to try and reduce
the number of items. It is usually more useful to have smaller, concise tables which are
easier to understand and which address a particular analysis.

30
Using the Data Visualizer app Data Visualizer overview

Chapter 6. Using the Data Visualizer app

6.1. Data Visualizer overview

With the Data Visualizer app, you can select content, for example indicators, data elements,
periods and organisation units, for an analysis. The app works well over poor Internet
connections and generates charts in the web browser. Little data is transferred over the
Internet.
• You can hide and show individual data series in the chart by clicking directly on the series
label in the chart. They appear either at the top or to the right of the chart.
• You can click on the triple left-arrow button on the top centre menu. This collapses the left
side menu and gives more space for the chart. You can get the menu back by clicking on
the same button again.

6.2. Create a chart

1. In the Apps menu, click Data Visualizer.
2. Select a chart type.
3. In the menu to the left, select the meta data you want to analyse. You must select one or
more elements from all of the three dimensions - data (indicators, data elements, reporting
rates), periods (relative, fixed) and organisation units (units or groups).

Last 12 Months from the period dimension and the root organisation unit are selected by
default.
4. Click Layout and arrange the dimensions.

You can keep the default selection if you want.

5. Click Update.

6.3. Select a chart type

The Data Visualizer app has nine different chart types, each with different characteristics. To
select a chart type:

31
Using the Data Visualizer app Select dimension items

1. In Chart type, click the chart type you need.

Table 6.1. Chart types

Chart type Description

Column chart Displays information as vertical rectangular columns with
lengths proportional to the values they represent.

Useful when you want to, for example, compare

performance of different districts.
Stacked column chart Displays information as vertical rectangular columns,
where bars representing multiple categories are stacked on
top of each other.

Useful when you want to, for example, display trends or

sums of related data elements.
Bar chart Same as column chart, only with horizontal bars.
Stacked bar chart Same as stacked column chart, only with horizontal bars.
Line chart Displays information as a series of points connected by
straight lines. Also referred to as time series.

Useful when you want to, for example, visualize trends in

indicator data over multiple time periods.
Area chart Is based on line chart, with the space between the axis and
the line filled with colors and the lines stacked on top of
each other.

Useful when you want to compare the trends of related

indicators.
Pie chart Circular chart divided into sectors (or slices).

Useful when you want to, for example, visualize the

proportion of data for individual data elements compared
to the total sum of all data elements in the chart.
Radar chart Displays data on axes starting from the same point. Also
known as spider chart.
Speedometer chart Semi-circle chart which displays values out of 100 %. Also
referred to as a gauge chart.

2. Click Update.

6.4. Select dimension items

A dimension refers to the elements which describe the data values in the system. There are
three main dimensions in the system:

• Data: Includes data elements, indicators and datasets (reporting rates), describing the
phenomena or event of the data.

• Periods: Describes when the event took place.

• Organisation units: Describes where the event took place.

The Data Visualizer app lets you use these dimensions completely flexible in terms of appearing
as series, categories and filter.

32
Using the Data Visualizer app Select indicators

Note
You can select dimension items in different ways:
• Double-click a dimension item name.
• Highlight one or several dimension items and click the single-arrow.
• To select all dimension items in a list, click the double-arrow.
• To deselect dimension items, use the arrows or double-click the names in the Selected
list.

6.4.1. Select indicators

The Data Visualizer app can display any number of indicators and data elements in a chart.
You can select both indicators and data elements to appear together in the same chart, with
their order of appearance the same as the order in which they are selected.
1. Click Data and select Indicators.
2. Select an indicator group.

The indicators in the selected group appear in the Available list.

3. Select one or several indicators by double-clicking the name.

The indicator moves to the Selected list.

6.4.2. Select data elements

The Data Visualizer app can display any number of indicators and data elements in a chart.
You can select both indicators and data elements to appear together in the same chart, with
their order of appearance the same as the order in which they are selected.
1. Click Data and select Data elements.
2. Select a data element group.

The data elements in the selected group appear in the Available list.
3. Select one or several data elements by double-clicking the name.

The data element moves to the Selected list.

6.4.3. Select reporting rates

The Data Visualizer app can display reporting rates in a chart, by itself or together with
indicators and data elements. Reporting rates are defined by data sets.
1. Click Data and select Reporting rates.

The reporting rates appear in the Available list.

2. Select one or several reporting rates by double-clicking the name.

The reporting rate moves to the Selected list.

6.4.4. Select fixed and relative periods

1. Click Periods.
2. Select one or several periods.

You can combine fixed periods and relative periods in the same chart. Overlapping periods
are filtered so that they only appear once.

33
Using the Data Visualizer app Select organisation units

• Fixed periods: In the Select period type box, select a period type. You can select any
number of fixed periods from any period type.
• Relative periods: In the lower part of the Periods section, select as many relative periods
as you like. The names are relative to the current date. This means that if the current
month is March and you select Last month, the month of February is included in the chart.

6.4.5. Select organisation units

1. Click Organisation units.
2. Click the gearbox icon.
3. Select a Selection mode and an organisation unit.

There are three different selection modes:

Table 6.2. Selection modes

Selection mode Description

Select organisation units Lets you select the organisation units you want to
appear in the chart from the organization tree.

Select User org unit to disable the organisation unit

tree and only select the organisation unit that is
related to your profile.

Select User sub-units to disable the organisation unit

tree and only select the sub-units of the organisation
unit that is related to your profile.

Select User sub-x2-units to disable the organisation

unit tree and only select organisation units two levels
down from the organisation unit that is related to your
profile.

This functionality is useful for administrators to create

a meaningful "system" favorite. With this option
checked all users find their respective organisation
unit when they open the favorite.
Select levels Lets you select all organisation units at one or more
levels, for example national or district level.

You can also select the parent organisation unit in the

tree, which makes it easy to select for example, all
facilities inside one or more districts.
Select groups Lets you select all organisation units inside one or
several groups and parent organisation units at the
same time, for example hospitals or chiefdoms.
4. Click Update.

6.4.6. Select additional dimension items

Depending on the settings for your organisation unit group sets and data element group sets,
you can select additional dimension items from the left menu.

Here you can add dimension items such as age, sex, etc. without having to add them as detailed
data element selections. This is useful when you want to separate these categories in your
analysis.

34
Using the Data Visualizer app Select series, category and filter

The additional dimension items you select are available in Chart layout as dimensions.

6.5. Select series, category and filter

You can define which dimension of the data you want to appear as series, category and filter.

1. Click Layout.

2. Drag and drop the dimensions to the appropriate space. Only one dimension can be in each
section.

3. Click Update.

35
Using the Data Visualizer app Select series, category and filter

Example 6.1. Chart illustrating the concepts of series, categories and filter

• Series: A series is a set of continuous, related elements (for example periods or data
elements) which you want to visualize in order to emphasize trends or relations in its data.

• Categories: A category is a set of elements (for example indicators or organisation units) for
which you want to compare its data.

• Filter: Since most charts are two-dimensional, a filter must be used on the third dimension
in order to use only a single element for the chart to become meaningful.

36
Using the Data Visualizer app Change the display of your chart

6.6. Change the display of your chart

1. Click Options.

2. Set the options as required.

Table 6.3. Chart options

Option Description
Show values Shows the values above the series in the chart.
Hide empty category items Hides the category items with no data from the chart.
Show trend lines Displays the trend line which visualizes how your
data evolves over time. For example if performance
is improving or deteriorating. Useful when periods
are selected as category.
Target value / title: Displays a horizontal line at the given domain value.
Useful for example when you want to compare your
performance to the current target.
Base value / title: Displays a horizontal line at the given domain value.
Useful for example when you want to visualize how
your performance has evolved since the beginning
of a process.

37
Using the Data Visualizer app Download a chart as an image or a
PDF

Option Description
Sort order: Allows you to sort the values on your chart from
either low to high or high to low.
Aggregation type: Defines how the data elements or indicators will
be aggregated within the chart. Some of the
aggregation types are By data element, Count, Min
and Max.
Include only completed events Includes only completed events in the aggregation
process. This is useful when you want for example to
exclude partial events in indicator calculations.
Range axis min/max: Defines the maximum and minimum value which will
be visible on the range axis.
Range axis tick steps: Defines the number of ticks which will be visible on
the range axis.
Range axis decimals: Defines the number of decimals which will be used
for range axis values.
Range axis title: Type a title here to display a label next to the range
axis (also referred to as the Y axis). Useful when you
want to give context information to the chart, for
example about the unit of measure.
Domain axis title: Type a title here to display a label below the domain
axis (also referred to as the X axis). Useful when you
want to give context information to the chart, for
example about the period type.
Hide chart legend Hides the legend and leaves more room for the chart
itself.
Hide chart title Hides the title of your chart.
Chart title: Type any title here to display it above the chart.

3. Click Update.

6.7. Download a chart as an image or a PDF

After you have created a chart you can download it to your local computer as an image or
PDF file.

1. Click Download.

2. Under Graphics, click Image (.png) or PDF (.pdf).

The file is automatically downloaded to your computer. Now you can for example embed the
image file into a text document as part of a report.

6.8. Download chart data source

You can download the data source behind a chart in JSON, XML, Excel, CSV, JXRML or Raw data
SQL formats with different identification schemes (ID, Code, and Name). The data document
uses identifiers of the dimension items and opens in a new browser window to display the URL
of the request to the Web API in the address bar. This is useful for developers of apps and other
client modules based on the DHIS2 Web API or for those who require a plan data source, for
instance for import into statistical packages.

38
Using the Data Visualizer app Download chart data source

To download plain data source formats:

1. Click Download.

2. Under Plain data source, click the format you want to download.

Table 6.4. Available formats

Format Action Description

JSON Click JSON Downloads JSON format based on ID
property.

You can also download JSON format based

on Code or Name property.
XML Click XML Downloads XML format based on ID
property.

You can also download XML format based

on Code or Name property.
Microsoft Click Microsoft Excel Downloads Microsoft Excel format based
Excel on ID property.

You can also download Microsoft Excel

format based on Code or Name property.
CSV Click CSV Downloads CSV format based on ID
property.

You can also download CSV format based

on Code or Name property.
JRXML Put the cursor on Advanced Produces a template of a Jasper Report
and click JRXML which can be further customized based on
your exact needs and used as the basis
for a standard report in DHIS 2.
Raw data SQL Put the cursor on Advanced Provides the actual SQL statement used
and click Raw data SQL to generate the data visualization. You
can use it as a data source in a Jasper
report, or as the basis for a SQL view.

39
Using the Data Visualizer app Manage chart favorites

6.9. Manage chart favorites

Saving your charts as favorites makes it easy to restore them later. It also gives you the
opportunity to share them with other users as an interpretation or display them on the
dashboard.

6.9.1. Save a chart as a favorite

1. Click Favorites.

The Favorites dialog box opens.

2. Click Add new.

The Create new favorite dialog box opens.

3. In the text box, type the name you want to give your chart.
4. Click Create.

6.9.2. Open a favorite

1. Click Favorites.

The Favorites dialog box opens.

2. Find the favorite you want to open. You can either use Prev and Next or the search field to
find a saved favorite. The list is filtered on every character that you enter.
3. Click the name.

6.9.3. Rename a favorite

1. Click Favorites.

The Favorites dialog box opens.

2. Find the favorite you want to rename.

You can either use Prev and Next or the search field to find a saved favorite.

40
Using the Data Visualizer app Overwrite a favorite

3. Click the grey rename icon next to the favorite's name.

The Rename favorite dialog box favorite opens.

4. Type the new name and click Update.

6.9.4. Overwrite a favorite

To save the current chart to an existing favorite (overwrite):
1. Click Favorites.

The Favorites dialog box opens.

2. Find the favorite you want to overwrite.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the green overwrite icon next to the favorite's name.
4. Click OK to confirm that you want to overwrite the favorite.

6.9.5. Share a chart interpretation

For certain analysis-related resources in DHIS2, you can share a data interpretation. An
interpretation is a link to the relevant resource together with a text expressing some insight
about the data.

To create an interpretation of a chart and share it with all users of the system:
1. Open or create a favorite chart.
2. Click Share > Write interpretation.

The Write interpretation dialog box opens.

3. In the text field, type a comment, question or interpretation.
4. Click Share.

The dialog box closes automatically. You can see the interpretation on the Dashboard.

6.9.6. Modify sharing settings for a favorite

After you have created a chart and saved it as a favorite, you can share the favorite with
everyone or a user group. To modify the sharing settings:

1. Click Favorites.
2. Find the favorite you want to share.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the blue share icon next to the favorite's name.
4. In the text box, enter the name of the user group you want to share your favorite with and
click the + icon.

The chosen user group is added to the list of recipients.

Repeat the step to add more user groups.

5. If you want to allow external access, select the corresponding box.
6. For each user group, choose an access setting. The options are:
• None
• Can view
• Can edit and view

41
Using the Data Visualizer app Delete a favorite

7. Click Save.

6.9.7. Delete a favorite

1. Click Favorites.

The Favorites dialog box opens.

2. Find the favorite you want to delete.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the red delete icon next to the favorite's name.
4. Click OK to confirm that you want to delete the favorite.

6.10. Embed charts in any web page

Certain analysis-related resources in DHIS2, like pivot tables, charts and maps, can be
embedded in any web page by using a plug-in. You will find more information about the plug-
ins in the Web API chapter in the DHIS2 Developer Manual.

To generate a HTML fragment that you can use to display the chart in an external web page:

1. Click Share > Embed in web page.

The Embed in web page window opens.

2. Click Select to highlight the HTML fragment.

6.11. Visualize a chart as a pivot table or a map

When you have made a chart you can switch between pivot table, chart and map visualization
of your data.

6.11.1. Open a chart as a pivot table

1. Click Chart > Open this chart as table.

Your current chart opens as a pivot table.

6.11.2. Open a chart as a map

1. Click Chart > Open this chart as map.

Your current chart opens as a map.

42
Using the GIS app About the GIS app

Chapter 7. Using the GIS app

7.1. About the GIS app

Main GIS screen

• The icons in the left upper corner represent the vector layers and they are the starting point
of the GIS app.
• In the top right corner you get an overview of the layers:
• If you are online you will see Google Streets and Google Hybrid which can be used as
background maps and layers. Switch between the two of them by checking the check box.
The default base map is OpenStreetMap. To get a nice background map, select the OSM
Light. By clearing a box you can hide the corresponding background completely.
• If you want to see the background, but with reduced opacity, you can set the visibility to
something lower than 100 % in the box to the right.
• The final four layers are the vector layers which you use for thematic mapping (explained
in the next section). The panels below hold the map legends when you create a thematic
map. A legend explains the link between values and colors on your map.
• Zoom to content automatically adjusts the zoom level and map center position to put the
data on your map in focus.
• To get information for an event you can simply click on it. This opens a pop-up window which
displays all available information for that event.
• The current longitude and latitude position of the mouse cursor is displayed in the bottom
right corner of the map.

7.2. Create a new thematic map

You use four vector layers to create a thematic map. The workflow for creating a new thematic
map is:
1. In the Apps menu, click GIS.

The DHIS2 GIS window opens.

2. In the top menu, click a layer you want to add to the map.

43
Using the GIS app Manage event layer

• Event layer
• Facility layer
• Boundary layer
• Thematic layer 1 - 4
3. Click Edit layer and select the parameters you need..
4. Click Update.

7.3. Manage event layer

The purpose of the event layer is to display the geographical location of events registered in
the DHIS2 tracker. This layer lets you drill down from the aggregated data displayed in the
thematic layers to the underlying individual events or cases.

Event layer

7.3.1. Create or modify event layer

1. In the top menu, click the event layer icon.
2. Click Edit layer.
3. Select a program and then select a program stage.

If there is only one stage available for the selected program, the stage is automatically
selected. A list of data elements and attributes will appear in the Available data items panel.
4. Select any data element or attribute from this list as part of your query.
• To select you can either double-click a data element or (multi) select and use the single-
arrow downward button. The double-arrow button will select all data elements in the list.
All selected data elements will get their own row in the Selected data items.
• You can use an element multiple times in your query by clicking Duplicate.
• For data elements of type text you will get two choices: Contains implies that the query will
match all values which contains your search value, and Is exact implies that only values
which is completely identical to your search query will be returned.
• For data elements of type option set, you can select any of the options from the drop down
box by using the down-wards arrow or by start typing directly in the box to filter for options.
44
Using the GIS app Turn off cluster

5. In the Periods section, select the time span for when the events took place. You can select
either a fixed period or a relative period.
• Fixed period: In the Period field, select Start/end dates and fill in a start date and an end
date.
• Relative period: In the Period field, select one of the relative periods, for example This
month or Last year.
6. In the Organisation units section, select the organisation units you want to include in the
query.
7. In the Options section, select if you want group nearby events and change style of the cluster
points.
8. Click Update.

7.3.2. Turn off cluster

By default events are clustered in a map. You can turn off this function to display all events
separately.
1. In the top menu, click the event layer icon.
2. Click Edit layer.
3. Click Options.
4. Clear Group nearby events check box.
5. Click Update.

7.3.3. Modify cluster style

1. In the top menu, click the event layer icon.
2. Click Edit layer.
3. In the Options section, change the Point color and Point radius.
4. Click Update.

7.3.4. Modify information in event pop-up windows

For events in a cluster map, you can modify the information displayed in the event pop-up
window.

Pop-up window with event information

1. On the home page, click Apps > Programs / Attributes.

2. Click Program.
3. Click the program you want to modify and select View program stages.
4. Click the program stage name and select Edit.

45
Using the GIS app Clear event layer

5. Scroll down to the Selected data elements section.

6. For every data element you want to display in the pop-up window, select corresponding
Display in reports.
7. Click Update.

7.3.5. Clear event layer

To clear all data in a map:
1. In the top menu, click the event layer icon.
2. Click Clear.

7.4. Manage facility layer

The facility layer displays icons that represent facilities based on the facility type. Polygons will
not show up on the map, so make sure to select an organisation unit level that has facilities.

Facility layer

7.4.1. Create or modify facility layer

1. In the top menu, click the facility layer icon.
2. Click Edit layer.
3. In the Organisation unit group icons section, select a Group set.
4. In the Organisation units section, select one or several organisation units.
5. In the Options section, select if you want to show labels and if so, how they look.
6. In the Options section, select if you want to display a circle with a certain radius around
each facility.
7. Click Update.

7.4.2. Search for an organisation unit

To locate an organisation unit in the map:
1. In the top menu, click the facility layer icon.
2. Click Search.

46
Using the GIS app Clear facility layer

The Organisation unit search dialog box opens.

3. In the text field, type the name of the organisation unit you are looking for or click a name
in the list.

The organisation unit is highlighted in the map.

7.4.3. Clear facility layer

To clear all data in a facility layer:
1. In the top menu, click the facility layer icon.
2. Click Clear.

7.5. Manage boundary layer

The purpose of the boundary layer is to display the boundaries and coordinates in the system.
No data will be shown. This layer is useful if you are offline and thus have no background map.

Boundary layer

7.5.1. Create or modify boundary layer

1. In the top menu, click the boundary layer icon.
2. Click Edit layer.
3. In the Organisation units section, select one or several organisation units.

You can select the organisation units you want to show on the map by selecting a level and a
parent. That means "show all organisations units at this level that are children of this parent".
4. In the Options section, select if you want to show labels and if so, how they look.
5. Click Update.

7.5.2. Search for an organisation unit

To locate an organisation unit in the map:
1. In the top menu, click the boundary layer icon.

47
Using the GIS app Navigate between organisation
hierarchies
2. Click Search.

The Organisation unit search dialog box opens.

3. In the text field, type the name of the organisation unit you are looking for or click a name
in the list.

The organisation unit is highlighted in the map.

7.5.3. Navigate between organisation hierarchies

When there are visible organisation units on the map, you can easily navigate up and down in
the hierarchy without using the level/parent user interface.
1. Right-click one of the organisation units.
2. Select Float up or Drill down.

The drill down option is disabled if you are on the lowest level or if there are no coordinates
available on the level below. Vice versa goes for floating up.

7.5.4. Clear boundary layer

To clear all data in a boundary layer:
1. In the top menu, click the boundary layer icon.
2. Click Clear.

7.6. Manage thematic layer 1- 4

The four thematic layer panels let you use your data for thematic mapping. Select your desired
combination of indicator/data element, period and map combination, then the organisation unit
level and parent to define the boundaries. If your database has coordinates and aggregated
data values for these organisation units, they will appear on the map.

Note
You must refresh the DHIS2 analytics tables to have aggregated data values available.

Thematic mapping

48
Using the GIS app Create or modify a thematic layer

7.6.1. Create or modify a thematic layer

1. In the top menu, click the icon of the thematic layer you want to create or modify.
2. Click Edit layer.
3. In the Data and periods section, select the data and periods you want to display.
4. In the Organisation units section, select one or several organisation units.
5. In the Options section, select Automatic or Predefined legend type.

• Automatic legend types means that the application will create a legend set for you based
on your what method, number of classes, low color and high color you select. Method
alludes to the size of the legend classes.

Set to Equal intervals they will be “highest map value – lowest map value / number of
classes”.

Set to Equal counts the legend creator will try to distribute the organisation units evenly.

The legend appears as an even gradation from the start color to the end color.
• If you have facilities in your thematic layer, you can set the radius for maximum and
minimum values by changing the values in the Low color / size and High color size boxes.
• For information about Predefined legend sets, see Section  7.10, “Manage map legend
sets” .
6. In the Options section, select if you want to show labels and if so, how they look.
7. Click Update.

7.6.2. Filter values in a thematic layer

Thematic layer 1-4 menu have a Filter option in addition to the boundary layer menu options.
It lets you apply value filters to the organisation units on the map. The filter is removed when
you close the filter window.

To filter values in a thematic layer:

1. In the top menu, click the icon of thematic layer you want to create or modify.
2. Click Filter....
3. Modify the Greater than and And/or lower than values.
4. Click Update.

7.6.3. Search for an organisation unit

To locate an organisation unit in a thematic layer:
1. In the top menu, click the relevant thematic layer icon.
2. Click Search.

The Organisation unit search dialog box opens.

3. In the text field, type the name of the organisation unit you are looking for or click a name
in the list.

The organisation unit is highlighted in the map.

7.6.4. Navigate between organisation hierarchies

When there are visible organisation units on the map, you can easily navigate up and down in
the hierarchy without using the level/parent user interface.

49
Using the GIS app Clear thematic layer

1. Right-click one of the organisation units.

2. Select Float up or Drill down.

The drill down option is disabled if you are on the lowest level or if there are no coordinates
available on the level below. Vice versa goes for floating up.

7.6.5. Clear thematic layer

To clear all data in a thematic layer:

1. In the top menu, click the relevant thematic layer icon.

2. Click Clear.

7.7. Manage facilities in a layer

You can have facilities in Facility, Boundary and Thematic layers.

7.7.1. Relocate a facility

1. Right-click a facility and click Relocate.

2. Put the cursor in the new location.

The new coordinate is stored permanently..

7.7.2. Swap longitude and latitude of a facility

1. Right-click a facility and click Swap lob/lat.

7.7.3. Display facility information

You can view organisation unit information set by the administrator in two different ways.

Table 7.1. View organisation unit information

Function Action
View information for the current 1. Click a facility.
period
View information for a selected 1. Right-click a facility and click Show information.
period 2. In the Infrastructural data section, select a period.

50
Using the GIS app Manage Earth Engine layer

7.8. Manage Earth Engine layer

The Google Earth Engine layer lets you display satellite imagery and geospatial datasets from
Google's vast catalog. This layer is useful in combination with thematic and event layers to
enhance analysis. The following layers are supported:

• Elevation: Metres above sea level

• Nighttime lights: Lights from cities, towns, and other sites with persistent lighting, including
gas flares (from 2013)

• Population density: Population in 100 x 100 m grid cells (from 2010)

7.8.1. Create or modify an Earth Engine layer

1. In the top menu, click the Google Earth Engine layer icon.

2. Select a data set, for example "Elevation".

3. Select Min / max value.

The meaning of these values depend on which data set you've selected.

4. Select a Color scale.

5. Select the number of Steps.

The number of steps means the number of distinct colors in the color scale.

6. Click Update.

51
Using the GIS app Manage map favorites

7.9. Manage map favorites

Favorite maps

Saving your maps as favorites makes it easy to restore them later. It also gives you the
opportunity to share them with other users as an interpretation or put it on the dashboard. You
can save all types of layers as a favorite. A favorite always opens with the default background
map.

7.9.1. Save a map as a favorite

When you have created a map it is convenient to save it as a favorite:
1. Click Favorites.

The Manage favorites dialog box opens.

2. Click Add new.

The Create new favorite dialog box opens.

3. In the text field, type the name you want to give your pivot table.
4. Click Create.

Your favorite is added to the list.

7.9.2. Open a favorite

1. Click Favorites.

The Manage favorites dialog box opens.

2. Find the favorite you want to open. You can either use Prev and Next or the search field to
find a saved favorite. The list is filtered on every character that you enter.
3. Click the name.

7.9.3. Rename a favorite

1. Click Favorites.

The Manage favorites dialog box opens.

2. Find the favorite you want to rename.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the grey rename icon next to the favorite's name.

52
Using the GIS app Overwrite a favorite

The Rename favorite dialog box favorite opens.

4. Type the new name and click Update.

7.9.4. Overwrite a favorite

To save the current map to an existing favorite (overwrite):
1. Click Favorites.

The Manage favorites dialog box opens.

2. Find the favorite you want to overwrite.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the green overwrite icon next to the favorite's name.
4. Click OK to confirm that you want to overwrite the favorite.

7.9.5. Share a map interpretation

For certain analysis-related resources in DHIS2, you can share a data interpretation. An
interpretation is a link to the relevant resource together with a text expressing some insight
about the data.

To create an interpretation of a map and share it with all users of the system:
1. Open or create a favorite map.
2. Click Share > Write interpretation.

The Write interpretation dialog box opens.

3. In the text field, type a comment, question or interpretation.
4. Click Share.

The dialog box closes automatically. You can see the interpretation on the Dashboard.

7.9.6. Modify sharing settings for a favorite

After you have created a map and saved it as a favorite, you can share the favorite with
everyone or a user group. To modify the sharing settings:

1. Click Favorites.
2. Find the favorite you want to share.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the blue share icon next to the favorite's name.
4. In the text box, enter the name of the user group you want to share your favorite with and
click the + icon.

The chosen user group is added to the list of recipients.

Repeat the step to add more user groups.

5. If you want to allow external access, select the corresponding box.
6. For each user group, choose an access setting. The options are:
• None

53
Using the GIS app Delete a favorite

• Can view
• Can edit and view
7. Click Save.

7.9.7. Delete a favorite

1. Click Favorites.

The Manage favorites dialog box opens.

2. Find the favorite you want to delete.

You can either use Prev and Next or the search field to find a saved favorite.
3. Click the red delete icon next to the favorite's name.
4. Click OK to confirm that you want to delete the favorite.

7.10. Manage map legend sets

You can create your own legend sets to ensure meaningful maps.

Note
Continuous legends are supposed to end and start on the same value, for example 0-50
and 50-80. The GIS app automatically take care of this. Do not try to do this yourself
by setting legends to for example 0-50 and 51-80. This will cause a usually unwanted
gap in your legend set.

7.10.1. Create a new legend set

1. Click Legends.

The Legend sets dialog box opens.

2. Click Add new.
3. In the Legend set name box, type the name you want to give the legend set.
4. Create the legends you want to have in your legend set:
a. In the Legend name field, type the legend name.
b. Select Start/end value.
c. Select Symbolizer.
d. Click Add legend.

The legend is added to Current legends.

e. Repeat until you have created all the legends you need.

Example 7.1. Vaccination coverage legends

Table 7.2. Example of vaccination coverage legends

Legend name Start value End value Symbolizer

Low bad 0 50 red
Medium 50 80 yellow
High good 80 100 green
Too high 100 1000 grey
54
Using the GIS app Change a legend set

5. Click Create.

Note
If your legend set has overlapping legends (for example 0-50 and 40-80) you will not
be allowed to proceed. If your legend set has a gap between the legends (for example
0-50 and 60-80) you will get a warning, but are allowed to proceed.

7.10.2. Change a legend set

1. Click Legends.

The Legend sets dialog box opens.

2. Click the edit icon next to the legend set you want to modify.
3. In the Current legends list, click the edit icon next to the legend you want to modify.

The Edit legend dialog box opens.

4. Modify the parameters and click Update.
5. In the Legend sets dialog box, click Update.

7.10.3. Delete a legend set

1. Click Legends.

The Legend sets dialog box opens.

2. Click the delete icon next to the legend set you want to delete.
3. Click OK to confirm that you want to delete the legend set.

7.10.4. Assign a legend set to indicator or data element

You can assign a legend set to an indicator or a data element in the Indicator/Data element
module. This legend set will then be automatically selected when such an indicator/data
element is selected in the GIS.

7.11. Download a map as image

1. Take a screenshot of the map with the tool of your choice.
2. Save the screenshot in desired format.

7.12. Embed a map in an external web page

Certain analysis-related resources in DHIS2, like pivot tables, charts and maps, can be
embedded in any web page by using a plug-in. You will find more information about the plug-
ins in the Web API chapter in the DHIS2 Developer Manual.

To generate a HTML fragment that you can use to display the map in an external web page:

1. Click Share > Embed in web page.

The Embed in web page window opens.

2. Click Select to highlight the HTML fragment.

55
Using the GIS app Search for a location

7.13. Search for a location

The place search function allows you to search for almost any location or address. The place
search is powered by the Mapzen mapping platform. This function is useful in order to locate
for example sites, facilities, villages or towns on the map.

1. On the left side of the GIS window, click the magnifier icon.
2. Type the location you're looking.

A list of matching locations appear as you type.

3. From the list, select a location. A pin indicates the location on the map.

7.14. Measure distance and area in a map

1. In the upper left part of the map, put the cursor on the Measure distances and areas icon
and click Create new measurement.
2. Add points to the map.
3. Click Finish measurement.

7.15. Visualize a map as a pivot table or a chart

When you have made a map you can switch between pivot table, chart and map visualization
of your data. The function is inactive if the data the map is based on cannot render as a chart
or table.

7.15.1. Open a map as a chart

1. Click Chart > Open this map as chart.

Your current map opens as a chart.

7.15.2. Open a map as a pivot table

1. Click Chart > Open this map as table.

Your current map opens as a pivot table.

56
Dashboards Setting up the dashboard

Chapter 8. Dashboards
Dashboards are intended to provide quick access to different analytical objects (maps, charts,
reports, tables, etc) to an individual user. Dashboards can also be shared with user groups. For
instance, a user or administrator could create a dashboard called "Malaria" which might contain
all relevant information on malaria. This dashboard could then be shared with the user group
called "Malaria control", which might consist of all users of the malaria control programme. All
users within this group would then be able to view the same dashboard.

8.1. Setting up the dashboard

The dashboard can contain any number of objects (charts, maps, reports, tables, resources,
etc). These can be freely arranged on the dashboard as you wish. Dashboard items can be
located and added by searching for favourites, resources, users or messages in the available
search box and clicking on the "Add" button.

In this screen shot, the dashboard has already been populated with a number of objects, such
as charts, map views, tables and messages. There are several hyperlink options available on
each item:
• Remove

Allows you to remove the item from the dashboard when you have the appropriate user
rights.
• Get as Image

Opens up a pop-up window and allows you to download the image to your computer.
• Share interpretation

Allows you to share an interpretation of the dashboard item. Your interpretation will be
shared publicly with other users of the DHIS2 system, in the "Interpretation" section of the
dashboard.
• Explore

Loads the favorite in its corresponding app (ie. a map will open full-sized in the GIS app).
• Resize

Resizes the dashboard item. There are 3 sizes in which to choose from.

57
Dashboards Managing the Dashboard

Maps, charts and tables can be viewed as full size as images (in the case of charts and map
views) or as HTML resources (in the case of reports, tables and messages).

To reorder how the dashboard appears, simply drag-and-drop any of the objects to a new
position. In order to change between the various dashboards which are available, simply select
the listed items that are available to review. The list can be scrolled though by using the <,
> symbols to the left of the dashboard names.

8.2. Managing the Dashboard

In addition to adding items or modifying the layout of a dashboard, further options allow
you to add additional dashboards, modify their names, delete an entire dashboard an share
the dashboard with other users. These additional items can be managed using the "Add,"
"Manage," and "Share" links on the top left of the dashboard next to the dashboard names.

• Add

Allows additional dashboards to be added.

• Manage

Can change the name of the dashboard, add messages to or delete the dashboard. This
applies to the currently selected dashboard item.
• Share

Allows the sharing of dashboard items with user groups. User permissions can also be
assigned to each user group.

8.3. Dashboard Sharing

In order to share a dashboard with user groups, first select "Share" from the dashboard page.
This will bring up the dashboard sharing settings options. To share the dashboard with specific
user groups, type in their name in the sharing settings dialogue box and click on the "+" sign
to add them to the dashboard sharing settings

All dashboards have two sharing groups set by default.

• External access (without login)

This option, when selected, provides access to the dashboard as an external resource. This is
useful for when you are creating an external web portal but would like to call information from
a dashboard you have made internally within DHIS2. By default, this option is not selected.

58
Dashboards Manage messages and feedback
messages
• Public access (with login)

This option allows the selected dashboard to be pushed to all users within your DHIS2
instance. This can also be hidden from public view by selecting the "None" option, which is
the default option for new dashboards.

User groups which have been added manually can be assigned two types of permissions within
the dashboard

• Can view

Provides the user group with view only rights to the dashboard.

• Can edit and view

Allows the user groups to edit the dashboard in addition to viewing it. Editing allows for
altering the layout, resizing and removing items, renaming/deleting the dashboard etc.

8.4. Manage messages and feedback messages

8.4.1. About messages and feedback messages

Within DHIS2 you can send messages and feedback messages to users, user groups and
organisation units. When you send a feedback message, it is routed to a particular user group.
If you're a member of this user group, you've access to feedback handling tools. You can
for example set the status of an incoming feedback to "Pending" while you're waiting for
information.

Note
Messages and feedback messages are not sent to users' e-mail addresses, the messages
only appear within DHIS2.

59
Dashboards Create a message

8.4.2. Create a message

1. From the Dashboard, click Messages.

2. Click Write message.
3. Define who you want to receive the message. You can send a message to organisation units,
users and user groups.
• In the To org unit field, select the organisation units or group of organisation units you
want to send the message to.
• In the To user field, select the users or user groups you want to send the message to.
4. Type a subject and a message.
5. Click Send.

8.4.3. Read a message

1. From the Dashboard, click Messages.
2. Click a message.

If the message is part of a conversation, you'll see all messages in this conversation.

8.4.4. Create a feedback message

1. From the Dashboard, click Write feedback.
2. Type a subject and a feedback message.
3. Click Send.

The feedback message will appear in all of the specified users' inboxes.

8.4.5. Configure feedback message function

To configure the feedback message function, you must:
1. Create a user group (for example "Feedback recipients") that contains all the users who
should receive feedback messages.

60
Dashboards Manage feedback messages

2. Click Apps > Settings > General > Feedback recipients and select the user group.

8.4.6. Manage feedback messages

Note
You'll only see feedback messages and have access to the feedback handling tools if
you are a member of the user group that is set up to handle feedback messagess.

You'll receive feedback messages to your Messages inbox. For feedback messages you've the
following options in addition to the messages options:

Table 8.1. Feedback handling tools

Function Description
Set status All feedback messages get the status Open
when created.

To keep track of existing feedback

messages, you can change the status to
Invalid, Pending or Solved.

You can filter feedback messages in your

inbox based on their status. This makes
it easier to switch between feedback
messages and normal messages.
Set priority You can mark a feedback message with
different priorities: None, Low, Medium or
High.

Setting the priority makes it easier to

keep track of which feedback message you
need resolved first, and which feedback
messages that can wait.
Write internal reply When you work in a feedback handling
team you might want to discuss the
feedback before sending an answer to the
sender. You can keep this discussion in
the same message conversation as the
feedback itself.

To send a reply that within the feedback

handling user group, click Internal reply.

61
User profiles User settings

Chapter 9. User profiles

With profiles, users can alter the appearance of their DHIS2, change the interface language,
and enabled SMS and email notifications. Users can also enter information into their "Profile".

9.1. User settings

To access the user settings menu, select "Profile->Settings". You can select the interface
language and the database language. The interface language refers to the translation of the
user interface of the DHIS2 software. The database language refers to the translated content
of the metadata contained in the system, for instance, data elements and indicators. Different
interface styles can be set to alter the apperarnce of the system.

User can choose to receive their messages via email and/or SMS by ticking the appropriate
check boxes.

If no value is set for a given user setting, the system setting value will be used.

9.2. User profile

Users can choose to enter more data, such as their email and phone number, job title, gender,
birthday, etc into their profile. Just select "Profile->Profile" from the main menu.

63