Dhis2 User Manual

DHIS2 User Manual
DHIS core version 2.34
DHIS2 Documentation Team

DHIS2 User Manual DHIS core version 2.34
Copyright © 2008-2021 DHIS2 Team
Last update: 2021-07-13
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
2
Table of contents DHIS core version 2.34
Table of contents
What is DHIS2?
DHIS2 Background
Key features and purpose of DHIS2
Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.
Technical background
Difference between Aggregated and Patient data in a HIS
Free and Open Source Software (FOSS): benefits and challenges
Using the Data Entry app
About the Data Entry app
Enter data in a data entry form
Mark a data value for follow-up
Edit data values in a completed data entry form
Display a data value's history
Display a data value's audit trail
Create minimum maximum value range manually
Enter data offline
Enable multi-organisation unit data entry
See also
Control data quality
About data quality checks
Validation rule analysis
Standard deviation outlier analysis
Minimum maximum outlier analysis
Follow-up analysis
Using the Capture app
About the Capture app
Register an event
Adding a relationship
Edit an event
Delete an event
Modify an event list layout
Filter an event list
Sort an event list
Download an event list
Predefined list views
User assignment
Tracker programs
Using the Event Capture app
About the Event Capture app
Register an event
Edit an event
Edit events in grid
Share events in edit mode
View an event audit history
Delete an event
Modify an event list's layout
Print an event list
Using the Tracker Capture app
About the Tracker Capture app
About tracked entity instance (TEI) dashboards
Workflow
3
Linking to the Tracker Capture App

Create a TEI and enroll it in a program
Open an existing TEI dashboard
Enroll an existing TEI in a program
Enter event data for a TEI
How to use geometry
How to assign a user to an event
Manage a TEI's enrollments
Send a message to a TEI
Mark a TEI for follow-up
Edit a TEI's profile
Add a relationship to a TEI
Share a TEI dashboard
Deactivate a TEI
Activate a TEI
Delete a TEI
Configure the TEI dashboard
Create reports
Data approval
Approving and accepting
Authorities for approving data
Configuring data approval
Data visibility
Approving data
Approving by category option group set
Approving by multiple category option group sets
Reporting functionality in the reports app
Using standard reports
Using dataset reports
Using reporting rate summary
Using resources
Using organisation unit distribution reports
Using the Data Visualizer app
Creating and editing visualizations
Change the display of your visualization
Adding Assigned Categories
Adding more axes
Manage saved visualizations
Visualization interpretations
Share a visualization
Download
See visualization as map
Analyze data in pivot tables
About the Pivot Table app
Create a pivot table
Change the display of your pivot table
Manage favorites
Download data from a pivot table
Embed a pivot table in an external web page
Visualize pivot table data as a chart or a map
Using the Maps app
About the Maps app
Create a new map
Manage thematic layers
4
Manage event layers

Manage tracked entity layers
Manage facility layers
Manage boundary layers
Manage Earth Engine layer
Add external map layers
File menu
Map interpretations
Save a map as an image
Search for a location
Measure distances and areas in a map
Get the latitude and longitude at any location
See also
Managing dashboards
About dashboards
Dashboard and control bar
Creating a dashboard
Removing items
Saving the dashboard
Editing an existing dashboard
Deleting a dashboard
Viewing a dashboard
Dashboard items with charts, pivot tables and maps
Interpretations
Sharing a dashboard
Using the Event Reports app
About the Event Reports app
Create an event report
Select dimension items
Select series, category and filter
Change the display of your table
Download chart data source
Manage favorites
Visualize an event report as a chart
Using the Event Visualizer app
About the Event Visualizer app
Create a chart
Select a chart type
Change the display of your chart
Download a chart as an image or a PDF
Manage favorites
Visualize a chart as a pivot table
Messaging
About messages and feedback messages
Create a message
Read a message
Create a feedback message
Attachments
Manage validation and feedback messages
Configure feedback message function
Set user account preferences
5
Configure metadata
About the Maintenance app
Manage categories
Manage data elements
Manage data sets and data entry forms
Manage indicators
Manage organisation units
[Work in progress] Manage validation rules
Manage attributes
Manage constants
Manage option sets
Manage legends
Manage predictors
Manage push reports
Manage external map layers
Manage SQL Views
Manage Locales
Edit multiple object groups at once
Configure programs in the Maintenance app
About programs
Configure event programs in the Maintenance app
Configure tracker programs in the Maintenance app
Configure program indicators
Configure program rules
Configure relationship types
Configure tracked entity types
Configure search
Clone metadata objects
Delete metadata objects
Change sharing settings for metadata objects
Display details of metadata objects
Translate metadata objects
Manage users, user roles and user groups
About user management
Workflow
Manage users
Manage user roles
Manage user groups
Enable support for OpenID
Decentralize user management
Example: user management in a health system
User authorities
About sharing of objects
Sharing of objects
Metadata sharing and access control
Metadata sharing applied
Data sharing and access control
Configure the Maps app
Context
Importing coordinates
Configure report functionality
Data sources for reporting
How to create report tables
Report table outcome
6
Standard reports
Charts
Adding the Report to DHIS2
Some final guidelines
Designing SQL based standard reports
Designing HTML based standard reports
System settings
General settings
Analytics settings
Server settings
Appearance settings
Email settings
Access settings
Calendar settings
Data import settings
Synchronization settings
OAuth2 clients
Data Administration
Data integrity
Maintenance
Resource tables
Analytics tables management
Data statistics
Lock exceptions
Min-Max Value Generation
Cache Statistics
Visualize usage statistics
About the Usage Analytics app
Create a usage analytics graph
Datastore Manager
Using the Datastore Manager
Add a new namespace and key to the Datastore Manager
Add a key to an existing namespace in the Datastore Manager
Delete a namespace or key from the Datastore Manager
Search for namespaces or keys
Search your JSON library
Edit namespaces or keys in the Datastore Manager
Scheduling
Creating a job
Configuring a job
Deleting a job
Job types
Import/Export App
Importing data
Exporting data
Configure metadata synchronizing
About data and metadata synchronization
Workflow
Configure metadata versioning on central instance
Connect local instance to central instance
Configure automatic metadata synchronization on local instance
Create a new metadata version manually on central or local instance
Reference information: metadata synchronization configuration parameters
7
Mobile
DHIS2 Mobile Introduction
Mobile browser based data entry
J2ME GPRS/3G Client
SMS Command
SMS Service
About data dimensions
Data dimensions: Core building blocks in DHIS2
Data elements: the what dimension
Organisation units: the where dimension
Period: the when dimension
Data collection vs. data analysis
Extended examples of data elements and forms
How this works in pivot tables
Case study: From paper forms to multidimensional datasets - lessons learned
Additional data dimensions
About additional data dimensions
Create or edit an attribute category and its options
Relationship model
Relationship Type
DHIS2 Glossary
A
B
C
D
H
I
N
O
P
U
About demo server, live package and database design
Using the DHIS2 demo server
Using the DHIS2 live package
Logging on to DHIS2
Logging out of DHIS2
Quick intro to designing a DHIS2 database
DHIS2 Tutorials
Create Scorecards using the Pivot Table app
Working with TextPattern
DHIS2 Frequently Asked Questions
Release and upgrade notes
8
What is DHIS2? DHIS2 Background
What is DHIS2?
After reading this chapter you will be able to understand:
• What is DHIS2 and what purpose it serves with respect to health information systems
(HIS)?
• What are the major technological considerations when it comes to deploying DHIS2, and
what are the options are for extending DHIS2 with new modules?
• What is the difference between patient based and aggregate data?
• What are some of the benefits and challenges with using Free and Open Source Software
(FOSS) for HIS?
DHIS2 Background
DHIS2 is a tool for collection, validation, analysis, and presentation of aggregate and patient-
based statistical data, tailored (but not limited) to integrated health information management
activities. It is a generic tool rather than a pre-configured database application, with an open
meta-data model and a flexible user interface that allows the user to design the contents of a
specific information system without the need for programming. DHIS2 is a modular web-based
software package built with free and open source Java frameworks.
DHIS2 is open source software released under the BSD license and can be obtained at no cost. It
runs on any platform with a Java Runtime Environment (JRE 7 or higher) installed.
DHIS2 is developed by the Health Information Systems Programme (HISP) as an open and
globally distributed process with developers currently in India, Vietnam, Tanzania, Ireland, and
Norway. The development is coordinated by the University of Oslo with support from NORAD and
other donors.
The DHIS2 software is used in more than 40 countries in Africa, Asia, and Latin America, and
countries that have adopted DHIS2 as their nation-wide HIS software include Kenya, Tanzania,
Uganda, Rwanda, Ghana, Liberia, and Bangladesh. A rapidly increasing number of countries and
organisations are starting up new deployments.
The documentation provided herewith, will attempt to provide a comprehensive overview of the
application. Given the abstract nature of the application, this manual will not serve as a complete
step-by-step guide of how to use the application in each and every circumstance, but rather will
seek to provide illustrations and examples of how DHIS2 can be implemented in a variety of
situations through generalized examples.
Before implementing DHIS2 in a new setting, we highly recommend reading the DHIS2
Implementation Guide (a separate manual from this one), also available at the main DHIS2
website.
Key features and purpose of DHIS2
The key features and purpose of DHIS2 can be summarised as follows:
• Provide a comprehensive data management solution based on data warehousing principles

and a modular structure which can easily be customised to the different requirements of a
management information system, supporting analysis at different levels of the
organisational hierarchy.
• Customisation and local adaptation through the user interface. No programming required to
start using DHIS2 in a new setting (country, region, district etc.).
9
What is DHIS2? Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.
Provide data entry tools which can either be in the form of standard lists or tables, or can
• be customised to replicate paper forms.
• Provide different kinds of tools for data validation and improvement of data quality.
• Provide easy to use - one-click reports with charts and tables for selected indicators or
summary reports using the design of the data collection tools. Allow for integration with
popular external report design tools (e.g. JasperReports) to add more custom or advanced
reports.
• Flexible and dynamic (on-the-fly) data analysis in the analytics modules (i.e. GIS,
PivotTables,Data Visualizer, Event reports, etc).
• A user-specific dashboard for quick access to the relevant monitoring and evaluation tools
including indicator charts and links to favourite reports, maps and other key resources in
the system.
• Easy to use user-interfaces for metadata management e.g. for adding/editing datasets or
health facilities. No programming needed to set up the system in a new setting.
• Functionality to design and modify calculated indicator formulas.
• User management module for passwords, security, and fine-grained access control (user
roles).
• Messages can be sent to system users for feedback and notifications. Messages can also
be delivered to email and SMS.
• Users can share and discuss their data in charts and reports using Interpretations,
enabling an active information-driven user community.
• Functionalities of export-import of data and metadata, supporting synchronisation of offline

installations as well as interoperability with other applications.
• Using the DHIS2 Web-API , allow for integration with external software and extension of the
core platform through the use of custom apps.
• Further modules can be developed and integrated as per user needs, either as part of the
DHIS2 portal user interface or a more loosely-coupled external application interacting
through the DHIS2 Web-API.
In summary, DHIS2 provides a comprehensive HIS solution for the reporting and analysis needs
of health information users at any level.
Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.
The wider context of HIS can be comprehensively described through the information cycle
presented in Figure 1.1 below. The information cycle pictorially depicts the different components,
stages and processes through which the data is collected, checked for quality, processed,
analysed and used.
10
What is DHIS2? Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.
The health information cycle
DHIS2 supports the different facets of the information cycle including:
• Collecting data.
• Running quality checks.
• Data access at multiple levels.
• Reporting.
• Making graphs and maps and other forms of analysis.
• Enabling comparison across time (for example, previous months) and space (for example,
across facilities and districts).
• See trends (displaying data in time series to see their min and max levels).
As a first step, DHIS2 serves as a data collection, recording and compilation tool, and all data (be
it in numbers or text form) can be entered into it. Data entry can be done in lists of data elements
or in customised user defined forms which can be developed to mimic paper based forms in order
to ease the process of data entry.
As a next step, DHIS2 can be used to increase data quality. First, at the point of data entry, a
check can be made to see if data falls within acceptable range levels of minimum and maximum
values for any particular data element. Such checking, for example, can help to identify typing
errors at the time of data entry. Further, user can define various validation rules, and DHIS2 can
run the data through the validation rules to identify violations. These types of checks help to
ensure that data entered into the system is of good quality from the start, and can be improved by
the people who are most familiar with it.
11
What is DHIS2? Technical background
When data has been entered and verified, DHIS2 can help to make different kinds of reports. The
first kind are the routine reports that can be predefined, so that all those reports that need to be
routine generated can be done on a click of a button. Further, DHIS2 can help in the generation
of analytical reports through comparisons of for example indicators across facilities or over time.
Graphs, maps, reports and health profiles are among the outputs that DHIS2 can produce, and
these should routinely be produced, analysed, and acted upon by health managers.
Technical background
DHIS2 as a platform
DHIS2 can be perceived as a platform on several levels. First, the application database is
designed ground-up with flexibility in mind. Data structures such as data elements, organisation
units, forms and user roles can be defined completely freely through the application user
interface. This makes it possible for the system to be adapted to a multitude of locale contexts
and use-cases. We have seen that DHIS2 supports most major requirements for routine data
capture and analysis emerging in country implementations. It also makes it possible for DHIS2 to
serve as management system for domains such as logistics, labs and finance.
Second, due to the modular design of DHIS2 it can be extended with additional software modules
or through custom apps. These software modules/apps can live side by side with the core
modules of DHIS2 and can be integrated into the DHIS2 portal and menu system. This is a
powerful feature as it makes it possible to extend the system with extra functionality when
needed, typically for country specific requirements as earlier pointed out.
The downside of the software module extensibility is that it puts several constraints on the
development process. The developers creating the extra functionality are limited to the DHIS2
technology in terms of programming language and software frameworks, in addition to the
constraints put on the design of modules by the DHIS2 portal solution. Also, these modules must
be included in the DHIS2 software when the software is built and deployed on the web server, not
dynamically during run-time.
In order to overcome these limitations and achieve a looser coupling between the DHIS2 service
layer and additional software artefacts, a REST-based API has been developed as part of DHIS2.
This Web API complies with the rules of the REST architectural style. This implies that:
• The Web API provides a navigable and machine-readable interface to the complete DHIS2
data model. For instance, one can access the full list of data elements, then navigate using
the provided URL to a particular data element of interest, then navigate using the provided
URL to the list of data sets which the data element is a member of.
• (Meta) Data is accessed through a uniform interface (URLs) using plain HTTP requests.
There are no fancy transport formats or protocols involved - just the well-tested, well-
understood HTTP protocol which is the main building block of the Web today. This implies
that third-party developers can develop software using the DHIS2 data model and data
without knowing the DHIS2 2specific technology or complying with the DHIS2 design
constraints.
• All data including meta-data, reports, maps and charts, known as resources in REST
terminology, can be retrieved in most of the popular representation formats of the Web of
today, such as XML, JSON, PDF and PNG. These formats are widely supported in
applications and programming languages and gives third-party developers a wide range of
implementation options.
12
What is DHIS2? Understanding platform independence
Understanding platform independence
All computers have an Operating System (OS) to manage it and the programs running it. The
operating system serves as the middle layer between the software application, such as DHIS2,
and the hardware, such as the CPU and RAM. DHIS2 runs on the Java Virtual Machine, and can
therefore run on any operating system which supports Java. Platform independence implies that
the software application can run on ANY OS - Windows, Linux, Macintosh etc. DHIS2 is platform
independent and thus can be used in many different contexts depending on the exact
requirements of the operating system to be used.
Additionally, DHIS2 supports three major database management systems systems (DBMS). DHIS2
uses the Hibernate database abstraction framework and is compatible with the following database
systems: PostgreSQL, MySQL and H2. PostgreSQL and MySQL are high-quality production ready
databases, while H2 is a useful in-memory database for small-scale applications or development
activities.
Lastly, and perhaps most importantly, since DHIS2 is a browser-based application, the only real
requirement to interact with the system is with a web browser. DHIS2 supports most web
browsers, although currently either Google Chrome, Mozilla Firefox or Opera are recommended.
Deployment strategies - online vs offline
DHIS2 is a network enabled application and can be accessed over the Internet, a local intranet as
well as a locally installed system. The deployment alternatives for DHIS2 are in this chapter
defined as i) offline deployment ii) online deployment and iii) hybrid deployment. The meaning and
differences will be discussed in the following sections.
Offline Deployment
An off-line deployment implies that multiple standalone off-line instances are installed for end
users, typically at the district level. The system is maintained primarily by the end users/district
health officers who enters data and generate reports from the system running on their local
server. The system will also typically be maintained by a national super-user team who pay
regular visits to the district deployments. Data is moved upwards in the hierarchy by the end
users producing data exchange files which are sent electronically by email or physically by mail or
personal travel. (Note that the brief Internet connectivity required for sending emails does not
qualify for being defined as on-line). This style of deployment has the obvious benefit that it works
when appropriate Internet connectivity is not available. On the other side there are significant
challenges with this style which are described in the following section.
• Hardware: Running stand-alone systems requires advanced hardware in terms of servers

and reliable power supply to be installed, usually at district level, all over the country. This
requires appropriate funding for procurement and plan for long-term maintenance.
• Software platform: Local installs implies a significant need for maintenance. From
experience, the biggest challenge is viruses and other malware which tend to infect local
installations in the long-run. The main reason is that end users utilize memory sticks for
transporting data exchange files and documents between private computers, other
workstations and the system running the application. Keeping anti-virus software and
operating system patches up to date in an off-line environment are challenging and bad
practices in terms of security are often adopted by end users. The preferred way to
overcome this issue is to run a dedicated server for the application where no memory sticks
are allowed and use an Linux based operating system which is not as prone for virus
infections as MS Windows.
• Software application: Being able to distribute new functionality and bug-fixes to the health
information software to users are essential for maintenance and improvement of the
13
What is DHIS2? Deployment strategies - online vs offline
system. Relying on the end users to perform software upgrades requires extensive training
and a high level of competence on their side as upgrading software applications might a
technically challenging task. Relying on a national super-user team to maintain the software
implies a lot of travelling.
• **Database maintenance:**A prerequisite for an efficient system is that all users enter data
with a standardized meta-data set (data elements, forms etc). As with the previous point
about software upgrades, distribution of changes to the meta-data set to numerous off-line
installations requires end user competence if the updates are sent electronically or a well-
organized super-user team. Failure to keep the meta-data set synchronized will lead to loss
of ability to move data from the districts and/or an inconsistent national database since the
data entered for instance at the district level will not be compatible with the data at the
national level.
Online deployment
An on-line deployment implies that a single instance of the application is set up on a server
connected to the Internet. All users (clients) connect to the on-line central server over the Internet
using a web browser. This style of deployment is increasingly possible due to increased
availability in (mobile) Internet coverage globally, as well as readily available and cheap cloud-
computing resources. These developments make it possible to access on-line servers in even the
most rural areas using mobile Internet modems (also referred to as dongles).
This on-line deployment style has huge positive implications for the implementation process and
application maintenance compared to the traditional off-line standalone style:
• Hardware: Hardware requirements on the end-user side are limited to a reasonably

modern computer/laptop and Internet connectivity through a fixed line or a mobile modem.
There is no need for a specialized server for each user, any Internet enabled computer will
be sufficient. A server will be required for on-line deployments, but since there is only one
(or several) servers which need to be procured and maintained, this is significantly simpler
(and cheaper) than maintaining many separate servers is disparate locations. Given that
cloud-computing resources continue to steadily decrease in price while increasing in
computational power, setting up a powerful server in the cloud is far cheaper than
procuring hardware.
• Software platform: The end users only need a web browser to connect to the on-line
server. All popular operating systems today are shipped with a web browser and there is no
special requirement on what type or version. This means that if severe problems such as
virus infections or software corruption occur one can always resort to re-formatting and
installing the computer operating system or obtain a new computer/laptop. The user can
continue with data entry where it was left and no data will be lost.
• Software application: The central server deployment style means that the application can
be upgraded and maintained in a centralized fashion. When new versions of the
applications are released with new features and bug-fixes it can be deployed to the single
on-line server. All changes will then be reflected on the client side the next time end users
connect over the Internet. This obviously has a huge positive impact for the process of
improving the system as new features can be distributed to users immediately, all users will
be accessing the same application version, and bugs and issues can be sorted out and
deployed on-the-fly.
• **Database maintenance:**Similar to the previous point, changes to the meta-data can be

done on the on-line server in a centralized fashion and will automatically propagate to all
clients next time they connect to the server. This effectively removes the vast issues related
to maintaining an upgraded and standardized meta-data set related to the traditional off-
14
line deployment style. It is extremely convenient for instance during the initial database
development phase and during the annual database revision processes as end users will
be accessing a consistent and standardized database even when changes occur
frequently.
This approach might be problematic in cases where Internet connectivity is volatile or missing in
long periods of time. DHIS2 however has certain features which requires Internet connectivity to
be available only part of the time for the system to work properly, such as offline data entry. In
general however, DHIS2 does require Internet connectivity of some sort, but this is increasingly
an easy problem to solve even in remote locations.
Hybrid deployment
From the discussion so far one realizes that the on-line deployment style is favourable over the
off-line style but requires decent Internet connectivity where it will be used. It is important to
notice that the mentioned styles can co-exist in a common deployment. It is perfectly feasible to
have on-line as well as off-line deployments within a single country. The general rule would be
that districts and facilities should access the system on-line over the Internet where sufficient
Internet connectivity exist, and off-line systems should be deployed to districts where this is not
the case.
Defining decent Internet connectivity precisely is hard but as a rule of thumb the download speed
should be minimum 10 Kbyte/second for the client and at least 1 Mbit/sec (dedicated) bandwidth
for the server.
In this regard mobile Internet modems which can be connected to a computer or laptop and
access the mobile network is an extremely capable and feasible solution. Mobile Internet
coverage is increasing rapidly all over the world, often provide excellent connectivity at low prices
and is a great alternative to local networks and poorly maintained fixed Internet lines. Getting in
contact with national mobile network companies regarding post-paid subscriptions and potential
large-order benefits can be a worthwhile effort. The network coverage for each network operator
in the relevant country should be investigated when deciding which deployment approach to opt
for as it might differ and cover different parts of the country.
Server hosting
The on-line deployment approach raises the question of where and how to host the server which
will run the DHIS2 application. Typically there are several options:
1. Internal hosting within the Ministry of Health
2. Hosting within a government data centre
3. Hosting through an external hosting company
The main reason for choosing the first option is often political motivation for having “physical
ownership” of the database. This is perceived as important by many in order to “own” and control
the data. There is also a wish to build local capacity for server administration related to
sustainability of the project. This is often a donor-driven initiatives as it is perceived as a concrete
and helpful mission.
Regarding the second option, some places a government data centre is constructed with a view
to promoting and improving the use and accessibility of public data. Another reason is that a
proliferation of internal server environments is very resource demanding and it is more effective to
establish centralized infrastructure and capacity.
15
Regarding external hosting there is lately a move towards outsourcing the operation and
administration of computer resources to an external provider, where those resources are
accessed over the network, popularly referred to as “cloud computing” or “software as a service”.
Those resources are typically accessed over the Internet using a web browser.
The primary goal for an on-line server deployment is provide long-term stable and high-
performance accessibility to the intended services. When deciding which option to choose for
server environment there are many aspects to consider:
1. Human capacity for server administration and operation. There must be human resources
with general skills in server administration and in the specific technologies used for the
application providing the services. Examples of such technologies are web servers and
database management platforms.
2. Reliable solutions for automated backups, including local off-server and remote backup.
3. Stable connectivity and high network bandwidth for traffic to and from the server.
4. Stable power supply including a backup solution.
5. Secure environment for the physical server regarding issues such as access, theft and fire.
6. Presence of a disaster recovery plan. This plan must contain a realistic strategy for making
sure that the service will be only suffering short down-times in the events of hardware
failures, network downtime and more.
7. Feasible, powerful and robust hardware.
All of these aspects must be covered in order to create an appropriate hosting environment. The
hardware requirement is deliberately put last since there is a clear tendency to give it too much
attention.
Looking back at the three main hosting options, experience from implementation missions in
developing countries suggests that all of the hosting aspects are rarely present in option one and
two at a feasible level. Reaching an acceptable level in all these aspects is challenging in terms of
both human resources and money, especially when compared to the cost of option three. It has
the benefit that is accommodates the mentioned political aspects and building local capacity for
server administration, on the other hand can this be provided for in alternative ways.
Option three - external hosting - has the benefit that it supports all of the mentioned hosting
aspects at a very affordable price. Several hosting providers - of virtual servers or software as a
service - offer reliable services for running most kinds of applications. Example of such providers
are Linode and Amazon Web Services. Administration of such servers happens over a network
connection, which most often anyway is the case with local server administration. The physical
location of the server in this case becomes irrelevant as that such providers offer services in most
parts of the world. This solution is increasingly becoming the standard solution for hosting of
application services. The aspect of building local capacity for server administration is compatible
with this option since a local ICT team can be tasked with maintaining the externally hosted
server, but with not being burdened with worrying about power supply and bandwidth constraints
which usually exist outside of major data centres.
An approach for combining the benefits of external hosting with the need for local hosting and
physical ownership is to use an external hosting provider for the primary transactional system,
while mirroring this server to a locally hosted non-critical server which is used for read-only
purposes such as data analysis and accessed over the intranet.
16
What is DHIS2? Difference between Aggregated and Patient data in a HIS
Difference between Aggregated and Patient data in a HIS
Patient data is data relating to a single patient, such as his/her diagnosis, name, age, earlier
medical history etc. This data is typically based on a single patient-health care worker interaction.
For instance, when a patient visits a health care clinic, a variety of details may be recorded, such
as the patient's temperature, their weight, and various blood tests. Should this patient be
diagnosed as having "Vitamin B 12 deficiency anaemia, unspecified" corresponding to ICD-10
code D51.9, this particular interaction might eventually get recorded as an instance of "Anaemia"
in an aggregate based system. Patient based data is important when you want to track
longitudinally the progress of a patient over time. For example, if we want to track how a patient is
adhering to and responding to the process of TB treatment (typically taking place over 6-9
months), we would need patient based data.
Aggregated data is the consolidation of data relating to multiple patients, and therefore cannot be
traced back to a specific patient. They are merely counts, such as incidences of Malaria, TB, or
other diseases. Typically, the routine data that a health facility deals with is this kind of
aggregated statistics, and is used for the generation of routine reports and indicators, and most
importantly, strategic planning within the health system. Aggregate data cannot provide the type
of detailed information which patient level data can, but is crucial for planning and guidance of the
performance of health systems.
In between the two you have case-based data, or anonymous "patient" data. A lot of details can
be collected about a specific health event without necessarily having to identify the patient it
involved. Inpatient or outpatient visits, a new case of cholera, a maternal death etc. are common
use-cases where one would like to collect a lot more detail that just adding to the total count of
cases, or visits. This data is often collected in line-listing type of forms, or in more detailed audit
forms. It is different from aggregate data in the sense that it contains many details about a
specific event, whereas the aggregate data would count how many events of a certain type, e.g.
how many outpatient visits with principal diagnosis "Malaria", or how many maternal deaths where
the deceased did not attend ANC, or how many cholera outbreaks for children under 5 years. In
DHIS2 this data is collected through programs of the type single event without registration.
Patient data is highly confidential and therefore must be protected so that no one other than
doctors can get it. When in paper, it must be properly stored in a secure place. For computers,
patient data needs secure systems with passwords, restrained access and audit logs.
Security concerns for aggregated data are not as crucial as for patient data, as it is usually
impossible to identify a particular person to a aggregate statistic . However, data can still be
misused and misinterpreted by others, and should not be distributed without adequate data
dissemination policies in place.
Free and Open Source Software (FOSS): benefits and challenges
Software carries the instructions that tell a computer how to operate. The human authored and
human readable form of those instructions is called source code. Before the computer can
actually execute the instructions, the source code must be translated into a machine readable
(binary) format, called the object code. All distributed software includes the object code, but FOSS
makes the source code available as well.
Proprietary software owners license their copyrighted object code to a user, which allows the user
to run the program. FOSS programs, on the other hand, license both the object and the source
code, permitting the user to run, modify and possibly redistribute the programs. With access to
the source code, the users have the freedom to run the program for any purpose, redistribute,
probe, adapt, learn from, customise the software to suit their needs, and release improvements to
the public for the good of the community. Hence, some FOSS is also known as free software,
17
What is DHIS2? Free and Open Source Software (FOSS): benefits and challenges
where “free” refers, first and foremost, to the above freedoms rather than in the monetary sense
of the word.
Within the public health sector, FOSS can potentially have a range of benefits, including:
• Lower costs as it does not involve paying for prohibitive license costs.
• Given the information needs for the health sector are constantly changing and evolving,
there is a need for the user to have the freedom to make the changes as per the user
requirements. This is often limited in proprietary systems.
• Access to source code to enable integration and interoperability. In the health sector
interoperability between different software applications is becoming increasingly important,
meaning enabling two or more systems to communicate metadata and data. This work is a
lot easier, and sometimes dependent on the source code being available to the developers
that create the integration. This availability is often not possible in the case of proprietary
software. And when it is, it comes at a high cost and contractual obligations.
• FOSS applications like DHIS2 typically are supported by a global network of developers,
and thus have access to cutting edge research and development knowledge.
18
Using the Data Entry app About the Data Entry app
Using the Data Entry app

About the Data Entry app
The Data Entry app is where you manually enter aggregated data in DHIS2. You register data 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. You configure the data sets in the
Maintenance app.
Note
If a data set has both a section form and a custom form, the system
displays the custom form during data entry. Users who enter data can't
select which form they want to use. In web-based data entry the order
of display preference is:
1. Custom form (if it exists)

2. Section form (if it exists)
3. Default form
Mobile devices do not support custom forms. In mobile-based data entry

the order of display preference is:

2. Default form
When you close an organisation unit, you can't register or edit data to this organisation unit in the
Data Entry app.
19
Using the Data Entry app Enter data in a data entry form
Enter data in a data entry form
1. Open the Data Entry app.
2. In the organisation unit tree to the left, select an organisation unit.
3. Select a Data set.
4. Select a Period.
The available periods are controlled by the period type of the data set (reporting
frequency). You can jump a year back or forward by clicking Prev year or Next year.
Note
Depending on how you've configured the data entry form, you might have to
enter additional information before you can open the date entry form. This can
for example be a project derived from a category combination.
5. Enter data in the data entry form.
◦ A green field means that the system has saved the value.
◦ A grey field means that the field is disabled and you can't enter a value. The cursor
will automatically jump to the next open field.
20
Using the Data Entry app Enter data in a data entry form
To move to the next field, press the Tab key or the Down Arrow key.
◦
◦ To move back to the previous field, press Shift+Tab or the Up Arrow key.
◦ If you type in an invalid value, for example a character in a field that only accepts
numeric values, you'll 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 minimum maximum value range for the field and you enter a
value that is outside this range, you'll get a pop-up message that says the value is
out of range. The value remains unsaved until you've changed the value or updated
the value range and then re-entered the value.
6. When you've filled in the form, click Run validation in the top right corner or below the data
entry form.
All validation rules which involves data elements in the current data entry form (data set)
are then run against the new data. If there are no violations of the validation rules, you'll
see a message saying The data entry screen successfully passed validation. If there are
validation violations, they will be presented in a list.
7. (Optional) Correct validation violations.
Note
Zero (0) will delete the value if the data element has been configured to not
store zeros.
8. When you've corrected errors and you're done with data entry, click Complete.
The system uses this information when generating completeness reports for district, county,
province or the national level.
21
Using the Data Entry app Mark a data value for follow-up
Mark a data value for follow-up
If you for example have a suspicious value that you need to investigate further, you can keep it
the system, but mark it for follow-up. In the Data Quality app you can then run a follow-up
analysis to view and correct all marked values.
2. Open an existing data entry form.
3. Double-click the field with the value you want to mark for follow-up.
4. Click the star icon.
Edit data values in a completed data entry form
22
Using the Data Entry app Display a data value's history
Click Incomplete.
3.
4. Change the relevant data values.
Note
Zero (0) will delete the value if the data element has been configured to not
store zeros,
5. Click Complete.
Display a data value's history
You can display the last 12 values registered for a field.
23
Using the Data Entry app Display a data value's audit trail
Double-click the field with the value you want to view the history for.
3.
4. Click Data element history.
Display a data value's audit trail
The audit trail allows you to view other data values which have been entered prior to the current
value. The audit trail also shows when the data value was altered and which user who made the
changes.
3. Double-click the field with the value you want to view the audit trail for.
4. Click Audit trail.
24
Using the Data Entry app Create minimum maximum value range manually
Create minimum maximum value range manually
1. In the Data Entry app, open a data entry form.
2. Double-click the field for which you want to set the minimum maximum value range.
3. Enter Min limit and Max limit.
4. Click Save.
If values don't fall within the new value range the next time you enter data, the data entry
cell will appear with an orange background.
5. (Optional) Type a comment to explain the reason for the discrepancy, for example an event
at a facility which may have generated a large number of clients.
6. (Optional) Click Save comment.
Tip
25
Using the Data Entry app Enter data offline
Click the star icon to mark the value for further follow-up.
Enter data offline
The Data Entry app works even if you don't have a stable Internet connection during data entry.
When you don't have an internet connection, the data you enter is saved to your local computer.
When the Internet connection is back, the app will push the data to the server. The total
bandwidth usage is reduced since data entry forms no longer are retrieved from the server for
each rendering.
Note
To use this functionality, you must login to the server while you've an
Internet connection.
• When you're connected to the Internet, the app displays this message at the top of the
data entry form:
• If your Internet connection breaks during data entry, the app detects it and displays this
message:
Now your data will be stored locally. You can continue to enter data as normal.
• Once you have entered all necessary data and the app detects that the Internet connection
is back, you'll see this message:
Click Upload to synchronize data with the server.
• When the data has successfully synchronized with the server, you'll see this confirmation
message:
26
Using the Data Entry app Enable multi-organisation unit data entry
Enable multi-organisation unit data entry
It can be useful 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.
Note
Multi-organisation unit data entry only works for section forms.
1. Open the System Settings app.
2. Select Enable multi-organisation unit forms.
3. In the Data Entry app, select the organisation unit immediately above the organisation unit
you want to enter data for in the organisation unit hierarchy.
Data elements will appear as columns and organisation units as rows in the form.
Note
The data entry forms should still be assigned to the facilities that you actually
enter data for, that is the organisation units now appearing in the form.
See also
• Control data quality
• Manage data sets and data entry forms
• Using the Maintenance app
27
Control data quality About data quality checks
Control data quality

About data quality checks
The Data Quality app contains tools to validate the accuracy and reliability of the data in the
system. You can assess different dimensions of data quality as outlined in the table below:
Dimension Description
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 reporting

organisation units 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 organisation units should

be submitted at the appointed time.
You can verify data quality in different ways, for example:
• At point of data entry, DHIS 2 can check the data entered to see if it falls within the
minimum maximum value ranges of that data element (based on all previous data
registered).
• By defining 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.
• By analysing data sets, that is, examine gaps in the data.
• By data triangulation, that is, comparing the same data or indicator from different sources.
Validation rule analysis
About validation rule analysis
A validation rule is based on an expression which defines a relationship between data element
values. The expression forms a condition which should assert that certain logical criteria are met.
The expression consist of:
• a left side
• a right side
• an operator
28
Control data quality Workflow
A validation rule could assert that "Suspected malaria cases tested" >= "Confirmed malaria
cases".
The validation rule analysis tests validation rules against the data registered in the system.
Validation violations are reported when the condition defined in the validation rule expression is
not met, which means when the condition is false.
You can configure a validation rule analysis to automatically send out information about validation
violations to selected user groups. These messages are called validation notifications and you
create them in the Maintenance app. Validation notifications are sent via the internal DHIS 2
messaging system.
Workflow
1. In the Maintenance app, create validation rules and validation rule groups.
2. (Optional) In the Maintenance app, create validation notifications.
3. Run the validation rule analysis, either automatically or manually.
◦ In the Scheduler app, you schedule the validation rule analysis to run automatically
for all validation rules included in one or several validation rule groups. After the
system has run the analysis, you'll see the validation violations (if any) in the
validation notifications sent via the internal DHIS 2 messaging system.
◦ In the Data Quality app, you run the validation rule analysis manually for selected
validation rules. After the analysis process has finished, you'll see a list of validation
violations (if any).
Schedule a validation rule analysis to run automatically
Note
Only validation rules that are included in one or several validation
notifications will be a part of the validation rule analysis. If there is no
corresponding validation notification for a validation rule, no notification
will be sent.
Note
While running validation rule analysis automatically, any results not
already persisted, will be persisted during this run. Persisted results can
currently only be accessed trough the API. Consult the developers guide
for more information about how persisted validation rule violations can
be accessed.
1. Verify that you have created all the validation rules, validation rule groups and validation
notifications you need.
2. Open the Scheduler app and click the add button in the bottom right corner.
3. Choose a suitable Name for the new job.
4. Select the Monitoring Job type using the drop-down menu.
5. Select a running frequency for the job, i.e. when and how often the job should run.
6. Fill in the Parameters section, including the Validation rule groups.
29
Control data quality Run a validation rule analysis manually
Press the Add job button to confirm the job creation. For more information on adding jobs,
7. see Scheduling.
Run a validation rule analysis manually
1. Verify that you have created all the validation rules, validation rule groups and validation
notifications you need.
2. Open the Data Quality app and click Validation rule analysis.
3. Select Start date and End date.
4. Select which Validation rule group you want to include in the analysis.
You can select all validation rules or all validation rules from a single validation rule group.
5. (Optional) Select Send notifications to trigger validation notifications.
Note
If you want to send out validation notifications, you must first create them in
the Maintenance app.
6. (Optional) Select Persist new results to persist any non-persisted results found during the
analysis
30
Control data quality See also
Select a Parent organisation unit.

7.
8. Click Validate.
The analysis process duration depends on the amount of data that is being analysed. If
there are no violations of the validation rules, you'll see a message saying Validation
passed successfully. If there are validation violations, they will be presented in a list.
9. (Optional) Click the show details icon to get more information about a validation violation. In
the pop-up window you'll find information about the data elements included in the validation
rules and their corresponding data values. You can use this information to identify the
source of the validation rule violation.
10. (Optional) Click Download as PDF, Download as Excel or Download as CSV to download
the validation violations list in PDF, Excel or CSV formats.
See also
• Manage validation rules
• Data Administration app
Standard deviation outlier analysis
About standard deviation outlier analysis
The standard deviation outlier analysis identifies values that are numerically distant from the rest
of the data, potentially indicating that they are outliers. The analysis is based on the standard
normal distribution. DHIS 2 calculates the mean of all values for an organisation unit, data
element, category option combination and attribute option combination. Outliers can occur by
chance of course, but can potentially indicate a measurement or data entry error.
Note
As indicated above, this data quality analysis is only appropriate for data
which is actually normally distributed. Data which has large seasonal
variation, or which may be distributed according to other statistical
models (e.g. logistical ) may lead values being flagged which actually
should be considered valid. It is therefore recommended to confirm first,
31
Control data quality Run a standard deviation outlier analysis
whether the data actually is normally distributed before running a

standard deviation outlier analysis.
Run a standard deviation outlier analysis
1. Open the Data Quality app and click Std dev outlier analysis.
2. Select From date and To date.
3. Select data set(s).
4. Select Parent organisation unit.
All children of the organisation unit will be included. The analysis is made on raw data
"under" the parent organisation unit, not on aggregated data.
5. 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.
6. Click Start.
there are standard deviations outliers, they will be presented in a list.
32
Control data quality Minimum maximum outlier analysis
For each outlier, you will see the data element, organisation unit, period, minimum value,
actual value and maximum value. The minimum and maximum values refer to the border
values derived from the number of standard deviations selected for the analysis.
Tip
Click the star icon to mark an outlier value for further follow-up.
Minimum maximum outlier analysis
About minimum maximum value based outlier analysis
You can verify the data quality at the point of data entry by setting a minimun/maximum value
range for each data value. You can define the value ranges manually or generate them
automatically.
The auto-generated minimum maximum value range is suitable only for normally distributed data.
DHIS2 will determine the arithmetic mean and standard deviation of all values for a given data
element, category option, organisation unit and attribute combination. Then the system will
calculate the minimum maximum value range based on the Data analysis std dev factor
specified in the System Settings app.
For data which is highly-skewed or zero inflated (as is often the case with aggregate data), the
values which DHIS2 auto-generates may not provide an accurate minimum maximum value range.
This can lead to excessive false violations, for example if you analyse values related to seasonal
diseases.
Note
Minimum maximum value ranges are calculated across all attribute
combination options for a given data element, category option and
organisation unit combination.
Workflow
1. Create a minimum maximum value range, either automatically or manually.
◦ In the Data Administration app, you generate value ranges automatically.
◦ In the Data Entry app, you may set value ranges manually.
2. In the Data Quality app, run the Min-max outlier analysis.
33
Control data quality Configure a minimum maximum outlier analysis
Configure a minimum maximum outlier analysis
Create minimum maximum value range automatically
Note
Auto-generated minimum maximum value ranges can be useful for many
situations, but it's recommended to verify that the data is actually
normally distributed prior to using this function.
You generate minimum maximum value ranges calculated by data set in the Data Administration
app. The new value ranges override any value ranges that the system has calculated previously.
1. Set the Data analysis standard deviation (std dev) factor:
1. Open the System Settings app, and click General.
2. In the Data analysis std dev factor field, enter a value.
This sets the number of standard deviations to use in the outlier analysis. The default
value is 2. Higher values indicate a broader distribution, which may lead to outliers
not being flagged correctly by the analysis.
2. Open the Data Administration app and click Min-max value generation.
4. Select an Organisation unit.
34
Control data quality Configure a minimum maximum outlier analysis
Click Generate.
5.
New minimum maximum value ranges for all data elements in the selected data sets for all
organisation units (including descendants) of the selected organisation units are
generated.
Create minimum/maximum value range manually
1. In the Data Entry app, open a data entry form.
2. Double-click the field for which you want to set the minimum/maximum value range.
3. Enter Min limit and Max limit in the dialog that appears.
4. Click Save.
If values don't fall within the new value range the next time you enter data, the data entry
cell will appear with an orange background.
35
Control data quality Run a minimum maximum outlier analysis
(Optional) Type a comment to explain the reason for the discrepancy, for example an event
5. at a facility which may have generated a large number of clients.
6. (Optional) Click Save comment.
Tip
Delete minimum maximum value range
You can permanently delete all minimum maximum value ranges for selected data sets and
organisation units in the Data Administration app.
1. Open the Data Administration app and click Min-max value generation.
3. Select an Organisation unit. Note, that the selection cascades to descendant organisation
units!
4. Click Remove.
Run a minimum maximum outlier analysis
1. Verify that you've created minimum maximum value ranges.
2. Open the Data Quality app and click Min-max outlier analysis.
3. Select From date and To date.
4. Select which data set(s) you want to include in the analysis.
36
Control data quality Follow-up analysis
Select Parent organisation unit.

5.
All children of the organisation unit will be included. The analysis is made on raw data
"under" the parent organisation unit, not on aggregated data.
6. Click Start.
there are validation violations, they will be presented in a list.

the list in PDF, Excel or CSV formats.
Tip
Follow-up analysis
About follow-up analysis
The follow-up analysis creates a list of all data values marked for follow-up. You can mark a data
value for follow-up in the Data Entry app and in the result list you get from a standard deviation
outlier or minimum maximum outlier analysis.
37
Control data quality Create list of data values marked for follow-up
Create list of data values marked for follow-up
1. Open the Data Quality app and click Follow-up analysis.
2. Select a data set or multiple data sets.
3. Select a parent Organisation unit.
there are data values marked for follow-up, they will be presented in a list.
4. Select a Start Date and End Date which defines the periods which you are interested in
looking for values which have been marked for follow up.
5. Press Follow up to generate a list of values which have been marked for follow up.

the validation violations list in PDF, Excel or CSV formats.
Tip
38
Control data quality Create list of data values marked for follow-up
Click the star icon to remove the follow-up tag from the data value. You
can also enter a comment in the field to indicate any additional
information regarding the value.
39
Using the Capture app About the Capture app
Using the Capture app

About the Capture app
The Capture app serves as a replacement for the Event Capture app. In the future, the intention
is to incorporate the Tracker Capture app and the Data Entry app into the Capture app.
In the Capture app you register events that occurred at a particular time and place. An event can
happen at any given point in time. This stands in contrast to routine data, which can be captured
for predefined, regular intervals. Events are sometimes called cases or records. In DHIS2, events
are linked to a program. The Capture app lets you select the organisation unit and program and
specify a date when a event happened, before entering information for the event.
Register an event
1. Open the Capture app.
2. Select an organisation unit.
3. Select a program.
You'll only see programs associated with the selected organisation unit and programs
you've access to, and that is shared with your user group through data level sharing.
4. If the program has a category combination set the category option will have to be selected.
5. Click New.
create new event
6. Fill in the required information. If the programs program stage is configured to capture a
location:
◦ If the field is a coordinate field you can either enter the coordinates directly or you
can click the map icon to the left of the coordinate field. The latter one will open a
map where you can search for a location or set on directly by clicking on the map.
◦ If the field is a polygon field you can click the map icon to the left of the field. This will
open a map where you can search for a location and capture a polygon (button in
the upper rigth corner of the map).
7. If desired you can add a comment by clicking the Write comment button at the bottom of
the form.
8. If desired you can add a relationship by clicking the Add relationship button at the bottom
of the form. See the section about Adding a relationship for more information.
9. Click Save and exit or click the arrow next to the button to select Save and add another.
◦ Save and add another will save the current event and clear the form. All the events
that you have captured will be diplayed in a list at the bottom of the page. When you
want to finish capturing events you can, if the form is blank, click the finish button or
40
Using the Capture app Adding a relationship
if your form contains data click the arrow next to Save and add another and select
Save and exit.
Note 1: Some data elements in an event might be mandatory (marked

with a red star next to the data element lable). What this means is that
all mandatory data elements must be filled in before the user is allowed
to complete the event. The exception to this is if the user has the
authority called "Ignore validation of required fields in Tracker and
Event Capture". If the user has this authority, the mandatory data
elements will not be required to be filled in before saving and the red
star will not be displayed next to the data element lable. Note that super
user that have the "ALL" authority automatically have this authority.
Note 2: The data entry form can also be diaplayed in row view. In this
mode the data elements are arranged horizontally. This can be achived
by clicking the Switch to row view button on the top right of the data
entry form. If you are currently in row view you can switch to the default
form view by clicking the Switch to form view button on the top right of
the data entry form.
Adding a relationship
Relationships can be added either during registration, editing or viewing of an event. Currently
the Capture App only supports Event to Tracked Entity Instance relationships.
1. While in an event, click Add relationship.
2. Select the relationship type you want to create.
3. You now have two options: Link to an existing Tracked Entity Instance or Create new
Tracked Entity Instance.
relationship options
41
Using the Capture app Link to an existing Tracked Entity Instance
Link to an existing Tracked Entity Instance
1. Click Link to an existing Tracked Entity Instance.
2. You should now be presented with some options for searching for a Tracked Entity
Instance. You have the option to select a program. If a program is selected the attributes
are derived from the selected program. If no program is selected, only the attributes that
belong to the Tracked Entity Instance will be visible.
search for Tracked Entity Instance
◦ If the Tracked Entity Instance or program is configured with a unique attribute, this
attribute can be used for finding a specific Tracked Entity Instance or program. This
attribute should be presented alone. When the unique attribute field has been filled
out, click the Search button located right below the unique attribute field.
◦ If the Tracked Entity Instance or program has attibutes these can be used for
searching by expanding the Search by attributes box. When all desired attribute
fields have been filled out, click the Search by attributes button located at the
bottom. You can also limit the search by setting the Organisation unit scope. If set
to All accessible you will search for the Tracked Entity Instance in all organisation
units you have access to. If you select Selected, you will be asked to select which
organisation units to search within.
3. After a successful search you will be presented with a list of Tracked Entity Instances
matching the search criteria. To create a relationship click the Link button on the Tracked
Entity Instance you would like to create a relationship to.
4. If you did not find the Tracked Entity Instance you were looking for, you can either click
the New search or Edit search buttons. New search will take you to new blank search
while Edit search will take you back to the search you just performed keeping the search
criteria.
Create new Tracked Entity Instance
1. Click Create new Tracked Entity Instance.
2. You are now presented with a form for registering a new Tracked Entity Instance. You can
choose to either register with or without a program. If a program is selected, the new
42
Using the Capture app Edit an event
Tracked Entity Instance will be enrolled in said program. You can also change the
Organisation unit by removing the one that is automatically set and selecting a new one.
register new Tracked Entity Instance
3. Fill in the desired (and possibly mandatory) attributes and enrollment details.
4. Click Create Tracked Entity Instance and Link.
Note: When filling in data you might face a warning telling you that a
possible duplicate has been found. You can click the warning to see
these duplicates and if the duplicate is a match you can choose to link
that Tracked Entity Instance by clicking the Link button. If the warning
is still present when you are done filling in data, you will not see the
Create Tracked Entity Instance and Link button. Instead you will be
pressented with a button called Review duplicates. When you click this
button a list of possible duplicates will be displayed. If any of these
duplicates matches the Tracked Entity Instance you are trying to
create you can click the Link button, if not you can click the Save as
new person button to register a new Tracked Entity Instance.
Edit an event
All events registered to the selected program show up in a list.
4. Click the event you want to modify.
5. Click the Edit event button.
6. Modify the event details and click Save.
43
Using the Capture app Delete an event
Delete an event
4. Click the triple dot icon on the event you want to delete.
5. In the menu that is displayed click Delete event.
delete event
Modify an event list layout
You can select which columns to show or hide in an event list. This can be useful for example
when you have a long list of data elements assigned to a program stage.
4. Click the gear icon on the top right of the event list.
5. Select the columns you want to display and click Save.
44
Using the Capture app Filter an event list
modify event list
Note: You can reorganize the order of the data elements by draging and
dropping them in the list.
Filter an event list
Along the top of the event list are button with the same names as the column headers in
the list.
4. Use the buttons on the top of the list to filter based on a report date or a specific data
element.
45
Using the Capture app Sort an event list
filter event
Note: Data elements will have slightly diffrent way that they are filtered.
A Number data element will for instance show a rang to filter on while a
Text data element will ask you to enter a search query to filter on.
Sort an event list
3. Select a program. All events registered to the selected program show up in a list.
4. Click one of the column headers to sort the list on that data element in ascending order.
A small upward arrow is displayed next to the column to show that the list is sorted in
ascending order.
5. Click the column header again to sort the list on that data element in descending order.
A small downward arrow is displayed next to the column to show that the list is sorted in
descending order.
46
Using the Capture app Download an event list
sort event
3. Select a program. All events registered to the selected program show up in a list.
4. Click the downward arrow icon on the top right of the event list.
5. Select the format you want to download.
47
Using the Capture app Predefined list views
download event list
Note: You can download an event list in JSON, XML or CSV formats.
Predefined list views
You can set up your own views and save them for later use. The views can also be shared with
others. A view consists of filters, column order and event sort order.
Saving a new view
1. Select an organisation unit and a program.
2. Set filters using the filter buttons above the event list (described in detail here).
1. Set the column order by clicking the cog icon and then, in the popover, specify the layout
according to your preference (how to modify the layout is described in detail here).
48
Using the Capture app Saving a new view
1. Sort the events by clicking on one of the column headers (described in detail here).
1. Open the more menu (three dots icon) to the right and then select "Save current view..."
1. Fill in a name for the view and click save.
49
Using the Capture app Loading a view
Loading a view
1. Select an organisation unit and a program with a predefined view.
2. The views should be available above the event list itself. Click on a view to load it.
1. An example of a loaded view.
50
Using the Capture app Updating a view
Updating a view
1. Load the view you would like to update (see loading a view).
2. Make your changes to filters, column order and/or event sort order.
Note
An asterisk(*) is appended to the view name when the view has
unsaved changes.
1. Open the more menu (three dots icon) to the right and then select "Update view".
Sharing a view
1. Load the view you would like to share (see loading a view).
2. Open the more menu (three dot icon) to the right and then select "Share view..."
51
Using the Capture app Deleting a view
1. Make your changes. You would typically add users/groups (1) and/or change the access
rights of users/groups added earlier (2).
Deleting a view
1. Load the view you would like to delete (see loading a view).
2. Open the more menu (three dots icon) to the right and then select "Delete view".
52
Using the Capture app User assignment
User assignment
Events can be assigned to users. This feature must be enabled per program.
Assigning new events
1. Select an organisation unit and a program with user assignment enabled.
2. Click New Event in the upper right corner.
3. You will find the assignee section near the bottom of the data entry page. Search for and
select the user you would like to assign the event to. The assignee will be preserved when
you save the event.
53
Using the Capture app Change assignee
Change assignee
1. Select an organisation unit and a program with user assignment enabled.
2. Click an event in the list
3. In the right column you will find the assignee section.
4. Click the edit button, or the Assign button if the event is not currently assigned to anyone.
5. Search for and select the user you would like to reassign the event to. The assignment is
saved immediately.
Assignee in the event list
In the event list you will be able to view the assignee per event. Moreover, you can sort and filter
the list by the assignee.
54
Using the Capture app Tracker programs
Filter by assignee
1. Click the Assigned to filter.
2. Select your preferred assignee filter and then click update.
Tracker programs
The Capture app doesn't support tracker programs yet, but the tracker programs are still listed. If
you select a tracker program, the app will lead you to the Tracker Capture app as shown below.
55
Using the Capture app Tracker programs
56
Using the Event Capture app About the Event Capture app
Using the Event Capture app

About the Event Capture app
In the Event Capture app you register events that occurred at a particular time and place. An
event can happen at any given point in time. This stands in contrast to routine data, which can be
captured for predefined, regular intervals. Events are sometimes called cases or records. In
DHIS2, events are linked to a program. The Event Capture app lets you select the organisation
unit and program and specify a date when a event happened, before entering information for the
event.
The Event Capture app works online and offline. If the Internet connectivity drops, you can
continue to capture events. The events will be stored locally in your web browser (client). When
connectivity has returned, the system will ask you to upload the locally stored data. The system
then sends the data to the server where the data is stored.
Note
If you close the web browser while in offline mode, it is not possible to
reopen a new web browser window and continue the working session.
However the data will still be saved locally and can be uploaded to the
server the next time the machine is online and the you have logged into
the server.
• You only see programs associated with the organisation unit you've selected and programs
you've access to view through your user role.
• Both skip-logic and validation error/warning messages are supported during registration.
• When you close an organisation unit, you can't register or edit events to this organisation
unit in the Event Capture app. You can still view and filter the event list and view the details
of an event.
• On-the-fly indicator expression evaluation is supported. If a program has indicators defined

for it and the moment all values related to the indicator expression are filled, the system will
calculate indicator and display the result.
57
Using the Event Capture app Register an event
• Sorting: this can be done by clicking the sorting icon of each column header. A red sorting
icon implies the current sorting column. However, the sorting functionality works only within
the page displayed. Currently, it is not possible to do sorting from serverside.
• Filtering: this is done by clicking the small search icon shown to the right of each column
header. Clicking them provides an input field to type a filtering criteria. The system starts
applying the filter the moment a user starts to type. During filtering it is possible to define
start and end dates for date type data elements and lower and upper limits for number
types. Server side filtering is not-support at the moment.
Register an event
1. Open the Event Capture app.
You'll only see programs associated with the selected organisation unit and programs
you've access to through your user role.
4. Click Register event.
5. Select a date.
6. Fill in the required information.
If the program's program stage is configured to capture GPS coordinate, you can enter the
coordinates in two ways:
◦ Enter values directly in corresponding fields.
◦ Choose a location in a map. The map option also displays polygons and points that
are defined for organisation units.
7. Click Save and add new or Save and go back.
Note: Some data elements in an event might be mandatory (marked with

a red star next to the data element lable). What this means is that all
58
Using the Event Capture app Edit an event
mandatory data elements must be filled in before the user is allowed to

save the event. The exception to this is if the user has the authority
called "Ignore validation of required fields in Tracker and Event
Capture". If the user has this authority, the mandatory data elements will
not be required to be filled in before saving and the red star will not be
displayed next to the data element lable. Note that super user that have
the "ALL" authority automatically have this authority.
Edit an event
4. Click the event you want to modify and select Edit.
5. Modify the event details and click Update.
Edit events in grid
The Edit in grid function allows you to edit a selected event within the table but only those
columns (data elements) visible in the grid. If you need more columns, use Show/hide columns to
specify which columns should be displayed in the list.
4. Click the event you want to modify and select Edit in grid.
5. Modify the event details.
6. Click on another event to close the edit mode.
Share events in edit mode
You can share an event in edit mode via its web address.
2. Open the event you want to share in edit mode.
3. Copy the URL.
Make sure that the URL contains "event" and "ou" (organisation unit) parameters.
4. Paste the URL in the sharing method of your choice, for example an e-mail or a message
within DHIS2.
If you're not logged in to DHIS2 when you click the link, you'll be asked to do so and then
taken to the dashboard.
59
Using the Event Capture app View an event audit history
View an event audit history
4. Click an event and select Audit history.
Delete an event
4. Click an event and select Remove.
5. Click Remove to cocnfirm the deletion.
Modify an event list's layout
You can select which columns to show or hide in an event list. This can be useful for example
when you have a long list of data elements assigned to a program stage. Once you've modified
the layout, it's saved on your user profile. You can have different layouts for different programs.
4. Click the Show/hide columns icon.
5. Select the columns you want to display and click Close.
Print an event list
4. Click Print list.
60
Using the Event Capture app Download an event list
4. Click the Downlad icon and select a format.
You can download an event list in XML, JSON or CSV formats.
61
Using the Tracker Capture app About the Tracker Capture app
Using the Tracker Capture app

About the Tracker Capture app
The Tracker Capture app is an advanced version of the Event Capture app.
• Event Capture: handles single events without registration
• Tracker Capture: handles multiple events (including single event) with registration.
• You capture event data for a registered tracked entity instance (TEI).
• You only see programs associated with the organisation unit you've selected and programs
you've access to view through your user role.
• The options you see in the search and register functions depend on the program you've
selected. The program attributes control these options. The attributes also decide the
columns names in the TEI list.
If you don't select a program, the system picks default attributes.
• Both skip-logic and validation error/warning messages are supported during registration.
unit in the Tracker Capture app. You can still search for TEIs and filter the search results.
You can also view the dashboard of a particular TEI.
62
Using the Tracker Capture app About tracked entity instance (TEI) dashboards
About tracked entity instance (TEI) dashboards
You manage a TEI from the TEI's dashboard in the Tracker Capture app.
• The dashboard consist of widgets. Drag and drop the widgets to place them in the order
and in the position you want.
• Click the pin icon to stick the right column of widgets to a fix position. This is useful
especially during data entry.
If you have many data elements or big form to fill in, stick the right widget column. Then all
the widgets you've placed in the right column remain visible while you scroll in the data
entry part.
• Any indicator defined for the program you've selected will have its value calculated and
displayed in the Indicators widget.
• Navigation:
◦ Back: takes you back to the search and registration page
◦ Previous and next buttons: takes you to the previous or next TEI dashboard in the
TEI search results list
◦ Other programs field: if the TEI is enrolled in other programs, they're listed here.
Click a program to change the program for which you enter data for the selected TEI.
When you change programs, the content in the widgets change too.
Workflow
Working process of Mother and child health program
63
Using the Tracker Capture app Linking to the Tracker Capture App
1. Create new or find existing TEI.
You can search on defined attributes, for example name or address.
2. Enroll TEI in a program.
3. Based on the services of the program by the time, the app creates an activity plan for the
TEI.
4. The TEI is provided with various services depending on the program. All services are
recorded.
5. Use information about the individual cases to create reports.
Linking to the Tracker Capture App
Link to a specific program on the "home screen"
You can share a program selection on the "home screen.
1. Open the Tracker Capture app.
2. Selecte the program you want to link to.
3. Copy the URL.
◦ Make sure that the URL contains the "program" parameter.
within DHIS2.
Note: If the program does not exist in the selected organisation unit
(that is stored in the local cache) the system will instead select the first
available program for that organisation unit. If the local cache is empty/
clean and the root organisation unit of the current user does not have
the specified program, the system will also here select the first available
program for the root organisation unit.
Linking to TEI dashboard
You can share a TEI dashboard via its web address.
64
Using the Tracker Capture app Create a TEI and enroll it in a program
Open the dashboard you want to share.

2.
3. Copy the URL.
Make sure that the URL contains "tei", "program" and "ou" (organisation unit) parameters.
within DHIS2.
Create a TEI and enroll it in a program
You can create a TEI and enroll that TEI to a program in one operation:
2. In the organisation unit tree in the left hand pane, select an organisation unit.
4. Click Register.
5. Fill in the required information.
Both tracked entity type and program can be configured to use a feature type. This makes
it possible to capture geometry for either the TEI or the enrollment. Supported feature type
is Point and Polygon. Please see How to use geometry.
6. If the selected program is configured to display first stage during registation, all mandatory
fields in the stage will have to be filled in. At the end of the stage you will also be asked if
you want to complete the stage that you have entered data for. If you select Yes, the stage
will have the status completed once saved. If you select No, the stage will have the staus
active.
7. If searching for program is configured, a background search will be performed on

searchable fields to help you prevent registering duplicates. If there is any matching TEIs, a
blue box will be displayed on the right side of the form with the possibility to view these
matching TEIs.
65
Using the Tracker Capture app Create a TEI and enroll it in a program
If there is any matching TEIs, click Continue to review possible duplicates before registering a
new one.
If there is no matching TEIs, click Save and continue or Save and add new
• Save and continue: completes the registration and opens the registered TEI's dashboard
• Save and add new: completes the registration but stays on the same page. Use this option
when you want to register and enroll one TEI after another without enter data.
Note: All mandatory attributes have to be filled in to be able to save.

Mandatory attributes are marked with a red star next to the attribute
lable. If the user has the authority called "Ignore validation of required
fields in Tracker and Event Capture" you will not be required to fill in
the mandatory attributes and will not see the red star next to the
attribute lable. Note that super user that have the "ALL" authority
automatically have this authority.
66
Using the Tracker Capture app Open an existing TEI dashboard
Open an existing TEI dashboard
There are multiple ways to find a TEI: Using the "Lists" which is predefined lists in the current
selection, or "Search" for global lookup.
Lists
Lists is used to find and display TEIs in the selected organisation unit and program.
1. Open Tracked Capture app
2. In the organisation unit tree in the left hand pane, select an organisation unit
3. Select a program
4. Click the "Lists" button if not already selected
If not configured, a set of predefined lists will be available:
1. Any TEI with any enrollment status
2. TEIs with an active enrollment of the current program
3. TEIs with a completed enrollment of the current program
4. TEIs with a cancelled enrollment of the current program
You can select which columns to show or hide in the lists for each program. This will be saved in
your user settings.
1. Click the grid icon button
2. Check the columns you want to include
3. Click Save
There is also an option to create a custom working list with own filters. This can be used to create
custom lists on the fly.
67
Using the Tracker Capture app Lists
Lists can also be downloaded or printed.
Custom predefined lists
If the program has any custom tracked entity filters associated with it, these will take the place of
the four predefined lists mentioned above. The predefined lists will when well configured be an
effective way to find or work with the data relevant for the user in that program.
Working lists can be defined with a wide variety of options, here are some examples:
• Display all TEIs with at least one event in a given program stage that
• has a due date on the current date.
• Display all TEIs that has at least one event that is assigned to the
• logged in user.
• Display all TEIs that is active, but is not assigned to any user.
68
Using the Tracker Capture app Search
Predefined working lists in tracker capture
See the API documentation for a full list of functionality supported for these predefined tracked
entity instance filters.
Search
Search is used to search for TEIs in the organisation units the user has search access to. This
can be used if you want to find a TEI, but you dont know which organisation unit or program the
TEI was enrolled in. There are two ways of doing this: With and without a program context.
Searchable fields needs to be configured. For configuring searching with program context, this is
done individually for each program in the program maintenance app. For configuring searching
without a program context, this is done individually for each tracked entity type in the tracked
entity type maintenance app.
Searching without a program context:
1. Open Tracker Capture app
2. Click the Search button
3. Searchable fields will be displayed in groups. Unique attributes is only individually

searchable. Non-unique attributes can be combined.
4. Fill in search criteria and click the search icon button.
Searching with a program context:
1. Open Tracker Capture app
2. Select an organisation unit which has the program you wish to search in
3. Select the program
4. Click the Search button
5. Searchable fields will be displayed in groups. Unique attributes is only individually

searchable. Non-unique attributes can be combined.
6. Fill in search criteria and click the search icon button
69
Using the Tracker Capture app Search
After the search has been done, you will be presented with the search result. Whats displayed
depends on the outcome of the search.
For unique attribute search:
• If no matching TEI found, you will get the possibility to open the registration form.
• If the TEI was found in the selected organisation unit, the TEI dashboard will automatically
open.
• If the TEI was found in outside the selected organisation unit, you will get the possibility to
open the TEI.
For non-unique attributes search:
• If no matching TEI's found, you will get the possibility to open the registration form.
• If matching TEI's found, you can either click on any TEI in the result list, or open the
registration form.
• If a too large number of matches was found, you will be prompted to refine your search
criteria
70
Using the Tracker Capture app Flagging tracked entity instance as potential duplicate
The search results have functionality for flagging tracked entity instances as possible duplicates,
see next chapter.
When choosing to open the registration form, the search values will automatically be filled into the
registration form.
Flagging tracked entity instance as potential duplicate
When searching for tracked entity instances in the tracker capture app, the user will sometimes
suspect that one or more of the search hits are duplicates of other tracked entity instances. The
user has the option of clicking on the flag possible duplicate link in the rightmost column of the
search result grid.
Tracked entity instances flagged in this way will be marked as "possible duplicate" in the DHIS2
database. The flag indicates that the tracked entity instance is/has a duplicate. The presence of
such a flag is visible to the user in two places. One is the result list itself (in this example Mark
Robinson is already flagged as a potential duplicate):
71
Using the Tracker Capture app Flagging tracked entity instance as potential duplicate
Tracker capture search results
The other place is within the tracked entity instance dashboard:
72
Using the Tracker Capture app Breaking the glass
Tracked entity instance flagged as duplicate
In addition to informing users about the tracked entity instance potentially being a duplicate, the
flag will be used by the underlying system for finding and merging duplicates in coming versions
of DHIS2.
Breaking the glass
If the program is configured with access level protected, and the user searches and finds tracked
entity instances that is owned by organisation unit that the user does not have data capture
authority for, the user is presented with the option of breaking the glass. The user will gove a
reason for breaking the glass, then gain temporary ownership of the tracked entity instance.
Enroll an existing TEI in a program
2. Open an existing TEI dashboard.
4. In the Enrollment widget, click Add new.
5. Fill in the required information and click Enroll.
Enter event data for a TEI
Widgets for data entry
In a TEI dashboard, you enter event data in the Timeline Data entry or Tabular data entry
widgets.
Data entry widgets in the Tracker Capture app
73
Using the Tracker Capture app Creating an event
Widget name Description
Timeline Data entry For data entry using either default or custom forms.
Depending on program definition, in particular program stages, events

will be displayed in a timely fashion. Clicking on any of them displays the
corresponding data entry. If a stage needs new event, a plus icon is
displayed for new event creation. To proceed with data entry, it is
mandatory to have event date. Once an event date is specified it is not
possible to change due date. The assumption is that by specifying event
date, the event has already taken place. If the event hasn't occurred yet, it
is possible to change due date - this is effectively doing nothing but
rescheduling. The buttons at the bottom help to change the status of a
selected event.
Another key feature from this widget is addition of multiple notes for an
event. Normally data recording is through data elements, however there
are cases where it is necessary to record additional information or
comments. This is where the notes section comes handy. However it is
not possible to delete a note. The idea is notes are more like log books.
Both skip-logic and validation error/warning messages are supported
during data entry.
Also included in the Timeline Data entry is the option to compare your
data entry to previous entries. This can be enabled by clicking the
"Switch to compare form" button (Two sheets of paper) in the top right
corner of the Timeline Data entry widget.
Tabular data entry For tabular-style data entry.
The widget displays the list of program stages as left-hand side labels.
Events will be listed in table for repeatable program stage, and allows for
in-line edits of event data values.
Creating an event
You can create an event for a TEI by:
3. In the Timeline Data entry or Tabular data entry widget, click the +-button.
4. Select a Programstage and set a Report date.
Program stages can be configured to use a feature type. This makes it possible to capture
geometry for an event. Supported feature type is Point and Polygon. Please see How to
use geometry.
5. Click Save.
74
Using the Tracker Capture app Schedule an event
Schedule an event
You can shedule an event for a future date by:
3. In the Timeline Data entry or Tabular data entry widget, click the Calendar icon.
4. Select a Programstage and set a Schedule date.
5. Click Save.
Refer an event
Sometimes it might be nessascary to refer a patient to a different Organisation unit. To refer a

TEI:
3. In the Timeline Data entry or Tabular data entry widget, click the Arrow icon.
4. Select a Programstage, Organisation unit and set a **Report date**.
5. Click either One-time referral which will only refer TEI for one single event or Move
permanently which will move TEI ownership to the selected Organisation Unit. Further
access to the TEI will be based on the ownership organisation unit.
Mandatory data elements in events
Some data elements in an event might be mandatory (marked with a red star next to the data
element lable). What this means is that all mandatory data elements must be filled in before the
user is allowed to complete the event. The exception to this is if the user has the authority called
"Ignore validation of required fields in Tracker and Event Capture". If the user has this
authority, the mandatory data elements will not be required to be filled in before saving and the
red star will not be displayed next to the data element lable. Note that super user that have the
"ALL" authority automatically have this authority.
How to use geometry
Tracked entity type, program and program stage can be configured to use a feature type. This
makes it possible to capture geometry for a TEI, program or event. Supported feature types are
Point and Polygon.
Capture coordinate
Option 1: Fill in the latitude and longitude into the field.
Option 2:
1. Click on the map icon

2. Find the location you want by either searching or locating it on the map
3. Right-click on the location you want, and choose Set coordinate
4. Click Capture at the bottom
Capture Polygon
1. Click on the map icon
75
Using the Tracker Capture app How to assign a user to an event
2. Find the location you want by either searching or locating it on the map
3. At the top left of the map, click the polygon icon
4. Draw a polygon on the map. To finish, connect the last point with the first point
5. Click Capture at the bottom
Polygons can also be deleted
1. Click the map icon

2. Click the trash can icon at the left side of the map, and select Clear all
How to assign a user to an event
In the Maintenance App a program stage can be configured to allow user assignment. If user
assignment is enabled, you will be able to assign a user to an event.
1. Click the Assigned user field.

2. Scroll or search for a user.
3. Click the user.
Manage a TEI's enrollments
The Enrollment widget gives access to information and functionality for the enrollment in the
selected program.
76
Using the Tracker Capture app TEI ownership
Enrollments widget
TEI ownership
The current ownership of all enrollments in the selected program is displayed in the "Owned by"
part of the enrollment widget. The ownership will always start out as the organisation unit that first
enrolled the TEI into the given program.
Ownership can be different for a TEIS different programs, for example one clinic can follow up a
patient in HIV, while another clinic follows up the same patient in MCH.
To update the ownership for a TEI/program combination, the user has to utilize the referral
functionality and select the "Move permanently" option while referring.
A user that has capture access to the organisation unit that is the current owner of the TEI/
Program will have write access to all enrollments for that TEI/Program combination. A user that
has search access to the organisation unit that is the current owner will have access to search
and find the TEI/Program combindation.
Deactivate a TEI's enrollment
If you deactivate a TEI dashboard, the TEI becomes 'read-only'. You can't enter data, enroll the
TEI or edit the TEI's profile.
3. In the Enrollment widget, click Deactivate.
4. Click Yes to confirm.
Activate a TEI's enrollment
3. In the Enrollment widget, click Activate.
Mark TEI's enrollment as complete
3. In the Enrollment widget, click Complete.
Reopen completed enrollment
3. In the Enrollment widget, click Reopen.
77
Using the Tracker Capture app Display TEI's enrollment history
Display TEI's enrollment history
3. In the Profile widget, click the Audit history icon.
Create a TEI enrollment note
An enrollment note is useful to record information about for example why an enrollment was
cancelled.
3. In the Notes widget, type your note and click Add.
Send a message to a TEI
3. In the Messaging widget and select SMS or E-mail.
4. Enter the required contact information.
If the TEI's profile contains an e-mail address or a phone number, these fields are filled in
automatically.
5. Type a message.
6. Click Send.
Mark a TEI for follow-up
You can use mark a TEI's enrollment for follow-up and then use this status as a filter when you
create Upcoming events and Overdue events reports. This can be useful for example to monitor
high-risk cases during a pregnancy program.
3. In the Enrollment widget, click the Mark for follow-up icon.
Edit a TEI's profile
You edit a TEI's profile or tracked entity attributes in the Profile widget.
3. In the Profile widget, click Edit.
4. Modify the profile and click Save.
78
Using the Tracker Capture app Add a relationship to a TEI
Add a relationship to a TEI
You can create a relationship from one TEI to another, for example linking a mother and a child
together or a husband and a wife. Depending on how the relationship type is configured, the
relative can inherit attributes.
Assume there are two programs: Antenatal care for the mother and Immunization for the child. If
first name, last name and address attributes are required for both programs, it is possible to
configure last name and address attributes as inheritable. Then during child registration, there is
no need to enter these inheritable attributes. You can add them automatically based on the
mother's value. If you want to have a different value for the child, you can override the
automatically generated value.
3. In the Relationships widget, and click Add.
4. Select a relationship type.
5. Search for the relative and select it. The search follows the same pattern as when
searching for tracked entity instances from the tracker front page. Searches are by default
covering the users search scope.
6. Select the tracked entity instance that matches the search criteria in the popup.
7. Click Save.
Note: If the relationship is a bi-directional relationship, the relationship

will be displayed in the TEI that the relationship was created in and in
the TEI that the relationship was linked to. Also, if the relationship is bi-
directional, each end of the relationship will have a unique name that will
be displayed in the relationship widget under the "Relationship" column.
Share a TEI dashboard
You can share a TEI dashboard via its web address.
2. Open the dashboard you want to share.
3. Copy the URL.
Make sure that the URL contains "tei", "program" and "ou" (organisation unit) parameters.
within DHIS2.
Deactivate a TEI
If you deactivate a TEI, the TEI becomes 'read-only'. Data associated with the TEI is not deleted.
79
Using the Tracker Capture app Activate a TEI
Open an existing TEI dashboard.

2.
3.
In the top right corner, click the button > Deactivate.
Activate a TEI
3.
In the upper top corner, click the button > Activate.
Delete a TEI
Warning
When you delete a TEI, you delete all data associated with the TEI.
3.
In the top right corner, click the button > Delete.
Configure the TEI dashboard
Show or hide widgets
3. Click the Settings icon, and select Show/hide widgets.
4. Select the widgets you want to show or hide.
5. Click Close.
80
Using the Tracker Capture app Save the dashboard's layout as default
Save the dashboard's layout as default
You can save the dashboard's layout as default for a program.
3. Click the Settings icon, and select Save dashboard layout as default.
Lock dashboard's layout
If you are the administrator you have the option of locking the layout of the dashboard for all
users.
3. Organize the widgets to the desired layout and save it as default (see section above).
4. Click the Settings icon, and select Lock layout for all users.
Users will still be able to reorganize the widgets temporarily, but the layout will be reset to the
admin's saved layout after page refresh. The remove widget buttons will be hidden when the
dashboard layout is locked.
Top bar
The top bar can be a helpful tool to see important data in a quick and easy way. To start using the
top bar:
3. Click the Settings icon, and select Top bar settings.
4. Click Activate top bar and click the data you would like to display in the top bar.
Change table display mode for Timeline Data Entry widget
The Timeline Data Entry widget has 5 diffrent table display modes that can be selected. The
different options are:
• Default form - Shows all data elements verticaly.
81
Using the Tracker Capture app Create reports
Compare form previous - Shows the prevoius (repeatable) program stage next to the
• current selected program stage.
• Compare form all - Shows all prevoius (repeatable) program stages next to the current
selected program stage.
• Grid form - Shows the data elements horizontaly.
• POP-over form - The same as Grid form, but when clicked the data elements are displayed
in a pop-up.
To change the current display mode, click the second icon in the widgets top bar (see image
below):
Once an option is selected the selection is stored for that spesific program stage. This mean that
you can have different table modes for the different program stages in a program.
Notes:
1. The Compare form options will function best if you have multipe
repeatable events (of the same program stage) present.
2. The Grid form and POP-over form options are not selectable if the
program stage has more than 10 data elements.
3. The icon in the widgets bar will change depending on the option
you have selected.
Create reports
2. Click Reports.
3. Select a report type.
Report types in the Tracker Capture app
Report type Description
Program summary A summary report for a particular program,

organisation unit and time frame. The report
consist of a list of TEIs and their records
organised based on program stages.
82
Using the Tracker Capture app Create reports
Report type Description
Program statistics A statistics report for a particular program. The

report provides for example an overview of
drop-outs or completion rates in a given time
frame at a particular organisation unit.
Upcoming events A tabular report showing tracked entity instances

and their upcoming events for a selected
program and time. You can sort the columns and
search the values. Show/hide operations are
possible on the columns. You can also export
the table to Microsoft Excel.
Overdue events A list of events for a selected program. The

report displays a list of TEIs and their events that
are not completed on time. You can sort the
columns and search the values You can also
export the table to Microsoft Excel.
The summary report displays a list of TEIs and their records for "MNCH/PNC (Adult Woman)"
program. The records are organized in the form of tabs where each tab is a program stage. The
columns in the table are data elements which are configured to be displayed in reports under
program stage definition.
83
Data approval Approving and accepting
Data approval
DHIS2 has an optional feature that allows authorized users to approve data that has been
entered. It allows data to be reviewed and approved at selected levels in the organisation unit
hierarchy, so the approval follows the structure of the hierarchy from lower levels to higher levels.
Data is approved for a combination of (a) period, (b) organisation unit and © workflow. Data may
be approved for the organisation unit for which it is entered, as well as for higher-level
organisation units to which the data is aggregated. As part of system settings, you can choose the
organisation unit level(s) at which data is approved. It can be approved at higher levels only after
it has been approved for all that organisation unit's descendants at lower levels for the same
workflow and period. When you approve a workflow, it approves data for any data sets that have
been assigned to that workflow.
After a period, organisation unit and workflow combination has been approved, data sets
associated with that workflow will be locked for that period and organisation unit, and any further
data entry or modification will be prohibited unless it is first un-approved.
For example, the following diagram illustrates that data has already been approved for
organisation units C and D, for a given period and workflow. It may now be approved for
organisation unit B for the same period and workflow. But it is not ready to be approved for
organization unit A. Before it can be approved for organisation unit A, it must be approved for B,
and for any other children of organisation unit A, for that period and workflow.
Approving at organisation units
DHIS2 supports two different types of approval processes: either a one-step process where the
data is approved at each level, or a two-step process where data is first approved and then
accepted at each level. This is illustrated in the following diagram:
84
Data approval Authorities for approving data
In the one-step process, data is approved at one level, and then approved at the next higher
level. Until it is approved at the next higher level, it may be unapproved at the first level. (For
example, if the data was approved my mistake, this allows the approver to undo their mistake.)
Once the data is approved at the next higher level, it may not be unapproved at the lower level
unless it is first unapproved at the higher level.
In the two-step process, data is approved at one level, and then the approval is accepted at the
same level. This acceptance is done by a user who is authorized to approve data at the next
higher level. Once the data is accepted, it may not be changed or unapproved unless it is first
unaccepted.
The two-step process is not required by DHIS2. It is an optional step for a user reviewing data at
the next higher level. It has the benefit of locking the acceptance from the level below, so
reviewer does not have to worry that the data could be changing from below while it is being
reviewed. It can also be used by the higher-level user to keep track of which lower-level data has
already been reviewed.
Two-step process can be activated by checking Acceptance required before approval in

SystemSettings app under General section.
Authorities for approving data
To approve data, you must be assigned a role containing one of these authorities:
• Approve data - You may approve data for the organisation unit(s) to which you are
assigned. Note that this authority does not allow you to approve data for lower-levels below
the organisation unit(s) to which you are assigned. This is useful to separate the users
authorized to approve at one level from the users authorized to approve at levels below.
• Approve data at lower levels - Allows you to approve data for all lower levels below the
organisation units assigned to you. This is useful if, for example, you are a district-level
user whose role includes approving the data for all the facilities within that district, but not
for the district itself. If you are assigned this as well as the Approve data authority, you may
approve data at the level of the organisation unit(s) to which you have been assigned, and
for any level below.
• Accept data at lower levels - Allows you to accept data for the level just below the
organisation unit(s) assigned to you. This authority can be given to the same users as
approve data. Or it may be given to different users, if you want to have some users who
accept data from the level below, and a different set of users who approve data to go up to
the next level above.
Configuring data approval
In the Maintenance app section under Data approval level you can specify the levels at which you
want to approve data in the system. Click the Add new button on this page and select the
organisation unit level at which you want approvals. It will be added to the list of approval
settings. You may configure the system for approving data at every organisation unit level, or only
at selected organisation unit levels.
Note that when you add a new approval level, you may optionally choose a Category option
group set. This feature is discussed later in this chapter.
Also in maintenance under Data approval workflow, you can define the workflows that will be
used for approving data. Each workflow can be associated with one or more approval levels. Any
two workflows may operate at all the same approval levels as each other, some of the same and
some different levels, or completely different levels.
85
Data approval Data visibility
If you want data for a data set to be approved according to a workflow, then assign the workflow
to the data set when you add or edit the data set. If you do not want data for a data set to be
subject to approval, then do not assign any workflow to that data set. For data sets that you want
to approve at the same time as each other, assign them to the same workflow. For data sets that
you want to approve independently, assign each data set to its own workflow.
Under System Settings -> Analytics, you can control what unapproved data (if any) will appear in
analytics. See the "Analytics settings" section of this user guide. Note that users who are
assigned to organisation units where data is ready for approval can alwyas view this data in
analytics, as can users assigned to higher-level organisation units if they have the Approve data
at lower levels authority or the View unapproved data authority.
Data visibility
If the option Hide unapproved data in analytics is enabled, data will be hidden from viewing by
users associated with higher levels. When determining whether a data record should be hidden
for a specific user, the system associates a user with a specific approval level and compares it to
the level to which the data record has been approved up to. A user is associated with the
approval level which matches the level of the organisation unit(s) she is linked to, or if no
approvel level exists at that level, the next approval level linked to an organisation unit level below
herself. A user will be allowed to see data which has been approved up to the level immediately
below her associated approval level. The rationale behind this is that a user must be ablet to view
the data that has been approved below so that she can eventually view and approve it herself.
Note that if the user has been granted the View unapproved data or the ALL authority she will be
able to view data irrespective of the approval status.
Lets consider the following example: There are four organisation unit levels, with approval levels
associated with level 2 and 4. User A at country level (1) gets associated with approval level 1
since the approval level exists at the same level as the organisation unit level. User B gets
associated with approval level 2 since there is no approval level directly linked to her organisation
unit level and approval level 2 is the immediate level below. User C gets associated with approval
level 2. User D is below all approval levels which implies that she can see all data entered at or
below her organisation unit level.
Hiding of unapproved data
Using this example, lets consider some scenarios:
• Data is entered at facility level: Only User D can see the data, as the data has not yet been
approved at all.
86
Data approval Approving data
Data is approved by User D at facility level: Data becomes visible to User C and User B, as
• the data is now approved at their level.
• Data is approved by User C at district level: Data becomes visible to User A, as data is now
approved at the level immediately below herself.
Approving data
To approve data, go to Reports and choose Data Approval. When this report shows data that is
configured for approval, it shows the approval status of the data in the report. The approval
status will be one of the following:
• Waiting for lower level org units to approve - This data is not yet ready to be approved,
because it first needs to be approved for all the child organisation units to this organisation
unit, for the same workflow and period.
• Ready for approval - This data may now be approved by an authorized user.
• Approved - This data has already been approved.
• Approved and accepted - This data has already been approved, and also accepted.
If the data you are viewing is in an approval state that can be acted upon, and if you have
sufficient authority, one or more of the following actions will be available to you on the Data
Approval form:
• Approve - Approve data that has not yet been approved, or that was formerly approved
and has been unapproved.
• Unapprove - Return to an unapproved state data that has been approved or accepted.
• Accept - Accept data that has been approved.
• Unaccept - Return to an unaccepted (but still approved) state data that has been
accepted.
In order to unapprove data for a given organisation unit, you must have the authority to approve
data for that organisation unit or to approve data for a higher-level organisation unit to which that
data is aggregated. The reason for this is as follows: If you are reviewing data for approval at a
higher organisation unit level, you should consider whether the data at lower organisation units
are reasonable. If all lower-level data looks good, you can approve the data at the higher level. If
some lower-level data looks suspect, you can unapprove the data at the lower level. This allows
the data to be reviewed again at the lower level, corrected if necessary, and re-approved up
through the organisation unit levels according to the hierarchy.
Approving by category option group set
When defining an approval level, you specify the organisation unit level at which data will be
approved. You may also optionally specify a category option group set. This is useful if you are
using category option groups to define additional dimensions of your data, and you want
approvals to be based on these dimensions. The following examples illustrate how this can be
done within a single category option group set, and by using multiple category option group sets.
Approving by one category option group set
For example, suppose you define a category option group set to represent NGOs who serve as
healthcare partners at one or more organisation units. Each category option group within this set
represents a different partner. The category option group for Partner 1 may group together
category options (such as funding account codes) that are used by that partner as a dimension of
87
Data approval Approving by one category option group set
the data. So data entered by Partner 1 is attributed to a category option in Partner 1's category
option group. Whereas data entered by partner 2 is attributed to a category option in Partner 2's
category option group:
Example Category Option Groups
Category option group set Category option group Category options
Partner Partner 1 Account 1A, Account 1B
Each partner could enter data for their accounts independently of the other, for the same or
different workflows, at the same or different facilities. So for example, data can be entered and/or
aggregated at the following levels for each partner, independently of each other:
Example category option groups
Tip
You can use the sharing feature on category options and category
option groups to insure that a user can enter data (and/or see data)
only for certain category options and groups. If you don't want users to
see data that is aggregated beyond of their assigned category options
and/or category option groups, you can assign Selected dimension
restrictions for data analysis, when adding or updating a user.
You can optionally define approval levels for partner data within any or all of these organisation
unit levels. For example, you could define any or all of the following approval levels:
Example Category Option Group Set approval levels
Approval level Organisation unit level Category option group set
1 Country Partner
2 District Partner
3 Facility Partner
88
Data approval Approving by multiple category option group sets
Approving by multiple category option group sets
You can also define approval levels for different category option group sets. To continue the
example, suppose that you have various agencies that manage the funding to the different
partners. For example, Agency A funds accounts 1A and 2A, while Agency B funds accounts 1B
and 2B. You could set up category option groups for Agency A, and Agency B, and make them
both part of a category option group set called Agency. So you would have:
Example Multiple Category Option Group Sets
Category option group set Category option group Category options
Agency Agency A Account 1A, Account 2A
Agency Agency B Account 1B, Account 2B
Now suppose that at the country level, you want each partner to approve the data entered by that
partner. Once this approval is done, you want each agency to then approve the data from
accounts that are managed by that agency. Finally, you want to approve data at the country level
across all agencies. You could do this by defining the following approval levels:
Example Multiple Category Option Group Set approval levels
Approval level Organisation unit level Category option group set
1 Country
2 Country Agency
3 Country Partner
Note that multiple approval levels can be defined for the same organisation unit level. In our
example, Partner 1 would approve country-wide data at approval level 3 from category options
Account 1A and Account 1B. Next, Agency A would approve country-wide data at approval level 2
from category options Account 1A (after approval by Partner 1) and Account 2A (after approval by
Partner 2.) Finally, after approval from all agencies, country-wide data can be approved at
approval level 1 across all category options. Note that approval level 1 does not specify a
category option group set, meaning that it is for approving data across all category options.
This example is meant to be illustrative only. You may define as many category option groups as
you need, and as many approval levels as you need at the same organisation unit level for
different category option group sets.
If you have multiple approval levels for different category option group sets at the same
organisation unit level, you may change the approval ordering in the Settings section, under
System Approval Settings. Just click on the approval level you wish to move, and select Move up
or Move down. If you have an approval level with no category option groups set, it must be the
highest approval level for that organisation unit level.
89
Reporting functionality in the reports app Using standard reports
Reporting functionality in the reports app

The reports app allows for canned, standard reports, data set reports, resources and org unit
distribution reports.
Using standard reports
You access the available reports by navigating to Apps->Reports (Beta). In the report menu in the
left bar, click Standard Report. A list of all pre-defined reports will appear in the main window.
You run/view a report by clicking on the triple-dot icon of the report and then selecting "Create"
from the contextual menu. If there are any pre-defined parameters, 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 "Generate
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.
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 (Beta).
A Criteria window will appear where you fill in the details for your report:
Dataset: The data set you want to display.
Report 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.
90
Reporting functionality in the reports app Using reporting rate summary
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.
Report 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.
Using reporting rate summary
Access the reporting rate summary from the Apps->Reports (Beta) menu. Reporting rate
summaries will show how many datasets (forms) that have been submitted by organisation unit
and period.
The reporting rate is calculation is 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.
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).
• Reporting rate: 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.
• Reporting rate 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 a data set.
• Select a period type and a period from the list of available periods for that period type.
• The report will then be rendered. Change any of the parameters above and click "Get
report" again see the corresponding results.
91
Reporting functionality in the reports app Using resources
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 cloud storage is configured for
your system, resources will be saved there.
To create a new resource:
1. Open the Reports (Beta) app and click Resource.
2. Click Add new.
3. Enter a Name.
4. Select a Type: Upload file or External URL.
5. Click Save.
Using organisation unit distribution reports
You can access the Orgunit Distribution reports from the left side menu in the Apps->Reports
(Beta).
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 the table-based report as Excel or CSV.
92
Reporting functionality in the reports app Using organisation unit distribution reports
93
Using the Data Visualizer app Creating and editing visualizations
Using the Data Visualizer app
Creating and editing visualizations
When you open the data-visualizer app from the dhis2 menu, you are presented with a blank
slate and you can start creating your visualization right away.
94
Using the Data Visualizer app Select visualization type
Select visualization type
Select the desired visualization type from the selector in the upper left corner:
95
96
Visualization type Description
Column Displays information as vertical rectangular columns with lengths

proportional to the values they represent.
Example: comparing performance of different districts.
Layout restrictions: exactly 1 dimension as series, exactly 1 dimension

as category.
Stacked column Displays information as vertical rectangular columns, where bars

representing multiple categories are stacked on top of each other.
Example: displaying trends or sums of related data elements.
Layout restrictions: same as Column.
Bar Same as Column, only with horizontal bars.
Stacked bar Same as Stacked column, only with horizontal bars.
Line Displays information as a series of points connected by straight lines.

Also referred to as time series.
Example: visualizing trends in indicator data over intervals of time.
Area Is based on a line (above), with the space between the axis and the
line filled with colors and the lines stacked on top of each other.
Example: comparing the trends of related indicators.
Pie Circle divided into sectors (or slices).
Example: visualizing the proportion of data for individual data elements

compared to the total sum of all data elements.
Layout restrictions: exactly 1 dimension as series, has no category.
Radar Displays data on axes starting from the same point. Also known as
spider chart.
Gauge Semi-circle which displays a single value, typically out of 100% (start
and end values are configurable).
Layout restrictions: exactly 1 dimension with exactly 1 item as series, d

ata dimension is locked to series.
97
Using the Data Visualizer app Select dimensions
Visualization type Description
Year over year (line) Useful when you want to compare one year of data to other years of
data. Based on calendar years.
Layout restrictions: period dimension is disabled.
Year over year (column) Same as Year over year (line), only with columns.
Single value Displays a single value in a dashboard friendly way.
Layout restrictions: same as Gauge.
Pivot table Summarizes the data of a more extensive table and might include
sums, averages, or other statistics, which the pivot table groups
together in a meaningful way.
Layout restrictions: none.
Select dimensions
From the dimensions menu on the left you can select the dimensions you want to show in your
visualization, including data, period, organisation units and dynamic dimensions. These can be
added by clicking on a dimension, by dragging and dropping a dimension to the layout area or by
hovering over a dimension and using on its context menu (three dots).
98
Using the Data Visualizer app Select dimensions
Just like in the dimensions menu, in the layout area you can also change the selections by
clicking on a dimension, dragging and dropping a dimension or by using a dimension's context
menu (three dots).
99
Using the Data Visualizer app Select dimension items
• Series: A series is a set of continuous, related elements (for example periods or data
elements) that you want to visualize in order to emphasize trends or relations in its data.
Also known as Columns for Pivot table visualizations.
• Categories: A category is a set of elements (for example indicators or organisation units)

for which you want to compare its data. Also known as Rows for Pivot table visualizations.
• Filter: The filter selection will filter the data displayed in the visualization. Note that if you
use the data dimension as filter, you can only specify a single indicator or data set as filter
item, whereas with other dimension types you can select any number of items.
A dimension refers to the elements that 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.
Data Visualizer is highly flexible in terms of allowing you to use these dimensions as series,
categories and filter.
To select items for a dimension, open the dimension modal window by clicking on a dimension.
This window will also be opened automatically when adding a dimension without selected items to
the layout. Select which items to add to the visualization by double-clicking an item or by selecting
an item with a single click and using the arrows in the middle. The order of appearance will be the
same as the order in which they are selected. Selected items can be reordered by dragging and
dropping them in the Selected section.
100
Select periods
When selecting a Period you have to option to choose between fixed periods and relative
periods. These can also be combined. Overlapping periods are filtered so that they only appear
once. For relative periods the names are relative to the current date, e.g. if the current month is
March and Last month is selected, the month of February is shown in the visualization.
101
Select organisation units
The organisation units dialog is flexible, offering essentially three ways of selecting organisation
units:
• Explicit selection: Use the tree to explicitly select the organisation units you want to appear
in the visualization. If you right-click on an organisation unit you can easily choose to select
all org units below it.
• Levels and groups: The Level and Group dropdowns are a convenient way to select all
units in one or more org unit groups or at specific levels. Example: select Chiefdom (level 3)
to get all org units at that level.
Please note that as soon as at least one level or group has been selected the org unit tree
now acts as the boundary for the levels/groups. Example: if you select Chiefdom (level 3)
and Kailahun org unit (at level 2) in the tree you get all chiefdom units inside Kailahun
district.
• The user's organisation units:
◦ User organisation unit: This is a way to dynamically select the org units that the
logged in user is associated to.
◦ User sub-units: Selects the sub-units of the user organisation unit.
102
Using the Data Visualizer app Change the display of your visualization
User sub-x2-units: Selects the units two levels below the user organisation unit.
◦
Change the display of your visualization
The display of a visualization can be changed by enabling/disabling and configuring several

options. Each visualization type can have a different set of available options. The options are
organised in tabs in the Options dialog and in sections within each tab.
1. Click Options to open the Options dialog.
2. Navigate the tabs in the dialog to see the available options.
3. Configure the desired options as required.
4. Click Update to apply the changes to the visualization.
List of available options
Option Description
Data tab
Aggregation type Defines how the data elements or indicators will be aggregated within the
visualization. Some of the aggregation types are By data element, Count, Min and
Max.
103
Using the Data Visualizer app List of available options
Option Description
Base line 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.
Column sub- Displays sub-totals in a Pivot table for each dimension.

totals If you only select one dimension, sub-totals will be hidden for those columns. This is
because the values will be equal to the sub-totals.
Column totals Displays total values in a Pivot table for each column, as well as a total for all values in
the table.
Cumulative Displays cumulative values in Column, Stacked column, Bar, Stacked bar, Line and
values Area visualizations
Custom sort order Controls the sort order of the values.
Dimension labels Shows the dimension names as part of a Pivot table.
Hide empty Hides the category items with no data from the visualization. Before first: hides missing
categories values only before the first value After last: hides missing values only after the last
value Before first and after last: hides missing values only before the first value and
after the last value All: hides all missing values This is useful for example when you
create Column and Bar visualizations.
Hide empty Hides empty columns from a Pivot table. This is useful when you look at large tables
columns where a large portion of the dimension items don't have data in order to keep the table
more readable.
Hide empty rows Hides empty rows from a Pivot table. This is useful when you look at large tables
where a large portion of the dimension items don't have data in order to keep the table
more readable.
Number type Sets the type of value you want to display in a Pivot table: Value, Percentage of
row or Percentage of column.
The options Percentage of row and Percentage of column mean that you'll
display values as percentages of row total or percentage of column total instead of the
aggregated value. This is useful when you want to see the contribution of data
elements, categories or organisation units to the total value.
Only include Includes only completed events in the aggregation process. This is useful for example
completed events to exclude partial events in indicator calculations.
Row sub-totals Displays sub-totals in a Pivot table for each dimension.

If you only select one dimension, sub-totals will be hidden for those rows. This is
because the values will be equal to the sub-totals.
104
Option Description
Row totals Displays total values in a Pivot table for each row, as well as a total for all values in the
table.
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.
Stacked values Displays 100 % stacked values in Stacked column and Stacked bar visualizations.
add up to 100%
Target line Displays a horizontal line at the given domain value. Useful for example when you
want to compare your performance to the current target.
Trend line Displays the trend line that visualizes how your data evolves over time. For example if
performance is improving or deteriorating. Useful when periods are selected as
category.
Value labels Shows the values above the series in the visualization.
Axes tab
Axis range Defines the maximum and minimum value that will be visible on the range axis.
Axis title Type a title here to display a label next to the x or y axis. Useful when you want to give
context information to the visualization, for example about the unit of measure.
Decimals Defines the number of decimals that will be used for range axis values.
Steps Defines the number of ticks that will be visible on the range axis.
Legend tab
Display legend Applies a legend to the values. This means that you can apply a color to the values.
You configure legends in the Maintenance app.
The Legend type section allows to control which color is applied. Select Use pre-
defined legend per data item to color a data point individually according to each data
element or indicator. Select Select a single legend for entire visualization to use a
single legend, chosen in a drop-down list of available legends.
The Legend style section allows to control where the color is applied, the text or
background based on the selected legend. You can use this option for scorecards to
identify high and low values at a glance. Not applicable for Single Value
visualizations.
Style tab
105
Option Description
Digit group Controls which character to use to separate groups of digits or "thousands". You can
separator set it to Comma, Space or None.
Display density Controls the size of the cells in a Pivot table. You can set it to Comfortable, Normal or
Compact. Compact is useful when you want to fit large tables into the browser screen.
Display Shows the name of all ancestors for organisation units, for example "Sierra Leone /
organisation unit Bombali / Tamabaka / Sanya CHP" for "Sanya CHP". The organisation units are then
hierarchy sorted alphabetically which will order the organisation units according to the hierarchy.
When you download a pivot table with organisation units as rows and you've selected
Display organisation unit hierarchy, each organisation unit level is rendered as a
separate column. This is useful for example when you create Excel pivot tables on a
local computer.
Font size Controls the size of a Pivot table text font. You can set it to Large, Normal or Small.
Chart/Table title Controls the title that appears above the visualization. Auto generated uses the default
title generated from the visualization's dimensions/filters. None removes the title. The
Custom option allows you to type a custom title.
Chart/Table Controls the subtitle that appears above the visualization. Auto generated uses the
subtitle default subtitle generated from the visualization's dimensions/filters. None removes
the subtitle. The Custom option allows you to type a custom subtitle.
Legend key Toggles the legend on and off leaving more room for the visualization itself.
No space Removes the space between the columns or bars in the visualization. Useful for
between bars/ displaying the visualization as an EPI curve.
columns
Value labels Shows the values above the series in the visualization.
Chart/Table title Controls the title that appears above the visualization. Auto generated uses the default
title generated from the visualization's dimensions/filters. None removes the title. The
Custom option allows you to type a custom title.
Limit values tab
Limit minimum/ Allows for the data to be filtered on the server side. You can instruct the system to
maximum values return only records where the aggregated data value is equal, greater than, greater or
equal, less than or less or equal to certain values. If both parts of the filter are used, it's
possible to filter out a range of data records.
Parameters tab
106
Using the Data Visualizer app Adding Assigned Categories
Option Description
Custom sort order Controls the sort order of the values.
Include Includes a column with cumulative values to a Pivot table.

cumulative
Include Includes a column with regression values to a Pivot table.

regression
Organisation unit Controls whether to ask user to enter an organisation unit when creating a standard
report in Reports app.
Parent Controls whether to ask user to enter a parent organisation unit when creating a
organisation unit standard report in Reports app.
Reporting period Controls whether to ask user to enter a report period when creating a standard report
in Reports app.
Top limit Controls the maximum number of rows to include in a Pivot table.
Adding Assigned Categories
Assigned Categories is a composite dimension that represents associated category option

combinations to the selected data element's category combination. This can be added by
dragging the Assigned Categories dimension from the left side dimensions menu and into the
visualization layout:
Another way of adding assigned categories is by accessing the Add Assigned Categories option
from the Data dimension's context menu (not available for Gauge, Year over year or Single
value).
107
Using the Data Visualizer app Adding more axes
Adding more axes
When combining data with different measurement scales you will get a more meaningful
visualization by having more than a single axis. For Column, Bar and Line you can do so by
clicking Manage chart axes in the Data dimension's context menu. If the option is disabled, make
sure that the Data dimension is on the Series axis and that at least two items have been added.
In the axis management dialog you can assign data items to the two axes.
Manage saved visualizations
Saving your visualizations makes it easy to find them later. You can also choose to share them
with other users or display them on a dashboard.
Open a visualization
1. Click File > Open.
2. Enter the name of a visualization in the search field, or click the < and > arrows to navigate
between different pages. The result can also be filtered by type and owner by using the
corresponding menus in the top right corner.
108
Using the Data Visualizer app Save a visualization
Click the name of the one you want to open.

3.
Save a visualization
1. a) Click File > Save.
2. Enter a Name and a Description for your visualization.
3. Click Save.
109
Using the Data Visualizer app Rename a visualization
Rename a visualization
1. Click File > Rename.
2. Enter the new name and/or description.
3. Click Rename.
Delete a visualization
1. Click File > Delete.
2. Click Delete.
110
Using the Data Visualizer app Get the link to the visualization
Get the link to the visualization
1. Click File > Get Link.
2. The URL can be copied via the browser's context menu that opens when right clicking on
the link.
Visualization interpretations
When viewing a saved visualization, you can expand the interpretations on the right side by
clicking on the Interpretations button in the upper right corner. The visualization description will
also be shown. The description supports rich text format.
New interpretations can be added by typing in the text field in the bottom right corner. Other users
can be mentioned with @username. Start by typing @ plus the first letters of the username or real
name and a list of matching users will be displayed. Mentioned users will receive an internal
DHIS2 message with the interpretation or comment. Interpretations can also be seen in the
Dashboard app.
It is possible to format the text with bold, italic by using the Markdown style markers * and _ for
bold and italic respectively (keyboard shortcuts are also available: Ctrl/Cmd + B and Ctrl/Cmd +
I). A limited set of emojis is supported and can be used by typing one of the following character
combinations: :) :-) :( :-( :+1 :-1. URLs are automatically detected and converted into a
clickable link.
To view the visualization according to the date of a particular interpretation, click on the
interpretation or its View button. This will regenerate the visualization with the relevant date,
which is indicated next to the visualization title. Clicking on Back to all interpretations will
regenerate the visualization with the current date.
To subscribe to the saved visualization, click the bell icon in the upper right corner. You will then
receive internal messages whenever another user likes/creates/updates an interpretation in this
saved visualization.
111
Using the Data Visualizer app Share a visualization
Share a visualization
Sharing settings can be accessed by clicking File > Share. Change sharing settings for the user
groups you want to modify, the available settings are:
• Can edit and view: Can view and edit the visualization.
• Can view only: Can only view the visualization.
• No access: Won't have access to the visualization. This setting is only applicable to Public
access and External access.
New users can be added by searching for them by name under Add users and user groups.
112
Using the Data Visualizer app Download
Download
Visualizations can be downloaded using the Download menu. All visualization types support
Graphics and Plain data source downloads, except for the Pivot table type, which can be
downloaded as Table layout and Plain data source.
Graphics download
Downloads an image (.png) or a PDF (.pdf) file to your computer.
Table layout download
Downloads a Excel (.xls), CSV (.csv) or HTML (.html) file to your computer.
Plain data source download
You can download the data source of a visualization 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.
Available formats
113
Using the Data Visualizer app See visualization as map
Format Action Description
JSON Click JSON Downloads JSON format based on the ID, Code
or Name property.
XML Click XML Downloads XML format based on the ID, Code or
Name property.
Microsoft Excel Click Microsoft Excel Downloads Microsoft Excel format based on the I
D, Code or Name property.
CSV Click CSV Downloads CSV format based on the ID, Code or
Name property.
XML data value Click Advanced > XML Downloads the raw data values as XML, as
set opposed to data which has been aggregated
along various dimensions.
JSON data Click Advanced > JSON Downloads the raw data values as JSON, as
value set opposed to data which has been aggregated
along various dimensions.
JRXML Click Advanced > JRXML Produces a template of a Jasper Report 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 Click Advanced > Raw data SQL Provides the actual SQL statement used 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.
See visualization as map
To see how a visualization would look on map, select the Open as Map Visualization type after
you're finished building your visualization.
114
Using the Data Visualizer app See visualization as map
115
Analyze data in pivot tables About the Pivot Table app
Analyze data in pivot tables

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 the data)
• 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.
Tip
• You must select at least one dimension on columns or rows.

• You must include at least one period.
• Data element group sets and reporting rates can't appear in the
same pivot table.
• A pivot table can't contain more than the maximum number of
analytic records which have been specified in the system settings.
The maximum number of records could also be constrained by the
maximum RAM which is available to your browser. You will be
prompted with a warning if your requested table exceeds a
particular size. From this prompt, you can either cancel the
request or continue building the table. Consider making smaller
tables instead of one table which displays all of your data
elements and indicators together.
• The Pivot Table app supports drill-down and up for periods and
organisation unit. This means that you can for example drill down
from yearly periods to quarters, months and weeks inside a pivot
table. You can also drill down from the global organisation unit to
countries, provinces and facilities.
Create a pivot table
1. Open the Pivot Table app.
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.
116
Analyze data in pivot tables Select dimension items
You can keep the default selection if you want.
4. Click Update.
In this example, indicators are listed as columns and periods as rows.
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 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:
Data dimension types
Data dimension type Definition Examples
Indicators An indicator is a calculated Coverage of immunization

formula based on data elements. across a specific district.
Data elements Represents the phenomenon for Number of malaria cases;

which data has been captured. number of BCG doses given.
117
Data dimension type Definition Examples
Data sets A collection of data elements Reporting rates for immunization

grouped for data collection. You and morbidity forms.
can select :
• 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 of a Average weight and height for
program representing events that children in a nutrition program.
have been captured.
Program indicators A calculated formula based on Average BMI score for children in
data elements in a program a nutrition 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.
118
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.
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 by Type of
organisation unit or Implementing partner. Dynamic dimensions work the same as fixed
dimensions.
Tip
119
Analyze data in pivot tables Modify pivot table layout
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.
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.
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 have
120
Analyze data in pivot tables Change the display of your pivot table
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:
Change the display of your pivot table
1. Open the Pivot Table app.
2. Create a new pivot table or open a favorite.
3. Click Options.
4. Set the options as required.
Pivot table options
Option Description
Data Show column totals Displays total values in the table for
each row and column, as well as a total
Show row totals
for all values in the table.
Show column sub-totals Displays subtotals in the table for each

dimension.
Show row sub-totals
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.
121
Option Description
Hide empty rows Hides empty rows from the table. This is
useful when you look at large tables
where a big part of the dimension items
don't have data in order to keep the
table more readable.
Hide empty columns Hides empty columns from the table.

This is useful when you look at large
tables where a big part of the dimension
items don't 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 M
ax.
Number type Sets the type of value you want to

display in the pivot table: Value, Percen
tage of row or Percentage of column.
The options Percentage of row andPer

centage of column mean that you'll
display values as percentages of row
total or percentage of column total
instead of the aggregated value. This is
useful when you want to see the
contribution of data elements, categories
or organisation units to the total value.
Measure criteria Allows for the data to be filtered on the

server side.
You can instruct the system to return

only records where the aggregated data
value is equal, greater than, greater or
equal, less than or less or equal to
certain values.
If both parts of the filter are used, it's

possible to filter out a range of data
records.
122
Option Description
Events Include only completed events Includes only completed events in the
aggregation process. This is useful for
example to exclude partial events in
indicator calculations.
Organisation Show hierarchy Shows the name of all ancestors for

units organisation units, for example "Sierra
Leone / Bombali / Tamabaka / Sanya
CHP" for Sanya CHP.
The organisation units are then sorted

alphabetically which will order the
organisation units according to the
hierarchy.
When you download a pivot table with

organisation units as rows and you've
selected Show hierarchy, each
organisation unit level is rendered as a
separate column. This is useful for
example when you create Excel pivot
tables on a local computer.
Legend Apply legend Applies a legend to the values. This

mean that you can apply a colour to the
values.
Select By data item to color the table

cells individually according to each data
element or indicator.
You configure legends in the Maintena

nce app.
Style Colors the text or background of cells in

pivot tables based on the selected
legend.
You can use this option for scorecards to

identify high and low values at a glance.
Style Display density Controls the size of the cells in the table.
You can set it to Comfortable, Normal
or Compact.
Compact is useful when you want to fit

large tables into the browser screen.
123
Option Description
Font size Controls the size of the table text font.

You can set it to Large, Normal or
Small.
Digit group separator Controls which character to separate

groups of digits or "thousands". You can
set it to Comma, Space or None.
General Table title Type a title here to display it above the

table.
Parameters (for
standard reports
only) Note
You create standard reports

in the Reports app.
In the Pivot Table app you

set which parameters the
system should prompt the
user for.
Reporting period Controls whether to ask user to enter a

report period.
Organisation unit Controls whether to ask user to enter an

organisation unit.
Parent organisation unit Controls whether to ask user to enter a

parent organisation unit.
Include regression Includes a column with regression

values to the pivot table.
Include cumulative Includes a column with cumulative

values to the pivot table.
Sort order Controls the sort order of the values.
Top limit Controls the maximum number of rows

to include in the pivot table.
5. Click Update.
124
Analyze data in pivot tables Manage favorites
Manage favorites
Saving your charts or pivot tables as favorites makes it easy to find them later. You can also
choose to share them with other users as an interpretation or display them on the dashboard.
You view the details and interpretations of your favorites in the Pivot Table, Data Visualizer,
Event Visualizer, Event Reports apps. Use the Favorites menu to manage your favorites.
Open a favorite
1. Click Favorites > Open.
2. Enter the name of a favorite in the search field, or click Prev and Next to display favorites.
3. Click the name of the favorite you want to open.
Save a favorite
1. Click Favorites > Save as.
2. Enter a Name and a Description for your favorite. The description field supports a rich text
format, see the interpretations section for more details.
3. Click Save.
Rename a favorite
1. Click Favorites > Rename.
2. Enter the new name for your favorite.
3. Click Update.
Write an interpretation for a favorite
An interpretation is a link to a resource with a description of the data at a given period. This
information is visible in the Dashboard app. To create an interpretation, you first need to create a
favorite. If you've shared your favorite with other people, the interpretation you write is visible to
those people.
1. Click Favorites > Write interpretation.
2. In the text field, type a comment, question or interpretation. You can also mention other
users with '@username'. Start by typing '@' plus the first letters of the username or real
name and a mentioning bar will display the available users. Mentioned users will receive an
internal DHIS2 message with the interpretation or comment. You can see the interpretation
in the Dashboard app.
It is possible to format the text with bold, italic by using the Markdown style markers * and _
for bold and italic respectively. Keyboard shortcuts are also available: Ctrl/Cmd + B and
Ctrl/Cmd + I. A limited set of smilies is supported and can be used by typing one of the
following character combinations: :) :-) :( :-( :+1 :-1. URLs are automatically detected and
converted into a clickable link.
3. Search for a user group that you want to share your favorite with, then click the + icon.
4. Change sharing settings for the user groups you want to modify.
◦ Can edit and view: Everyone can view and edit the object.
◦ Can view only: Everyone can view the object.
125
Analyze data in pivot tables Subscribe to a favorite
None: The public won't have access to the object. This setting is only applicable to
◦ Public access.
5. Click Share.
Subscribe to a favorite
When you are subscribed to a favorite, you receive internal messages whenever another user
likes/creates/updates an interpretation or creates/update an interpretation comment of this
favorite.
1. Open a favorite.
2. Click >>> in the top right of the workspace.
3. Click on the upper-right bell icon to subscribe to this favorite.
Create a link to a favorite
1. Click Favorites > Get link.
2. Select one of the following:
◦ Open in this app: You get a URL for the favorite which you can share with other
users by email or chat.
◦ Open in web api: You get a URL of the API resource. By default this is an HTML
resource, but you can change the file extension to ".json" or ".csv".
Delete a favorite
1. Click Favorites > Delete.
2. Click OK.
View interpretations based on relative periods
To view interpretations for relative periods, such as a year ago:
1. Open a favorite with interpretations.
3. Click an interpretation. Your chart displays the data and the date based on when the
interpretation was created.To view other interpretations, click them.
Download data from a pivot table
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.
Tip
126
Analyze data in pivot tables Download plain data source format
When you download a pivot table with organisation units as rows and you've
selected Show hierarchy in Table options, each organisation unit level is
rendered as a separate column. This is useful for example when you create
Excel pivot tables on a local computer.
Tip
You can create a pivot table in Microsoft Excel from the downloaded
Excel file.
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.
Available formats
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 Excel Click Microsoft Excel Downloads XML format based on ID property.
You can also download Microsoft Excel format

based on Code or Name property.
Click CSV
CSV Downloads CSV format based on ID property.
You can also download CSV format based on

Code or Name property.
127
Analyze data in pivot tables Download a CSV format without rendering data in the web browser
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 to
and click Raw data SQL generate the pivot table. You can use it as a
data source in a Jasper report, or as the basis
for an SQL view.
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.
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.
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.
128
Analyze data in pivot tables Visualize pivot table data as a chart or a map
Visualize 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.
Open a pivot table as a chart
1. Click Chart > Open this table as chart.
Your current pivot table opens as a chart.
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.
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.
Open a pivot table as a map
1. Click Chart > Open this table as map
Your current pivot table opens as a map.
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.
129
Using the Maps app About the Maps app
Using the Maps app

About the Maps app
The Maps App is introduced in release 2.29 and serves as a replacement of the GIS App offering
a more intuitive and user-friendly interface. The mapping engine from version 2.34 is based on
WebGL technology, capable of showing thousands of features on a map simultaneously.
With the Maps app you can overlay multiple layers and choose among different base maps. You
can create thematic maps of areas and points, view facilities based on classifications, and
visualize catchment areas for each facility. You can add labels to areas and points, and search
and filter using various criteria. You can move points and set locations on the fly. Maps can be
saved as favorites and shared with other users and groups, or downloaded as an image.
Note
To use predefined legends in the Maps app, you need to create them
first in the Maintenance app.
• The layer panel on the left side of the workspace shows an overview of the layers for the
current map:
◦ As layers are added, using the (+) Add layer button, they are arranged and
managed in this panel.
◦ The basemap is always shown in the panel. The default basemap is OSM Light and
is selected by default. OpenStreetMap Detailed contains more map features and
place names. There are 4 basemaps from Bing Maps, replacing Google Maps
provided in previous versions. Bing Road and Bing Dark shows roads, borders and
places. Use the dark version if the colors on your map layers are bright. Bing Aerial
and Bing Aerial Labels shos satellite and detailed aerial imagery. Switch between
them by selecting the desired image.
130
The small arrow button to the right of the layer panel, at the top, allows the panel to
◦ be hidden or shown.
• The File button near the top left allows you to open and save maps:
◦ New
will clear any existing map layers to create a new map.
◦ Open
will display a dialog box with a list of existing maps where they be opened, renamed,
shared and deleted. The title of the current map is displayed in the header bar above
the File button.
◦ Save
will save any changes to the current map.
◦ Save as
will save the current map with a new name.
◦ Rename
allows you to change the name and/or description of the current map.
◦ Translate
allows you to translate the name and/or description of the current map.
◦ Share
will open a dialog where the current map can be shared with everyone or a group of
users.
◦ Get link
will provide a direct link to the current map.
◦ Delete
deletes the current map.
• The Download button next to the File button allows you to download the current map as a
PNG image.
• The Interpretations button at top right opens an interpretations panel on the right side of
the workspace. The button is only clickable if the map is saved.
◦ Map details shows information about the current map.
◦ Interpretations allows you to view, add, edit and share interpretations about the
current map.
• The + and - buttons on the map allow you to zoom in and out of the map respectively. The
mouse scroll wheel zoom is continuous, allowing us to fit the map perfectly to your content.
• The rotate map button (triangle arrows) allows you to rotate and tilt the map to enhance
the view of your data. Press the button (or the Control key on your keyboard) while moving
your mouse to change the map view. Click to button again to reset the view.
131
Fullscreen (four arrows) allows you to view the map in fullscreen. To exit fullscreen click
• the button again or the escape key on your keyboard.
• Zoom to content (bounded magnifying glass symbol) automatically adjusts the zoom level
and map center position to put the data on your map in focus.
• Search (magnifying glass symbol) allows searching for and jumping to a location on the
map.
• The ruler button allows you to measure distances and areas on the map.
• Right-click on the map to display the longitude and latitude of that location.
Basemaps
Basemap layers are represented by layer cards in the layer panel such as:
Along the top of the basemap card from left to right are:
• The title of the selected basemap
• An arrow symbol to collapse and expand the basemap card
In the middle of the basemap card is the list of available basemaps. The current basemap is
highlighted.
Along the bottom of the basemap card is:
• An eye symbol for toggling the visibility of the layer
• A slider for modifying the layer transparency
132
Using the Maps app Create a new map
Create a new map
1. In the Apps menu, click Maps. The DHIS2 Maps window opens.
2. Click the (+) Add layer button in the top left. You are presented with the layer selection
dialog:
3. Select a layer to add to the current map. Possible options are:
◦ Thematic
◦ Events
◦ Tracked entities
◦ Facilities
◦ Boundaries
In addition, there are several layers provided by Google Earth Engine and other services:
◦ Population density
◦ Elevation
◦ Temperature
◦ Precipitation
◦ Landcover
133
Using the Maps app Manage thematic layers
Nighttime lights
◦
Labels overlay is an external layer defined in the Maintenance app.
Manage thematic layers
Thematic maps represent spatial variation of geographic distributions. Select your desired
combination of indicator/data element, period and organisation unit level. If your database has
coordinates and aggregated data values for these organisation units, they will appear on the
map.
Note
You must generate the DHIS2 analytics tables to have aggregated data
values available.
Thematic layers are represented by layer cards in the layer panel such as:
Along the top of the thematic card from left to right are:
• A grab field to allow dragging and re-ordering layers with the mouse
• The title and period associated with the layer
• An arrow symbol to collapse and expand the thematic card
In the middle of the thematic card is a legend indicating the value ranges displayed on the layer.
Along the bottom of the thematic card from left to right are:
• An edit (pencil) button to open the layer configuration dialog
134
Using the Maps app Create a thematic layer
A more actions (three dots) button with additional options:

•
◦ A data table toggle button to show or hide the data table associated with the layer
◦ Download data allows you to download the data for this layer in GeoJSON format for
use in other mapping software
◦ Edit layer is the same as edit button above
◦ Remove layer will remove this layer from the current map.
Create a thematic layer
To create an event layer, choose Thematic on the Add layer selection. This opens the Events
layer configuration dialog.
1. In the DATA tab:
◦ Select a data type and then select respectively the group and the target element.
The available fields depend on the type of item selected.
◦ Select a value from the Aggregation type field for the data values to be shown on
the map. By default, "By data element" is selected. Alternative values are: Count;
Average; Sum; Standard deviation; Variance; Min; Max. See also Aggregation
operators.
2. In the PERIOD tab
135
◦ select the time span over which the thematic data is mapped. You can select either a
relative or a fixed period.
▪ Relative period
In the Period type field select Relative, then select one of the relative periods,
for example Last year or Last 12 months, in the Period field. If you select a
relative period covering multiple years/months/weeks/days the layer can be
displayed as
▪ Single (aggregate)
Show aggregate values for the relative period selected (default).
▪ Timeline
Includes a timeline allowing you to step through the periods. Only one
timeline layer can be added to the same map.
▪ Split map views
Show multiple maps allowing you to compare different periods side by

side. Supported for relative periods with 12 items or below. Can not be
combined with other layer types.
▪ Fixed period
136
In the Period type field select period length, then select the target in the
Period field.
▪ Start/end dates
In the Period type field select Start/end dates and fill in a start date and an
end date.
3. In the ORG UNITS tab:
◦ Select the organisation units you want to include in the layer. It is possible to select
either
▪ One or more specific organisation units, organisation unit levels in the

hierarchy, organisation unit groups, or
▪ A relative level in the organisation unit hierarchy, with respect to the user. By
selecting a User organisation unit the map data will appear differently for
users at different levels in the organisation unit hierarchy.
4. In the FILTER tab:
137
◦ Click ADD FILTER and select an available data item to add a new filter to the data
set.
▪ Select a data dimension from the drop down box. You can reduce the number
of dimensions shown by using the search field. Click on the name to select a
dimension.
▪ When a dimension is selected you get a second drop down with dimension
items. Check the items you want to include in the filter.
Multiple filters may be added. Click the trash button on the right of the filter to remove
it.
5. In the STYLE tab:
138
Using the Maps app Modify a thematic layer
◦ Select either Automatic or Predefined legend.
▪ 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
the range of each interval will be (highest data value - lowest data
value / number of classes)
▪ Equal counts
the legend creator will try to distribute the organisation units evenly.
▪ If you have facilities in your thematic layer, you can set the radius for minimum
and maximum values by changing the values in the Low size and High size
boxes respectively.
6. Click ADD LAYER.
Modify a thematic layer
1. In the layer panel, click the edit (pencil) icon on the thematic layer card.
2. Modify the setting on any of the tabs as desired.
3. Click UPDATE LAYER.
139
Using the Maps app Filter values in a thematic layer
Filter values in a thematic layer
Thematic layers have a data table option that can be toggled on or off from the thematic layer
card.
The data table displays the data forming the thematic layer.
• clicking on a title will sort the table based on that column; toggling between ascending and
descending.
• entering text or expressions into the filter fields below the titles will apply those filters to the
data, and the display will adjust according to the filter. The filters are applied as follows:
◦ NAME
filter by name containing the given text
◦ VALUE
filter values by given numbers and/or ranges, for example: 2,>3&\<8
◦ LEGEND
filter by legend containing the given text
◦ RANGE
filter by ranges containing the given text
◦ LEVEL
filter level by numbers and/or ranges, for example: 2,>3&\<8
◦ PARENT
filter by parent names containing the given text
◦ ID
140
Using the Maps app Search for an organisation unit
filter by IDs containing the given text
◦ TYPE
filter by GIS display types containing the given text
◦ COLOR
filter by color names containing the given text
Note
Data table filters are temporary and are not saved with the map layers
as part of the favourite.
Search for an organisation unit
The NAME filter field in the data table provides an effective way of searching for individual
organisation units.
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 Drill up one level or Drill down one level.
The drill down option is disabled if you are on the lowest level or if there are no coordinates
available on the level below. Likewise the drill up option is disabled from the highest level.
Remove thematic layer
To clear all data in a thematic layer:
1. In the layer card to the left, click the more actions (three dots) icon and then on Remove
layer.
The layer is removed from the current map.
Manage event layers
The event layer displays the geographical location of events registered in the DHIS2 tracker.
Provided that events have associated point or polygon coordinates, you can use this layer to drill
down from the aggregated data displayed in the thematic layers to the underlying individual
events or cases.
You can also display aggregated events at the facility or at the boundary level. You do this
through a thematic layer using event data items. This is useful when you only have the
coordinates for the Org Unit under which the events are recorded.
141
Using the Maps app Create an event layer
Event layers are represented by layer cards in the layer panel such as:
Along the top of the event card from left to right are:
• The title and period associated with the layer
• An arrow symbol to collapse and expand the event card
In the middle of the event card is a legend indicating the styling of the layer.
Along the bottom of the event card from left to right are:
• A more actions (three dots) button with additional options:
Create an event layer
To create an event layer, choose Events on the Add layer selection. This opens the Events layer
configuration dialog.
1. In the DATA tab:
142
◦ Select a program and then select a program stage. The Stage field is only shown
once a program is selected.
If there is only one stage available for the selected program, the stage is
automatically selected.
◦ Select a value from the Coordinate field for the positions shown on the map. By
default, "Event location" is selected. Depending on the data elements or attributes
that belong to a program, other coordinates such as "Household position" are
available.
143
◦ 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.
144
either
▪ One or more specific organisation units, or
4. In the FILTER tab:
145
◦ Click ADD FILTER and select an available data item to add a new filter to the data
set.
▪ For data item 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.
▪ For data item of type number, you can select operators like equal, not equal,
greater than or less than.
▪ For data item of type boolean (yes/no), you can check the box if the condition
should be valid or true.
▪ For data item 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.
Multiple filters may be added. Click the trash button on the right of the filter to remove
it.
146
◦ Select Group events to group nearby events (cluster), or View all events to display
events individually.
◦ Select a color for the event or cluster points.
◦ Select the radius (between 1 and 20) for the events.
◦ Select Show buffer to display visual buffer around each event. The radius of the
buffer can be modified here. This option is only available if you select View all
events above.
◦ Select a Style by data element to colorise the events according to a data value. If
you also select to group events, the culsters will be displayed as small donut charts
showing the distribution of the data values. The options varies for different data
types:
▪ Option sets: Select a color for each option in an option set. You can set
default colors for an option in the Maintenance app.
▪ Numbers: You can style a numeric data element in the same way as thematic
layers using automatic or predefined legends.
▪ Booleans: Select a color for true/yes and another for false/no.
6. Click ADD LAYER.
147
Using the Maps app Modify an event layer
Modify an event layer
1. In the layer panel, click the edit (pencil) icon on the event layer card.
2. Modify the setting on the DATA, PERIOD, FILTER, ORG UNIT and STYLE tabs as desired.
Modify information in event pop-up windows
You can modify the information displayed in the event pop-up window.
1. Open the Maintenance app.
2. Select Program.
3. Click the program you want to modify and select 2 Assign data elements.
4. For every data element you want to display in the pop-up window, select corresponding
Display in reports.
5. Click Save.
Download raw event layer data
The raw data for event layers can be downloaded in GeoJSON format for more advanced geo-
analytics and processing in desktop GIS software such as QGIS. The downloaded data includes
all individual events as GeoJSON features, including attributes for each data element selected for
Display in reports.
148
Using the Maps app Download raw event layer data
• In the layer card to the left, click the more actions (three dots) icon and then on Download
data
• Select the ID format to use as the key for Data Element values in the downloaded
GeoJSON file. There are three options available:
◦ ID - Use the unique ID of the data element

◦ Name - Use the human-friendly name of the data element (translated)
◦ Code - Use the code of the data element
• Select whether or not to Use human-readable keys for other Event attributes, such as
Program Stage, Latitude, Longitude, Event Data, and Organization Unit ID, Name, and
Code. When this option is not selected these values will be the computer-friendly ID
instead of the human-readable (and translated) name.
• Click the DOWNLOAD button to generate and download a GeoJSON file. The data will be
requested from the DHIS2 server and processed by the maps application. This operation
may take several minutes to complete.
• Once the GeoJSON file has been downloaded it can be imported into most standard GIS
software applications.
Note that the downloaded data does not include style information as it is
not natively supported by the GeoJSON format. Styles can optionally be
recreated in external GIS applications using the attributes of each
feature.
149
Using the Maps app Clear event layer
Clear event layer
To clear all event layer data in a map:
layer.
Manage tracked entity layers
The tracked entity layer displays the geographical location of tracked entities registered in the
DHIS2. Provided that tracked entities have associated point or polygon coordinates, you can
explore these on a map.
Tracked entity layers are represented by layer cards in the layer panel such as:
Along the top of the tracked entity card from left to right are:
• A grab field to allow dragging and re-ordering layers with the mouse.
• The title and period associated with the layer.
• An arrow symbol to collapse and expand the tracked entity card.
In the middle of the tracked entity card is a legend indicating the styling of the layer.
Along the bottom of the tracked entity card from left to right are:
150
Using the Maps app Create a tracked entity layer
Remove layer will remove this layer from the current map.
◦
Create a tracked entity layer
To create an tracked entity layer, choose Tracked entities on the Add layer selection. This opens
the Tracked entity layer configuration dialog.
1. In the DATA tab:
◦ Select the Tracked Entity Type you want to show on the map.
◦ Select a Program where the tracked entities belong.
◦ Set the Program status to be Active or Completed.
◦ Set the Follow up status of the tracked entity for the given program.
2. In the Relationships tab
151
Caution
Displaying tracked entity relationships in Maps is an experimental feature
◦ If a Tracked Entity Type with has been selected, you can select the Display Tracked
Entity relationships checkbox
◦ Once checked, you can select the type of relationship to display on the map from the
dropdown list. Only relationships FROM the selected Tracked Entity type are
available.
152
◦ If no program is selected, you can set start and end dates when the tracked entities
were last updated.
◦ If a program is selected, you can set start and end dates for the program period.
153
◦ Select the organisation units you want to include in the layer. You have 3 selection
modes:
▪ Selected only: Include tracked entities belonging to selected org units only.
▪ Selected and below: Included tracked entities in and right below selected org
units.
▪ Selected and all below: Included tracked entities in and all below selected org
units.
154
Using the Maps app Modify a tracked entity layer
◦ Select a color for the tracked entities points and polygons.
◦ Select the point size (radius between 1 and 20) for the points.
◦ Select Show buffer to display visual buffer around each tracked entity. The buffer
distance in meters can be modified here.
◦ If a relationship type has been selected on the relationships tab you can select color,
point size, and line color for relationships and related tracked entities instances
6. Click ADD/UPDATE LAYER.
Modify a tracked entity layer
1. In the layer panel, click the edit (pencil) icon on the tracked entity layer card.
2. Modify the setting on the DATA, PERIOD, ORG UNIT and STYLE tabs as desired.
Clear a tracked entity layer
To clear a tracked entity layer from a map:
layer.
155
Using the Maps app Manage facility layers
Manage facility layers
The facility layer displays icons that represent types of facilities. Polygons do not show up on the
map, so make sure that you select an organisation unit level that has facilities.
A polygon is an enclosed area on a map representing a country, a district or a park.
Facility layers are represented by layer cards in the layer panel such as:
Along the top of the facilities card from left to right are:
• The Facilities title
• An arrow symbol to collapse and expand the facilities card
In the middle of the facilities card is a legend indicating the group set representation.
Along the bottom of the facilities card from left to right are:
156
Using the Maps app Create a facility layer
Create a facility layer
To create facility layer, choose Facilities on the **Add layer**selection. This opens the Facility
layer configuration dialog.
1. In the GROUP SET tab:
◦ Select a Group set from the list of organisation unit group sets defined for your
DHIS2 instance.
2. In the ORGANISATION UNITS tab
157
Using the Maps app Create a facility layer
◦ select the organisation unit level(s) and/or group(s) from the selection fields on the
right hand side.
either
158
Using the Maps app Create or modify a facility layer
◦ select any styling you wish to apply to the facilities.
▪ Show labels
Allows labels to be shown on the layer. Font size, weight and color can be
modified here.
▪ Show buffer
Allows a visual buffer to be displayed on the layer around each facility. The
radius of the buffer can be modified here.
4. Click ADD LAYER.
Create or modify a facility layer
1. In the layer panel, click the edit (pencil) icon on the facility layer card.
2. Modify the setting on the GROUP SET, ORGANISATION UNITS and STYLE tabs as
desired.
Filter values in a facility layer
Facility layers have a data table option that can be toggled on or off from the facility layer card.
159
Using the Maps app Search for a facility
The data table displays the data forming the facility layer.
descending.
◦ NAME
◦ ID
◦ TYPE
Note
Search for a facility
facilities.
Remove facility layer
To clear all data in a facility layer:
layer.
160
Using the Maps app Manage facilities in a layer
Manage facilities in a layer
You can have facilities in Facility, Boundary and Thematic layers.
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. This cannot be undone.
Swap longitude and latitude of a facility
1. Right-click a facility and click Swap longitude/latitude.
This is useful if a user inverted latitude and longitude coordinates when creating the
organisation unit.
Display facility information
You can view organisation unit information set by the administrator as follows:
View organisation unit information
Function Action
View information for the current period 1. Click a facility.
View information for a selected period 1. Right-click a facility and click Show information.
2. In the Infrastructural data section, select a period.
Note
You configure the displayed infrastructural data in the Sys

tem Settings app.
Manage boundary layers
The boundary layer displays the borders and locations of your organisation units. This layer is
particularly useful if you are offline and don't have access to background maps.
161
Using the Maps app Create a boundary layer
Boundary layers are represented by layer cards in the layer panel such as:
Along the top of the boundary card from left to right are:
• The Boundaries title
• An arrow symbol to collapse and expand the boundary card
Along the bottom of the boundary card from left to right are:
Create a boundary layer
To create boundary layer, choose Boundaries on the **Add layer**selection. This opens the
Boundary layer configuration dialog.
1. In the ORGANISATION UNITS tab
162
Using the Maps app Create a boundary layer
◦ select the organisation unit level(s) and/or group(s) from the selection fields on the
right hand side.
either
163
Using the Maps app Modify a boundary layer
◦ select any styling you wish to apply to the boundaries.
▪ Show labels
Allows labels to be shown on the layer. Font size and weight can be modified
here.
▪ Point radius
Sets the base radius when point type elements, such as facilities, are
presented on the boundary layer.
3. Click ADD LAYER.
Modify a boundary layer
1. In the layer panel, click the edit (pencil) icon on the boundary layer card.
2. Modify the setting on the ORGANISATION UNITS and STYLE tabs as desired.
Filter values in a boundary layer
Boundary layers have a data table option that can be toggled on or off from the boundary layer
card.
164
Using the Maps app Search for an organisational unit
The data table displays the data forming the boundary layer.
descending.
◦ NAME
◦ LEVEL
filter level by numbers and/or ranges, for example: 2,>3&\<8
◦ PARENT
filter by parent names containing the given text
◦ ID
◦ TYPE
Note
Search for an organisational unit
organisational units displayed in the boundary layer.
165
Using the Maps app Navigate between organisation hierarchies
Navigate between organisation hierarchies
You can modify the target of the boundary layer in the hierarchy without using the level/parent
user interface.
1. Right-click one of the boundaries.
2. Select Drill up one level or Drill down one level.
The drill down option is disabled if you are on the lowest level. Likewise the drill up option is
disabled from the highest level.
Remove boundary layer
To clear all data in a boundary layer:
layer.
Manage Earth Engine layer
The Google Earth Engine layer lets you display satellite imagery and geospatial datasets from
Google's vast catalog. These layers is useful in combination with thematic and event layers to
enhance analysis. The following layers are supported:
• Population density estimates with national totals adjusted to match UN population division
estimates. Population in 100 x 100 m grid cells (from 2010).
• Elevation above sea-level. You can adjust the min and max values so it better represents
the terrain in your region.
• Temperature: Land surface temperatures collected from satellite. Blank spots will appear in
areas with a persistent cloud cover.
166
Using the Maps app Create an Earth Engine layer
Precipitation collected from satellite and weather stations on the ground. The values are in
•
millimeters within 5 days periods. Updated monthly, during the 3 rd week of the following
month.
• Land cover: 17 distinct landcover types collected from satellites.
• Nighttime lights: Lights from cities, towns, and other sites with persistent lighting, including
gas flares (from 2013).
Create an Earth Engine layer
To create an Earth Engine layer, choose the desired layer from the **Add layer**selection. This
opens the layer configuration dialog.
1. In the STYLE tab
◦ Modify the parameters specific to the layer type.
◦ Adjust the legend range, steps and colors, as desired.
2. Click ADD LAYER.
Add external map layers
External map layers are represented as either:
• Basemaps
167
Using the Maps app Add external map layers
These are available in the basemap card in the layers panel and are selected as any other
basemap.
• Overlays
These are available in the Add layer selection. Unlike basemaps, overlays can be placed
above or below any other overlay layers.
Overlay layers are represented by additional layer cards in the layer panel such as:
Along the top of the overlay card from left to right are:
• The title of the external map layer
• An arrow symbol to collapse and expand the overlay card
Along the bottom of the overlay card from left to right are:
• A delete (trash can) icon to remove the layer from the current thematic map.
Here are some examples of external layers:
168
Using the Maps app File menu
File menu
Use the File menu to manage your maps. Several menu items will be disabled until you open or
save a map.
Saving your maps 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
layer configurations as a favorite.
Create a new map
Click File > New.
NB! This will clear the current map layers you have without saving.
169
Using the Maps app Open a new map
Open a new map
1. Click File > Open. A dialog box opens with a list of maps.
2. Find the favorite you want to open. You can either use \< and > or the search field to find a
saved map. The list is filtered on every character that you enter. You can filter the list by
selecting Show all, Created by me or Created by others.
3. Click the name of the map you want to open.
Save a map
When you have created a map it is convenient to save it for later use:
1. Click File > Save.
2. Enter a Name (required) and a Description (optional) the first time you save a map.
3. Click SAVE.
Save a copy of a map
1. Click File > Save as...
2. Enter a Name (required) and a Description (optional) for the map.
3. Click SAVE.
Rename a map
1. Click File > Rename.
2. Enter a new Name and/or Description for your map.
3. Click RENAME. The map is updated.
Translate a map
1. Click File > Translate.
2. Select the Locale (language) your translation.
3. Enter a translated Name and Description. The original text will show below the field.
4. Click SAVE.
Modify sharing settings for a map
After you have created a map and saved it, you can share the map with everyone or a user
group. To modify the sharing settings:
1. Click File > Share. The sharing settings dialog opens.
2. In the text box, search for the name of the user or group you want to share your favorite
with and select it.
The chosen user or 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.
170
Using the Maps app Get the link to a map
For each user group, choose an access setting. The options are:
4.
◦ None (for default groups only, as they cannot be removed)
◦ Can view
◦ Can edit and view
5. Click CLOSE to close the dialog.
Get the link to a map
1. Click File > Get link. A link dialog opens.
2. Copy the link.
Delete a map
1. Click File > Delete. A confirmation dialog is displayed.
2. Click DELETE to confirm that you want to delete the favorite. Your map is deleted and the
layers are cleared from the view.
Map interpretations
An interpretation is a description of a map at a given period. This information is visible in the

Dashboard app. Click Interpretations in the top right of the workspace to open the interpretations
panel. The button is only clickable if the map is saved.
2. Click Interpretations in the top right of the workspace to open the interpretations panel.
171
Using the Maps app Write interpretation for a map
Click an interpretation. Your map displays the data and the date based on when the
3. interpretation was created. To view other interpretations, click them.
Write interpretation for a map
To create an interpretation, you first need to create a map and save it. If you've shared your map
with other people, the interpretation you write is visible to those people.
2. Click Interpretations in the top right of the workspace to open the interpretations panel.
3. A text field will appear with a placeholder "Write an interpretation" for users that have read
access to the favorite.
5. Click SAVE if you want your interpretation to have the same sharing settings as the map.
Click SAVE & SHARE if you want to change the sharing settings (see below) for your
interpretation.
Change sharing settings for an interpretation
1. Click an interpretation (see how to view an interpretation above).
2. Click Share below the interpretation. The sharing settings dialog opens.
3. Search for and add a users and user groups that you want to share your map with.
4. Change sharing settings for the users you want to modify:
◦ No access: The public won't have access to the object. This setting is only
applicable to Public access.
5. Click CLOSE when sharing settings are updated.
Save a map as an image
You can download your map as an image by clicking on the Download button in the top menu
172
Using the Maps app Search for a location
Map download is not supported in Internet Explorer or Safari, we recommend to use Google
Chrome or Firefox.
1. Select if you want to include the map name or not. This option is only available if the map is
saved.
2. Select if you want to include the map legend. You can position the legend in one of the 4
corners of your map.
3. Click Download to download your map.
Search for a location
The place search function allows you to search for almost any location or address. This function is
useful in order to locate for example sites, facilities, villages or towns on the map.
173
Using the Maps app Measure distances and areas in a map
1. On the right side of the Maps 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.
Measure distances and areas in a map
1. In the upper left part of the map, put the cursor on the Measure distances and areas
(ruler) icon and click Create new measurement.
2. Add points to the map.
3. Click Finish measurement.
174
Using the Maps app Get the latitude and longitude at any location
Get the latitude and longitude at any location
Right-click a point on the map and select Show longitude/latitude. The values display in a pop-up
window.
See also
• Manage legends
175
Managing dashboards About dashboards
Managing dashboards
About 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.
A user or administrator could create a dashboard called "Antenatal care" which might contain all
relevant information on antenatal care. This dashboard could then be shared with the user group
called "ANC control", which might consist of all users of the ANC control program. All users within
this group would then be able to view the same dashboard.
Dashboard and control bar
Dashboards have a title, description, and any number of dashboard items. The dashboard items
can be of many different types, including charts, maps, reports, tables, resources, messages, and
text items. Above the dashboard is the control bar, which shows all your available dashboards,
including a dashboard search field, and a + button for creating a new dashboard.
The dashboard has two modes: view and edit/create. When you first log in to DHIS2, your most
recently used dashboard will be displayed in view mode, if you are on the same computer as you
were previously. If you are using a different computer, then the first starred dashboard will be
displayed. If there are no starred dashboards, then the first dashboard (alphabetically) will be
displayed. Starred dashboards always show first in the dashboard list.
The screenshot below shows a dashboard called "Antenatal Care", which has been populated
with charts and maps.
Searching in the list of dashboards
You can search for a specific dashboard using the search field in the upper left of the control bar
entitled “Search for a dashboard”. The search is case insensitive, and as you type, the list of
dashboards will filter down to those that match your search text.
176
Managing dashboards Customizing the height of the control bar
Customizing the height of the control bar
You can set a specific height for the dashboards control bar by down-clicking and dragging the
bottom edge of the control bar. When you finish dragging, the new height will be set. Clicking on
Show more will expand the control bar to its maximum height (10 "rows"). Clicking on Show less
will reset the height to your customized height.
Creating a dashboard
To create a new dashboard, click the green + button in the left corner of the control bar to go into
create mode. Add a title in the title field, and optionally a description in the description field.
Create mode:
Adding items to the dashboard
Add items to the dashboard by searching from the item selector in the upper right part of the
dashboard area. Available items include:
• Visualizations
• Maps
• Event reports
• Event charts
• Report
• Resources
• Apps
• Email
• Text boxes
177
Managing dashboards Spacer items
Spacer
•
The list of items in the drop-down initially displays 10 visualizations (charts and tables), and 5
from each of the other categories, based on the search text you enter. Email, text boxes and
spacer items are also found in the drop-down. To view more items, click on Show more, and the
list for that type will be extended to 25 items. If you still do not find the item you want, try typing a
more specific search text.
Once you select an item, it will be added to the top left position of the dashboard. The added
items can be moved using the mouse by down-clicking on the item and dragging it to the desired
position. It can also be resized with the mouse by down-clicking on the drag handle in the lower
right corner of the item and dragging to the desired size.
Spacer items
The dashboard is configured with the "anti-gravity" setting for positioning items. This means that
items will "rise" upwards until they run into another item. In order to force empty vertical space
between items (like an empty row), you can add spacer items to the dashboard. They are only
visible in edit/create mode. In view mode, they are not displayed, but take up the defined space.
Spacer in edit/create mode:
178
Managing dashboards Spacer items
Spacer in view mode:
179
Managing dashboards Removing items
Removing items
Remove items by clicking on the red trash can at the upper right of the item. Be aware that
because of the "anti-gravity" setting in the dashboard, when you remove an item, the items that
are positioned below the removed item will "rise" upwards.
Saving the dashboard
When creating or editing a dashboard, changes are only saved when you click Save changes
button in the dashboard edit bar at the top of the page. If you don't want to save your changes,
click the Exit without saving button to the upper right. You will then be returned to view mode
with the dashboard you were previously viewing.
Editing an existing dashboard
If you have access rights to edit the currently active dashboard, there will be an Edit button to the
right of the dashboard title in view mode. Click on this button to enter edit mode.
Refer to the above section about creating dashboards for information on adding and removing
items to the dashboard.
Translating dashboard title and description
You can add translations for dashboard title and description while in edit mode. The dialog
provides a list of languages to translate to, and shows the original dashboard title underneath the
name input field.
180
Managing dashboards Deleting a dashboard
1. Click on the TRANSLATE button located above the dashboard
2. Select the language you wish to add a translation for.
3. Add the title and/or description, and click SAVE
Deleting a dashboard
If you have access to delete the dashboard, then there will be a Delete button located above the
dashboard, when in edit mode. A confirmation dialog will first be displayed to confirm that you
want to delete the dashboard.
Viewing a dashboard
When in view mode, you can toggle showing the description, star a dashboard, apply filters, and
share the dashboard with other users and groups.
To view the description, click on the i button to the right of the title
Starred dashboards
Your starred dashboards are listed first in the list of dashboards. To star a dashboard, click on the
star button to the right of the title. When the star is “filled”, that means the dashboard is starred.
Starring a dashboard only applies to you, not other users.
Filtering a dashboard
Multiple filters can be applied to a dashboard for changing the data displayed in the various
dashboard items. The filters are applied to each dashboard item in the same way: each added
filter overrides the original value for that dimension in the original chart, table or map
181
Managing dashboards Filtering a dashboard
(visualization). It is possible to filter on Organisation Units, Periods and other dynamic dimensions
depending on the DHIS2 instance.
To add a filter, click on the Add Filter button and choose the dimension:
Adding a filter
A dialog opens where the filter selection can be made.
182
Managing dashboards Filtering a dashboard
Org Unit filter selection
Click on Confirm in the dialog to apply the filter to the current dashboard.
Filters are not stored, so when switching to a different dashboard they are lost. Filter badges
appear above the dashboard items to indicate that what is shown in the dashboard items is not
the original visualization, but a manipulated one where the filters override the stored dimensions'
values.
Current filters displayed as badges above the dashboard
Filter badges can be clicked for opening the filter selection dialogs thus allowing for filter editing. A
filter can be removed by clicking on the Remove button in the badge. Whenever a filter is added,
edited or removed, the dashboard items reload to show the updated data. Filter badges are
always visible at the top of the page when scrolling the dashboard content.
183
Managing dashboards Dashboard items with charts, pivot tables and maps
Dashboard items with charts, pivot tables and maps
Switching between visualizations
Dashboard items showing charts, pivot tables and maps can be toggled between these
visualizations. Click on the item menu button in the upper right corner of the item and choose the
desired view:
Interpretations
You can write interpretations for the chart, pivot table, map, event report, and event chart items.
From the dashboard item menu, click on Show interpretations and details:
and the item will be expanded vertically underneath to show the description, interpretations and
replies. You can like an interpretation, reply to an interpretation, and add your own interpretation.
You can edit, share or delete your own interpretations and replies, and if you have moderator
access, you can delete others’ interpretations.
It is possible to format the description field, and interpretations with bold, italic by using the
Markdown style markers * and _ for bold and italic respectively. The text field for writing new
interpretations has a toolbar for adding rich text. Keyboard shortcuts are also available: Ctrl/Cmd
+ B and Ctrl/Cmd + I. A limited set of smilies is supported and can be used by typing one of the
Interpretations are sorted in descending order by date, with the most recent shown on top.
Interpretation replies are sorted in ascending order by date, with the oldest shown on top.
184
Managing dashboards Sharing a dashboard
Sharing a dashboard
In order to share a dashboard with user groups, click on the SHARE button to the right of the
dashboard title to display the dashboard sharing settings options. To share the dashboard with
specific users or user groups, type in the name in the input field to add them to the dashboard
sharing settings
185
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
through the API. 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. For more information, see Viewing analytical resource
representations in the developer guide.
• 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 that 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
186
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.
You can provide users with the url of the dashboard, allowing them to navigate directly to the
dashboard. To get the dashboard url, just access the dashboard in view mode, and copy the
browser url. For example, the url to the Antenatal Care dashboard in play.dhis2.org/demo is:
https://play.dhis2.org/demo/dhis-web-dashboard/#/nghVC4wtyzi
187
Using the Event Reports app About the Event Reports app
Using the Event Reports app

About the Event Reports app
With the **Event Report**s app you can analyse events in two types of reports:
• Aggregated event reports: Pivot table-style analysis with aggregated numbers of events
By selecting Aggregated values from the top-left menu you can use the Event Reports
app to create pivot tables with aggregated numbers of events. An event report is always
based on a program. You can do analysis based on a range of dimensions. Each
dimension can have a corresponding filter. Dimensions can be selected from the left-side
menu. Similar to the pivot tables app, aggregated event reports may be limited by the
amount of RAM accessible by the browser. If your requested table exceeds a set size, you
will recieve a warning prompt asking whether or not you want to continue.
• Individual event reports: Lists of events
By selecting Events from the top-left menu you can use the Event Reports app to make
searches or queries for events based on a flexible set of criteria. The report will be
displayed as a table with one row per event. Each dimension can be used as a column in
the table or as a filter. Each dimension can have a criteria (filter). Data elements of type
option set allows for "in" criteria, where multiple options can be selected. Numeric values
can be compared to filter values using greater than, equal or less than operators.
Create an event report
1. Open the Event Reports app.
2. Select Aggregated values or Events.
3. In the menu to the left, select the meta data you want to analyse.
4. Click Layout and arrange the dimensions.
188
Using the Event Reports app Select dimension items
5. Click Update.
An event report is always based on a program and you can do analysis based on a range of
dimensions. For programs with category combinations, you can use program categories and
category option group sets as dimensions for tables and charts. Each dimension item can have a
corresponding filter.
1. Select data elements:
1. Click Data.
2. Select a program and a program stage.
The data elements associated with the selected program are listed under Available.
Each data element acts as a dimension.
3. Select the data elements you need by double-clicking their names.
Data elements can be filtered by type (Data elements, Program attributes, Program
indicators) and are prefixed to make them easily recognizable.
After selecting a data element, it is visible under Selected data items.
4. (Optional) For each data element, specify a filter with operators such as "greater
than", "in" or "equal" together with a filter value.
2. Select periods.
1. Click Periods.
2. Select one or several periods.
You have three period options: relative periods, fixed periods and start/end dates.
You can combine fixed periods and relative periods in the same chart. You cannot
combine fixed periods and relative periods with start/end dates in the same chart.
Overlapping periods are filtered so that they only appear once.
▪ Fixed periods: In the Select period type box, select a period type. You can
select any number of fixed periods from any period type. Fixed periods can for
example be "January 2014".
▪ 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. Relative periods has the advantage
that it keeps the data in the report up to date as time goes.
▪ Start/end dates: In the list under the Periods tab, select Start/end dates. This
period type lets you specify flexible dates for the time span in the report.
3. Select organisation units.
1. Click Organisation units.
2. Click the gearbox icon.
189
Using the Event Reports app Select series, category and filter
Select a Selection mode and an organisation unit.

3.
There are three different selection modes:
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.
You can define which data dimension you want to appear as columns, rows and filters in the pivot
table. Each data element appears as individual dimensions and can be placed on any of the axes.
Note
Data elements of continuous value types (real numbers/decimal
numbers) can only be used as filters, and will automatically be
positioned as filters in the layout dialog. The reason for this is that
190
Using the Event Reports app Change the display of your table
continuous number cannot be grouped into sensible ranges and used

on columns and rows.
1. Click Layout.
2. Drag and drop the dimensions to the appropriate space.
3. Click Update.
Change the display of your table
You can customize the display of an event report.
1. Click Options.
2. Set the options as required. Available options are different between aggregated event
reports and individual event reports.
Event reports options
Option Description Available for report type
Data Show column Displays totals at the end of Aggregated event

totals each column in the pivot table. report
Show column Displays sub-totals for each Aggregated event

sub-totals column in the pivot table. report
Show row totals Displays totals at the end of Aggregated event

each row in the pivot table. report
Show row sub- Displays sub-totals for each Aggregated event

totals row in the pivot table. report
Displays labels for

Show dimension Aggregated event
dimensions.
labels report
Hide empty rows Hides empty rows in the pivot Aggregated event
table. report
Hide n/a data Hides data tagged as N/A from Aggregated event
the chart. report
Include only Includes only completed Aggregated event

completed events events in the aggregation report
process. This is useful when
Individual event
you want for example to
report
exclude partial events in
indicator calculations.
191
Using the Event Reports app Change the display of your table
Option Description Available for report type
Limit Sets a limit of the maximum Aggregated event

number of rows that you can report
display in the table, combined
with a setting for showing top
or bottom values.
Output type Defines the output type. The Aggregated event

output types are Event, Enroll report
ment andTracked entity
instance.
Program status Filters data based on the Aggregated event

program status: All, Active, C report
ompleted or Cancelled.
Event status Filters data based on the Aggregated event

event status: All, Active, Com report
pleted, Scheduled, Overdue
or Skipped.
Organisation
Show hierarchy Includes the names of all Aggregated event
units
parents of each organisation report
unit in labels.
Style Display density Controls the size of the cells in Aggregated event
the table. You can set it to Co report
mfortable, Normal or Compa
Individual event
ct.
report
Compact is useful when you
want to fit large tables into the
browser screen.
Font size Controls the size of the table Aggregated event

text font. You can set it to Larg report
e, Normal or Small.
Individual event
report
Digit group Controls which character to Aggregated event

separator separate groups of digits or report
"thousands". You can set it to
Individual event
Comma, Space or None.
report
3. Click Update.
192
Using the Event Reports app Download chart data source
You can download the data source behind an event report in HTML, JSON, XML, Microsoft Excel
or CSV formats.
1. Click Download.
Available formats
Format Description
HTML Creates HTML table based on selected meta data
JSON Downloads data values in JSON format based on selected meta data
XML Downloads data values in XML format based on selected meta data
Microsoft Excel Downloads data values in Microsoft Excel format based on selected
meta data
CSV Downloads data values in CSV format based on selected meta data
Manage favorites
Open a favorite
Save a favorite
3. Click Save.
Rename a favorite
193
Using the Event Reports app Write an interpretation for a favorite
Click Update.
3.
those people.
◦ None: The public won't have access to the object. This setting is only applicable to
Public access.
5. Click Share.
favorite.
1. Open a favorite.
194
Using the Event Reports app Delete a favorite
Delete a favorite
2. Click OK.
Visualize an event report as a chart
When you have made an event report you can open it as a chart:
Click Chart > Open this chart as table.
195
Using the Event Visualizer app About the Event Visualizer app
Using the Event Visualizer app

About the Event Visualizer app
With the Event Visualizer app, you can create charts based on event data.
Create a chart
1. \<Open the Event Visualizer app and select a chart type.
2. In the menu to the left, select the meta data you want to analyse.
3. Click Layout and arrange the dimensions.
4. Click Update.
Select a chart type
The Event Visualizer app has eight different chart types, each with different characteristics. To
select a chart type:
1. In Chart type, click the chart type you need.
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.
196
Using the Event Visualizer app Select dimension items
Chart type Description
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.
2. Click Update.
An event chart is always based on a program and you can do analysis based on a range of
dimensions. For programs with category combinations, you can use program categories and
category option group sets as dimensions for tables and charts. Each dimension item can have a
corresponding filter. You select dimension items from the left-side menu.
1. Select data elements:
1. Click Data.
2. Select a program and a program stage.
The data elements associated with the selected program are listed under Available.
Each data element acts as a dimension.
3. Select the data elements you need by double-clicking their names.
197
Using the Event Visualizer app Select dimension items
Data elements can be filtered by type (Data elements, Program attributes, Program
indicators) and are prefixed to make them easily recognizable.
After selecting a data element, it is visible under Selected data items.
4. (Optional) For each data element, specify a filter with operators such as "greater
than", "in" or "equal" together with a filter value.
2. Select periods.
1. Click Periods.
2. Select one or several periods.
You have three period options: relative periods, fixed periods and start/end dates.
You can combine fixed periods and relative periods in the same chart. You cannot
combine fixed periods and relative periods with start/end dates in the same chart.
Overlapping periods are filtered so that they only appear once.
▪ Fixed periods: In the Select period type box, select a period type. You can
select any number of fixed periods from any period type. Fixed periods can for
example be "January 2014".
▪ 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. Relative periods has the advantage
that it keeps the data in the report up to date as time goes.
▪ Start/end dates: In the list under the Periods tab, select Start/end dates. This
period type lets you specify flexible dates for the time span in the report.
3. 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:
Selection modes
198
Using the Event Visualizer app Select series, category and filter
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.
You can define which data dimension you want to appear as series, category and filter. Each data
element appears as individual dimensions and can be placed on any of the axes. Series and
category panels can only have one dimension at the time.
Note
Data elements of continuous value types (real numbers/decimal
numbers) can only be used as filters, and will automatically be
positioned as filters in the layout dialog. The reason for this is that
continuous number cannot be grouped into sensible ranges and used
on columns and rows.
1. Click Layout.
199
Using the Event Visualizer app Change the display of your chart
Drag and drop the dimensions to the appropriate space. Only one dimension can be in
2. each section.
3. Click Update.
Change the display of your chart
You can customize the display of an event report.
1. Click Options.
2. Set the options as required.
Chart options
Option Description
Data Show values Displays values as numbers on top of

each series.
Use 100% stacked Displays 100 % stacked values in

values column charts.
Use cumulative values Displays cumulative values in line

charts.
Hide n/a data Hides data tagged as N/A from the chart.
Include only completed Includes only completed events in the

events aggregation process. This is useful
when you want for example to exclude
partial events in indicator calculations.
Hide empty categories Hides the category items with no data

from the chart.
None: doesn't hide any of the empty

categories
Before first: hides missing values only

before the first value
After last: hides missing values only

after the last value
Before first and after last: hides

missing values only before the first value
and after the last value
All: hides all missing values
This is useful for example when you

create column and bar charts.
200
Using the Event Visualizer app Change the display of your chart
Option Description
Trend line 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 line value/title Displays a horizontal line and title

(optional) at the given domain value.
Useful for example when you want to
compare your performance to the
current target.
Base line value/title Displays a horizontal line and title

(optional) at the given domain value.
Useful for example when you want to
visualize how your performance has
evolved since the beginning of a
process.
Sort order Allows you to sort the values on your

chart from either low to high or high to
low.
Output type Defines the output type. The output

types are Event, Enrollment andTrack
ed entity instance.
Program status Filters data based on the program

status: All, Active, Completed or Canc
elled.
Event status Filters data based on the event status: Al

l, Active, Completed, Scheduled, Over
due or Skipped.
Axes 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.
201
Using the Event Visualizer app Download a chart as an image or a PDF
Option Description
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.
General Hide chart legend Hides the legend and leaves more room
for the chart itself.
Hide chart title Hides the title (default or custom) of your

chart.
Chart title Type a title here to display a custom title

above the chart. If you don't enter a title,
the default title is displayed.
Hide chart subtitle Hides the subtitle of your chart.
Chart subtitle Type a subtitle here to display a custom

subtitle above the chart but below the
title. If you don't enter a subtitle, no
subtitle is displayed in the chart.
3. Click Update.
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 PNG (.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.
You can download the data source behind a chart in HTML, JSON, XML, Microsoft Excel or CSV
formats. 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
202
Using the Event Visualizer app Manage favorites
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.
Available formats
Format Description
HTML Creates HTML table based on selected meta data
JSON Downloads data values in JSON format based on selected meta data
XML Downloads data values in XML format based on selected meta data
Microsoft Excel Downloads data values in Microsoft Excel format based on selected
meta data
CSV Downloads data values in CSV format based on selected meta data
Manage favorites
Open a favorite
Save a favorite
3. Click Save.
Rename a favorite
203
Using the Event Visualizer app Write an interpretation for a favorite
Click Update.
3.
those people.
◦ None: The public won't have access to the object. This setting is only applicable to
Public access.
5. Click Share.
favorite.
1. Open a favorite.
204
Using the Event Visualizer app Delete a favorite
Delete a favorite
2. Click OK.
Visualize a chart as a pivot table
When you have made a chart you can open it as a pivot table:
Click Chart > Open this chart as table.
205
Messaging About messages and feedback messages
Messaging
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
called the feedback recipient group. If you are a member of this user group, you have access to
feedback handling tools. You can, for example, set the status of an incoming feedback to
"Pending" while you are waiting for information.
In addition to the user-to-user and feedback messages, depending on your configuration the
system will also send you system-generated messages. These messages could be triggered by
different events, including system or background job failures and validation analysis results.
Feedback handling tools are also available for validation results and the priority will be set to the
importance of the validation rule violated.
To visit the app click message icon in header bar or find the Messaging app in the app search
box.
Note
Messages and feedback messages are not sent to users' e-mail
addresses, the messages only appear within DHIS2.
With 2.30 we introduced a new messaging app which offers a richer
messaging experience. Specifically:
• Switch between list view and compact view by clicking the icon in
the top right corner.
◦ The list view is simplistic and gives a good overview of all
messages and is especially suited for feedback and
validation messages.
◦ The compact view is a modern way of view messages where
the user has more information in one view, hence viewing
and replying several messages is easier.
206
Messaging Create a message
The first screenshot in this section displays list view, while the
screenshot in section Read a message displays the compact
view.
• A new search field is added which enables the user to search for
messages. The search filters messages on different message
attributes; subject, text and senders. This implies that you are
able to narrow down the message conversation list by entering a
search.
• A auto refresh feature is added so that the app fetches new
messages at a set interval, every 5 minutes. This feature is
disabled by default.
• For every message conversation you are able to add participants
to the conversation. This is very useful if you want input on that
particular conversation or if someone should also see the
information. It is not possible to delete participants from a
conversation.
Create a message
1. Click Compose.
2. Define who you want to receive the message. You can send a message to organisation
units, users and user groups.
◦ In the To field you can search for organisation units, users and user groups and
select the wished recipients.
3. Type a subject and a message.
4. Click Send.
207
Messaging Read a message
Read a message
1. Select the appropriate message type to the left.
2. Click a message.
If the message is part of a conversation, you will see all messages in this conversation.
Create a feedback message
1. Follow the steps as for creating a message, only selecting Feedback message instead of
entering recipients.
2. The message will be created as a feedback message and will appear in all of the specified
users' Ticket folder.
Attachments
With 2.31 we introduced attachments to messages. When creating or replying to a message

conversation you have the possibility to add attachments. Currently there are no limitations to
type or size of the file.
Manage validation and feedback messages
Note
You will only see feedback messages and have access to the extended
handling tools if you are a member of the user group that is set up to
handle feedback messages.
With the new app you manage extended tools for tickets and validation
messages through the icon menu which appears when viewing a
message or checking of messages in the conversation list.
All messages selected
208
Messaging All messages selected and extended choice picker selected
All Messages Selected
All messages selected and extended choice picker selected
All messages selected and extended choice picker selected
You will receive feedback messages to your Ticket folder and validation messages to your
Validation folder. For feedback and validation messages you have the following options in
addition to the messages options:
Feedback handling tools
209
Messaging Configure feedback message function
Function Description
Priority You can mark a feedback/validation 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.
Status All feedback/validation messages get the status Op

en when created.
To keep track of existing feedback messages, you

can change the status to Pending, Invalid or
Solved.
You can filter feedback/validation messages based

on their status with the two drop down menus in the
internal header bar.
Assigned to You can assign a feedback message to any

member of the user group that is set up to handle
feedback messages.
You can assign a validation message to any user in

the system.
- means that you haven't assigned a user to the

feedback message.
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.
Configure feedback message function
To configure the feedback message function, you must:
1. Create a user group (for example "Feedback message recipients") that contains all the
users who should receive feedback messages.
2. Open the System Settings app and click General > Feedback recipients and select the
user group you created in the previous step.
210
Set user account preferences Configure feedback message function
Set user account preferences

In User settings, you can change the display language of DHIS2 and the language of the
database. The database language is the translated content of the metadata, such as data
elements and indicators. You can also choose a display style, and enable or disable SMS and
email notifications. If you wish to, you can choose to display a short name, such as "Joe" in the
analysis modules, rather than your full name.
In User profile, you can add personal information to your profile such as your email address,
mobile phone number, date of birth, profile picture and more. When you send messages, the
person receiving the message can see these profile details. You can also provide account names
for various direct messaging services, which will be used by the system.
In Account settings, you can reset your password and setup 2-Factor authentication. Setting up
2-Factor authentication will require you to download the Google Authenticator app on you mobile
device.
In the View full profile section, you find a summary of your profile details. This section includes a
few fields that you cannot edit yourself, such as user roles and user organisation units.
In the About DHIS2 section, you find a list of details about the DHIS2 instance.
211
Configure metadata About the Maintenance app
Configure metadata
About the Maintenance app
In the Maintenance app you configure all the metadata objects you need to collect and analyze
data:
• Categories
• Data elements
• Data sets and data entry forms
• Indicators
• Organisation units
• Program metadata: tracked entity, tracked entity attribute and relationship type
• Validation rules
• Attributes
• Constants
• Options sets
• Legends
• Predictors
• Push reports
• External map layers
Note
The functions you have access to depend on your user role's access
permissions.
Navigating metadata objects
Metadata objects are presented in a list with predefined columns that are relevant for each object.
You may customize which columns are shown in the list for the current object. These
customizations are per user, and therefore will not affect other users. Note that these changes do
not edit any metadata, just how the list is presented.
212
Configure metadata Navigating metadata objects
Managing visible columns
1. Click the
settings-icon
-icon to the top right of the list of objects you want to configure.
2. A dropdown-menu will appear, select Manage columns.
3. A dialog will appear, with the default columns selected.
4. Click any column-name in the list of Available columns to add them to the list of selected
columns.
5. You may reorder the selected columns by drag-and-dropping the
reorder-icon
-icon.
6. You may also remove any column from the view by clicking the X-icon next to the name.
7. Click Save once you are satisified with your changes.
213
Configure metadata Manage categories
You may easily reset to the default values by clicking the Reset to default button.
Download metadata
You can download the metadata for the object you are currently viewing. The metadata download
will respect any filters you have active for the list.
1. Click the
settings-icon
-icon to the top right of the list of objects you want to configure.
2. A dropdown-menu will appear, select Download.
3. A dialog will appear, where you can select the desired format and compression.
4. With sharing can be selected to include sharing-data for the metadata.
Manage categories
About categories
Categories are typically a concept, for example "Gender", "Age" or "Disease Status". Data
elements such as "Number of cases of confirmed malaria" are often broken into smaller
component parts to determine, for example, the number of confirmed malaria cases of particular
age groups.
Use categories to disaggregate data elements into individual components. You can also use
categories to assign metadata attributes to all data recorded in a specific dataset, such as
"Implementing partner" or "Funding agency."
Create three categories: "Under 1", "1-5" and "Over 5". Assign them as categories to the data
element. This creates three separate fields for this data in the data entry forms:
• Number of confirmed malaria cases (Under 1)
• Number of confirmed malaria cases (1-5)
• Number of confirmed malaria cases (Over 5)
Without categories, you would have had to create each of the data elements listed above
separately.
In the Maintenance app, you manage the following and category objects:
Category objects in the Maintenance app
Object type Available functions
Category option Create, edit, clone, share, delete, show details and
translate
Category Create, edit, clone, share, delete, show details and

translate
214
Configure metadata Workflow
Category combination Create, edit, clone, share, delete, show details and
translate
Category option combination Edit and show details
Category option group Create, edit, clone, share, delete, show details and
translate
Category option group set Create, edit, clone, share, delete, show details and
translate
Workflow
1. Create all category options.
2. Create categories composed by the multiple category options you've created.
3. Create category combinations composed by either one or multiple categories.
4. Create data elements and assign them to a category combination.
Create or edit a category option
When possible, recycle category options. For instance, there might be two categories which might
share a particular category option (for example \<1 year of age). When creating the categories,
this category option could be reused. This is important if particular category options (or category
option combinations) that need to be analyzed together.
1. Open the Maintenance app and click Category > Category option.
2. Click the add button.
3. Fill in the form:
1. Name
2. Start date
3. End date
4. Select organisation units and assign them.
Tip
You can automatically select all organisation units that belong to an
organisation unit level or organisation unit group, for example "Chiefdom" or
"Urban. To do this:
Select an Organisation unit level or Organisation unit group and click
Select.
5. Click Save.
215
Configure metadata Create or edit a category
Create or edit a category
When you have created all category options for a particular category, you can create that
category.
1. Open the Maintenance app and click Category > Category.
1. Name
2. Code
3. Data dimension type
A category either be of type "Disaggregation" or "Attribute". For disaggregation of

data elements, you select Disaggregation. The data dimension type "Attribute"
allows the category to be used to assign a combination of categories to data
recorded through a data set.
4. Data dimension
If you select Data dimension, the category will be available to the analytics as
another dimension, in addition to the standard dimensions of "Period" and
"Organisation unit".
4. Select category options and assign them.
5. Click Save.
Create or edit a category combination
Category combinations lets you combine multiple categories into a related set.
You can disaggregate the data element "Number of new HIV infections" into the following
categories:
• HIV Service: "Other", "PMTCT", "TB"
• Gender: "Male", "Female"
In this example, there are two levels of disaggregation that consist of two separate data element
categories. Each data element category consist of several data element category options.
In DHIS2, different data elements are disaggregated according to a common set of categories. By
combining these different categories into a category combination and assigning these
combinations to data elements, you can apply the appropriate disaggregation levels quickly to a
large number of data elements.
1. Open the Maintenance app and click Category > Category combination.
1. Name
2. Code
216
Configure metadata Create or edit a category option group
Data dimension type

3.
4. Skip category total in reports
4. Select categories and assign them.
5. Click Save.
Create or edit a category option group
You can group and classify category options by using category option groups. The main purpose
of the category option group set is to add more dimensionality to your captured data for analysis
in for example the Pivot table or Data Visualizer apps.
Consider a system where data is collected by "projects", and projects are modelled as category
options. The system must be able to analyse data based on which donor supports the project. In
this case, create a category option group set called "Donor". Each donor can be created as a
category option group, where each category option / project is put in the appropriate group. In
the data analysis applications, the "Donor" group set will appear as a data dimension, while each
donor appear as dimension items, ready to be included in reports.
To create a category option group:
1. Open the Maintenance app and click Category > Category option group.
1. Name
2. Short name: Define a short name for the data element.
3. Code
4. Select Category options and assign them.
5. Click Save.
Create or edit a category option group set
You can group category option groups in category option group sets. The main purpose of the
category option group set is to add more dimensionality to your captured data for analysis in for
example the Pivot table or Data Visualizer apps.
1. Open the Maintenance app and click Category > Category option group set.
1. Name
2. Description
3. Data dimension
4. Select Category option groups and assign them.
217
Configure metadata Use category combinations for data sets
Click Save.
5.
Use category combinations for data sets
When categories and category combinations have the data dimension type "Attribute", they can
apply a common set of attributes to a related set of data values contained in a data set. When
category combinations are used as a attribute, they serve as another dimension (similar to
"Period" and "Organisation unit") which you can use in your analysis.
Suppose that a NGO is providing ART services in a given facility. They would need to report each
month on the "ART monthly summary", which would contain a number of data elements. The NGO
and project could potentially change over time. In order to attribute data to a given NGO and
project at any point in time, you need to record this information with each data value at the time of
data entry.
1. Create two categories with the data dimension type "Attribute": "Implementing partner" and
"Projects".
2. Create a category combination with the data dimension type "Attribute": "Implementing
partners and projects".
3. Assign the categories you've created to the category combination.
4. Create a data set called "ART monthly summary" and select the "Implementing partners
and projects" category combination.
When you enter data in the Data entry app, you can select an "Implementing partner" and a
"Project". Each recorded data value, is assigned a specific combination of these categories as an
attribute. These attributes (when specified as a dimension) can be used in the analysis
applications similar to other dimensions, for example the period and organisation unit.
Assign a code to a category option combination
You can assign a code to category option combinations. This makes data exchange between
DHIS2 and external systems easier. The system creates the category option combinations
automatically.
1. Open the Maintenance app and click Category > Category option combination.
218
Configure metadata Clone metadata objects
In the list, find the object you want to modify.

2.
3. Click the options menu and select Edit.
4. Enter a code.
5. Click Save.
Cloning a data element or other objects can save time when you create many similar objects.
1. Open the Maintenance app and find the type of metadata object you want to clone.
2. In the object list, click the options menu and select Clone.
3. Modify the options you want.
4. Click Save.
You can assign different sharing settings to metadata objects, for example organisation units and
tracked entity attributes. These sharing settings control which users and users groups that can
view or edit a metadata object.
Some metadata objects also allows you to change the sharing setting of data entry for the object.
These additional settings control who can view or enter data in form fields using the metadata.
Note
The default setting is that everyone (Public access) can find, view and
edit metadata objects.
1. Open the Maintenance app and find the type of metadata object you want to modify.
2. In the object list, click the context menu and select Sharing settings.
3. (Optional) Add users or user groups: search for a user or a user group and select it. The
user or user group is added to the list.
4. Change sharing settings for the access groups you want to modify.
◦ Can edit and view: The access group can view and edit the object.
◦ Can view only: The access group can view the object.
◦ No access (only applicable to Public access): The public won't have access to the
object.
5. Change data sharing settings for the access groups you want to modify.
◦ Can capture data: The access group can view and capture data for the object.
◦ Can view data: The access group can view data for the object.
◦ No access: The access group won't have access to data for the object.
6. Click Close.
219
Configure metadata Delete metadata objects
Note
You can only delete a data element and other data element objects if no
data is associated to the data element itself.
Warning
Any data set that you delete from the system is irrevocably lost. All data
entry forms, and section forms which may have been developed will also
be removed. Make sure that you have made a backup of your database
before deleting any data set in case you need to restore it at some point
in time.
1. Open the Maintenance app and find the type of metadata object you want to delete.
2. In the object list, click the options menu and select Delete.
3. Click Confirm.
1. Open the Maintenance app and find the type of metadata object you want to view.
2. In the object list, click the options menu and select Show details.
DHIS2 provides functionality for translations of database content, for example data elements,
data element groups, indicators, indicator groups or organisation units. You can translate these
elements to any number of locales. A locale represents a specific geographical, political, or
cultural region.
Tip
To activate a translation, open the System Settings app, click > >
Appearance and select a language.
1. Open the Maintenance app and find the type of metadata object you want to translate.
2. In the object list, click the options menu and select Translate.
Tip
If you want to translate an organisation unit level, click directly on the
Translate icon next to each list item.
3. Select a locale.
4. Type a Name, Short name and Description.
5. Click Save.
220
Configure metadata Manage data elements
Manage data elements
About data elements
Data elements are the base of DHIS2. Data elements define what is actually recorded in the
system, for example number of immunisations or number of cases of malaria.
Data elements such as "Number of cases of confirmed malaria" are often broken into smaller
component parts to determine, for example, the number of confirmed malaria cases of particular
age groups.
In the Maintenance app, you manage the following data elements objects:
Data element objects in the Maintenance app
Data element Create, edit, clone, share, delete, show details and
translate
Data element group Create, edit, clone, share, delete, show details and
translate
Data element group set Create, edit, clone, share, delete, show details and
translate
Workflow
1. Create all category options.
2. Create categories composed by the multiple category options you've created.
3. Create category combinations composed by either one or multiple categories.
4. Create data elements and assign them to a category combination.
221
Configure metadata Create or edit a data element
Create or edit a data element
1. Open the Maintenance app and click Data elements > Data element.
3. In the Name field, define the precise name of the data element.
Each data element must have a unique name.
4. In the Short name field, define a short name for the data element.
Typically, the short name is an abbreviation of the full data element name. This attribute is
often used in reports to display the name of the data element, where space is limited.
5. (Optional) In the Code field, assign a code.
In many countries data elements are assigned a code.
6. (Optional) In the Color field, assign a color which will be used for this data element in the
data capture apps.
7. (Optional) In the Icon field, assign an icon which will be used for this data element in the
data capture apps.
8. In the Description field, type a description of the data element. Be as precise as possible
and include complete information about how the data element is measured and what its
purpose is.
9. (Optional) In the Field mask field, you may type a template that's used to provide hints for
correct formatting of the data element.
NOTE
222
So far this is only implemented in the DHIS2 Android Capture app; not in the
Capture and Tracker Capture web apps.
The following are special characters that can be used in the mask. The special characters
match exactly one character of the given type.
Character Match
\d digit
\x lower case letter
\X capital letter
\w any alphanumeric character
For example, the pattern can be used to show hyphens as needed in the input field of the
data element. E.g "\d\d\d-\d\d\d-\d\d\d, would show a hyphen for every third digit.
10. In the Form name field, type an alternative name of the data element. This name can be
used in either section or automatic data entry forms. The form name is applied
automatically.
11. In the Domain type field, select whether the data element is an aggregate or tracker type
of data element.
12. In the Value type field, select the type of data that the data element will record.
Value types
Value type Description
Age -
Coordinate A point coordinate specified as longitude

and latitude in decimal degrees. All
coordinate should be specified in the format
"-19.23 , 56.42" with a comma separating the
longitude and latitude.
Date Dates rendered as calendar widget in data

entry.
Date & time Is a combination of the DATE and TIME data

elements.
Email Email.
File A file resource where you can store external

files, for example documents and photos.
223
Image A file resource where you can store photos.
Unlike the FILE data element, the IMAGE

data element can display the uploaded
image directly in forms.
Integer Any whole number (positive and negative),

including zero.
Letter A single letter.
Long text Textual value. Renders as text area with no

length constraint in forms.
Negative integer Any whole number less than (but not

including) zero.
Number Any real numeric value with a single decimal

point. Thousands separators and scientific
notation is not supported.
Percentage Whole numbers inclusive between 0 and

100.
Phone number Phone number.
Positive integer Any whole number greater than (but not

including) zero.
Positive of zero integer Any positive whole number, including zero.
Organisation unit Organisation units rendered as a hierarchy

tree widget.
If the user has assigned "search

organisation units", these will be displayed
instead of the assigned organisation units.
Unit interval Any real number greater than or equal to 0

and less than or equal to 1.
Text Textual value. The maximum number of

allowed characters per value is 50,000.
224
Time Time is stored in HH:mm format.
HH is a number between 0 and 23
mm is a number between 00 and 59
Tracker associate Tracked entity instance. Rendered as dialog

with a list of tracked entity instances and a
search field.
Username DHIS2 user. Rendered as a dialog with a list

of users and a search field. The user will
need the "View User" authority to be able to
utilise this data type
Yes/No Boolean values, renders as drop-down lists

in data entry.
Yes only True values, renders as check-boxes in data

entry.
13. In the Aggregation type field, select the default aggregation operation that will be used on
the data element.
Most data elements should have the Sum operator. This includes all data elements which
should be added together. Other data elements, such as staffing levels, should be set to
use the Average operator, when values along the time dimension should not be added
together, but rather averaged.
Aggregation operators
Aggregation operator Description
Average Average the values in both the period as and

the organisation unit dimensions.
Average (sum in organisation unit hierarchy) Average of data values in the period dimension,
sum in the organisation unit dimensions.
Count Count of data values.
Min Minimum of data values.
Max Maximum of data values.
225
None No aggregation is performed in any dimension.
Sum Sum of data values in the period and

organisation unit dimension.
Standard deviation Standard deviation (population-based) of data

values.
Variance Variance (population-based) of data values.
14. If you want to save zeros for a particular reason, select Store zero data values. By default,
DHIS2 does not store zeros entered in the data entry module.
15. In the URL field, enter a link to an in-depth description of the data element.
For example a link to a metadata repository or registry that contains detailed technical
information about the definition and measurement of the data element.
16. In the Category combination field, define which category combination the data element
should have. This is also known as the "disaggregation".
17. Select an Option set.
Option sets are predefined lists of options which can be used in data entry.
18. Select an Option set for comments.
Option sets for comments are predefined lists of options which can be used to specify
standardized comments for data values in data entry.
19. Assign one or multiple Legends.
Legends are used in for example the Maps app to display certain data elements with
certain icons.
20. Set the Aggregation levels to allow the data element to be aggregated at one or more
levels:
1. In the left pane, select the levels you want to assign to the data element.
2. Click the right arrow to assign the aggregation levels.
By default, the aggregation will start at the lowest assigned organisation unit. If you for
example select "Chiefdom", it means that "Chiefdom", "District", and "National" aggregates
use "Chiefdom" (the highest aggregation level available) as the data source, and PHU data
will not be included. PHU data will still be available for the PHU level, but not included in
aggregations to the levels above.
If you select both "District" and "Chiefdom", it means that the "District" and "National" level
aggregates use District data as their source, "Chiefdom" will use Chiefdom, and "PHU" will
use PHU.
226
Configure metadata Create or edit a data element group
If applicable, enter custom attributes values, for example Classification or Collection

21. method.
Note
You create custom attributes in the Maintenance app: Other > > Attributes.
22. If applicable, select compulsory data element group sets, for example Main data element
group or Tracker-based data.
Note
You'll only see data element group sets in this form if you've created them and
set them to Compulsory.
You create data element group sets in the Maintenance app: Data element >
Date element group set.
23. Click Save.
Create or edit a data element group
Data element groups lets you classify related data elements into a common theme. For example,
two data elements "Measles immunisation" and "BCG Immunisation" might be grouped together
into a data element group "Childhood immunisation".
To create a data element group:
1. Open the Maintenance app and click Data elements > Data element group.
1. Name
2. Short name
3. Code
4. Select data elements and assign them.
5. Click Save.
Create or edit a data element group set
Data element group sets allows you to categorise multiple data element groups into a set. The
system uses data element group sets during analysis and reporting to combine similar data
element groups into a common theme. A data element group can be part of multiple data element
group sets.
1. Open the Maintenance app and click Data elements > Data element group set.
1. Name
2. Code
227
Description
3.
4. Compulsory
5. Data dimension
4. Select data element groups and assign them.
Available data element groups are displayed in the left panel. Data element groups that are
currently members of the data element group set are displayed in the right hand panel.
5. Click Save.
4. Click Save.
Note
object.
228
No access: The access group won't have access to data for the object.
◦
6. Click Close.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
229
Configure metadata Manage data sets and data entry forms
Manage data sets and data entry forms
About data sets and data entry forms
All data entry in DHIS2 is organised in data sets. A data set is a collection of data elements
grouped together for data entry and data export between instances of DHIS2. To use a data set
to collect data for a specific organisation unit, you must assign the organisation unit to the data
set. Once you have assigned the data set to an organisation unit, that data set is available in the
Data entry app. Only the organisation units that you have assigned the data set to can use the
data set for data entry.
A category combination can link to both data elements and data sets. If you use a category
combination for a data set, the category combinations is applicable for the whole form. This
means that you can use categories to capture information which is common to an entire form, for
example the name of the a project or grant. When a data set is linked to a category combination,
those categories will be displayed as drop-down boxes in the Data entry app. Data captured in
the form will then be linked to the selected category options from those drop-down boxes. For
information about how to create categories and category combinations, see section "Manage data
elements and categories". Make sure that you set the type of categories and category
combinations to "Attribute".
An scenario for when categories are useful is when you need to capture a data entry form for a
implementing partner organisation and a project. In that case:
1. Create category options and categories for all partner organisations and projects and link
them in a new category combination.
2. Assign the category combination to the data set (form) for which you need to capture this
information.
When opening this data set in data entry module, the partner organisation and project
categories will automatically be rendered as drop-down boxes, allowing you to select a
specific implementing partner organisation and project before continuing to do data entry.
You create and edit data sets in the Maintenance app. Here you define, for example, which data
elements you want to include in the data set and the data collection frequency.
You enter data in the Data entry app. The Data entry app uses data entry forms to display the
data sets. There are three types of data entry forms:
Data entry form types
230
Configure metadata About data sets and data entry forms
Data entry form type Description
Default form Once you have assigned a data set to an organisation unit, a
default form is created automatically. The default form is then
available in the Data entry app for the organisation units you
have assigned it to.
A default form consist of a list of the data elements belonging to

the data set together with a column for inputting the values. If your
data set contains data elements with a non-default category
combination, for example age groups or gender, additional
columns are automatically created in the default form based on
the different categories.
If you use more than one category combination you get multiple
columns in the default form with different column headings for the
options.
Section form If the default form doesn't meet your needs, you can modify it to
create a section form. Section forms give you more flexibility when
it comes to using tabular forms.
In a section form you can, for example, create multiple tables with
subheadings and disable (grey out) cells in a table.
When you have added a section form to a data set, the section
form is available in the Data entry app.
Custom form If the form you want to design is too complicated for default or
section forms, you can create a custom form. A custom form takes
more time to create than a section form, but you have full control
over the design.
You can, for example, mimic an existing paper aggregation form

with a custom form. This makes data entry easier, and should
reduce the number incorrectly entered data elements.
When you have added a custom form to a data set, the custom
form is available in the Data entry app.
Note
If a data set has both a section form and a custom form, the system
displays the custom form during data entry. Users who enter data can't
select which form they want to use. In web-based data entry the order
of display preference is:
1. Custom form (if it exists)

3. Default form
231
Mobile devices do not support custom forms. In mobile-based data entry

the order of display preference is:

2. Default form
In the Maintenance app, you manage the following data set objects:
Data set objects in the Maintenance app
Data set Create, assign to organisation units, edit, share,

delete, show details and translate
Edit compulsory data elements
Add and remove multiple data sets to organisation

units at once
Section form Create, edit and manage grey fields
Section Change display order, delete and translate
Custom form Create, edit and script
Workflow
You need to have data elements and categories to create data sets and data entry forms.
1. Create a data set.
2. Assign the data set to organisation units.
A default form is created automatically.
3. Create a section form or a custom form.
Now you can register data in the Data entry app.
232
Configure metadata Create or edit a data set
Create or edit a data set
1. Open the Maintenance app and click Data set > Data set.
3. In the Name field, type the precise name of the data set.
4. In the Short name field, define a short name for the data set.
Typically, the short name is an abbreviation of the full data set name. This attribute is often
used to display the name of the data set where space is limited.
6. In the Description field, type a description of the data set.
7. Enter the number of Expiry days.
The number of expiry days controls for how long it should be possible to enter data in the
Data entry app for this data set. Expiry days refer to the number of days after the end date
of the selected data entry period where the data entry form should be open for entry. After
the number of days has expired, the data set will be locked for further entry.
You can set manual exceptions to this using the lock exception functionality in the Data
Administration app.
Note
To allow data entry into all possible historical time periods, set the number of
expiry days to zero.
233
Configure metadata Create or edit a data set
If you want it to be possible to enter data for future periods, type the number of periods in
8. the Open future periods for data entry field.
The value is the number of future periods which are available for data entry.
For a monthly data set a value of 2 allows you to enter data for 2 months in advance. This
is useful for, by example, population, target and planning data.
9. In the Days after period to qualify for timely submission field, type the number of days in
which data can be entered to be considered reported on time.
To verify the number of timely reports submitted, go to Reports > Reporting rate summary.
10. Select a Period type.
The period type defines the frequency of reporting for the particular data set. The
frequency can for example be daily, quarterly or yearly.
11. Select a Category combination to assign it to the data set.
Tip
Click Add new to create category combinations that you're missing. In the form
that opens, create the category combinations you need. When you're done,
click Refresh values.
12. In the Complete notification recipients list, select a user group that should receive a
message when the data set is marked as complete in the Data Entry app.
The message is delivered through the DHIS2 messaging system.
13. If you want the user who entered the data to receive a message when the data set is
marked as complete in the Data entry app, select Send notification to completing user.
The message is delivered through the DHIS2 messaging system.
14. If applicable, select, a Data approval workflow.
15. If you want it to be possible to use the data set within the Java mobile DHIS2 application,
select Enable for Java mobile client.
16. If you want it to be mandatory to fill all values for a data element in data entry if one or
more values have been filled, select All fields for data elements required.
This means that if you enter one data value for a data element in an entry field (that is for a
category option combination), then you must enter data for all fields belonging to that data
element (that is all category option combinations).
17. If you want it to be possible to mark a data entry form as complete only if the validation of
that form is successful, select Complete allowed only if validation passes.
If you select this option, you can't mark the form as complete if validation fails.
18. If you want it to be mandatory that any missing values require a comment to justify their
absence, select Missing values requires comment on complete.
19. (Optional) Assign one or multiple Legends.
20. If applicable, select Skip offline.
234
Configure metadata Create or edit Data set Notification
This option controls whether this data entry form should be downloaded and saved in the
user's web browser. Normally you shouldn't select Skip offline. This is the default setting. If
you have big forms which are rarely used you can consider selecting this option to speed
up initial loading in the data entry module.
21. If applicable, select Data element decoration
If you select this option, descriptions of data elements render in call-outs in downloaded
data sets in offline mode in the Data entry app.
22. If applicable, select Render sections as tabs.
This option is only applicable for section forms. The option allows you to render each
section as a tab horizontally above the data set. This is useful for long data sets as it allows
appropriate sections to be selected quickly without going through the entire form.
23. If applicable, select Render vertically.
This option is only applicable for section forms.
You can override the category combination for each selected data set by clicking on the
gear icon above the list of selected data elements. This allows you to utilize a specific
category combination (disaggregation) within the current data set instead of the category
combination associated directly with the data element itself.
25. Select indicators and assign them.
26. In the organisation unit tree, select the organisation units you want to assign the data set
to.
Tip
◦ Click Organisation unit level to select all organisation units that belong
to a certain organisation level.
◦ Click Organisation unit group to select all organisation units that belong
to a certain organisation unit group.
27. Click Save.
You can now use the data set in the Data Entry app for the organisation units that you have
assigned to and for periods according to the selected frequency (period type).
Create or edit Data set Notification
1. Open the Maintenance app and click Data set > Data set notification.
235
What to send?
1. In the Name field, type the precise name of the data set notification.
3. Enter Data sets.
These data sets will be associated to this notification. In case any of them is completed for
a certain period and organisation unit, notification will be generated by the system.
Note
Nothing will happen if no data set is selected
4. In Message template section there are two parameters.
◦ Subject template subject of the notification sent in notification. It can have values
from the list of variables available on the right side.
◦ Message template actual message sent in notification. It can have values from the
list of variables available on the right side.
Note
Subject is only relevant in case of Email and internal DHIS2 messages. It is
ignored in case of SMS.
236
When to send?
1. Data set notification trigger field determine when to send notification.
◦ Data Set Completion will trigger notification as soon as data set is completed.
◦ Schedule Days will schedule notification based on number days relative to

scheduled date. Schedule date will be decided by Period associated with Data set.
▪ Send notification as provides two different types of notifications
▪ Collective summary send notification in summary mood
▪ Single notification sends notification in single mood
Note
Send notification as option is only available in case of scheduled notification.
This option is set to default which is Single notification in case of completion
notification
Who to send?
1. Notification recipient field determine recipients of the notification.
◦ Organisation Unit contact will send notification to contact assigned to organisation

unit which the data has been collected from.
◦ UserGroup will send notification to all the member of the selected UserGroup.
Note
An internal DHIS2 message will be sent in case if recipient is UserGroup.
Moreover user will also receive SMS/EMAIL if phone number and email
237
Configure metadata Override data elements' category combinations in a data set
address exist for that user and SMS/EMAIL notifications are enabled in
SystemSettings
Override data elements' category combinations in a data set
You can override which category combination to use for a data element within the context of a
data set. This means that a data element can use different category combinations within different
data sets. This is useful when you want to reuse a data element since you don't have to replicate
the data element to allow multiple category combinations.
If different regions within your organisation unit hierarchy use different disaggregations, or if the
disaggregations change over time, you can represent this by creating different data sets with the
appropriate category combinations.
2. In the list, find the data set you want to modify.
4. Go to the data elements section and click the spanner icon.
5. Select new category combinations and click Close.
6. Click Save.
Edit compulsory data elements in a data set
You can add or remove data elements which will be marked as compulsory during data entry.
2. In the list, find the data set you want to edit.
3. Click the options menu and select Edit compulsory data elements.
4. Assign the compulsory data elements.
5. Click Save.
Download default data forms in PDF format
You can download a default data from in PDF format for offline data entry.
2. In the list, find the object you want to download.
3. Click the options menu and select Get PDF for data entry.
Manage section forms
Create a section form
Section forms are separated automatically by data element category combinations, which produce
a spreadsheet like data entry form for each section.
2. In the list, find the data set you want to create a section form for.
238
Configure metadata Manage section forms
Click the options menu and select Manage sections.

3.
5. (Optional) In the Name field, type the name of the section.
6. (Optional) In the Description field, type a description of the section.
7. (Optional) To display totals for rows in the section form during data entry, select Show row
totals.
8. (Optional) To display totals for columns in the section form during data entry, select Show
column totals.
9. Assign data elements to the section:
1. (Optional) Select a Category combination filter.
Note
You can only use one category combination per section.
Option Description
None Displays all data elements that don't have a

category combination.
<No filter> Displays all data elements.
10. (Optional) Sort the data elements within the section by using the up and down arrows to
the left of the assigned data elements field.
11. Click Save.
12. Repeat add section steps for each section you want to have in your section form.
In the Data Entry app you can now use the section form. The section form appears
automatically when sections are available for the selected data set. Data sets which have
section forms will automatically display the section form.
Note how each data element category has been separated into a separate section, and a data
entry table has been automatically generated by the system. Use of section forms in combination
with data element categories can drastically reduce the amount of time which is required to create
data entry forms for data sets.
239
Edit a section form
2. In the list, find the data set you want to edit the section form for.
3. Click the options menu and select Manage sections.
4. In the list, find the section you want to edit.
6. Edit the section and click Save.
7. Repeat edit section steps for each section you want to edit.
Manage grey fields in a section form
You can disable data elements and category options for data entry. That means it won’t be
possible to enter data into these fields during data entry.
240
4. In the list, find the section you want to edit.
5. Click the options menu and select Manage grey fields.
6. Select which fields you want to disable.
Note
If you've sections that contain data elements assigned to multiple category
combinations, switch between the category combinations to view all fields.
7. Click Save.
Change section display order in a section form
You can control in which order sections are displayed in a section form.
241
Configure metadata Manage custom forms
Click the options menu and select Manage sections.

3.
4. In the list, find the section you want to move.
5. Click the options menu and select Move up or Move down.
If the section you want to move is the first or last section in the list, you'll only see one of
the move options.
Delete a section in a section form
4. In the list, find the section you want to delete.
5. Click the options menu and select Delete.
Translate a section in a section form
3. Click the options menu and select Translate.
4. Select a locale.
5. Enter the required information.
6. Click Close.
Manage custom forms
Create a custom form
You design custom forms in a built-in WYSIWYG HTML editor. If you select Source, you can paste
HTML code directly in the editing area. For a complete guide on how to use the editor, refer to
http://docs.ckeditor.com/.
242
To create a custom form:
1. Open the Maintenance app and click Data set.
2. In the list, find the data set you want to add a custom form to.
3. Click the options menu and select Design data entry form.
4. In the editing area, create the custom form.
◦ Double-click on a object in the left-hand list to insert it in the form.
◦ If you already have the HTML code for your form, click Source and paste the code.
5. Select a Form display style.
6. Click Save.
Scripting in custom forms
In custom data entry form you can use JavaScript to create dynamic behaviour and
customizations. As an example, you can hide form sections based on specific user input for data
elements, or show specific information when a form loads.
Events
The DHIS2 data entry module provides a range of events which you can register for and use to
perform actions at certain times. The events are registered on the document element. The jQuery
event object and the data set identifier are always the first two arguments provided to the callback
functions. The table below provides an overview of the events and when they are triggered.
243
Data entry events
Key Description Arguments
dhis2.de.event.formLoaded Triggered after the data entry form is Event | Data set ID
rendered, but before data values are set
in entry fields.
dhis2.de.event.dataValuesLoad Triggered after data values are set in Event | Data set ID
ed entry fields.
dhis2.de.event.formReady Triggered when the data entry form is Event | Data set ID
completely rendered and loaded with all
elements.
dhis2.de.event.dataValueSaved Triggered when a data value is saved Event | Data set ID | Data
successfully. value object
dhis2.de.event.completed Triggered when a data set is Event | Data set ID |

successfully marked as complete. Complete registration
object
dhis2.de.event.uncompleted Triggered when a data set is Event | Data set ID

successfully marked as incomplete.
dhis2.de.event.validationSucce Triggered when validation is done and Event | Data set ID

ss there were no violations.
dhis2.de.event.validationError Triggered when validation is done and Event | Data set ID

there were one or more violations.
dhis2.ou.event.orgUnitSelected Triggered when one or more Event | Org unit IDs | Org
organisation units are selected in the unit names | Sub org unit
org unit web tree. IDs
To register for an event:
<script type="text/javascript">
dhis2.util.on( 'dhis2.de.event.formReady', function( event, ds ) {

console.log( 'The form with id: ' + ds + ' is loaded!' );
} );
dhis2.util.on( 'dhis2.de.event.dataValueSaved', function( event, ds, dv ) {

console.log( 'Data value: ' + dv.value + ' was saved with data element: ' + dv.de );
} );
dhis2.util.on( 'dhis2.de.event.completed', function( event, ds, cr ) {

console.log( 'Form was completed for org unit: ' + cr.ou );
} );
244
</script>
Note
Be careful to only use "namespaced" events like the ones in the
example above and not general ones like "click" as the dhis2.util.on
method will deregister the event first.
If your function only applies to certain data sets you can use the supplied data set identifier and
shortcut your function for unwanted data sets like this:
dhis2.de.on( 'dhis2.de.event.validationSuccess', function( event, ds ) {

if ( $.inArray( ds, ['utXOiGbEj14', 'Re7qzHEThSC'] ) == -1 ) {
return false;
}
console.log( 'Form with id: ' + ds + ' validated successfully!' );
} );
The identifiers of the input fields in the data entry form is on the format described below. This
format can be used to select the input fields in your script and perform actions on them:
<dataelementid>-<optioncomboid>-val
Since the data set identifier is provided for all events a feasible alternative is to utilize the "files"
Web API resource and keep your callback functions in a single file, where you let the JavaScript
code take action based on which data set is currently loaded.
Functions
The DHIS2 data entry module contains JavaScript API functions which can be accessed from
custom data entry forms.
dhis2.de.api.getSelections: This function returns a JavaScript object which contains properties

for all dimensions with corresponding values for the identifiers of the selected options. It contains
properties for "ds" (data set), "pe" (period), "ou" (organisation unit) and identifiers for all data set
categories.
An example response looks like this:
{
+ ds: "lyLU2wR22tC",
+ pe: "201605",
+ ou: "g8upMTyEZGZ",
+ LFsZ8v5v7rq: "CW81uF03hvV",
+ yY2bQYqNt0o: "yMj2MnmNI8L"
+}
Example JavaScript usage of this function:
245
Configure metadata Change sharing settings for metadata objects
var sel = dhis2.de.api.getSelections();

+var orgUnit = sel["ou"];
+var partner = sel["LFsZ8v5v7rq"];
Note
object.
6. Click Close.
Note
246
Configure metadata Display details of metadata objects
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
Manage indicators
About indicators
An indicator is a formula that can consist of multiple data elements, constants, organisation unit
group counts and mathematical operators. The indicator consist typically of a numerator and
denominator. You use indicators to calculate coverage rates, incidence and other values that are
a result of data element values that have been entered into the system. Calculated totals do not
have a denominator.
Note
247
Configure metadata About indicators
You never enter indicator values directly in DHIS2, you calculate them.
An indicator formula can consist of mathematical operators, for example plus and minus; functions
(see below); and of the following elements:
Indicator elements
Indicator element Type Description
Constant Component Constants are numerical values

which remain the same for all
indicator calculations. This is
useful in order to have a single
place to change values that
might change over time.
Constants are applied AFTER

data element values have been
aggregated.
Data elements Component Data elements are substituted by

the data value captured for the
data element.
Days Operator "Days" is special operator that

always provides the number of
days for a given indicator
calculation.
For example: if you want to

calculate the "Percentage of time
vaccine refrigerator was non-
functional", you could define the
numerator as:
("Days-"Number of days vaccine

refrigerator was
available"")/"Days"
If the fridge was available 25

days in June, the indicator would
be calculated as:
(30-25/25)*100 = 17 %
If you want to calculate the total

for Quarter 1, the number of days
("Days") would be:
31+28+31 = 90
The "Days" parameter will

always be the number of days in
the period of interest.
248
Configure metadata About indicators
Indicator element Type Description
Organisation unit counts Component You can use organisation unit

groups in formulas. They will be
replaced by the number of
organisation units in the group.
During aggregation, the
organisation units in the group
will be intersected with the part of
the organisation unit hierarchy
being requested.
This lets you use the number of

public facilities in a specific
district in indicators. This is
useful for example when you
create facility infrastructure
surveys and reports.
Programs Component Click Programs and select a

program to view all data
elements, attributes and
indicators related to a specific
program.
The program components you

include in your formula will have
a program tag assigned to them.
You can use the following functions in an indicator formula:
Indicator functions
Indicator Function Arguments Description
if (boolean-expr, true-expr, false- Evaluates the boolean

expr) expression and if true returns the
true expression value, if false
returns the false expression
value. The arguments must
follow the rules for any indicator
expression.
isNull (element) Returns true if the element value

is missing (null), otherwise false.
isNotNull (element) Returns true if the element value

is not missing (not null),
otherwise false.
249
Indicator Function Arguments Description
firstNonNull (element [, element ...]) Returns the value of the first

element that is not missing (not
null). Can be provided any
number of arguments. Any
argument may also be a numeric
or string literal, which will be
returned if all the previous
objects have missing values.
greatest (expression [, expression ...]) Returns the greatest (highest)

value of the expressions given.
Can be provided any number of
arguments.
least (expression [, expression ...]) Returns the least (lowest) value

of the expressions given. Can be
provided any number of
arguments.
In the Maintenance app, you manage the following indicator objects:
Indicator objects in the Maintenance app
Indicator Create, edit, clone, share, delete, show details and

translate
Indicator type Create, edit, clone, delete, show details and

translate
Indicator group Create, edit, clone, share, delete, show details and
translate
Indicator group set Create, edit, clone, share, delete, show details and
translate
Workflow
1. Create indicator types.
2. Create indicators.
3. Create indicator groups.
4. Create indicator group sets.
250
Configure metadata Create or edit an indicator type
Create or edit an indicator type
Indicator types define a factor that is applied during aggregation. Indicator values that are
calculated during a data mart export or report table generation process will appear properly
formatted, and will therefore not require an additional multiplier (for example 100 in the case of
percent) for the values to appear correctly formatted.
Note
As of version 2.4 of DHIS2, the "Calculated data element" object has
been deprecated. Instead, you can create a calculated data element by
creating an indicator type with a factor of "1" and by setting the
"Number" option to "Yes". The effect of setting the "Number" option to
"Yes" will be that the indicator will effectively not have a denominator.
You will therefore only be able to define a numerator, which will serve as
the formula of the calculated data element.
1. Open the Maintenance app and click Indicator > Indicator type.
3. In the Name field, type the name of the indicator type, for example "Per cent", "Per
thousand", "Per ten thousand".
4. Type a Factor.
The factor is the numeric factor that will be multiplied by the indicator formula during the
calculation of the indicator.
5. Click Save.
251
Configure metadata Create or edit an indicator
Create or edit an indicator
1. Open the Maintenance app and click Indicator > Indicator.
3. In the Name field, type the full name of the indicator, for example "Incidence of confirmed
malaria cases per 1000 population".
4. In the Short name field, type an abbreviated name of the indicator, for example "Inc conf.
malaria per 1000 pop".
The short name must be less than or equal to 25 characters, including spaces.
In many countries indicators are assigned a code.
252
Configure metadata Create or edit an indicator
(Optional) In the Color field, assign a color to reprersent the indicator.

6.
7. (Optional) In the Icon field, assign an icon to illustrate the meaning of the indicator.
8. In the Description field, type a brief, informative description of the indicator and how it is
calculated.
9. If you want to apply an annualization factor during the calculation of the indicator, select
Annualized.
Typically, an annualized indicator's numerator is multiplied by a factor of 12, and the

denominator is for instance a yearly population figure. This allows for monthly coverage
values to be calculated with yearly population figures.
10. Select the number of Decimals in data output.
11. Select an Indicator type.
This field determines a factor that will automatically be applied during the calculation of the
indicator. Possible choices are determined by the indicator types. For example, a "Percent"
indicator will automatically be multiplied by a factor of 100 when exported to the data mart,
so that it will display as a percentage.
13. In the URL field, enter a link, for example a link to an indicator registry, where a full
metadata description of the indicator can be made available.
14. (Optional) Enter a Category option combination for aggregate data export..
You use this setting to map aggregated data exported as raw data to another server.
Typically you do this type of data exchange mapping when you want to create anonymous
aggregated data from patient data recorded in programs (event data).
15. (Optional) Enter an Attribute option combination for aggregate data export..
You use this setting to map aggregated data exported as raw data to another server.
Typically you do this type of data exchange mapping when you want to create anonymous
aggregated data from patient data recorded in programs (event data).
16. If applicable, enter custom attributes values, for example Classification or Collection
method.
Note
You create custom attributes in the Maintenance app: Other > > Attributes.
17. Click Edit numerator.
1. Type a clear description of the numerator.
2. Define the numerator by double-clicking components in the right-hand field. The

components then appears as part of the formula in the left-hand field. Add
mathematical operators by double-clicking the icons below the left-hand field.
You formula must be mathematically valid. This includes correct use of parentheses
when necessary.
3. Click Done to save all changes to the numerator.
253
Configure metadata Create or edit an indicator group
Click Edit denominator.

18.
1. Type a clear description of the denominator.
2. Define the denominator by double-clicking components in the right-hand field. The

components then appears as part of the formula in the left-hand field. Add
mathematical operators by double-clicking the icons below the left-hand field.
You formula must be mathematically valid. This includes correct use of parentheses
when necessary.
3. Click Done to save all changes to the denominator.
19. If applicable, select compulsory indicator group sets, for example Human resources.
Note
You'll only see indicator group sets in this form if you've created them and set
them to Compulsory.
You create indicator group sets in the Maintenance app: Indicator > Indicator
group set.
20. Click Save.
Create or edit an indicator group
1. Open the Maintenance app and click Indicator > Indicator group.
254
Configure metadata Create or edit an indicator group set
Type a name.
3.
4. Select indicators and assign them.
5. Click Save.
Create or edit an indicator group set
Indicator group sets create combined groups of similar indicators. For example, you might have a
group of indicators called "Malaria" and "Leishmaniasis". Both of these groups could be combined
into a group set called "Vector-borne diseases". Indicator groups sets are used during analysis of
data to combine similar themes of indicators.
1. Open the Maintenance app and click Indicators > Indicator group.
1. Name
2. Description
3. Compulsory
4. Select indicator groups and assign them.
255
Available indicator groups are displayed in the left panel. Indicator groups that are currently
members of the indicator group set are displayed in the right hand panel.
5. Click Save.
4. Click Save.
Note
object.
6. Click Close.
Note
256
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
Manage organisation units
In this section you will learn how to:
• Create a new organisation unit and build up the organisation unit hierarchy
• Create organisation unit groups, group sets, and assign organisation units to them
257
Configure metadata About organisation units
Modify the organisation unit hierarchy

•
About organisation units
The organisation unit hierarchy defines the organisation structure of DHIS2, for example how
health facilities, administrative areas and other geographical areas are arranged with respect to
each other. It is the "where" dimension of DHIS2, similar to how periods represent the "when"
dimension.
The organisation unit hierarchy is built up by parent-child relations. In DHIS2, each of these
nodes is an organisation unit. A country might for example have eight provinces, and each
province might have a number of districts as children. Normally, the lowest levels consist of
facilities where data is collected. Data collecting facilities can also be located at higher levels, for
example national or provincial hospitals. Therefore, you can create skewed organisation trees in
DHIS2.
• You can only have one organisation hierarchy at the same time.
• You can have any number of levels in a hierarchy.
Typically national organisation hierarchies in public health have four to six levels.
• You can create additional classifications by using organisation groups and organisation
group sets.
For example to create parallel administrative boundaries to the health care sector.
• It is recommended to use organisation unit groups to create a non-geographical hierarchy.
• An organisation unit can only be a member of a single organisation unit group within an
organisation unit group set.
• An organisation unit group can be part of multiple organisation unit group sets.
• The organisation unit hierarchy is the main vehicle for data aggregation on the
geographical dimension.
unit in the Event Capture and Tracker Capture apps.
Important
You can change the organisation unit hierarchy after you've created it,
even organisation units that collect data. However, DHIS2 always uses
the latest hierarchy for data aggregation. So if you change the
hierarchy, you loose the temporal representation of the hierarchy across
time.
District A is sub-divided into District B and District C. Facilities which
belonged to District A are reassigned to District B and C. Any historical
data, which you entered before the split occurred, is still registered as
belonging to District B and C, not to the obsolete District A.
In the Maintenance app, you manage the following organisation unit objects:
Organisation unit objects in the Maintenance app
258
Organisation unit Create, edit, clone, delete, show details and

translate
Organisation unit group Create, edit, clone, share, delete, show details and
translate
Organisation unit group set Create, edit, clone, share, delete, show details and
translate
Organisation unit level Edit and translate
Hierarchy operations Move organisation units
Workflow
The recommended workflow is:
1. Create organisation units.
2. Create organisation unit groups.
3. Create organisation unit group sets.
Create or edit an organisation unit
259
Configure metadata Create or edit an organisation unit
You add organisation units to the hierarchy one by one, either as a root unit or as a child of a
selected organisation unit. You can only have one root unit.
1. Open the Maintenance app and click Organisation unit > Organisation unit.
3. Select which organisation unit your new organisation unit will belong to:
1. Click Parent organisation unit.
2. In the organisation unit tree, locate the parent organisation unit and select it. Your
selection is marked in yellow.
Tip
Click the arrows to expand the organisation unit tree.
3. Click Select.
4. Enter a Name of the organisation unit.
Each organisation unit must have an unique name.
5. Enter a Short name for the organisation unit.
Typically, the short name is an abbreviation of the full organisation unit name. This attribute
is often used in reports to display the name of the organisation unit, where space is limited.
6. (Optional) Assign a Code.
In many countries organisation units are assigned a code.
7. (Optional) Type a Description of the organisation unit.
8. Select an Opening date.
The opening dates control which organisation units that existed at a point in time, for
example when analysing historical data.
9. If applicable, select a Closed date.
10. In the Comment field, enter any additional information that you would like to add.
11. (Optional) In the URL field, enter a link to an external web site that has additional
information about the organisation unit.
12. Enter contact information:
◦ Contact person
◦ Address
◦ E-mail
◦ Phone number
13. (Optional) Enter Latitude and Longitude.
260
Configure metadata Create or edit an organisation unit group
You must have latitude and longitude values to create maps in the Maps app. Then your
organisation units can be represented as points on a map, for example a health facility.
Without this information, the Maps app will not work.
It might be more efficient to import coordinates later as a batch job for all organisation units
using the Import-Export app. You also use the Import-Export app to create polygons. A
polygon is an organisation unit that represent an administrative boundary.
14. If applicable, select Data sets and assign them.
Note
You control whether a user should be able to assign data sets to an
organisation unit in the System Settings app:
Open the System Settings app, click Access and select Allow assigning
object to related objects during add or update.
15. If applicable, select Programs and assign them.
Note
You control whether a user should be able to assign programs to an
organisation unit in the System Settings app:
Open the System Settings app, click Access and select Allow assigning
object to related objects during add or update.
16. If applicable, enter custom attributes values, for example HR identifier.
Note
You configure the custom attributes in the Maintenance app:
Open the Maintenance app and click Other > Attribute.
17. Click Save.
Create or edit an organisation unit group
Organisation unit groups allow you to classify related organisation units into a common theme.
You can for example group all organisation units that are hospitals in an Hospital group.
1. Open the Maintenance app and click Organisation unit > Organisation unit group.
1. Name: Provide a precise, unique and descriptive name for the organisation unit
group.
2. Short name: The short name should be less than 25 characters. Typically, the short
name is an abbreviation of the full organisation unit name. This attribute is used in
certain places in DHIS2 where space is limited.
3. Code
261
Configure metadata Create or edit an organisation unit group set
Symbol: Select a symbol which will be used to display the organisation unit (points
4. only) when the layer is displayed in the Maps app.
4. In the organisation tree, click the organisation units you want to add to the organisation unit
group.
You can locate an organisation unit in the tree by expanding the branches (click on the
arrow symbol), or by searching for it by name.
The selected organisation units display in orange.
5. Click Save.
Create or edit an organisation unit group set
Organisation unit group sets allows you to create additional classifications of organisation units.
The group sets create new dimensions so that you can make a more detailed data analysis. You
an easily filter, organise or aggregate data by groups within a group set.
• You can have any number of organisation unit group sets.
• The default organisation unit group sets are Type and Ownership.
• An organisation unit can only be a member of a single organisation unit group within an
• An organisation unit group can be part of multiple organisation unit group sets.
• You can define whether an organisation unit group set is compulsory or not, which will
affect the completeness of the data. Compulsory means that all organisation units must be
member of a group in that group set.
Note
In the Data integrity part of the Data administration app you can verify
if you've accidentally assigned the same organisation unit to multiple
groups within the same group set. In this app you also find information
about organisation units that are not members of a compulsory
1. Open the Maintenance app and click Organisation unit > Organisation unit group set.
3. Fill in:
1. Name: Provide a precise name for the organisation unit group set.
2. Code
3. Description: Describe what the organisation unit group set measures or captures.
4. If you want all organisation units to be members of a group within the group set, select
Compulsory.
5. (Optional) Select Data dimension.
6. (Optional) Select Include subhierarchy in analytics.
262
If you select this, a sub-organisation unit will inherit the organisation unit group property
from its closest "parent" organisation unit. Any property on the sub-organisation unit will
override the inherit value.
If an organisation unit have no associated organisation unit group, the organisation unit
can inherit its closest parent's organisation unit group. If none of the parent organisation
unit groups have an organisation unit group for a given org unit group set, the result will
still be "blank", but if at least one parent has an organisation unit group, sub-organisation
unit will inherit it.
include subhierarchy in analytics" is enabled, which means the org units inherit their closest
parents org unit group IF the org unit is white (no org unit group associated with it).
7. Select organisation unit groups and assign them.
In the left-hand list, you find the available organisation unit groups. Use the arrows to move
selected groups between the two lists.
If there are no organisation unit groups in the left-hand list, click Add new. In the form that
opens, create the organisation units group you need. When you're done, click Refresh
values.
Note
An organisation unit can only be a member of a single organisation unit group
within an organisation unit group set.
8. Click Save.
You want to analyse data based on the ownership of the facilities. All facilities have an owner so
you need to make sure that all organisation units get this classification. To do that you can use
the Compulsory option:
1. Create a group for each ownership type, for example "MoH", "Private" and "Faith-based".
2. Assign all facilities in the database to one of these groups.
3. Create an organisation unit group set called "Ownership" and select Compulsory.
4. Assign the organisation unit groups "MoH", "Private" and "Faith-based" to the "Ownership"
organisation group set.
263
264
Configure metadata Assign names to organisation unit levels
Group you organisation unit in two ways and aggregate data on these two parallel hierarchies
Use to aggregate data (only in analytics apps)
An additional setting to the organisation unit group set, creates a dynamic "membership" to a
You don't change the organisation unit hierarchy
Scalable and dynamic
Dynamic inclusion of hierarchy
Dynamic additional classification
Assign names to organisation unit levels
When you add children to an organisation unit, DHIS2 automatically creates a new organisation
unit level if necessary. The system also assigns a generic name to this level, for example "Level
5". You can replace the generic name with a contextual name, for example "Country", "Province",
265
Configure metadata Move organisation units within a hierarchy
"District" or "Health Facility". DHIS2 uses the contextual names anywhere levels are referred to,
for example in the Maps app.
1. Open the Maintenance app and click Organisation unit > Organisation unit level.
The loading time of the list depends on the depth of the organisation unit hierarchy tree.
2. For the organisation unit levels you want to modify, type a name.
3. Select the number of offline levels.
Note
You configure the default value in the System Settings app:
Open the System Settings app, click General and select a level in the Max
offline organisation unit levels list.
4. Click Save.
Move organisation units within a hierarchy
You can move organisation units within in the hierarchy by changing the parent of a selected
organisation unit.
1. Open the Maintenance app and click Organisation unit > Hierarchy operations.
2. In the left-hand hierarchy tree, select the organisation unit(s) you want to move.
Note
If the selected organisation unit is has sub-organisation units, all of them move
to the new parent organisation unit.
3. In the right-hand hierarchy tree, select which organisation unit you want to move the
selected organisation unit(s) to.
4. Click Move x organisation units, where x stands for the number of organisation units you
have selected.
Your changes are immediately reflected in the left-hand side hierarchy tree.
Close an organisation unit
When you close an organisation unit, you can't register or edit events to this organisation unit in
the Event Capture and Tracker Capture apps.
1. Open the Maintenance app and click Organisation unit > Organisation unit.
2. In the object list, click the options menu and select Edit.
3. Select a Closed date.
4. Click Save.
266
In the object list, click the options menu and select Clone.
2.
4. Click Save.
Note
object.
6. Click Close.
Note
Warning
267
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
[Work in progress] Manage validation rules
About validation rules
A validation rule is based on an expression. The expression defines a relationship between data
element values. The expression forms a condition with certain logical criteria.
The expression consists of:
• A left side
• A right side
• An operator
A validation rule asserting that the total number of vaccines given to infants is less than or equal
to the total number of infants.
268
Configure metadata About validation rules
In the Maintenance app, you manage the following validation rule objects:
Object type What you can do
Validation rule Create, edit, clone, delete, show details, and

translate
Validation rule group Create, edit, clone, delete, share, show details, and
translate
Validation notification Create, edit, clone, delete, show details, and

translate
About sliding windows
You can use sliding windows to group data across multiple periods as opposed to selecting data
for a single period. Sliding windows have a size, that is to say, the number of days to cover, a
starting point and an end point. The example below shows disease surveillance data:.
• The data in the orange section, selects data based on the current period. There is a
threshold, which is calculated once for each week or period, and this is shown in the
"Result" section.
• The data in the blue section is the sliding window. It selects data from the past 7 days. The
"Result" shows the total number of confirmed cases of a disease.
• The validation rule makes sure users are notified when the total number of cases breaks
the threshold for the period.
Different behaviour of validation rules
With sliding windows Without sliding windows
Used only for event data. Used for event data and aggregate data.
Data selection is based on a fixed number of days Data selection is always based on a period.
(periodType).
269
Configure metadata Create or edit a validation rule
With sliding windows Without sliding windows
The position of the sliding window is alwaysrelative Data is always selected for the same period as the
to the period being compared. period being compared.
See also: How to use sliding windows when you're Creating or editing a validation rule.
About validation rule groups
A validation rule group allows you to group related validation rules. When you run a validation rule
analysis, you can choose to run all of the validation rules in your system, or just the validation
rules in one group.
About validation notifications
You can configure a validation rule analysis to automatically send notifications about validation
errors to selected user groups. These messages are called validation notifications. They are sent
via the internal DHIS2 messaging system.
You can send validation rule notifications as individual messages or as message summaries. This
is useful, for example, if you want to send individual messages for high-priority disease outbreaks,
and summaries for low-priority routine data validation errors.
Create or edit a validation rule
1. Open the Maintenance app and click Validation > Validation rule.
3. Type a Name.
The name must be unique among the validation rules.
5. (Optional) Type a Description.
6. Select an Importance: High, Medium or Low.
8. Select an Operator: Compulsory pair, Equal to, Exclusive pair, Greater than, Greater
than or equal to or Not equal to.
The Compulsory pair operator allows to require that data values must be entered for a
form for both left and right sides of the expression, or for neither side. This means that you
can require that if one field in a form is filled, then one or more other fields must also be
filled.
The Exclusive pair allows to assert that if any value exist on the left side then there should
be no values on the right side (or vice versa). This means that data elements which
compose the rule on either side should be mutually exclusive from each other, for a given
time period / organisation unit /attribute option combo.
9. Create the left side of the expression:
1. Click Left side.
270
Configure metadata Create or edit a validation rule
Select Sliding window if you want to view data relative to the period you are
2. comparing. See also About validation rules.
3. Select a Missing value strategy. This selection sets how the system evaluates a
validation rule if data is missing.
Option Description
Skip if any value is missing The validation rule will be skipped if any of
the values which compose the expression
are missing. This is the default option.
Always select this option you use the Exclu

sive pair or Compulsory pair operator.
Skip if all values are missing The validation rule will be skipped only if all
of the operands which compose it are
missing.
Never skip The validation rule will never be skipped in

case of missing data, and all missing
operands will be treated effectively as a
zero.
4. Type a Description.
5. Build an expression based on the available data elements, program objects,

organisation units, counts and constants.
In the right pane, double-click the data objects you want to include in the expression.
Combine with the mathematical operators located below the left pane.
6. Click Save.
10. Create the right side of the expression:
1. Click Right side.
Option Description

271
Configure metadata Create or edit a validation rule group
Option Description
of the operands which compose it are
missing.

case of missing data, and all missing
operands will be treated effectively as a
zero.
3. Select Sliding window if you want to view data relative to the period you are
comparing. See also About validation rules.
4. Type a Description.
5. Build an expression based on the available data elements, program objects,

organisation units, counts and constants.
In the right pane, double-click the data objects you want to include in the expression.
Combine with the mathematical operators located below the left pane.
6. Click Save.
11. (Optional) Choose which Organisation unit levels this rule should be evaluated for.
Leaving this empty will cause the validation rule to be evaluated at all levels.
12. (Optional) Click Skip this rule during form validation to avoid triggering this rule while
doing data entry
13. Click Save.
Create or edit a validation rule group
1. Open the Maintenance app and click Validation > Validation rule group.
3. Type a Name.
6. Double-click the Validation rules you want to assign to the group.
7. Click Save.
Create or edit a validation notification
1. Open the Maintenance app and click Validation > Validation notification.
3. Type a Name.
272
Select Validation rules.

5.
6. Select Recipient user groups.
7. (Optional) Select Notify users in hierarchy only.
If you select this option, the system will filter the recipient users. (The system derives the
recipient users from the recipient user groups.) The filter is based on which organisation
unit the recipient user belongs to. The users linked to organisation units which are
ancestors of the organisation unit where the violation took place will receive validation
notifications. The system will ignore other users and these users won't receive validation
notifications.
8. Create the message template:
1. Create the Subject template.
Double-click the parameters in the Template variables field to add them to your
subject.
2. Create the Message template.
Double-click the parameter names in the Template variables field to add them to
your message.
9. Click Save.
4. Click Save.
Note
273
Change sharing settings for the access groups you want to modify.
4.
object.
6. Click Close.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
274
Configure metadata Manage attributes
In the object list, click the options menu and select Translate.
2.
Tip
3. Select a locale.
5. Click Save.
Manage attributes
About attributes
You can use metadata attributes to add additional information to metadata objects. In addition to
the standard attributes for each of these objects it may be useful to store information for
additional attributes, for example the collection method for a data element.
In the Maintenance app, you manage the following attribute objects:
Attribute objects in the Maintenance app
275
Configure metadata Create or edit an attribute
Attribute Create, edit, clone, delete, show details and

translate
Create or edit an attribute
1. Open the Maintenance app and click Attribute.
3. In the Name field, type the name of the attribute.
Each attribute must have a unique name
5. Select a Value type.
If the value supplied for the attribute does not match the value type you will get a warning.
7. Select the options you want, for example:
◦ Select Mandatory if you want an object to always have the dynamic attribute.
◦ Select Unique if you want the system to enforce that values are unique for a specific
object type.
8. Click Save.
The dynamic attribute is now available for the objects you assigned it to.
4. Click Save.
Note
Warning
276
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
Manage constants
About constants
Constants are static values which can be made available to users for use in data elements and
indicators. Some indicators, such as "Couple year protection rate" depend on constants which
usually do not change over time.
277
Configure metadata Create or edit a constant
In the Maintenance app, you manage the following constant objects:
Constant objects in the Maintenance app
Constant Create, edit, clone, share, delete, show details and

translate
Create or edit a constant
1. Open the Maintenance app and click Other > Constant.
3. In the Name field, type the name of the constant.
4. (Optional) In the Short name field, type an abbreviated name of the constant.
6. In the Description field, type a brief, informative description of the constant.
7. In the Value field, define the constant's value.
8. Click Save.
The constant is now available for use.
278
In the object list, click the options menu and select Clone.
2.
4. Click Save.
Note
object.
6. Click Close.
Note
Warning
279
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
Manage option sets
About option sets
Option sets provide a pre-defined drop-down (enumerated) list for use in DHIS2. You can define
any kind of options.
An option set called "Delivery type" would have the options: "Normal", "Breach", "Caesarian" and
"Assisted".
280
Configure metadata Create or edit an option set
Option set objects in the Maintenance app
Option set Create, edit, clone, share, delete, show details and
translate
Option group Create, edit, clone, share, delete, show details and
translate
Option group set Create, edit, clone, share, delete, show details and
translate
Create or edit an option set
Important
Option sets must have a code as well as a name. You can change the
names but you can't change the codes. Both names and codes of all
options must be unique, even across different option sets.
1. Open the Maintenance app and click Other > Option set.
3. In the Primary details tab, define the option set:
1. In the Name field, type the name of the constant.
2. In the Code field, assign a code.
281
Configure metadata Create or edit an option group
Select a Value type.

3.
4. Click Save.
4. For each option you need, perform the following tasks:
1. Click the Options tab.
3. Type a Name and a Code. Optionally also select a Color and an Icon which will be
used for this option in the data capture apps.
4. Sort the options by name, code/value or manually.
5. Click Save.
Create or edit an option group
You can group and classify options within an option set by using option groups. This way you
can create a subset of options in an option set. The main purpose of this is to be able to filter
huge option sets into smaller, related parts.
Options that are grouped can be hidden or shown together in tracker and event capture through
program rules.
Note
You cannot change the Option set selected in an Option group once it
has been created.
1. Open the Maintenance app and click Other > Option group.
1. Name
2. Short name
3. Code
4. Option set
4. Once an Option set is selected, you can assign the Options you want to group.
5. Click Save.
Create or edit an option group set
Option group sets allows you to categorise multiple option groups into a set. The main purpose
of the option group set is to add more dimensionality to your captured data for analysis.
Note
You cannot change the Option set selected in an Option group set
once it has been created.
1. Open the Maintenance app and click Other > Option group set.
282
Fill in the form:

3.
1. Name
2. Code
3. Description
4. Option set
5. Data dimension
If you select Data dimension, the group set will be available to the analytics as
another dimension, in addition to the standard dimensions of “Period” and
“Organisation unit”.
4. Select option groups and assign them.
Available option groups are displayed in the left panel. Option groups that are currently
members of the option group set are displayed in the right hand panel.
5. Click Save.
4. Click Save.
Note
283
No access (only applicable to Public access): The public won't have access to the
◦ object.
6. Click Close.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
284
Configure metadata Manage legends

3. Select a locale.
5. Click Save.
Manage legends
About legends
You can create, edit, clone, delete, show details and translate legends to make the maps you're
setting up for your users meaningful. You create maps in the Maps app.
Note
Continuous legends must consist of legend items that end and start with
the same value, for example: 0-50 and 50-80. Do not set legend items
like this: 0-50 and 51-80. This will create gaps in your legend.
Create or edit a legend
Note
It is not allowed to have gaps in a legend.
It is not allowed to have overlapping legend items.
1. Open the Maintenance app and click Other > Legend.
3. In the Name field, type the legend name.
5. Create the legend items you want to have in your legend:
1. Select Start value and End value.
2. Select Number of legend items.
3. Select a color scheme.
4. Click Create legend items.
Tip
Click the options menu to edit or delete a legend item.
6. (Optional) Add more legend items:
2. Enter a name and select a start value, an end value and a color.
3. Click OK.
285
(Optional) Change the color scales.

7.
1. Click the colour scale to view a list of color scale options, and select a color scale.
2. To customize a color scale, click the add button. In the Edit legend item dialog, click
the color scale button and hand-pick colors, or enter your color values.
8. Click Save.
Legend item Start value End value
Low bad 0 50
Medium 50 80
High good 80 100
Too high 100 1000
4. Click Save.
Note
object.
286
Change data sharing settings for the access groups you want to modify.
5.
6. Click Close.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
287
Configure metadata Assign a legend to indicator or data element
Select a locale.
3.
5. Click Save.
Assign a legend to indicator or data element
You can assign a legend to an indicator or a data element in the Maintenance app, either when
you create the object or edit it. When you then select the indicator or data element in the Maps
app, the system automatically selects the assigned legend.
See also
• Using the GIS app
Manage predictors
About predictors
A predictor tells DHIS2 how to generate a data value based on data values from past periods
and/or the period of the data value. It defines which past periods to sample, and how to combine
the data to produce a predicted value. A predictor always generates an aggregate data value, but
the past data values used to calculate the predicted value may come from aggregate data, event
data, or both.
A simple use of predictors would be to copy a past period data value into a new period, for
example into the next month, or into the same quarter in the next year. A more complex use of
predictors would be for disease surveillance, to predict what value would be expected in a given
week or month of the year, based on previous data values. A validation rule could then be used to
see how the actual value compares with the expected (predicted) value.
You can specify the organisation unit level(s) for which a predictor will generate values. For
example in disease surveillance you can use one predictor to give the expected value at each
local facility, given the amount of variation you would expect at a single facility, while using a
different predictor to estimate the value you would expect summed over all facilities in a district,
given the (smaller) proportional variation that you would expect when adding up the values for all
facilities in the district. You could also define additional predictors at any higher levels of the
organisation unit hierarchy, where you might expect different proportions of variation.
Alternatively, you can define a single predictor for all these levels and use the standard deviation
function to determine what amounts of deviation were measured at each level.
In the Maintenance app, you manage the following predictor objects:
Predictor objects in the Maintenance app
Predictor Create, edit, clone, delete, show details and

translate
Sampling past periods
Predictors can generate data values for periods that are in the past, present, or future. These
values are based on data from the predicted period, and/or sampled data from periods prior to
the predicted period.
288
Configure metadata Sampling past periods
If you need data only from the same period in which the prediction is made, then you don't need
to read this section. This section describes how to sample data from periods prior to the predicted
period.
Sequential sample count
A predictor's Sequential sample count gives the number of immediate prior periods to sample. For
example, if a predictor's period type is Weekly and the Sequential sample count is 4, this means
to sample four prior weeks immediately preceding the predicted value week. So the predicted
value for week 9 would use samples from weeks 5, 6, 7, and 8:
If a predictor's period type is Monthly and the Sequential sample count is 4, this means to sample
four prior months immediately preceding the predicted value month. So the predicted value for
May would use samples from weeks January, February, March, and April:
The Sequential sample count can be greater than the number of periods in a year. For example, if
you want to sample the 24 months immediately preceding the predicted value month, set the
Sequential sample count to 24:
Sequential skip count
A predictor's Sequential skip count tells how many periods should be skipped immediately prior to
the predicted value period, within the Sequential sample count. This could be used, for instance,
in outbreak detection to skip one or more immediately preceding samples that might in fact
contain values from the beginning of an outbreak that you are trying to detect.
For example, if the Sequential sample count is 4, but the Sequential skip count is 2, then the two
samples immediately preceding the predicted period will be skipped, resulting in only two periods
being sampled:
Annual sample count
A predictor's Annual sample count gives the number of prior years for which samples should be
collected at the same time of year. This could be used, for instance, for disease surveillance in
289
Configure metadata Sampling past periods
cases where the expected incidence of the disease varies during the year and can best be
compared with the same relative period in previous years. For example, if the Annual sample
count is 2 (and the Sequential sample count is zero), then samples would be collected from
periods in the immediately preceding two years, at the same time of year.
Sequential and annual sample counts together
You can use the sequential and annual sample counts together to collect samples from a number
of sequential periods over a number of past years. When you do this, samples will be collected in
prior years during the period at the same time of year as the predicted value period, and also in
previous years both before and after the same time of year, as determined by the Sequential
sample count number.
For example, if the Sequential sample count is 4 and the Annual sample count is 2, samples will
be collected from the 4 periods immediately preceding the predicted value period. In addition
samples will be collected in the prior 2 years for the corresponding period, as well as 4 periods on
either side:
Sequential, annual, and skip sample counts together
You can use the Sequential skip count together with the sequential and annual sample counts.
When you do this, the Sequential skip count tells how many periods to skip in the same year as
the predicted value period. For example, if the Sequential sample count is 4 and the Sequential
skip count is 2, then the two periods immediately preceding the predicted value period period will
be skipped, but the two periods before that will be sampled:
If the Sequential skip count is equal to or greater than the Sequential sample count, then no
samples will be collected for the year containing the predicted value period; only periods from
past years will be sampled:
290
Configure metadata Create or edit a predictor
Sample skip test
You can use the Sample skip test to skip samples from certain periods that would otherwise be
included, based on the results of testing an expression within those periods. This could be used,
for instance, in disease outbreak detection, where the sample skip test could identify previous
disease outbreaks, to exclude those samples from the prediction of a non-outbreak baseline
expected value.
The Sample skip test is an expression that should return a value of true or false, to indicate
whether or not the period should be skipped. It can be an expression that tests any data values in
the previous period. For example, it could test for a data value that was explicitly entered to
indicate that a previous period should be skipped. Or it could compare a previously predicted
value for a period with the actual value recorded for that period, to determine if that period should
be skipped.
Any periods for which the Sample skip test is true will not be sampled. For example:
Create or edit a predictor
1. Open the Maintenance app and click Other > Predictor.
3. In the Name field, type the predictor name.
6. Select an Output data element. Values generated by this predictor are stored as
aggregate data associated with this data element and the predicted period.
The value is rounded according to the value type of the data element: If the value type is
an integer type, the predicted value is rounded to the nearest integer. For all other value
types, the number is rounded to four significant digits. (However if there are more than four
digits to the left of the decimal place, they are not replaced with zeros.)
7. (Optional) Select an Output category combo. This dropdown will only show if the selected
data element has categoryCombos attached to it. If this is the case, you can select which
categoryCombo you would like to use.
291
Select a Period type.

8.
9. Assign one or more organisation unit levels. The output value will be assigned to an
organisation unit at this level (or these levels). The input values will come from the
organisation unit to which the output is assigned, or from any level lower under the output
organisation unit.
10. Create a Generator. The generator is the expression that is used to calculate the predicted
value.
1. Type a Description of the generator expression.
Option Description

of the values which compose it are missing.

case of missing data, and all missing values
will be treated effectively as a zero.
3. Enter the generator expression. You can build the expression by selecting data
elements for aggregate data, or program data elements, attributes or indicators.
Organisation unit counts are not yet supported.
To use sampled, past period data, you should enclose any items you select in one of
the following aggregate functions (note that these function names are case-
sensitive):
Aggregate function Means
avg(x) Average (mean) value of x
count(x) Count of the values of x
max(x) Maximum value of x
median(x) Median value of x
min(x) Minimum value of x
292
Aggregate function Means
percentileCont(p, x) Continuous percentile of x, where p is the

percentile as a floating point number
between 0 and 1. For example, p = 0 will
return the lowest value, p = 0.5 will return the
median, p = 0.75 will return the 75 th
percentile, p = 1 will return the highest value,
etc. Continuous means that the value will be
interpolated if necessary. For example,
percentileCont( 0.5, #{FTRrcoaog83} ) will
return 2.5 if the sampled values of data
element FTRrcoaog83 are 1, 2, 3, and 4.
stddev(x) Standard deviation of x. This function is

eqivalent to stddevSamp. It's suggested that
you use the function stddevSamp instead for
greater clarity.
stddevPop(x) Population standard deviation of x: sqrt(

sum( (x - avg(x))^2 ) / n )
stddevSamp(x) Sample standard deviation of x: sqrt(

sum( (x - avg(x))^2 ) / ( n - 1 ) ). Note that this
value is not computed when there is only
one sample.
sum(x) Sum of the values of x
Any items inside an aggregate function will be evaluated for all sampled past periods,
and then combined according to the formula inside the aggregate function. Any items
outside an aggregate function will be evaluated for the period in which the prediction
is being made.
You can build more complex expressions by clicking on (or typing) any of the
elements below the expression field: ( ) * / + - Days. Constant numbers may be
added by typing them. The Days option inserts [days] into the expression which
resolves to the number of days in the period from which the data came.
You can also use the following non-aggregating functions in your expression, either
inside aggregate functions, or containing aggregate functions, or independent of
aggregate functions:
293
Function Means
if(test, valueIfTrue, valueIfFalse) Evaluates test which is an expression that

evaluates to a boolean value -- see Boolean
expression notes below. If the test is true,
returns the valueIfTrue expression. If it is fal
se, returns the valueIfFalse expression.
isNull(item) Returns the boolean value true if the item is

null (missing), otherwise returns false. The it
em can be any selected item from the right
(data element, program data element, etc.).
isNotNull(item) Returns true if the item value is not missing

(not null), otherwise false.
firstNonNull(item [, item ...]) Returns the value of the first item that is not
missing (not null). Can be provided any
number of arguments. Any argument may
also be a numeric or string literal, which will
be returned if all the previous items have
missing values.
greatest(expression [, expression ...]) Returns the greatest (highest) value of the

expressions given. Can be provided any
number of arguments.
least(expression [, expression ...]) Returns the least (lowest) value of the

expressions given. Can be provided any
Boolean expression notes: A boolean expression must evaluate to true or false.

The following operators may be used to compare two values resulting in a boolean
expression: \<, >, !=, ==, >=, and \<=. The following operators may be used to
combine two boolean expressions: && (logical and), and || (logical or). The unary
operator ! may be used to negate a boolean expression.
Generator expression examples:
Generator expression Means
sum(#{FTRrcoaog83.tMwM3ZBd7BN}) Sum of the sampled values of data element

FTRrcoaog83 and category option
combination (disaggregation)
tMwM3ZBd7BN
294
Generator expression Means
avg(#{FTRrcoaog83}) + 2 * Average of the sampled values of of data

stddevSamp(#{FTRrcoaog83}) element FTRrcoaog83 (sum of all
disaggregations) plus twice its sample
standard deviation
sum(#{FTRrcoaog83}) / sum([days]) Sum of all sampled values of data element

FTRrcoaog83 (sum of all disaggregations)
divided by the number of days in all sample
periods (resulting in the overall average
daily value)
sum(#{FTRrcoaog83}) + #{T7OyqQpUpNd} Sum of all sampled values of data element

FTRrcoaog83 plus the value of data element
T7OyqQpUpNd in the period being
predicted for
1.2 * #{T7OyqQpUpNd} 1.2 times the value of data element

T7OyqQpUpNd, in the period being
predicted for
if(isNull(#{T7OyqQpUpNd}), 0, 1) If the data element T7OyqQpUpNd is null in

the period being predicted, then 0, otherwise
1.
percentileCont(0.5, #{T7OyqQpUpNd}) Continuous 50 th percentile of the sampled

values for data element T7OyqQpUpNd.
Note that this is the same as
median(#{T7OyqQpUpNd})
if(count(#{T7OyqQpUpNd}) == 1, 0, If there is one sample value present for data

stddevSamp(#{T7OyqQpUpNd})) element T7OyqQpUpNd, then 0, otherwise
the sample standard deviation of these
sample values. (Note that if no samples are
present then the stddevSamp returns no
value, so no value is predicted.)
11. (Optional) Create a Sample skip test. The sample skip test tells which previous periods if
any to exclude from the sample.
1. Type a Description of the skip test.
2. Enter the sample skip test expression. You can build the expression by selecting
data elements for aggregate data, or program data elements, attributes or indicators.
Organisation unit counts are not yet supported. As with the generator function, you
may click on (or type) any of the elements below the expression field: ( ) * / + - Days.
The non-aggregating functions described above may also be used in skip tests.
295
Configure metadata Create or edit a predictor group
The expression must evaluate to a boolean value of true or false. See Boolean
expression notes above.
Skip test expression examples:
Skip test expression Means
#{FTRrcoaog83} > #{M62VHgYT2n0} The value of data element FTRrcoaog83

(sum of all disaggregations) is greater than
the value of data element M62VHgYT2n0
(sum of all disaggregations)
#{uF1DLnZNlWe} > 0 The value of data element uF1DLnZNlWe

(sum of all disaggregations) is greater than
the zero
#{FTRrcoaog83} > #{M62VHgYT2n0} || The value of data element FTRrcoaog83

#{uF1DLnZNlWe} > 0 (sum of all disaggregations) is greater than
the value of data element M62VHgYT2n0
(sum of all disaggregations) or the value of
data element uF1DLnZNlWe (sum of all
disaggregations) is greater than the zero
12. Enter a Sequential sample count value.
This is for how many sequential periods the calculation should go back in time to sample
data for the calculations.
13. Enter an Annual sample count value.
This is for how many years the calculation should go back in time to sample data for the
calculations.
14. (Optional) Enter a Sequential skip count value.
This is how many sequential periods, immediately preceding the predicted value period,
should be skipped before sampling the data.
15. Click Save.
Create or edit a predictor group
1. Open the Maintenance app and click Other > Predictor group.
3. Type a Name. This field needs to be unique.
4. (Optional) In the Code field, assign a code. This field needs to be unique.
6. Double-click the Predictors you want to assign to the group.
7. Click Save.
296
4. Click Save.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
297
Configure metadata Manage push reports

3. Select a locale.
5. Click Save.
Manage push reports
About push reports
Push reports allows you to increase awareness and usage of data analysis by sending reports
with charts, tables and maps directly to users e-mail addresses.
• A push report gets its content from existing dashboards.
• A push report lists the dashboard items in the same order as on the dashboard.
• A push report can only contain dashboard items with charts, maps or tables.
• You create the push report and its schedule in the Maintenance app.
• The Title and Message parameters you set up in the Maintenance app, are included in
each report. The Name you give the report is not included in the report. Instead, the name
is used to identify the push analysis object in the system. This way a report can be named
one thing, and the title of the report can be another.
• When you run a push report job, the system compiles a list of recipients from the user
groups you've selected. The system then generates a report for each member of the
selected user groups. Each of the dashboard items are generated specifically for each
user. This means that the data included in the report reflects the data the user has access
to. All users could therefore get the same report (if all the data is "static") or custom reports
(if all the data is "dynamic"), or a combination of the two.
• Push reports are sent by e-mail to the recipients, not through the internal DHIS2 messaging
system. If a user doesn't have a valid e-mail, or if the job fails, no e-mails are sent. In this
case, the problem is logged on the server.
Note
The data generated in the push reports is public so verify that you don't
include any sensitive data.
298
Configure metadata About push reports
In the Maintenance app, you manage the following push reports objects:
Push reports objects in the Maintenance app
Push analysis Create, edit, clone, delete, show details, translate,

preview and run
299
Configure metadata Create or edit a push report
Create or edit a push report
1. Open the Maintenance app and click Other > Push analysis.
3. In the Name field, type the name of the scheduled report.
This name is not included in the report e-mail. Instead, the name is used to identify the
push analysis object in the system.
5. Add a report Title.
This title is included in the report e-mail.
6. (Optional) Add a Message.
This message is included in the report e-mail.
7. Select a Dashboard to base the report on.
8. Select and assign the user groups you want to send the report to.
9. Select a Scheduling frequency: Daily, Weekly or Monthly.
Note
If you schedule a push report to "Monthly" and "31", the scheduled report job
will not run if the month has less than 31 days.
10. (Optional) Select Enable to activate the push report job.
The job won't run until you activate it.
11. Click Save.
Preview push reports
2. In the push report list, locate the push report you want to preview.
3. Click the options menu and select Preview.
A preview of the push report opens in a new window.
Run push report jobs
2. In the push report list, locate the push report you want to run.
3. Click the options menu and select Run now.
The push report job runs immediately.
300
4. Click Save.
Note
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
301
Configure metadata Manage external map layers

3. Select a locale.
5. Click Save.
Manage external map layers
About external map layers
You can customize GIS by including map layers from various sources and combine them with your
own data in DHIS2. DHIS2 supports common map service formats such as Web Map Service
(WMS), Tile Map Service (TMS) and XYZ tiles.
Create or edit an external map layer
Note
DHIS2 only supports the Web Mercator projection (EPSG:3857) so
make sure that the external service supports this projection.
External map layer objects in the Maintenance app
External map layer Create, edit, clone, delete, show details and
translate
1. Open the Maintenance app and click Other > External map layer.
3. In the Name field, type a name that describes the content of the external map layer.
This is the name you'll see in the Maps app.
5. Select a Map service format.
DHIS2 supports three common map service formats:
◦ Web Map Service (WMS)
Image format: PNG format allows layers to be transparent, JPG format offers better
compression and is often faster to load.
Layers: A WMS can contain several individual layers, and you can specify which you
want to include (comma separated). Refer to the WMS GetCapabilities document to
see the available layers.
◦ Tile Map Service (TMS)
◦ XYZ tiles (can also be used for WMTS)
302
Enter the URL to the map service.

6.
Note
XYZ and TMS URLs must contain placeholders {}, for example: http://
{s}.tile.osm.org/{z}/{x}/{y}.png.
7. (Optional) Enter Source of the map layers. The field can contain HTML tags if you want to
link to the source.
When you use an external map service it is important to highlight where the data comes
from.
8. Select a Placement:
◦ Bottom - basemap: For the Maps app, this makes the external map layer selectable
as the base map (i.e. as an alternative to the DHIS2 base maps).
◦ Top - overlay: For the Maps app, this allows the external map to be added from the
Add Layer selection and placed anywhere above the base map.
9. (Optional) Add a legend.
You can add a legend in two ways:
◦ Select a predefined Legend to describe the colors of the map layer.
Tip
Click Add new to create legends that you're missing. In the form that
opens, create the legends you need. When you're done, click Refresh
values.
◦ Enter a link to an external image legend in Legend image URL.
These are often provided for WMS. See under LegendURL in the WMS
GetCapabilites document.
10. Click Save.
4. Click Save.
Note
303
Warning
in time.
3. Click Confirm.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
Manage SQL Views
The SQL View functionality of DHIS2 will store the SQL view definition internally, and then
materialize the view when requested.
Database administrators must be careful about creating database views directly in the DHIS2
database. For instance, when the resource tables are generated, all of them will first be dropped
and then re-created. If any SQL views depend on these tables, an integrity violation exception will
be thrown and the process will be aborted.
304
Configure metadata Creating a new SQL view
The SQL views are dropped in reverse alphabetical order based on their names in DHIS2, and
created in regular alphabetical order. This allows you to have dependencies between SQL views,
given that views only depend on other views which come earlier in the alphabetical order. For
instance, "ViewB" can safely depend on "ViewA". Otherwise, having views depending on other
view result in an integrity violation error.
Creating a new SQL view
To create a new SQL view, click Apps > Maintenance > Other > SQL View and click the Add +
button.
The "Name" attribute of the SQL view will be used to determine the name of the table that DHIS2
will create when the view is materialized by the user. The "Description" attribute allows one to
provide some descriptive text about what the SQL view actually does. Finally, the "SQL query"
should contain the SQL view definition. Only SQL "SELECT" statements are allowed and certain
sensitive tables (i.e. user information) are not accessible Press "Save" to store the SQL view
definition.
SQL View management
In order to utilize the SQL views, simply click the view and from the context menu, choose
"Execute query". Once the process is completed, you will be informed that a table has been
created. The name of the table will be provided, and is composed from the "Description" attribute
provided in the SQL view definition. Once the view has been generated, you can view it by
clicking the view again, and selecting "Show SQL View".
Tip
If you have a view which depends on another view, you should be
careful about how the views are named. When analytics is run on the
DHIS2 server, all views must be dropped, and are recreated. When
analytics starts, the views are dropped in alphabetical order, and then
recreated in reverse alphabetical order. Thus, if view A depends on view
B, it must appear before view B in alphabetical order. If it appears after
305
Configure metadata Manage Locales
view B in alphabetical order, analytics may fail, as the view with

dependencies will not be dropped in the correct order.
Manage Locales
It is possible to create custom locales in DHIS2. In addition to the locales available through the
system, you might want to add a custom locale such as "English" and "Zambia" to the system. This
would allow you to translate metadata objects to local languages, or to account for slight variants
between countries which use a common metadata definition.
The locale is composed of a language along with a country. Select the desired values and press
"Add". This custom locale will now be available as one of the translation locales in the system.
Edit multiple object groups at once
The Metadata group editor in the Maintenance app allows you to edit multiple object groups at
the same time. You can edit the following objects types:
Object types in the Metadata group editor
Category option
Category option group
Data element Add one data element to multiple data element

groups
Remove one data element from multiple data

element groups
Data element group Add multiple data elements to one data element
group
Remove multiple data elements from one data

element group
306
Configure metadata Edit multiple objects in an object group
Indicator Add one indicator to multiple indicator groups
Remove one indicator from multiple indicator

groups
Indicator group Add multiple indicators to one indicator group
Remove multiple indicators from one indicator

group
Edit multiple objects in an object group
1. Open the Maintenance app and click Metadata group editor.
2. Click Manage items in group.
3. Select an object group type, for example Indicator groups.
4. Select an object group, for example HIV.
5. In the left-hand list, select the object(s) you want to add to the object group and click the
right arrow.
6. In the right-hand list, select the object(s) you want to remove from the object group and
click the left arrow.
Edit an object in multiple object groups
1. Open the Maintenance app and click Metadata group editor.
2. Click Manage groups for item.
3. Select an object type, for example Indicators.
4. Select an object, for example ANC LLITN coverage.
5. In the left-hand list, select the objects group(s) you want to add the object to and click the
right arrow.
6. In the right-hand list, select the object group(s) you want to remove the object from and
click the left arrow.
307
Configure programs in the Maintenance app About programs
Configure programs in the Maintenance app

About programs
Traditionally, public health information systems have been reporting aggregated data of service
provision across its health programs. This does not allow you to trace the people provided with
these services. In DHIS2, you can define your own programs with stages. These programs are a
essential part of the "tracker" functionality which lets you track individual records. You can also
track other ‘entities’ such as wells or insurances. You can create two types of programs:
Program types
Program type Description Examples of use
Event program Single event without registration To record health cases without
program (anonymous program or registering any information into
SEWoR) the system.
Anonymous, individual events To record survey data or

are tracked through the health surveillance line-listing.
system. No person or entity is
attached to these individual
transactions.
Has only one program stage.
Tracker program Single event with registration To record birth certificate and
program (SEWR) death certificate.
An entity (person, commodity,

etc.) is tracked through each
individual transaction with the
health system
Has only one program stage.
A tracked entity instance (TEI)

can only enroll in the program
once.
Multi events with registration Mother Health Program with

program (MEWR) stages as ANC Visit (2-4+),
Delivery, PNC Visit.
An entity (person, commodity,
etc.) is tracked through each
individual transaction with the
health system
Has multiple program stages.
To create a program, you must first configure several types of metadata objects. You create these
metadata objects in the Maintenance app.
++++
308
Program metadata objects in the Maintenance app
Object type Description Available functions
Event program A program to record single event Create, edit, share, delete, show
without registration details and translate
Tracker program A program to record single or Create, edit, share, delete, show
multiple events with registration details and translate
Program indicator An expression based on data Create, edit, clone, share, delete,
elements and attributes of show details and translate
tracked entities which you use to
calculate values based on a
formula.
Program rule Allows you to create and control Create, edit, clone, delete, show
dynamic behaviour of the user details and translate
interface in the Tracker Capture
and Event Capture apps.
Program rule variable Variables you use to create Create, edit, clone, delete, show
program rule expressions. details and translate
Relationship type Defines the relationship between Create, edit, clone, share, delete,
tracked entity A and tracked show details and translate
entity B, for example mother and
child.
309
Tracked entity type Types of entities which can be Create, edit, clone, share, delete,
tracked through the system. Can show details and translate
be anything from persons to
commodities, for example a
medicine or a person.
A program must have one

tracked entity. To enrol a tracked
entity instance into a program,
the tracked entity of an entity and
tracked entity of a program must
be the same.
Note
A program must be specified

with only one tracked entity.
Only tracked entity as same
as the tracked entity of
program can enroll into that
program.
Tracked entity attribute Used to register extra information Create, edit, clone, share, delete,
for a tracked entity. show details and translate
Can be shared between

programs.
Program A program consist of program Create, edit, share, delete,

stages. assign to organisation units,
show details and translate
Program stage A program stage defines which Create, edit, share, change sort
actions should be taken at each order, delete, show details and
stage. translate
Program indicator group A group of program indicators Create, edit, clone, share, delete,
show details and translate
Validation rule A validation rule is based on an Create, edit, clone, share, delete,
expression which defines a show details and translate
relationship between data
element values.
310
Configure programs in the Maintenance app Configure event programs in the Maintenance app
Program notification Automated message reminder Create, edit and delete
Set reminders to be
automatically sent to enrolled
tracked entity instances before
scheduled appointments and
after missed visits.
Program stage notification Automated message reminder Create, edit and delete
Set reminders to be
automatically sent whenever a
program stage is completed, or
before or after the due date.
Configure event programs in the Maintenance app
About event programs
Single event without registration programs are called event programs. You configure them in the
Maintenance app. Event programs can have three types of data entry forms:
Types of data entry forms for event programs
Form type Description
Basic Lists all data elements which belong to the program.

You can change the order of the data elements.
Section A section groups data elements. You can then

arrange the order of the sections to create the
desired layout of the data entry form.
Custom Defines the data entry form as HTML page.
Note
• Custom forms takes precedence over section forms if both are

present.
• If no custom or section form are defined, the basic form will be
used.
• The Android apps only supports section forms.
You can create program notifications for event programs. The notifications are sent either via the
internal DHIS2 messaging system, via e-mail or via text messages (SMS). You can use program
notifications to, for example, send an automatic reminder to a tracked entity 10 days before a
311
Configure programs in the Maintenance app Workflow: Create an event program
scheduled appointment. You use the program’s tracked entity attributes (for example first name)
and program parameters (for example enrollment date) to create a notification template. In the
Parameters field, you'll find a list of available tracked entity attributes and program parameters.
Workflow: Create an event program
1. Enter the event program details.
2. Assign data elements.
3. Create data entry form(s): Basic, Section or Custom.
4. Assign the program to organisation unit(s).
5. Create program notification(s).
Create or edit an event program
Enter event program details
1. Open the Maintenance app and click Program > Program.
2. Click the add button and select Event Program in the popup menu.
3. Enter program details, then click next.
Field Description
Name The name of the program.
Color Color used for this program in the data capture

apps.
Icon Icon used for this program in the data capture

apps.
Short name A short name of the program. The short name is

used as the default chart or table title in the
analytics apps.
Description A detailed description of the program.
Version The version of the program. This is used for

example when people collect data offline in an
Android implementation. When they go online
and synchronize their metadata, they should get
the latest version of the program.
Category combination The category combination you want to use. The

default setting is None.
312
Configure programs in the Maintenance app Create or edit an event program
Field Description
Data approval workflow The data approval workflow you want to use.
The default setting is No value.
Completed events expiry date Defines the number of days for which you can
edit a completed event. This means that when
an event is completed and the specified number
of expiry days has passed, the event is locked.
If you set "Completed events expiry days" to 10",

an event is locked ten days after the completion
date. After this date you can no longer edit the
event.
Expiry period type The expiry days defines for how many days after
the end of the previous period, an event can be
Expiry days
edited. The period type is defined by the expiry
period type. This means that when the specified
number of expiry days has passed since the end
date of the previous period, the events from that
period are locked.
If you set the expiry type to "Monthly" and the

expiry days to "10" and the month is October,
then you can't add or edit an event to October
after the 10 th of November.
Block entry form after completed

Select checkbox to block the entry form after
completion of the event of this program.
This means that the data in the entry form can't

be changed until you reset the status to
incomplete.
Feature type
Sets wether the program is going to capture a
geographical feature type or not.
4. None Nothing is captured.
5. Polygon An area is captured. For single event

programs the area will be the area representing
the event being captured. For tracker programs,
the area will represent the area of the
enrollment.
6. Point A point/coordinate is captured. For single
event programs the point will be representing
the event being captured. For tracker programs,
the point will represent the enrollment.
313
Field Description
Validation strategy Sets the server and client side validation

requirement. > Data type validations is always
performed regardless of the validation strategy.
An integer field is never stored containing text,
for example.
7. On complete This option will enforce required
field and error messages to be fixed when
completing the event, but the event can be
saved to the server without passing these
validation requirements.
◦ For legacy reasons, this is always the
validation strategy for tracker programs,
where each data value in the event is
stored to the server while entrering data.
8. On update and insert This option will enforce

required field validation when saving the event
to the server regardless of the completion status.
When using this option no events can be stored
without passing validations.
Pre-generate event UID Select checkbox to pre-generate unique event

id numbers.
Description of report date

Type a description of the report date.
This description is displayed in the case entry

form.
9. Click next.
Assign data elements
1. Click Assign data elements.
2. In the list of available items, double-click the data elements you want to assign to the event
program.
3. (Optional) For each data element, add additional settings:
Setting Description
Compulsory The value of this data element must be filled into

data entry form before you can complete the
event.
Allow provided elsewhere Specify if the value of this data element comes
from other facility, not in the facility where this
data is entered.
314
Setting Description
Display in reports Displays the value of this data element into the
single event without registration data entry
function.
Date in future Will allow user to select a date in future for date
data elements.
Mobile render type Can be used to select different render types for
mobile devices. Available options vary
depending on the data element's value type. For
example, for a numerical value you may select
"Default", "Value", "Slider", "Linear scale", and
"Spinner".
Desktop render type WARNING: NOT IMPLEMENTED YET.
Can be used to select different render types for

desktop (i.e. the web interface). Available
options vary depending on the data element's
value type. For example, for a numerical value
you may select "Default", "Value", "Slider",
"Linear scale", and "Spinner".
4. Click next.
Create data entry forms
The data entry forms decide how the data elements will be displayed to the user in the Event
Capture app.
1. Click Create data entry form.
2. Click Basic, Section or Custom.
3. To create a Basic data entry form: Drag and drop the data elements in the order you want.
4. To create a Section data entry form:
1. Click the add button and enter a section's name, description and render type for
desktop and mobile.
2. Click the section so it's highlighted by a black line.
3. Add data elements by clicking the plus sign next to the data elements' names.
4. Repeat above steps until you've all the sections you need.
5. Change the section order: click the options menu, then drag the section to the place
you want.
315
To create a Custom data entry from: Use the WYSIWYG editor to create a completely
5. customized form. If you select Source, you can paste HTML code directly in the editing
area. You can also insert images for example flags or logos.
6. Click next.
Access
Access options decide who can capture data for the program or view/edit the program's
metadata. A program can be shared to organisation units, and in addition, the main program and
any program stages' access options can be configured through the Sharing dialog. Access
options are available in the Access tab.
Assign organization units:
1. In the organisation tree, double-click the organisation units you want to add to the program
to.
arrow symbol), or by searching for it by name. The selected organisation units display in
orange.
Change roles and access:
1. Scroll down to the Roles and access section.
The first row shows the main program's access options, and each subsequent row shows
the options of one program stage. Program stages with a warning icon (exclamation mark)
contain access options that deviate from the main program, meaning they are accessed by
a different combination of users.
2. Click on either of the rows and the Sharing dialog will show.
3. Modify the access options accordingly. See documentation on the sharing dialog for details.
4. Click the Apply button.
5. Repeat the process for each program/program stage. You can also copy all access options
from the main program to your child programs:
1. Select the program stages you want to have similar access options as the main
program by toggling the checkboxes on the right hand side of the program stages.
You can also choose to Select all program stages, Deselect all program stages or
Select similar stages, in terms of access options, to that of the main program.
Similar stages are toggled by default.
2. Click Apply to selected stages
Create program notifications
1. Create the message you want to send:
1. Click What to send?.
2. Enter a Name.
3. Create the Subject template: Double-click the parameters in the Template variables
field to add them to your subject.
316
Note
The subject is not included in text messages.
4. Create the Message template: Double-click the parameter names in the Template
variables list to add them to your message.
Dear A{w75KJ2mc4zz}, You're now enrolled in V{program_name}.
2. Define when you want to send the message:
1. Click When to send it?.
2. Select a Notification trigger.
Notification trigger Description
Program stage completion The program stage notification is sent when

the program stage is completed
Days scheduled (due date) The program stage notification is sent XX

number of days before or after the due date
You need to enter the number of days before

or after the scheduled date that the
notification will be send.
3. Define who you want to send the message to:
1. Click Who to send it to?.
2. Select a Notification recipient.
Notification recipient Description
Tracked entity instance Receives program notifications via e-mail or

text message.
To receive a program notification, the

recipient must have an e-mail address or a
phone number attribute.
Organisation unit contact Receives program notifications via e-mail or

text message.
To receive a program notification, the

receiving organisation unit must have a
registered contact person with e-mail
address and phone number.
317
Configure programs in the Maintenance app Reference information: Program notification parameters
Notification recipient Description
Users at organisation unit All users registered to the selected

organisation unit receive program
notifications via the internal DHIS2
messaging system.
User group All members of the selected user group

receive the program notifications via the
internal DHIS2 messaging system
Program TBA
3. Click Save.
4. Repeat above steps to create all the program notifications you need.
5. Click Save.
Note
You configure when the program notifications are sent in the Data
Administration app > Scheduling > Program notifications scheduler.
• Click Run now to send the program notifications immediately.

• Select a time and click Start to schedule the program notifications
to be send at a specific time.
Reference information: Program notification parameters
Program notification parameters to use in program notifications
Notification type Variable name Variable code
Program Current date

V{current_date}
Days since enrollment date

V{days_since_enrollment_date}
Enrollment date
V{enrollment_date}
Incident date
V{incident_date}
318
Configure programs in the Maintenance app Configure tracker programs in the Maintenance app
Organisation unit name

V{org_unit_name}
Program name
V{program_name}
Program stage Current date

V{current_date}
Days since due date

V{days_since_due_date}
Days until due date

V{days_until_due_date}
Due date
V{due_date}

V{org_unit_name}
Program name
V{program_name}
Program stage name

V{program_stage_name}
Configure tracker programs in the Maintenance app
About Tracker programs
Single or multiple event programs with registration are called Tracker programs. A program must
be specified with only one tracked entity. Only tracked entities that are the same as the tracked
entity of program can enroll into that program. A program needs several types of metadata that
you create in the Maintenance apps.
Workflow: Create a tracker program
1. Enter the tracker program details.
2. Enter enrollment details.
3. Assign attributes and create section or custom registration form.
319
Configure programs in the Maintenance app Create or edit a Tracker program
Create program stages.

4.
5. Configure access, and assign to organisation units.
6. Create program and program stage notification(s).
Create or edit a Tracker program
1. Open the Maintenance app and click Program > Program.
2. Click the add button and select Tracker Program in the popup menu.
Enter program details
Field Description
Name The name of the program.
Color Color used for this program in Tracker capture.
Icon Icon used for this program in Tracker capture
Short name A short name of the program. The short name is

used as the default chart or table title in the
analytics apps.
Description A detailed description of the program.
Version The version of the program. This is used for

example when people collect data offline in an
Android implementation. When they go online and
synchronize their metadata, they should get the
latest version of the program.
Tracked Entity Type The tracked entity type you want to use. A program
can only have one type of tracked entity.
Category combination The category combination you want to use. The

default setting is None.
Display front page list Select checkbox to display a list of Tracked Entity
Instances in Tracker Capture. If not selected, the
Search will be displayed.
First stage appears on registration page Select checkbox to display the first program stage
together with the registration (enrollment).
Access level Choose the access level of the program.
320
Field Description
Completed events expiry days Defines the number of days for which you can edit a
completed event. This means that when an event is
completed and the specified number of expiry days
has passed, the event is locked.
If you set "Completed events expiry days" to 10", an

event is locked ten days after the completion date.
After this date you can no longer edit the event.
Expiry period type The expiry days defines for how many days after the
end of the previous period, an event can be edited.
Expiry days
The period type is defined by the expiry period type.
This means that when the specified number of
expiry days has passed since the end date of the
previous period, the events from that period are
locked.
If you set the expiry type to "Monthly" and the expiry

days to "10" and the month is October, then you
can't add or edit an event to October after the 10th of
November.
Minimum number of attributes required to search

Specify the number of tracked entity attributes that
needs to be filled in to search for Tracked Entities in
the Program.
Maximum number of tracked entity instances to

Specify the maximum number of tracked entity
return in search
instances that should be returned in a search. Enter
0 for no limit.
Enter enrollment details
Field Description
Allow future enrollment dates

Select checkbox if you want to allow tracked entity
instances to be enrolled in the program on a future
date.
Allow future incident dates

Select checkbox if you want to allow the incident
date in the program to be on a future date.
321
Field Description
Only enroll once (per tracked entity instance

Select checkbox if you want a tracked entity to be
lifetime)
able to enroll only once in a program. This setting is
useful for example in child vaccination or post-
mortem examination programs where it wouldn’t
make sense to enroll a tracked entity more than
once.
Show incident date

This setting allows you to show or hide the incident
date field when a tracked entity enroll in the
program.
Description of incident date

Type a description of the incident date
For example:
In an immunization program for child under 1 year

old, the incident date is the child's birthday.
In a maternal program, the incident date is the date

of last menstrual period.
Type a description of the enrollment date

The date when the tracked entity is enrolled into the
program
Ignore overdue events

When a tracked entity enrolls into the program, the
events corresponding to the program stages are
created. If you select this checkbox, the system will
not generate overdue events.
Feature type
• None:Nothing is captured.
• Polygon: An area is captured. For single
event programs the area will be the area
representing the event being captured. For
tracker programs, the area will represent the
area of the enrollment.
• Point:: A point/coordinate is captured. For
single event programs the point will be
tracker programs, the point will represent the
enrollment.
Related program
Choose a Tracker program which is related to the
program you are creating, for example an ANC and
a Child program.
322
Assign tracked entity attributes.
1. In the list of Available program tracked entity attributes, double-click the attributes you
want to assign to the program.
2. (Opptional) For each assigned attribute, add additional settings:
Setting Description
Display in list Displays the value of this attribute in the list of

tracked entity instances in Tracker capture.
Mandatory The value of this attribute must be filled into data

entry form before you can complete the event.
Date in future Will allow user to select a date in future for date
attributes.
mobile devices. Available options vary
depending on the attribute's value type. For
"Spinner".

desktop (i.e. the web interface). Available
options vary depending on the attribute's value
type. For example, for a numerical value you
may select "Default", "Value", "Slider", "Linear
scale", and "Spinner".
3. Create registration form
The registration form defines how the attributes will be displayed to the user in consuming
apps, such as Android and Tracker Capture.
1. Click Create registration form.
2. Click Section or Custom.
3. To create a Section form:
1. Click the add button and enter a section’s name, description and render type
for desktop and mobile.
2. Click the section so it is highlighted by a black border.
3. Add data elements by clicking the plus sign next to the name of the data
elements you wish to add.
323
4. Repeat above steps until you have all the sections you need. To change the
section order: click the options menu, then drag the section to the place you
want.
4. To create a Custom registration form: Use the WYSIWYG editor to create a

completely customized form. If you select Source, you can paste HTML code directly
in the editing area. You can also insert images for example flags or logos.
5. Click add stage.
Create program stages
A program consist of program stages. A program stage defines which actions should be taken at
each stage.
Note
Changes to a program stage is not saved until you save the program.
1. Click the plus sign to create a program stage.

2. Enter program stage details: 1. Enter a Name. 2. (Optional) select a Color and an Icon that
will be used by the data capture apps to identify this program stage. 3. Enter a
Description. 4. In the Scheduled days from start field, enter the minimum number of days
to wait for starting the program stage.
3. Enter repeatable program stage details.
1. Specify if the program stage is Repeatable or not.
3. Clear Display generate event box after completed if you don't want to display
Create new event box to create new event for a repeatable stage after you click
Complete for an event of the stage in data entry form. This field is selected by
default.
4. Enter Standard interval days. The number of days to repeat the repeatable program
stage.
5. (Optional) Select a Default next scheduled date. This will show a list of assigned
data elements of type date. If an element is selected, the Tracker client will use this
as the default starting date. The data element can be used by program rules to
dynamically schedule intervals between events.
4. Enter form details
Option Action
Auto-generate event Clear check box to prevent creating an event of this

program stage automatically when a entity is
enrolled in the program.
Open data entry form after enrollment Select check box to automatically open the event of
this stage as soon as the entity has enrolled into the
program.
324
Option Action
If you have selected the Open data entry form after

Report date to use
enrollment check box, also select a Report date to
use: Date of incident or Date of enrollment.
This is the date used as report date for an event that

has been opened automatically.
If the Report date to use is selected as one of those

two ('incident date'/'enrollment date'), in Dashboard,
the 'Report date' of the event will be set as one of
those two.
User assignment of events Select check box to enable user assignment of the
program stage.
This means that in Tracker capture there will be a

list of users to which the event can be assigned.
Block entry form after completed Select check box to block the entry form after
completion of the event of this stage.
This means that the data in the entry form can't be

changed until you reset the status to incomplete.
Ask user to complete program when stage is Select check box to trigger a pop-up which asks the
completed user if he/she wants to create the event of next
stage.
Ask user to create new event when stage is Select check box to trigger a pop-up which asks the
complete users if he/she wants to create a new event of this
stage when an event of this stage is completed.
This property is active only if you have selected Re

peatable.
Generate events by enrollment date Check on it for auto-generating due dates of events
from program-stages of this program based on the
enrollment date. If it is not checked, the due dates
are generated based on incident date.
Hide due dates Select checkbox to hide due dates for events.
325
Option Action
Feature type
• None:Nothing is captured.
• Polygon: An area is captured. For single
event programs the area will be the area
tracker programs, the area will represent the
area of the enrollment.
• Point:: A point/coordinate is captured. For
single event programs the point will be
tracker programs, the point will represent the
enrollment.
Pre-generate event UID Select check box to pre-generate unique event id

numbers.
Description of report date Type a description of the report date.
This description is displayed in the data entry form.
Description of due date Type a description of the due date.
1. Assign data elements to program stage:
1. In the list of Available data elements, double-click the data elements you want to
assign to the program stage.
2. For each assigned data element, review the properties. You can select:
Option Action
Compulsory The value of this data element must be filled into

data entry form before completing the event.
Allow provided elsewhere Specify if the value of this data element comes from
other facility, not in the facility where this data is
entered.
Display in reports Display the value of this data element into the single
event without registration data entry function.
Date in future Allow to select a date in future for date data

elements.
326
Option Action
Skip synchronization Allow data element to be skipped when running

data synchronization jobs.
mobile devices. Available options vary depending
on the attribute's value type. For example, for a
numerical value you may select "Default", "Value",
"Slider", "Linear scale", and "Spinner".

desktop (i.e. the web interface). Available options
vary depending on the attribute's value type. For
"Spinner".
1. Create data entry forms for program stage
The data entry forms decide how the data elements will be displayed to the user in the
Tracker Capture app.
1. Click Create data entry form.
2. Click Basic, Section or Custom.
3. To create a Basic data entry form: Drag and drop the data elements in the order you
want.
4. To create a Section data entry form:
1. Click the add button and enter a section's name, description and render type
for desktop and mobile.
2. Click the section so it's highlighted by a black border.
3. Add data elements by clicking the plus sign next to the data elements' names.
4. Repeat above steps until you've all the sections you need.
5. Change the section order: click the options menu, then drag the section to the
place you want.
5. To create a Custom data entry from: Use the WYSIWYG editor to create a
completely customized form. If you select Source, you can paste HTML code directly
in the editing area. You can also insert images for example flags or logos.
6. Click add stage.
327
Access
Access options decide who can capture data for the program or view/edit the program's
metadata. A program can be shared to organisation units, and in addition, the main program and
any program stages' access options can be configured through the Sharing dialog. Access
options are available in the Access tab.
Assign organization units:
1. In the organisation tree, double-click the organisation units you want to add to the program
to.
arrow symbol), or by searching for it by name. The selected organisation units display in
orange.
Change roles and access:
1. Scroll down to the Roles and access section.
The first row shows the main program's access options, and each subsequent row shows
the options of one program stage. Program stages with a warning icon (exclamation mark)
contain access options that deviate from the main program, meaning they are accessed by
a different combination of users.
2. Click on either of the rows and the Sharing dialog will show.
3. Modify the access options accordingly. See documentation on the sharing dialog for details.
4. Click the Apply button.
5. Repeat the process for each program/program stage. You can also copy all access options
from the main program to your child programs:
1. Select the program stages you want to have similar access options as the main
program by toggling the checkboxes on the right hand side of the program stages.
You can also choose to Select all program stages, Deselect all program stages or
Select similar stages, in terms of access options, to that of the main program.
Similar stages are toggled by default.
2. Click Apply to selected stages
Create program notifications
You can create program notifications for programs with registration and their program stages. The
notifications are sent either via the internal DHIS2 messaging system, via e-mail or via text
messages (SMS). You can use program notifications to, for example, send an automatic reminder
to a tracked entity 10 days before a scheduled appointment. You use the program’s tracked entity
attributes (for example first name) and program parameters (for example enrollment date) to
create a notification template.
1. Open the Maintenance app and click Program and then notifications.
A list of existing program notifications for the selected program opens. If the program
doesn't have any program notifications, the list is empty.
2. Click on add button and select Program notification.
328
![](resources/images/program/what_to_send.png)
3. Enter a Name.
Double-click the parameters in the Parameters field to add them to your subject.
Note
Double-click the parameter names in the Parameters field to add them to your message.
Dear A{w75KJ2mc4zz}, You're now enrolled in V{program_name}.
6. In the When-to-send it field, select what should trigger the notification.
329
Trigger Description Note
Program enrollment The program notification is -

sent when the TEI enrols in
the program.
Program completion The program notification is -

sent when the program of TEI
is completed
Days scheduled (incident The program notification is You need to enter the number
date) sent XX number of days of days before or after the
before or after the incident scheduled date that the
date notification will be send.
Days scheduled (enrollment The program notification is You need to enter the number
date) sent XX number of days of days before or after the
before or after the enrollment scheduled date that the
date notification will be send.
Program Rule Notification will be triggered Program rule with

as a result of program rule ProgramRuleActionType.SEN
exeuction. DMESSAGE need to be in
place to make this trigger
successful.
7. In the Who-to-send-it field, select who should receive the program notification.
Recipient type Description Note
Tracked entity instance Receives program To receive a program

notifications via e-mail or text notification, the recipient must
message. have an e-mail address or a
Organisation unit contact Receives program To receive a program

notifications via e-mail or text notification, the receiving
message. organisation unit must have a
registered contact person with
e-mail address and phone
number.
330
Users at organisation unit:

All users registered to the -
selected organisation unit
receive program notifications
via the internal DHIS2
messaging system.
User group All members of the selected -

user group receive the
program notifications via the
internal DHIS2 messaging
system
Limit To Hierarchy Send notification only to those This option is only available
users who belong to any of the when User Group is selected
organisation unit in the as recipient.
hierarchy.
Parent OrgUnit Only Send notification only to those This option is only available
users who belong to parent when User Group is selected
organisation unit. as recipient.
Program Attribute TrackedEntityAttribute can This parameter will only be

also be selected as recipient. effective if
TrackedEntityAttribute value
type is PHONE_NUMBER/
EMAIL.
8. Click Save.
331
Configure programs in the Maintenance app Create a program stage notification
Create a program stage notification
332
333
1. Open the Maintenance app and click Program and then notifications.
A list of existing program stage notifications for the selected program stage opens. If the
program stage doesn't have any program stage notifications, the list is empty.
2. Click on add button and select**Program stage notification**.
3. Click Add new.
4. Enter a Name.
Double-click the parameter names in the Parameters field to add them to your subject.
Note
Double-click the parameter names in the Parameters field to add them to your message.
Dear A{w75KJ2mc4zz}, please come to your appointment the V{due_date}.
7. In the When-to-send-it field, select what should trigger the notification.
334
Trigger Description Note
Program stage completion The program stage notification -

is sent when the program
stage is completed
Days scheduled (due date) The program stage notification You need to enter the number
is sent XX number of days of days before or after the
before or after the due date scheduled date that the
notification will be send.
Program Rule Notification will be triggered Program rule with

as a result of program rule ProgramRuleActionType.SEN
execution. DMESSAGE need to be in
place to make this trigger
successful.
8. In the Recipients field, select who should receive the program stage notification. You can
select:
Tracked entity instance Receives program To receive a program stage

notifications via e-mail or text notification, the recipient must
message. have an e-mail address or a
Organisation unit contact Receives program To receive a program stage

notifications via e-mail or text notification, the receiving
message. organisation unit must have a
registered contact person with
e-mail address and phone
number.
The system selects the same

organisation unit as where the
event took place.
Users at organisation unit:

All users registered to the -
selected organisation unit
receive program notifications
via the internal DHIS2
messaging system.
335
Configure programs in the Maintenance app Reference information: Program notification parameters
User group All members of the selected -

user group receive the
program notifications via the
internal DHIS2 messaging
system
Limit To Hierarchy Send notification only to those -

users who belong to any of the
organisation unit in the
hierarchy.
Parent OrgUnit Only Send notification only to those -

users who belong to parent
organisation unit.
Data Element Data Element associated with Data Element will only be
ProgramStage can be effective if DataElement has
selected as recipient. value type PHONE_NUMBER
/EMAIL.
9. Click Save.
Reference information: Program notification parameters
Program notification parameters to use in program notifications
Program Current date

V{current_date}
Days since enrollment date

V{days_since_enrollment_date}
Enrollment date
V{enrollment_date}
Incident date
V{incident_date}

V{org_unit_name}
336
Configure programs in the Maintenance app Configure program indicators
Program name
V{program_name}
Program stage Current date

V{current_date}
Days since due date

V{days_since_due_date}
Days until due date

V{days_until_due_date}
Due date
V{due_date}

V{org_unit_name}
Program name
V{program_name}
Program stage name

V{program_stage_name}
Configure program indicators
About program indicators
Program indicators are expressions based on data elements and attributes of tracked entities
which can be used to calculate values based on a formula. Program indicators consist of an
aggregation type, an analytics type, an expression and a filter.
Program indicators are evaluated based on the assigned aggregation type, expression and filter.
The order of evaluation is:
1. The filter will filter the events which become part of the evaluation/aggregation routine.
2. The expression will be evaluated per event.
3. All evaluated expression values will be aggregated according to the aggregation type of the
program indicator.
Program indicator components
337
Configure programs in the Maintenance app About program indicators
Program rule component Description
Aggregation type The aggregation type determines how the program

indicator will be aggregated. The following
aggregation types are available:
• Average
• Average (number)
• Average (number, disaggregation)
• Average (sum in organisation unit hierarchy)
• Average (sum of numbers)
• Average (sum of numbers, disaggregation)
• Average (Yes/No)
• Count
• Custom
The "custom" aggregation type allows you to

specify the aggregation type in-line in the
expression. All other aggregation types are
applied to the entire expression.
Using the "custom" aggregation type might

lead to an exception of the order of
evaluation described above where
individual parts of the expression can be
evaluated and aggregated, as opposed to
the entire expression being evaluated prior
to aggregation.
• Default
• Max
• Min
• None
• Standard deviation
• Sum
• Variance
338
Analytics type The available analytics types are event and enroll
ment.
The analytics type defines whether the program

indicator is calculated based on events or program
enrollments. This has an impact on what type of
calculations can be made.
• Events implies a data source where each

event exists as an independent row. This is
suitable for performing aggregations such as
counts and sums.
• Enrollments implies a data source where all

events for a single enrollment is combined
on the same row. This allows for calculations
which can compare event data from various
program stages within a program
enrollment.
339
Analytics period boundaries Defines the boundaries for the program indicator
calculation. The boundaries determine which
events or enrollments gets included in
aggregations, always relative to the aggregate
reporting period start and end. When creating the
program indicator, the default boundaries will get
preselected based on analytics type.
• For analytics type event, the default

boundaries will be configured to
encapsulate any events with an event date
after the reporting period starts and before
the reporting period ends.
• For analytics type enrollment, the default

boundaries will encapsulate all enrollments
with an enrollment date after the reporting
date starts and before the reporting period
ends. In addition, the default enrollment
program indicator evaluates the newest
event for all program stages regardless of
date.
It is possible to change the upper and lower

boundaries to include a longer or shorter period
relative to the reporting period, or delete one of the
boundaries - in effect returning all data before or
after a certain period. It is also possible to add more
constraints, for example to make an enrollment
program indicator only include event data up to a
given point in time.
• Boundary target: Can be incident date, event

date, enrollment date or custom. Designates
what is being constrained by the boundary.
custom is used make boundary that target

either a date data element, tracked entity
attribute or the presence of an event in a
program stage. This is done with a custom
expression on the form:
◦ Data element of type date:

#{programStageUid.dataElementUi
d}.
#{A03MvHHogjR.a3kGcGDCuk6}
◦ Tracked entity attribute of type date:

#{attributeUid}.
A{GPkGfbmArby}
◦ Presence of one event in a specific

program stage:
PS_EVENTDATE:programStageUid.
340
Expression The expression defines how the indicator is being

calculated. The expression can contain references
to various entities which will be substituted with a
related values when the indicator is calculated:
• Data elements: Will be substituted with the

value of the data element for the time period
and organisation unit for which the
calculation is done. Refers to both program
stage and data element.
• Attributes: Will be substituted with the value

of the attribute for the person / tracked entity
for which the calculation is done.
• Variables: Will be substituted with special

values linked to the program, including
incident date and date of enrollment for the
person, current date and count of values in
the expression for the time period and
organisation unit for which the calculation is
done.
• Constants: Will be substituted with the value

of the constant.
The expression is a mathematical expression and

can also contain operators.
For single event programs and tracker programs

with analytics type event, the expression will be
evaluated per event, then aggregated according to
its aggregation type.
For tracker programs with analytics type enrollment,

the expression will be evaluated per enrollment,
then aggregated according to its aggregation type.
341
Configure programs in the Maintenance app Create or edit a program indicator
Filter The filter is applied to events and filters the data

source used for the calculation of the indicator. I.e.
the filter is applied to the set of events before the
indicator expression is being evaluated. The filter
must evaluate to either true or false. It filter is
applied to each individual event. If the filter
evaluates to true then the event is included later in
the expression evaluation, if not it is ignored. The
filter can, in a similar way as expressions, contain
references to data elements, attributes and
constants.
The program indicator filter can in addition use

logical operators. These operators can be used to
form logical expressions which ultimately evaluate
to either true or false. For example you can assert
that multiple data elements must be a specific value,
or that specific attributes must have numerical
values less or greater than a constant.
In the Maintenance app, you manage the following program indicator objects:
Program indicator Create, edit, clone, share, delete, show details and
translate
Program indicator group Create, edit, clone, share, delete, show details and
translate
Create or edit a program indicator
Note
A program indicator belongs to exactly one program.
1. Open the Maintenance app and click Indicator > Program indicator.
3. Select a Program and enter:
◦ Name
◦ Short name
◦ Code
◦ Color
342
Configure programs in the Maintenance app Create or edit a program indicator group
Icon
◦
◦ Description
4. Select number of Decimals in data output.
5. Select an Aggregation type.
6. Select a if you want to Display in form.
7. Assign one or multiple **Legend**s.
8. (Optional) Enter a Category option combination for aggregate data export.
9. (Optional) Enter an Attribute option combination for aggregate data export.
10. Create the expression.
1. Click Edit expression.
2. Create the expression based on mathematical operators and the attributes, variables
and constants listed to the right.
11. Create the filter.
1. Click Edit filter.
2. Create the expression based on mathematical operators and the attributes, variables
and constants listed to the right.
12. Click Save.
Create or edit a program indicator group
1. Open the Maintenance app and click Indicator > Program indicator group.
3. Enter Name and Code.
4. In the list of available program indicators, double-click the program indicators you want to
assign to your group.
5. Click Save.
Reference information: Expression and filter examples per value type
The table below shows examples of how to write expressions and filters for different data element
and attribute value types:
Expression and filter examples per value type
343
Configure programs in the Reference information: Functions, variables and operators to use in
Maintenance app program indicator expressions and filters
Value types Example syntax
Integer Numeric fields, can be used for aggregation as an

expression, or in filters:
Negative integer
Positive or zero integer #{mCXR7u4kNBW.K0A4BauXJDl} >= 3
Positive integer
Number
Percentage
Yes/No Boolean fields. Yes is translated to numeric 1, No to

numeric 0. Can be used for aggregation as an
Yes only
expression, or in filters:
#{mCXR7u4kNBW.Popa3BauXJss} == 1
Text Text fields. Can be checked for equality in filters:
Long text
#{mCXR7u4kNBW.L8K4BauIKsl} == 'LiteralValue'
Phone number
Email
Date Date fields. Most useful when combined with a

d2:daysBetween function, which produces a
Age
number that can be aggregated as an expression or
used in filters:
d2:daysBetween(#{mCXR7u4kNBW.JKJKBausssl},V{enrollm
ent_date}) > 100
Can also directly be checked for equality in filters:
#{mCXR7u4kNBW.JKJKBausssl} == '2011-10-28'
Reference information: Functions, variables and operators to use in program indicator expressions
and filters
An expression that includes both attributes, data elements and constants looks like this:
(A{GPkGfbmArby} + #{mCXR7u4kNBW.NFkjsNiQ9PH}) * C{bCqvfPR02Im}
An expression which uses the custom aggregation type and hence can use inline aggregation
types looks like this:
344
(sum(#{mCXR7u4kNBW.K0A4BauXJDl} * #{mCXR7u4kNBW.NFkjsNiQ9PH}) / sum(#{mCXR7u4kNBW.NFkjsNiQ9PH})) *

100
Note how the "sum" aggregation operator is used inside the expression itself.
Functions to use in a program indicator expression or filter
The program indicator expression and filter support a range of functions. The functions can be
applied to data elements and attributes:
Functions to use in a program indicator expression or filter
Function Arguments Description
d2:hasValue (object) Returns true if the data element/attribute has a value.

Can be used in filters to distinguish between the number
0 and no value, and to distinguish between explicit "No"
and no selection for a Yes/No field.
d2:minutes (datetime, datetime) Produces the number of minutes between two data
Between elements/attributes of type "date and time". The static
datetime format is 'yyyy-MM-dd hh:mm'. Any of the
arguments can be replaced with PS_EVENTDATE:
(programStageUid) to compare the latest event date from
a given program stage.
d2:daysBet (date, date) Produces the number of days between two data
ween elements/attributes of type date. The static date format is
'yyyy-MM-dd'. Any of the arguments can be replaced with
PS_EVENTDATE:(programStageUid) to compare the
latest event date from a given program stage.
d2:weeksB (date, date) Produces the number of full weeks between two data
etween elements/attributes of type date. The static date format is
d2:monthsB (date, date) Produces the number of full months between two data
etween elements/attributes of type date. The static date format is
d2:yearsBet (date, date) Produces the number of full years between two data
ween elements/attributes of type date. The static date format is
345
d2:condition (boolean-expr, true-expr, Evaluates the boolean expression and if true returns the
false-expr) true expression value, if false returns the false
expression value. The conditional expression must be
quoted. The true-expr and false-expr arguments must
follow the rules of any program indicator expression
(including functions).
d2:zing (expression) Returns zero if the expression is negative, otherwise

returns the expression value. The expression must follow
the rules of any program indicator expression (including
functions).
d2:oizp (expression) Returns one if the expression is zero or positive,

otherwise returns zero. The expression must follow the
rules of any program indicator expression (including
functions).
d2:zpvc (object, [,object ...]) Returns the number of numeric zero and positive values
among the given object arguments. Can be provided any
d2:relations ([relationshipTypeUid]) Produces the number of relationships of the given type

hipCount that is connected to the enrollment or event. When no
type is given, all types are counted.
d2:count (dataElement) Useful only for enrollment program indicators. Counts the
number of data values that has been collected for the
given program stage and data element in the course of
the enrollment. The argument data element is supplied
with the #{programStage.dataElement} syntax.
d2:countIfV (dataElement, value) Useful only for enrollment program indicators. Counts the
alue number of data values that matches the given literal
value for the given program stage and data element in
the course of the enrollment. The argument data element
is supplied with the #{programStage.dataElement}
syntax. The value can be a hard coded text or number,
for example 'No_anemia' if only the values containing
this text should be counted.
346
d2:countIfC (dataElement, condition) Useful only for enrollment program indicators. Counts the
ondition number of data values that matches the given condition
criteria for the given program stage and data element in
the course of the enrollment. The argument data element
is supplied with the #{programStage.dataElement}
syntax. The condition is supplied as a expression in
single quotes, for example '<10' if only the values less
than 10 should be counted.
if (boolean-expr, true-expr, Evaluates the boolean expression and if true returns the
false-expr) true expression value, if false returns the false
expression value. This is identical to the d2:condition
function except that the boolean-expr is not quoted.
isNull (object) Returns true if the object value is missing (null),

otherwise false.
isNotNull (object) Returns true if the object value is not missing (not null),
otherwise false.
firstNonNull (object [, object ...]) Returns the value of the first object that is not missing
(not null). Can be provided any number of arguments.
Any argument may also be a numeric or string literal,
which will be returned if all the previous objects have
missing values.
greatest (expression [, expression ...]) Returns the greatest (highest) value of the expressions
given. Can be provided any number of arguments. Each
expression must follow the rules of any program indicator
expression (including functions).
least (expression [, expression ...]) Returns the least (lowest) value of the expressions given.
Can be provided any number of arguments. Each
expression must follow the rules of any program indicator
expression (including functions).
A filter that uses the "hasValue" function looks like this:
d2:hasValue(#{mCXR7u4kNBW.NFkjsNiQ9PH})
A filter that uses the "relationshipCount(relationshipTypeUid)" function looks like this:
d2:relationshipCount('KLkjshoQ90U')
347
An expression that uses the "zing" and "oizp" functions looks like this:
d2:zing(A{GPkGfbmArby}) + d2:oizp(#{mCXR7u4kNBW.NFkjsNiQ9PH}))
An expression that uses the "daysBetween" function looks like this:
d2:daysBetween(#{mCXR7u4kNBW.k8ja2Aif1Ae},'2015-06-01')
An expression that uses the "yearBetween" function to compare the latest event of the program
stage 'mCXR7u4kNBW' to the enrollment date looks like this:
d2:daysBetween(V{enrollment_date},PS_EVENTDATE:mCXR7u4kNBW)
An expression that uses the "condition" function looks like this:
d2:condition('#{mCXR7u4kNBW.NFkjsNiQ9PH} > 100',150,50)
An expression that uses the "countIfValue" function to only count the number of times the value
10 has been collected looks like this:
d2:countIfValue(#{mCXR7u4kNBW.NFkjsNiQ9PH}),10)
An expression that uses the "zpvc" function looks like this:
d2:zpvc(A{GPkGfbmArby}),#{mCXR7u4kNBW.NFkjsNiQ9PH}),4,-1)
An expression that uses the "if" and "isnull" functions looks like this:
if(isNull(A{GPkGfbmArby}),10,20)
An expression that uses the "firstNonNull" function looks like this:
firstNonNull(A{GPkGfbmArby}),#{mCXR7u4kNBW.NFkjsNiQ9PH},44)
An expression that uses the "greatest" function looks like this:
greatest(#{mCXR7u4kNBW.k8ja2Aif1Ae},#{mCXR7u4kNBW.NFkjsNiQ9PH},1)
Variables to use in a program indicator expression or filter
The program indicator expression and filter support a range of variables:
Variables to use in a program indicator expression or filter
348
Variable Description
event_date The date of when the event or the last event in the enrollment took place.
creation_date The date of when an event or enrollment was created in the system.
due_date The date of when an event is due.
sync_date The date of when the event or enrollment was last syncronized with the Android app.
incident_date The date of the incidence of the event.
enrollment_date The date of when the tracked entity instance was enrolled in the program.
enrollment_status Can be used to include or exclude enrollments in certain statuses.
When calculating the haemoglobin improvement/deterioration throughout a

pregnancy, it might make sense to only consider completed enrollments. If non-
completed enrollments is not filtered out, these will represent half-finished ANC
followups, where the final improvement/deterioration is not yet established.
current_date The current date.
value_count The number of non-null values in the expression part of the event.
zero_pos_value_c The number of numeric positive values in the expression part of the event.
ount
event_count The count of events (useful in combination with filters).
enrollment_count The count of enrollments (useful in combination with filters). Aggregation type for the
program indicator must be COUNT.
tei_count The count of tracked entity instances (useful in combination with filters). Aggregation
type for the program indicator must be COUNT.
org_unit_count The count of organisation units (useful in combination with filters). Aggregation type
for the program indicator must be COUNT.
program_stage_n Can be used in filters for including only certain program stages in a filter for tracker
ame programs. Uses the name of the program stage:
V{program_stage_name} == 'ANC first visit'
349
Variable Description
program_stage_id Can be used in filters for including only certain program stages in a filter for tracker
programs. Uses the unique identifier of the program stage:
V{program_stage_id} == 'YPSSfbmAtt1'
analytics_period_s Can be used in filters or expressions for comparing any date to the first date in each
tart reporting period.
d2:daysBetween(#{WZbXY0S00lP.w4ky6EkVahL}, V{analytics_period_start})
analytics_period_ Can be used in filters or expressions for comparing any date to the last inclusive
end date in each reporting period.
A filter that uses the "Analytics period end" variable to only include women who has an LMP that
would be in the first trimester:
d2:daysBetween(#{WZbXY0S00lP.w4ky6EkVahL}, V{analytics_period_end}) <= 84
An expression that uses the "value count" variable looks like this:
(#{A03MvHHogjR.a3kGcGDCuk6} + #{A03MvHHogjR.wQLfBvPrXqq}) / V{value_count}
An expression that uses the "event_date" and "incident_date" variables looks like this:
d2:daysBetween(V{incident_date},V{event_date})
Operators to use in a program indicator filter
Operators to use in a program indicator filter
Operator Description
and Logical AND
or Logical OR
== Equal to
!= Not equal to
350
Configure programs in the Maintenance app Configure program rules
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
These operators can be used to form logical expressions which ultimately evaluate to either true
or false. For example you can assert that multiple data elements must be a specific value, or that
specific attributes must have numerical values less or greater than a constant.
A filter that uses both attributes and data elements looks like this:
A{cejWyOfXge6} == 'Female' and #{A03MvHHogjR.a3kGcGDCuk6} <= 2
Tip
DHIS2 is using the JEXL library for evaluating expressions which
supports additional syntax beyond what is covered in this
documentation. See the reference at the project home page to learn
how you can create more sophisticated expressions
Configure program rules
About program rules
Program rules allows you to create and control dynamic behaviour of the user interface in the
Tracker Capture and Event Capture apps. During data entry, the program rules expressions are
evaluated each time the user interface is displayed, and each time a data element is changed.
Most types of actions will take effect immediately when the user enters values in the Tracker
Capture and Event Capture apps.
Program rule components
Program rule action Each program rule contains one or multiple actions.
These are the behaviours that are triggered in the
user interface when the expression is true. Actions
will be applied at once if the expression is true, and
will be reverted if the expression is no longer true.
There are several types of actions and you can
have several actions in one program rule.
351
Configure programs in the Maintenance app Workflow
Program rule expression Each program rule has a single expression that
determines whether the program rule actions
should be triggered, if the expression evaluates to
true. If the expression is true the program rule is in
effect and the actions will be executed. If the
expression is false, the program rule is no longer in
effect and the actions will no longer be applied.
You create the expression with standard

mathematical operators, custom functions, user-
defined static values and program rule variables.
The program rule variables represent attribute and
data element values which will be evaluated as part
of the expression.
Program rule variable Program rule variables lets you include data values
and attribute values in program rule expressions.
Typically, you'll have to create one or several
program rule variables before creating a program
rule. This is because program rules expressions
usually contain at least one data element or
attribute value to be meaningful.
The program rule variables are shared between all

rules in your program. When you create multiple
program rules for the same program, these rules will
share the same library of program rule variables.
In the Maintenance app, you manage the following program rule objects:
Program rule Create, edit, clone, delete, show details and

translate
Program rule variable Create, edit, clone, share, delete, show details and
translate
Workflow
1. In the Maintenance app, create program rule variable(s) if needed.
2. In the Maintenance app, create the program rule:
1. Enter the program rule details.
2. Create the program rule expression.
3. Define the program rule actions.
352
Configure programs in the Maintenance app Create or edit a program rule variable
In the Tracker Capture or Event Capture apps, verify that the program rule behaves as
3. expected.
Create or edit a program rule variable
1. Open the Maintenance app and click Program > Program rule variable.
3. Select a Program and enter a Name.
4. Select if you want to Use code for option set.
This option is only effective when the data element or tracked entity attribute is connected
to an option set. If you don't select this option, the program rule variable will be populated
with the option set's name. If you select the option, the program rule variable will be
populated with the option set's code instead.
5. Select a Source type and enter the required information.
Depending on the source type, you'll have to select, for example, a Program stage, Data
element or Tracked entity attribute.
The source types determine how the program rule variable is populated with a value.
Source type Description
Data element from the newest event for a This source type works the same way as Data
program stage element from the newest event in the current
program, except that it only evaluates values
from one program stage.
This source type can be useful in program rules

where the same data element is used in several
program stages, and a rule needs to evaluate
the newest data value from within one specific
stage.
353
Data element from the newest event in the This source type is used when a program rule
current program variable needs to reflect the newest known
value of a data element, regardless of what
event the user currently has open.
This source type is populated slightly differently

in Tracker Capture and Event Capture apps:
Tracker Capture: the program rule variable will

be populated with the newest data value
collected for the given data element within the
enrollment.
Event Capture: the program rule variable will

be populated with the newest data value found
within the 10 newest events in the same
organisation unit.
The newest data value is determined with event

date.
Data element in current event Program rule variables with this source type will
contain the data value from the same event that
the user currently has open.
This is the most commonly used source type,

especially for skip logic (hide actions) and
warning/error rules.
354
Data element from previous event Program rule variables with this source type will
contain the value from a specified data element
from a previous event. Only older events is
evaluated, not including the event that the user
currently has open.
This source type is commonly used when a data

element only should be collected once during
an enrollment, and should be hidden in
subsequent events.
Another use case is making rules for validating

input where there is an expected progression
from one event to the next - a rule can evaluate
whether the previous value is higher/lower and
give a warning if an unexpected value is
entered.
This source type is populated slightly differently

in Tracker Capture and Event Capture apps:
Tracker Capture: the program rule variable will

collected for the given data element within the
enrollment - but only evaluating the events that
comes before the current event date.
Event Capture: the program rule variable will

collected within the 10 events preceding the
current event date - not including the current
event.
The newest data value is determined with event

date.
355
Configure programs in the Maintenance app Create or edit a program rule
Calculated value Program rule variable with this source type is

not connected directly to any form data - but will
be populated as a result of some other program
rules ASSIGN action.
This variable will be used for making preliminary

calculations, having a ASSIGN program rule
action and assigning a value, this value can be
used by other program rules - potentially making
the expressions simpler and more maintanable.
These variables will not be persisted and will

stay in memory only during the exectution of the
set of program rules. Any program rule that
assigns a data value to a preliminary calculated
value would normally also have a priority
assigned - to make sure that the preliminary
caculation is done before the rule that
consumes the calculated value.
Tracked entity attribute Populates the program rule variable with a

specified tracked entity attribute for the current
enrollment.
Use this is the source type to create program

rules that evaluate data values entered during
registration.
This source type is also useful when you create

program rules that compare data in events to
data entered during registration.
This source type is only used for tracker

programs (programs with registration).
6. Click Save.
Create or edit a program rule
Note
A program rule belongs to exactly one program.
1. Open the Maintenance app and click Program > Program rule.
3. Enter the program rule details. These fields are not shown to the end user, they are only
meant for the program administrator.
◦ Program
356
Trigger rule only for program stage

◦
If a program stage is selected, the program rule will only run for the selected
program stage, as opposed to being run for every program stage in the program.
◦ Name
◦ Description
◦ Priority
Let's say you have 16 program rules in your program. You configure the program
rules with the following priority settings:
▪ Priority 1 for program rule A
▪ Priority 2 for program rules B - K
▪ No priority for program rules L - P
Result: the system runs the program rules in the following order:
1. Program rule A
2. Program rules B - K (you can't find out or configure in which order the system
runs these program rules)
3. Program rules L - P.
4. Click Enter program rule expression and create the program rule expression with the help
of variables, functions and operators.
5. Click Define program rule actions and create the actions executed when the expression is
true.
1. Click the add button, select an Action and enter the required information.
Depending on the action type, you'll have to perform different types of settings. For
some action types, you must also enter free text or create expressions.
Action type Required settings Description
357
Assign value Data element to assign Used to help the user

value to calculate and fill out fields in
the data entry form. The
Program rule variable to
idea is that the user
assign value to
shouldn’t have to fill in
Expression to evaluate values that the system can
and assign calculate, for example BMI.
When a field is assigned a

value, the user sees the
value but the user can't edit
it.
Example from Immunization

stock card i Zambia: The
data element for vaccine
stock outgoing balance is
calculated based on the
data element for incoming
stock balance minus the
data elements for
consumption and wastage.
Advanced use: configure an

'assign value' to do a part of
a calculation and then
assign the result of the
calculation to a program
rule variable. This is the
purpose with the
"Calculated value" program
rule variable.
Display text Display widget Used to display information

that is not an error or a
Static text
warning, for example
Expression to evaluate feedback to the user. You
and display after static can also use this action to
text display important
information, for example the
patient's allergies, to the
user.
358
Display key/value pair Display widget Used to display information

that is not an error or a
Key label
warning.
Expression to evaluate
Example: calculate number
and display as value
of weeks and days in a
pregnancy and display it in
the format the clinician is
used to see it in. The
calculation is based on
previous recorded data.
Error on complete Data element to display Used whenever you've

error next to cross-consistencies in the
form that must be strictly
Tracked entity attribute to
adhered to. This action
display error next to
prevents the user from
Static text continuing until the error is
resolved.
Expression to evaluate
and display after static This action differs from the
text regular Show error since
the error is not shown until
the user tries to actually
complete the form.
If you don't select a data

element or a tracked entity
attribute to display the error
next to, make sure you write
a comprehensive error
message that helps the user
to fix the error.
359
Hide field Data element to hide Used when you want to

hide a field from the user.
hide Custom message for
blanked field allows you to
Custom message for
define a custom message
blanked field
displayed to the user in
case the program rule hides
and blanks out the field after
the user typed in or selected
a value.
If a hide field action hides a

field that contains a value,
the field will always
removed. If no message is
defined, a standard
message will be displayed
to alert the user.
Hide section Program stage section to TBA

hide
Hide program stage Program stage to hide Used when you want to
hide a program stage
section from the user.
Make field mandatory Data element to make TBA

mandatory

make mandatory
360
Show error Data element to display Used whenever there are

error next to rules which must strictly be
adhered to. The show error
action prevents the user
display error next to
from continuing until the
Static text error is resolved.
Expression to evaluate Such a strict validation

and display after static should only be used when
text it's certain that the
evaluated expression is
never true unless the user
has made a mistake in data
entry.
It's mandatory to define a

message that is shown to
the user when the
expression is true and the
action is triggered.
You can select which data

element or tracked entity
attribute to link the error to.
This will help the user to fix
the error.
In case several data

elements or attributes are
involved, select the one that
is most likely that the user
would need to change.
361
Show warning Data element to display Used to give the user a

warning next to warning about the entered
data, but at the same time to
allow the user to save and
display warning next to
continue.
Static text
You can use warnings to
Expression to evaluate help the user avoid errors in
and display after static the entered data, while at
text the same time allow the
user to consciously
disregard the warnings and
save a value that is outside
preset expectations.
Static text defines the

message shown to the user
when the expression is true
and the action is triggered.

the error.
In case several data

elements or attributes are
involved, select the one that
is most likely that the user
would need to change.
362
Warning on complete Data element to display Used to give the user a

warning next to warning if he/she tries to
complete inconsistent data,
but at the same time to
display warning next to
allow the user to continue.
Static text The warning is shown in a
dialog when the user
Expression to evaluate completes the form.
and display after static
text Static text defines the
message shown to the user
when the expression is true
and the action is triggered.
This field is mandatory.

the error.
If you don't select a data

element or a tracked entity
attribute to display the error
next to, make sure you write
a comprehensive error
message that helps the user
to fix the error.
Send Message Message template to send Send Message triggers a

notification based on
provided message
template. This action will be
taken immediately. The
message template will be
parsed and variables will be
substituted with actual
values.
363
Schedule Message Message template to send Schedule Message will

schedule notification at date
Data field which contains
provided by Expression in
expression to evaluate the
the data field. Sample
date which notification
expression is given below
should be sent at. If this
expression results in any
d2:addDays( '2018-04-20',
value other than Date, then
'2' )
resultant will be discarded
and notification will not get
scheduled. Message template will be
parsed and variables will be
substituted with actual
values.
Hide option Data element to hide Used to selectively hide a

option for single option for an option
set in a given data element/
tracked entity attribute.
hide option for
When combined with show
Option that should be
option group the hide
hidden
option takes presedence.
Hide option group Data element to hide Used to hide all options in a
option group for given option group and data
element/tracked entity
attribute.
hide option group for
When combined with show
Option group that should
option group the hide
be hidden
option group takes
precedence.
Show option group Data element to show Used to show only options
option group for from a given option group in
a given data element/
tracked entity attribute. To
show option group for
show an option group
Option group that should implicitly hides all options
be shown that is not part of the
group(s) that is shown.
2. Click Save.
3. (Optional) Repeat above steps to add more actions.
6. Click Save.
364
Configure programs in the Maintenance app Example: Program rules
Example: Program rules
Note
You can view all examples on the demo server: https://play.dhis2.org/
dev/dhis-web-maintenance/#/list/programSection/programRule
This example shows how to configure a program rule which calculate number of weeks and days
in a pregnancy and display the result in the format the clinician is used to see it in. The calculation
is based on previous recorded data.
1.
2.
365
3.
The full expression in the Data field:
d2:concatenate(d2:weeksBetween(#{lmp}, V{current_date}), '+',

d2:modulus(d2:daysBetween(#{lmp}, V{current_date}), 7))
366
This example shows how to configure a program rule to display text in the Feedback widget in the
Tracker Capture app.
1.
2.
367
3.
4.
368
This example shows how to configure a program rule to always display certain data in the
Feedback widget in the Tracker Capture app. This is useful when you want to make sure that vital
data, for example medicine allergies, is always visible.
1.
2.
369
3.
4.
370
371
By using a program rule of type "Assign value" you can calculate the "Gestational age at visit"
value and fill it in the data entry form. You configure the program rule to calculate "Gestational
age at visit" based on either "LMP date" or "Ultrasound estimated due date".
1.
2.
372
Configure programs in the Reference information: Operators and functions to use in
Maintenance app program rule expression
3.
Reference information: Operators and functions to use in program rule expression
Tip
You can nest functions within each other and with sub-expressions to
form more complex conditions. An example that produces the
gestational age in weeks, based on last menstrual date:
373
d2:floor( d2:daysBetween(#{lastMenstrualDate},V{event_date}) / 7 )
Tip
The source type will determine how the d2: function calls will evaluate a
(sourcefield) parameter.
Example: where #{hemoglobinCurrent} is set to source type Data
element in current event. The following function call with evaluate
whether haemoglobin is entered in the current event.
d2:hasValue( 'hemoglobinCurrent' )
Example: where #{hemoglobin} is set to source type Data element from

the newest event in the current program. The following function call
with evaluate whether there exists a value for the haemoglobin in any
event in the enrollment.
d2:hasValue( 'hemoglobin' )
Example: where #{hemoglobinPrevious} is set to source type Data

element from previous event . The following function call with evaluate
whether there exists a value for the haemoglobin among the events
preceding the current event.
d2:hasValue( 'hemoglobinPrevious' )
Possible operators to use in a program rule expression
+ Add numbers together
- Subtract numbers from each other
* Multiply two numbers
/ Divide two numbers
% The modulus of two numbers
&& Logical AND. True only when the expression on the left and right side is true. The left and
right side can be yes/no, yes only or a sub-expression in parenthesis.
|| Logical OR. True when either the expression on the left or the expression on the right side
is true. The left and right side can be yes/no, yes only or a sub-expression in parenthesis.
374
> Left number greater than right number
>= Left number greater than or equal to right number
< Left number less than right number
<= Left number less than or equal to right number.
== Left side equal to right side. Supports numbers, text, yes/no and yes only.
!= Left side not equal to right side. Supports numbers, text, yes/no and yes only.
! Negates the following value. Can be used for yes/no, yes only or a sub-expression in
parenthesis.
() Parenthesis is used to group sub-expressions.
Custom functions to use in a program rule expression
d2:ceil (number) Rounds the input argument up to the nearest whole

number.
Example:
d2:ceil(#{hemoglobinValue})
d2:floor (number) Rounds the input argument down to the nearest whole
number.
An example producing the number of weeks the woman

is pregnant. Notice that the sub-expression
#{gestationalAgeDays}/7 is evaluated before the floor
function is executed:
d2:floor(#{gestationalAgeDays}/7)
d2:round (number) Rounds the input argument to the nearest whole number.
375
d2:modulus (number,number) Produces the modulus when dividing the first with the
second argument.
An example producing the number of days the woman is

into her current pregnancy week:
d2:modulus(#{gestationalAgeDays},7)
d2:zing (number) Evaluates the argument of type number to zero if the

value is negative, otherwise to the value itself.
d2:oizp (number) Evaluates the argument of type number to one if the

value is zero or positive, otherwise to zero.
d2:concate (object, [,object, object,...]) Produces a string concatenated string from the input
nate parameters. Supports any number of parameters. Will
mainly be in use in future action types, for example to
display gestational age with
d2:concatenate('weeks','+','gestationalageDays').
d2:daysBet (date, date) Produces the number of days between the first and
ween second argument. If the second argument date is before
the first argument the return value will be the negative
number of days between the two dates. The static date
format is 'yyyy-MM-dd'.
Example, calculating the gestational age(in days) of a

woman, based on the last menstrual period and the
current event date:
d2:daysBetween(#{lastMenstrualDate},V{event_date})
d2:weeksB (date, date) Produces the number of full weeks between the first and
etween second argument. If the second argument date is before
number of weeks between the two dates. The static date
d2:monthsB (date, date) Produces the number of full months between the first and
etween second argument. If the second argument date is before
number of months between the two dates. The static date
d2:yearsBet (date, date) Produces the number of years between the first and
ween second argument. If the second argument date is before
number of years between the two dates. The static date
376
d2:addDays (date, number) Produces a date based on the first argument date,
adding the second argument number of days.
An example calculating the pregnancy due date based

on the last menstrual period:
d2:addDays(#{lastMenstrualDate},283)
d2:count (sourcefield) Counts the number of values that is entered for the
source field in the argument. The source field parameter
is the name of one of the defined source fields in the
program - see example
Example usage where #{previousPregnancyOutcome} is

one of the source fields in a repeatable program stage
"previous pregnancy":
d2:count('previousPregnancyOutcome')
d2:countIfV (sourcefield,text) Counts the number of matching values that is entered for
alue the source field in the first argument. Only occurrences
that matches the second argument is counted. The
source field parameter is the name of one of the defined
source fields in the program - see example.
Example usage where #{previousPregnancyOutcome} is

one of the source fields in a repeatable program stage
"previous pregnancy". The following function will
produce the number of previous pregnancies that ended
with abortion:
d2:countIfValue('previousPregnancyOutcome','Abortion')
d2:countIfZ (sourcefield) Counts the number of values that is zero or positive

eroPos entered for the source field in the argument. The source
field parameter is the name of one of the defined source
fields in the program - see example.
Example usage where #{fundalHeightDiscrepancy} is

one of the source fields in program, and it can be either
positive or negative. The following function will produce
the number of positive occurrences:
d2:countIfZeroPos('fundalHeightDiscrepancy')
377
d2:hasValue (sourcefield) Evaluates to true of the argument source field contains a

value, false if no value is entered.
Example usage, to find if the source field

#{currentPregnancyOutcome} is yet filled in:
d2:hasValue('currentPregnancyOutcome')
d2:zpvc (object, [,object, object,...]) Returns the number of numeric zero and positive values
among the given object arguments. Can be provided
with any number of arguments.
d2:validate (text, regex-pattern) Evaluates to true if the input text is an exact match with
Pattern the supplied regular expression pattern. The regular
expression needs to be escaped.
Example expression, triggering actions if a number is not

on the pattern 9999/99/9:
!d2:validatePattern(A{nrc},'\\d{6}\/\\d{2}\/\\d')
Example expression, triggering actions that if the

address is not consisting of letters or white spaces, then
a white space, then a number:
!d2:validatePattern(A{registrationAddress},'[\\w ]+ \
\d+')
Example, triggering actions if a name contains any

numbers:
!d2:validatePattern(A{name},'[^\\d]*')
Example expression, triggering actions if a mobile

number contains the illegal number sequence 555:
d2:validatePattern(A{mobile} ,'.*555.*')
d2:left (text, num-chars) Evaluates to the left part of a text, num-chars from the first
character.
The text can be quoted or evaluated from a variable:
d2:left(#{variableWithText}, 3)
378
d2:right (text, num-chars) Evaluates to the right part of a text, num-chars from the
last character.
The text can be quoted or evaluated from a variable:
d2:right(#{variableWithText}, 2)
d2:substring (text, start-char-num, end- Evaluates to the part of a string specified by the start and
char-num) end character number.
Example expression:
d2:substring(#{variableWithText}, 1, 3)
If the #{variableWithText} in the above example was

'ABCD', then the result of the evaluation would be 'BC'
d2:split (text, delimiter, element-num) Split the text by delimiter, and keep the nth element(0 is
the first).
The text can be quoted or evaluated from a variable, the

delimiter must be quoted:
d2:split(#{variableWithText}, '-', 1)
Note: comma delimiter(,) is not supported.
d2:length (text) Find the length of a string.
Example:
d2:length(#{variableWithText})
d2:inOrgUn (text) Evaluates whether the current organisation unit is in the

itGroup argument group. The argument can be defined with
either ID or organisation unit group code. The current
organisation unit will be the event organisation unit when
the rules is triggered in the context of an event, and the
enrolling organisation unit when the rules is triggered in
the event of a TEI registration form.
Example expression:
d2:inOrgUnitGroup('HIGH_RISK_FACILITY')
d2:hasUser (user role) Returns true if current user has this role otherwise false
Role
Example expression:
d2:hasUserRole('UYXOT4A3ASA')
379
d2:zScore Z-Score weight for age Calculates z-score based on data provided by WHO
WFA indicator weight-for-age indicator. e varies between -3.5 to 3.5
depending upon the value of weight.
Example expression:
d2:zScoreWFA( ageInMonths, weight, gender )
> **Gender** > > Gender is concidered female by

default. Any of the following codes can be used to denote
male: 'Male', 'MALE', 'male', 'ma', 'm', 'M', 0, false
d2:zScoreH Z-Score height for age Calculates z-score based on data provided by WHO
FA indicator height-for-age indicator. Its value varies between -3.5 to
3.5 depending upon the value of height.
Example expression:
d2:zScoreHFA( ageInMonths, height, gender )
d2:zScore Z-Score weight for height Calculates z-score based on data provided by WHO
WFH indicator weight-for-height indicator. Its value varies between -3.5
to 3.5 depending upon the value of the weight.
Example expression:
d2:zScoreWFH( height, weight, gender )
d2:minValue Get minimum value for Function gets minimum value of provided data element
provided item across entire enrollment.
Example expression:
d2:minValue( 'blood-pressure' )
d2:maxValu Get maximum value for Function gets maximum value of provided data element
e provided item across entire enrollment.
Example expression:
d2:maxValue( 'blood-pressure' )
Standard variables to use in program rule expressions
380
Variable Type Description
V{current_d (date) Contains the current date whenever the rule is executed.
ate}
Example expression:
d2:daysBetween(#{symptomDate},V{current_date}) < 0
V{event_da (date) Contains the event date of the current event execution.
te} Will not have a value at the moment the rule is executed
as part of the registration form.
V{event_sta (string) Contains status of the current event or enrollment.

tus}
Example expression to check status is:
V{event_status} == 'COMPLETED'
V{due_date} (date) This variable will contain the current date when the rule
is executed. Note: This means that the rule might
produce different results at different times, even if nothing
else has changed.
V{event_co (number) Contains the total number of events in the enrollment.

unt}
V{enrollme (date) Contains the enrollment date of the current enrollment.

nt_date} Will not have a value for single event programs.
V{incident_ (date) Contains the incident date of the current enrollment. Will
date} not have a value for single event programs.
V{enrollme (string) Universial identifier string(UID) of the current enrollment.

nt_id} Will not have a value for single event programs.
V{event_id} (string) Universial identifier string(UID) of the current event

context. Will not have a value at the moment the rule is
executed as part of the registration form.
V{orgunit_c (string) Contains the code of the orgunit that is linked to the
ode} current enrollment. For single event programs the code
from the current event orgunit will be used instead.
Example expression to check whether orgunit code starts

with WB_:
d2:left(V{orgunit_code},3) == 'WB_'
V{environm (string) Contains a code representing the current runtime

ent} environment for the rules. The possible values is
"WebClient", "AndroidClient" and "Server". Can be used
when a program rule is only supposed to run in one or
more of the client types.
381
Configure programs in the Maintenance app Configure relationship types
Variable Type Description
V{program_ (string) Contains the ID of the current program stage that

stage_id} triggered the rules. This can be used to run rules in
specific program stages, or avoid execution in certain
stages. When executing the rules in the context of a TEI
registration form the variable will be empty.
V{program_ (string) Contains the name of the current program stage that
stage_nam triggered the rules. This can be used to run rules in
e} specific program stages, or avoid execution in certain
stages. When executing the rules in the context of a TEI
registration form the variable will be empty.
Configure relationship types
About relationship types
A relationship represents a link between two entities in the Tracker-model. A relationship is

considered data in DHIS2 and is based on a Relationship Type, similar to how a Tracked Entity
Instance is based on a Tracked Entity Type.
Relationships always include two entities, and these entities can include Tracked Entity Instances,
Enrollments and Events, and any combination of these. Note that not all of these combinations
are available in the current apps.
In addition, relationships can be defined as unidirectional or bidirectional. The only functional

difference is currently that these requires different levels of access to create. Unidirectional
relationships requires the user to have data write access to the “from” entity and data read
access for the “to” entity, while bidirectional relationships require data write access for both sides.
For more information about configuration and the meaning of 'From constraint' and 'To constraint',
see Relationship model.
Create or edit a relationship type
1. Open the Maintenance app and click Program > Relationship type.
3. Type a Name of the relationship type.
4. (Optional) Assign a Code.
5. (Optional) Provide a Description of the relationship.
6. (Optional) Select whether the relationship should be bidirectional
7. Provide Relationship name seen from inititating entity. This is the name of the
relationship that will be shown in the Data Entry app at the 'left' side of the relationship. E.g.
in a Mother-child relationship this could be 'Mother of'.
8. (Optional) Provide Relationship name seen from receiving entity. This is the name of the
relationship that will be shown at the 'right' side of the relationship in the Data Entry app.
E.g. in a Mother-child relationship this could be 'Mother'.
9. Select a 'From constraint'. This limits what kind of entities that can be included in the
relationship. Relationship model.
382
Configure programs in the Maintenance app Configure tracked entity types
Select a 'To constraint'. This limits what kind of entities that can be included in the
10. relationship. Relationship model.
11. Click Save.
Configure tracked entity types
About tracked entity types
A tracked entity is a types of entities which can be tracked through the system. It can be anything
from persons to commodities, for example a medicine or a person.
A program must have one tracked entity. To enroll a tracked entity instance into a program, the
tracked entity type and tracked entity type of a program must be the same.
Tracked entity attributes are used to register extra information for a tracked entity. Tracked entity
attributes can be shared between programs.
Create or edit a tracked entity attribute
1. Open the Maintenance app and click Program > Tracked entity attribute.
3. In the Name field, type the tracked entity attribute name.
4. (Optional) Type a Short name.
5. (Optional) Type a Form name.
8. (Optional) In the Field mask field, you may type a template that's used to provide hints for
correct formatting of the attribute. NOTE: So far only implemented in the DHIS2 Android
Capture app, not in the Capture and Tracker Capture web apps. The following are special
characters that can be used in the mask. The special characters match exactly one
character of the given type.
Character Match
\d digit
\x lower case letter
\X capital letter
\w any alphanumeric character
For example, the pattern can be used to show hyphens as needed in the input field of the data
element. E.g "\d\d\d-\d\d\d-\d\d\d, would show an hyphen for every third digit.
2. In the Value type field, select the type of data that the tracked entity attribute will record.
Value types
383
Configure programs in the Maintenance app Create or edit a tracked entity attribute
Age -
Coordinate A point coordinate specified as longitude

and latitude in decimal degrees. All
coordinate should be specified in the format
"-19.23 , 56.42" with a comma separating the
longitude and latitude.
Date Dates render as calendar widget in data

entry.
Date & time -
E-mail -
File A file resource where you can store external

files, for example documents and photos.
Image Similar to File, but restricted to images.
Integer Any whole number (positive and negative),

including zero.
Letter -
Long text Textual value. Renders as text area in forms.
Negative integer Any whole number less than (but not

including) zero.
Number Any real numeric value with a single decimal

point. Thousands separators and scientific
notation is not supported.
Percentage Whole numbers inclusive between 0 and

100.
Phone number
Positive integer Any whole number greater than (but not

including) zero.
Positive of zero integer Any positive whole number, including zero.
384
Configure programs in the Maintenance app Create or edit a tracked entity attribute
Organisation unit -
Unit interval Any real number greater than or equal to 0

and less than or equal to 1.
Text Textual value. The maximum number of

allowed characters per value is 50,000.
Time Time is stored in HH:mm format.
HH is a number between 0 and 23
mm is a number between 00 and 59
Tracker associate -
Username Rendered as a dialog with a list of users and

a search field. The user will need the "View
User" authority to be able to utilise this data
type
Yes/No Boolean values, renders as drop-down lists

in data entry.
Yes only True values, renders as check-boxes in data

entry.
3. Select an Aggregation type.
Aggregation operators
Average Average the values in both the period as and

the organisation unit dimensions.
Average (sum in organisation unit hierarchy) Average of data values in the period dimension,
sum in the organisation unit dimensions.
Count Count of data values.
Min Minimum of data values.
385
Configure programs in the Maintenance app Create or edit a tracked entity type
Max Maximum of data values.
None No aggregation is performed in any dimension.
Sum Sum of data values in the period and

organisation unit dimension.
Standard deviation Standard deviation (population-based) of data

values.
Variance Variance (population-based) of data values.
4. Select Unique to specify that the values of the tracked entity attribute is unique.
There are two options for the unique setting:
◦ Entire system: The values of the tracked entity attribute can duplicate with values
which belong to other tracked entity attributes. But the values in this tracked entity
attribute must not duplicate.
Select Automatically generated to allow automatic generation of the tracked entity

attribute value. When the generate setting is selected on, an optional field for
specifying pattern also displays. This field should contain a pattern based on the
TextPattern syntax. When the value is automatically generated, it will be unique for
this attribute for the entire system. See the TextPattern section for more information
on how it works.
◦ Organisation unit: The values of the tracked entity attribute must not duplicate in the
same organisation unit.
5. Select Inherit to registry a new entity for relationship with an available entity, all inherit
entity attribute values of the entity will be pre-filled in the registration form.
6. (Optional) Select Confidential.
This option is only available if you have configured encryption for the system.
7. (Optional) Select Display in list without program.
9. Click Save.
Create or edit a tracked entity type
1. Open the Maintenance app and click Program > Tracked entity type.
2. Click the add button or an already existing tracked entity type.
3. Type a Name of the tracked entity.
386
Configure programs in the Maintenance app Configure search
(Optional) select a Color and an Icon that will be used by the data capture apps to identify
4. this tracked entity type.
5. (Optional) Enter a Description of the tracked entity.
6. (Optional) Enter a Minimum number of attributes required to search. This specifies the
amount of attributes that need to be filled out in order to be able to search for this tracked
entity type in a global search. See Configure Search for more information.
7. (Optional) Enter a Maximum number of tracked entity instances to return in search. This
specifies the amount of tracked entity instances that will be returned in a global search.
See Configure Search for more information.
8. (Optional) Add Tracked entity type attributes. This is used to configure search, see
Configure Search for more information.
9. (Optional) Enter an Alternative name of the tracked entity.
10. Click Save.
Configure search
Users can be given search organisation units, which makes it possible to search for tracked entity
instances outside their data capture organisation units.
Searching can be done either in the context of a program, or in the context of a tracked entity
type. To be give users the option of searching in the context of a program, it is necessary to
configure which of the programs tracked entity attributes is searchable. To give users the option
of searching in the context of a tracked entity type, you will have to configure which of the tracked
entity type attributes is searchable.
Configure search for tracker program
To be able to search with a program, you will have to make some of the program attributes
searchable. Unique program attributes will always be searchable.
1. Open Program app
2. Open or create a tracker program
3. Go to Attributes
4. If you have no attributes, add one
5. Set the attribute searchable
Searchable program attributes will assigned to a search group.
• Unique group. One group per unique program attribute. Unique attributes cannot be
combined with other program attributes in a search. The result from the search can only be
0 or 1 tracked entity instance.
• Non-unique group. This group contains all non-unique program attributes and makes it
possible to combine multiple attributes in a search.
387
Configure programs in the Maintenance app Configure search for tracked entity type
There are two limits that can be set for a program search, as part of the Program configuration.
• Minimum number of attributes required to search: This property defines how many of the
non-unique attributes that must be entered before a search can be performed.
• Maximum number of tracked entity instances to return: This property defines the maximum
number of results a user will get in her search. If a too large number of tracked entity
instances is found, the user must provide a more specific search.
Configure search for tracked entity type
Note
TET = Tracked entity type
To be able to search without a program, you will have to make some of the TET attributes
searchable. Unique TET attributes will always be searchable.
1. Open Tracked entity type app
2. Open a Tracked entity type
3. If the TET has no attributes, add one
4. Set the attribute searchable
Searchable TET attributes will assigned to a search group.
• Unique group. One group per unique TET attribute. Unique attributes cannot be combined
with other TET attributes in a search. The result from the search can only be 0 or 1 tracked
entity instance.
• Non-unique group. This group contains all non-unique TET attributes and makes it possible
to combine multiple attributes in a search.
There are two limits that can be set for a TET search
• Minimum number of attributes required to search: This property defines how many of the
non-unique attributes that must be entered before a search can be performed.
• Maximum number of tracked entity instances to return: This property defines the maximum
number of results a user will get in her search. If a too large number of tracked entity
instances is found, the user must provide a more specific search.
Configure search organisation units for a user
To be able to search in other organisation units than the users data capture organisation units,
the user must be assigned with search organisation units. Giving a user a search organisation
unit will also give it access to search in all children of that organisation unit.
1. Open Users app
2. Click on a user
3. Open Assign search organisation units
4. Select organisation units
5. Click Save
388
Configure programs in the Maintenance app Clone metadata objects
4. Click Save.
Note
Warning
in time.
3. Click Confirm.
Note
389
Configure programs in the Maintenance app Display details of metadata objects
No access (only applicable to Public access): The public won't have access to the
◦ object.
6. Click Close.
cultural region.
Tip
Tip
3. Select a locale.
5. Click Save.
390
Manage users, user roles and user groups About user management
Manage users, user roles and user groups

About user management
Multiple users can access DHIS2 simultaneously and each user can have different authorities.
You can fine-tune these authorities so that certain users can only enter data, while others can
only generate reports.
• You can create as many users, user roles and user groups as you need.
• You can assign specific authorities to user groups or individual users via user roles.
• You can create multiple user roles each with their own authorities.
• You can assign user roles to users to grant the users the corresponding authorities.
• You can assign each user to organisation units. Then the user can enter data for the
assigned organisation units.
User management terms and definitions
Term Definition Example
Authority A permission to perform one or several Create a new data element

specific tasks
Update an organisation unit
View a report
User A person's DHIS2 user account admin
traore
guest
User role A group of authorities Data entry clerk
System administrator
Antenatal care program access
User group A group of users Kenya staff
Feedback message recipients
HIV program coordinators
You manager users, user roles and user groups in the Users app.
Objects in the Users app
391
Manage users, user roles and user groups About users
User Create, edit, invite, clone, disable, display by organisation unit, delete and show
details
User role Create, edit, share, delete and show details
User group Create, edit, join, leave, share, delete and show details
About users
Each user in DHIS2 must have a user account which is identified by a user name. You should
register a first and last name for each user as well as contact information, for example an email
address and a phone number.
It is important that you register the correct contact information. DHIS2 uses this information to
contact users directly, for example sending emails to notify users about important events. You can
also use the contact information to share for example dashboards and pivot tables.
A user in DHIS2 is associated with an organisation unit. You should assign the organisation unit
where the user works.
When you create a user account for a district record officer, you should assign the district where
he/she works as the organisation unit.
The assigned organisation unit affects how the user can use DHIS2:
• In the Data Entry app, a user can only enter data for the organisation unit she is
associated with and the organisation units below that in the hierarchy. For instance, a
district records officer will be able to register data for her district and the facilities below that
district only.
• In the Users app, a user can only create new users for the organisation unit she is
associated with in addition to the organisation units below that in the hierarchy.
• In the Reports app, a user can only view reports for her organisation unit and those below.
(This is something we consider to open up to allow for comparison reports.)
An important part of user management is to control which users are allowed to create new users
with which authorities. In DHIS2, you can control which users are allowed to perform this task.
The key principle is that a user can only grant authorities and access to data sets that the user
itself has access to. The number of users at national, province and district level are often
relatively few and can be created and managed by the system administrators. If a large
proportion of the facilities are entering data directly into the system, the number of users might
become unwieldy. It is recommended to delegate and decentralize this task to the district officers,
it will make the process more efficient and support the facility users better.
About user roles
A user role in DHIS2 is a group of authorities. An authority means the permission to perform one
or more specific tasks.
A user role can contain authorities to create a new data element, update an organisation unit or
view a report.
392
Manage users, user roles and user groups About user groups
A user can have multiple user roles. If so, the user's authorities will be the sum of all authorities
and data sets in the user roles. This means that you can mix and match user roles for special
purposes instead of only creating new ones.
A user role is associated with a collection of data sets. This affects the Data Entry app: a user
can only enter data for the data sets registered for his/her user role. This can be useful when, for
example, you want to allow officers from health programs to enter data only for their relevant data
entry forms.
Recommendations:
• Create one user role for each position within the organisation.
• Create the user roles in parallel with defining which user is doing which tasks in the system.
• Only give the user roles the exact authorities they need to perform their job, not more. Only
those who are supposed to perform a task should have the authorities to perform it.
About user groups
A user group is a group of users. You use user groups when you set up sharing of objects or
notifications, for example push reports or program notifications.
See also:
Sharing
Manage program notifications
Mange push reports
Workflow
1. Define the positions you need for your project and identify which tasks the different
positions will perform.
2. Create roughly one user role for each position.
3. Create users.
4. Assign user roles to the users.
5. Assign the users to organisation units.
6. (Optional) Group users in user groups.
7. Share datasets with users or user-groups via the Sharing Dialog in Data set management
section of the Maintenance app
Tip
For users to be able to enter data, you must add them to an
organisational unit level and share a dataset with them.
393
Manage users, user roles and user groups Manage users
Manage users
Create a user
1. Open the Users app and click on the + in the Users card.
2. Select whether you want to fill in all the personal user information, or invite the user by
email to complete the rest of the user information:
3. Create account with user details
Choose this option if you would like to enter all the login details of the new user such as
username, password, etc. Under these conditions, the fields username, password,
surname, first name, and roles are mandatory.
After you've created the user, the account is ready for the user to use with the user name
and password that you provide.
394
Manage users, user roles and user groups Create a user
4. Email invitation to create account
Choose this option if you want to send an invitation by email to the user. Then she/he must
return to DHIS2 and finish setting up their user account. The account that the user finishes
setting up will be limited according to how you configure the account.
Note
In order to use this feature the system should have a valid email
configuration in SystemSettings -> Email
Enter the email address to which the invitation should be sent. If you want to, you may also enter
the user name that the account will have. If you leave the user name empty, then the user may
choose their own user name when they respond to the invitation (as long as it is not taken
already for another user.)
After you've created the user, the system sends an email to the address you provided. It contains
a unique web link by which the user can return to the system and activate their account by
entering the rest of their user information. The user must finish setting up the account within 4
days, after that the invitation becomes invalid.
1. (Optional) Provide values for the fields OpenID, LDAP identifier, Mobile phone number,
WhatsApp, Facebook messenger, Skype, Telegram and Twitter.
2. Select an Interface language.

You can select a language into which fixed elements of the DHIS2 user interface have been
translated.
3. Select a Database language.

You can select a language into which implementation-supplied items have been translated
in the database, for example data element names or organisation unit level names.
4. In the Available roles section, double-click the user roles you want to assign to the user.
395
Manage users, user roles and user groups Create a user
Select Data capture and maintenance organisation units.

5.
The data capture and maintenance organisation units control for which organisation units
the user can do data entry. You must assign at least one data capture and maintenance
organisation unit to each user.
Users will have access to all sub-organisation units of the assigned organisation units. For
example, if you've assigned a user to a district which has several facilities contained in the
district, the user would have access to the district's data, as well as all of the facilities
contained within the district.
6. (Optional) Select Data output and analysis organisation units.
The data output and analysis organisation units controls for which organisation units the
user can view aggregated data in the analytics apps, for example the Pivot Table and GIS
apps. You can assign any number of data output and analysis organisation units to a user.
Users will have access to all sub-organisation units of the assigned organisation units. You
shouldn't select the descendants of an organisation unit which you have already selected.
For example, if you've assigned the user to a district, you shouldn't select the facilities
within that district.
Note
Assigning data output and analysis organisation units organisation units
is optional. If you don't specify any organisation unit, the user will have
access to the full organisation unit hierarchy for viewing aggregated
data. As with the data capture organisation units, you should not select
descendant organisation units of a unit which you have already
396
Manage users, user roles and user groups Edit user objects
selected.
In several places in the analytics apps, you can select "user

organisation unit" for the organisation unit dimension. This mechanism
will first attempt to use the data view organisation units linked to the
current user. If not found, it will use the data capture and maintenance
organisation units. If the user has been assigned to multiple
organisation units, the use of "user organisation unit" may result in
unpredictable behaviour.
1. Click Show more options and an additional three fields will show. (Optional)
2. In the Search organisation units select the organisation units you want the user to be able
to search in.
3. (Optional) In the Available user groups section, double-click the user groups you want to
assign to the user.
4. (Optional) In the Available dimension restrictions for data analytics section, double-click
the dimensions you want to assign to the user.
You can restrict the values the user sees in data analytics apps by selecting dimensions
that will restrict the user's view.
Example
Let's say you have defined Implementing Partner as a category option
group set, and you have shared with this user only one or more specific
implementing partners (category option groups). If you want to make
sure that the user does not see totals in analytics that include values
from other groups, assign Implementing Partner to the user.
This insures that any data visible to the user through the analytics apps
will be filtered to select only the Implementing Partner category option
group(s) which are visible to the user.
1. Click Save.
Edit user objects
1. Open the Users app and find the type of user object you want to edit.
2. In the object list, directly click the relevant object, or click the menu icon and select Edit.
4. Click Save.
397
Manage users, user roles and user groups Disable users
Disable users
You can disable a user. This means that the user's account is not deleted, but the user can't log in
or use DHIS2.
1. Open the Users app and click User.
2. In the list, click the menu icon of relevant user record and select Disable.
3. Click OK to confirm.
Warning
If you are using the Android Capture App disabling a user will cause the
application to delete the local data stored on the phone next time the
user attemps an on-line login. Please make sure that when you use the
disable user function all the data has been synced with the server. Or
that you are using this funcionality to ensure data deletion in case of a
device being lost.
Display a user's profile
2. In the list, click the menu icon of the relevant user and select Profile.
Filter users by organisation unit
You can view all users that have been assigned to a particular organisation unit.
1. Open the Users app and click Users.
2. Above the user list, click on the Organisation Unit filter input.
3. A pop-up will appear in which you can select the organisation units you would like to filter
by.
The list of users will be filtered to only include users which have been assigned to the selected
organisation units.
Clone users
2. In the object list, click the menu icon of the relevant user and select Replicate.
3. Enter a new user name and password for the cloned user account.
4. Click Replicate.
5. In the object list, click the user you just created and click Edit.
7. Click Save.
Change user password
To change a user's password:
398
Manage users, user roles and user groups Delete user objects
In the object list, click the menu icon of the relevant user and select Edit.
2.
3. Enter a new password and retype it.
4. Click Save.
Password requirements
The following rules apply when you create a new password. The password must:
• Contain at least 8 characters. Note that this number is configurable through the system
setting "Minium characters in password", which can be up to 14 characters.
• Not contain more than 40 characters.
• Contain at least one special character (non-alphanumeric character).
• Contain at least one upper-case character.
• Contain at least one lower-case character.
• Contain at least one digit (number).
• Not contain the username or email address of the user account.
• Not contain generic words such as system, admin, user, login, and manager.
• Not be one of the previous 24 passwords the user has used. This does not apply in case
when a super user resets the password for another user.
Delete user objects
1. Open the Users app and find the type of user object you want to delete.
2. In the object list, click the menu icon of the relevant object and select Remove.
Display details of user objects
1. Open the Users app and find the type of user object you want to view.
2. In the object list, click the menu icon of the relevant object and select Show details.
Disable Two Factor Authentication for a user
If a user has enabled Two Factor Authentication and then loses access to his/her authentication
device (e.g. smartphone gets lost or broken), this user will not be able to log into the system any
more. To solve this issue, a user manager can disable Two Factor Authentication for the affected
user, so that the user is able to access the system again using just a password.
1. Open the Users app and click Users.
2. In the object list, click the menu icon of the relevant user and select Disable Two Factor
Authentication.
3. Click OK to confirm
Note
399
Manage users, user roles and user groups Manage user roles
The option to disable Two Factor Authentication will only be available for
users that have set up Two Factor Authentication via the user-profile-
app.
Manage user roles
Create a user role
1. Open the Users app and click User role.
2. Click Add new.
3. Enter a Name, for example "Super user" or "Admin user".
4. Enter a Description.
5. In the Authorities section, select the authorities you want to give to the user role. You can
also use the filter inputs above the authority section to search for a specific authority.
6. Click Add.
400
Manage users, user roles and user groups Edit user objects
Edit user objects
4. Click Save.
Delete user objects
Change sharing settings for user objects
1. Open the Users app and find the type of user object you want to modify.
2. In the object list, click the relevant object and select Sharing settings.
3. (Optional) Search for a user group and select it, then click the plus icon. The user group is
added to the list.
4. (Optional) Select External access (without login).
5. Change the settings for the user groups you want to modify.
6. None
7. Can view: Everyone in the user group can view the object
8. Can edit and view: Everyone in the user group can view and edit the object
9. Click Save.
Manage user groups
Create a user group
1. Open the Users app and click User group.
2. Click Add new.
3. In the Name field, type the name of the user group.
4. In the Available users section, double-click the users you want to add to the user group.
5. In the Available user groups section, double-click the user groups you want to add to the
user group.
6. Click Add.
401
Manage users, user roles and user groups Join user groups
Join user groups
2. In the list, click the relevant user group and select Join group.
Leave user groups
2. In the list, click the relevant user group and select Leave group.
Edit user objects
4. Click Save.
Delete user objects
Change sharing settings for user objects
1. Open the Users app and find the type of user object you want to modify.
2. In the object list, click the relevant object and select Sharing settings.
3. (Optional) Search for a user group and select it, then click the plus icon. The user group is
added to the list.
4. (Optional) Select External access (without login).
5. Change the settings for the user groups you want to modify.
6. None
7. Can view: Everyone in the user group can view the object
8. Can edit and view: Everyone in the user group can view and edit the object
9. Click Save.
Enable support for OpenID
DHIS2 supports the OpenID standard, which allows third party login using a OpenID provider, for
more information see http://openid.net. To create a custom OpenID URL for a user name you can
visit this URL and log in with your OpenID provider: http://openid-provider.appspot.com.
402
Manage users, user roles and user groups Decentralize user management
To enable support for OpenID in DHIS2, you must:
1. Set your OpenID provider: This can be done inside system settings, under "Access". Here
you can set both the OpenID provider, and also the label to display on the login page to
login with this provider (defaults to Login with OpenID).
2. Set the OpenID identifier on the user: For every user that should be able to login with his
OpenID identifier, you will need to set this on the user itself. This can be done in user
management, under the email field, there is not a field called OpenID which can be used to
fill in the OpenID identifier.
Decentralize user management
DHIS2 supports a concept for user management referred to as managed users which allows to
explicitly define which users should be allowed to manage or modify which users. To "manage a
user" implies that you can see and modify that user. The basic concept for user management is
that you can see and modify users which you have been granted all of the authorities; in other
words you can modify users which have a subset of your own authorities. The managed users
concept gives you greater control over this.
The managed users concept allows you to define which users should be able to manage which
users. This is configured through user groups and memberships within such groups. A user group
can be configured to be allowed to manage other user groups from the standard add and update
user interface. The effect is that a specific user can manage all users which are members of user
groups which can be managed by a user group that the user is member of. In other words, users
can be managed by all members of user groups which are managing user groups they are
member of.
To enable this concept you should grant users the authority to "Add/update users within managed
groups", and not grant access to the standard "Add/update users" authority. An implication of the
managed users concept is that when creating a user with the "Add/update users within managed
groups" only, the user must be made a member of at least one user group that the current user
can manage. If not, the current user would lose access to the user being created immediately.
This is validated by the system.
When granted the "Add/update users within managed groups" authority, the system lets a user
add members to user groups for which she has read-only access to. The purpose of this is to
allow for decentralized user management. You may define a range of user groups where other
users may add or remove members, but not remove or change the name of the group.
Example: user management in a health system
In a health system, users are logically grouped with respect to the task they perform and the
position they occupy.
1. Define which users should have the role as system administrators. They are often part of
the national HIS division and should have full authority in the system.
2. Create roughly one user role for each position.
Examples of common positions are:
403
Manage users, user roles and user groups Example: user management in a health system
Recommended
Position Typical tasks Comment
authorities
Only system
System administrators Set up the basic Add, update and delete
administrators should
structure the core elements of the
modify metadata.
(metadata) of the system, for example
system. data elements, If you allow users
indicators and data outside the system
sets. administrators team to
modify the metadata, it
might lead to problems
with coordination.
Updates to the system

should only be
performed by the
administrators of the
system.
National health managers Monitor and Access to the reports Don't need access to
analyse data module, the GIS, Data enter data, modify data
Province health managers
Quality apps and the elements or data sets.
dashboard.
National health Enter data that Access to all the -

information system comes from analysis and validation
division officers (HISO) facilities which are apps
not able to do so
District health records and Access to the Data
directly
information officers Entry app.
(DHRIO) Monitor, evaluate
and analyse data
Facility health records and
information officers (HRIO)
Data entry clerks - - -
404
User authorities Example: user management in a health system
User authorities
Accept data at lower levels F_ACCEPT_DATA_LOWER_LEVELS
Access my data mart F_MYDATAMART_VIEW
Add Facility F_FRED_CREATE
Add Locale F_LOCALE_ADD
Add Option Set F_OPTIONSET_ADD
Add Organisation Unit Group Set F_ORGUNITGROUPSET_ADD
Add Program Rule F_PROGRAM_RULE_ADD
Add Public Map F_MAP_PUBLIC_ADD
Add Relationship Type F_RELATIONSHIPTYPE_ADD
Add/Remove Members In Read-Only User Groups F_USER_GROUPS_READ_ONLY_ADD_MEMBE

RS
Add SQL View F_SQLVIEW_ADD
Add Tracked Entities F_TRACKED_ENTITY_ADD
Add Tracked Entity Attribute Value F_TRACKED_ENTITY_ATTRIBUTEVALUE_ADD
Add Tracked Entity Form F_TRACKED_ENTITY_FORM_ADD
Add Tracked Entity Instance Comment F_TRACKED_ENTITY_COMMENT_ADD
Add Tracked Entity Relationship F_RELATIONSHIP_ADD
Add/Update Attribute F_ATTRIBUTE_ADD
Add/Update Chart F_CHART_ADD
Add/Update Concept F_CONCEPT_ADD
Add/Update Constant F_CONSTANT_ADD
Add/Update Data Value F_DATAVALUE_ADD
Add/Update Indicator Type F_INDICATORTYPE_ADD
Add/Update Min/max rule F_DATAELEMENT_MINMAX_ADD
Add/Update Organisation Unit F_ORGANISATIONUNIT_ADD
Add/Update Private Category Option Group F_CATEGORY_OPTION_GROUP_PRIVATE_ADD
Add/Update Private Category Option Group Set F_CATEGORY_OPTION_GROUP_SET_PRIVATE_

ADD
Add/Update Private Data Element F_DATAELEMENT_PRIVATE_ADD
Add/Update Private Data Element Category F_CATEGORY_PRIVATE_ADD
Add/Update Private Data Element Category Combo F_CATEGORY_COMBO_PRIVATE_ADD
Add/Update Private Data Element Category Option F_CATEGORY_OPTION_PRIVATE_ADD
Add/Update Private Data Element Category Option F_CATEGORY_OPTION_COMBO_PRIVATE_ADD

Combo
Add/Update Private Data Element Groups F_DATAELEMENTGROUP_PRIVATE_ADD
Add/Update Private Data Element Group Sets F_DATAELEMENTGROUPSET_PRIVATE_ADD
Add/Update Private Data Set F_DATASET_PRIVATE_ADD
Add/Update Private Document F_DOCUMENT_PRIVATE_ADD
Add/Update Private Indicator F_INDICATOR_PRIVATE_ADD
Add/Update Private Indicator Group F_INDICATORGROUP_PRIVATE_ADD
405
Add/Update Private Indicator Group Sets F_INDICATORGROUPSET_PRIVATE_ADD
Add/Update Private Option Set F_OPTIONSET_PRIVATE_ADD
Add/Update Private Organisation Unit Group F_ORGUNITGROUP_PRIVATE_ADD
Add/Update Private Organisation Unit Group Set F_ORGUNITGROUPSET_PRIVATE_ADD
Add/Update Private Program F_PROGRAM_PRIVATE_ADD
Add/Update Private Report F_REPORT_PRIVATE_ADD
Add/Update Private SQL View F_SQLVIEW_PRIVATE_ADD
Add/Update Private Tracked Entity Attribute F_TRACKED_ENTITY_ATTRIBUTE_PRIVATE_ADD
Add/Update Private User Group F_USERGROUP_PRIVATE_ADD
Add/Update Private User Role F_USERROLE_PRIVATE_ADD
Add/Update Private Validation Rule Group F_VALIDATIONRULEGROUP_PRIVATE_ADD
Add/Update Program Attribute F_PROGRAM_ATTRIBUTE_ADD
Add/Update Program Indicator F_ADD_PROGRAM_INDICATOR
Add/Update Program Stage F_PROGRAMSTAGE_ADD
Add/Update Program Stage Section F_PROGRAMSTAGE_SECTION_ADD
Add/Update Public Category Option Group F_CATEGORY_OPTION_GROUP_PUBLIC_ADD
Add/Update Public Category Option Group Set F_CATEGORY_OPTION_GROUP_SET_PUBLIC_A

DD
Add/Update Public Chart F_CHART_PUBLIC_ADD
Add/Update Public Dashboard F_DASHBOARD_PUBLIC_ADD
Add/Update Public Data Element F_DATAELEMENT_PUBLIC_ADD
Add/Update Public Data Element Category F_CATEGORY_PUBLIC_ADD
Add/Update Public Data Element Category Combo F_CATEGORY_COMBO_PUBLIC_ADD
Add/Update Public Data Element Category Option F_CATEGORY_OPTION_PUBLIC_ADD
Add/Update Public Data Element Category Option F_CATEGORY_OPTION_DELETE
Add/Update Public Data Element Category Option F_CATEGORY_OPTION_COMBO_PUBLIC_ADD

Combo
Add/Update Public Data Element Groups F_DATAELEMENTGROUP_PUBLIC_ADD
Add/Update Public Data Element Group Sets F_DATAELEMENTGROUPSET_PUBLIC_ADD
Add/Update Public Data Set F_DATASET_PUBLIC_ADD
Add/Update Public Document F_DOCUMENT_PUBLIC_ADD
Add/Update Public Indicator F_INDICATOR_PUBLIC_ADD
Add/Update Public Indicator Group F_INDICATORGROUP_PUBLIC_ADD
Add/Update Public Indicator Group Sets F_INDICATORGROUPSET_PUBLIC_ADD
Add/Update Public Option Set F_OPTIONSET_PUBLIC_ADD
Add/Update Public Organisation Unit Group F_ORGUNITGROUP_PUBLIC_ADD
Add/Update Public Organisation Unit Group Set F_ORGUNITGROUPSET_PUBLIC_ADD
Add/Update Public Program F_PROGRAM_PUBLIC_ADD
Add/Update Public Report F_REPORT_PUBLIC_ADD
Add/Update Public Report Table F_REPORTTABLE_PUBLIC_ADD
Add/Update Public SQL View F_SQLVIEW_PUBLIC_ADD
Add/Update Public Tracked Entity Attribute F_TRACKED_ENTITY_ATTRIBUTE_PUBLIC_ADD
406
Add/Update Public User Group F_USERGROUP_PUBLIC_ADD
Add/Update Public User Role F_USERROLE_PUBLIC_ADD
Add/Update Public Validation Rule Group F_VALIDATIONRULEGROUP_PUBLIC_ADD
Add/Update Section F_SECTION_ADD
Add/Update Tracked Entity F_TRACKED_ENTITY_ADD
Add/Update Tracked Entity Attributes F_ALLOW_EDIT_TRACKED_ENTITY_ATTRIBUTE

S
Add/Update Tracked Entity Data Value F_TRACKED_ENTITY_DATAVALUE_ADD
Add/Update Tracked Entity Instance F_TRACKED_ENTITY_INSTANCE_ADD
Add/Update User F_USER_ADD
Add/Update User Group Managing Relationships F_USERGROUP_MANAGING_RELATIONSHIPS_

ADD
Add/Update User Within Managed Group F_USER_ADD_WITHIN_MANAGED_GROUP
Add/Update Validation Criteria F_VALIDATIONCRITERIA_ADD
Add/Update Validation Rule F_VALIDATIONRULE_ADD
Add Validation Rule Groups F_VALIDATIONRULEGROUP_ADD
Administrate data mart F_DATAMART_ADMIN
Administrate data mart F_DATA_MART_ADMIN
Administrate data visualizer F_DV_ADMIN
Administrate GIS F_GIS_ADMIN
Approve data F_APPROVE_DATA
Approve data at lower levels F_APPROVE_DATA_LOWER_LEVELS
Archive data F_ARCHIVE_DATA
Change GIS Configuration F_GIS_CONFIGURATION_UPDATE
Change Location of Tracked Entity Instance F_TRACKED_ENTITY_INSTANCE_CHANGE_LO

CATION
Change order in Data Set F_DATASET_ORDER_CHANGE
Change system settings F_SYSTEM_SETTING
Change Tracked Entity Instance Location F_TRACKED_ENTITY_CHANGE_LOCATION
Chart External Access F_CHART_EXTERNAL
Concept Management F_CONCEPT_MANAGEMENT
Constant Management F_CONSTANT_MANAGEMENT
Copy Excel Item F_COPY_EXCEL_ITEM_ADMINISTRATION
Create and download backup F_DASHBOARD_DOWNLOAD_BACKUP
Data Admin Locking F_DATAADMIN_LOCK
Data Admin Unlocking F_DATAADMIN_UNLOCK
Delete Attribute F_ATTRIBUTE_DELETE
Delete Category Option Group F_CATEGORY_OPTION_GROUP_DELETE
Delete Category Option Group Set F_CATEGORY_OPTION_GROUP_SET_DELETE
Delete Chart F_CHART_DELETE
Delete Concept F_CONCEPT_DELETE
Delete Constant F_CONSTANT_DELETE
407
Delete Data Element F_DATAELEMENT_DELETE
Delete Data Element Category F_CATEGORY_DELETE
Delete Data Element Category Combo F_CATEGORY_COMBO_DELETE
Delete Data Element Groups F_DATAELEMENTGROUP_DELETE
Delete Data Element Group Sets F_DATAELEMENTGROUPSET_DELETE
Delete Data Set F_DATASET_DELETE
Delete Data Value F_DATAVALUE_DELETE
Delete Document F_DOCUMENT_DELETE
Delete Excel Template F_EXCEL_TEMPLATE_MANAGEMENT_DELETE
Delete Facility F_FRED_DELETE
Delete Indicator F_INDICATOR_DELETE
Delete Indicator Group F_INDICATORGROUP_DELETE
Delete Indicator Group Sets F_INDICATORGROUPSET_DELETE
Delete Indicator Type F_INDICATORTYPE_DELETE
Delete Locale F_LOCALE_DELETE
Delete Min/max rule F_DATAELEMENT_MINMAX_DELETE
Delete Option Set F_OPTIONSET_DELETE
Delete Organisation Unit F_ORGANISATIONUNIT_DELETE
Delete Organisation Unit Group F_ORGUNITGROUP_DELETE
Delete Organisation Unit Group Set F_ORGUNITGROUPSET_DELETE
Delete Program F_PROGRAM_DELETE
Delete Program Attribute F_PROGRAM_ATTRIBUTE_DELETE
Delete Program Enrollment F_PROGRAM_INSTANCE_DELETE
Delete Program Stage F_PROGRAMSTAGE_DELETE
Delete Program Stage Section F_PROGRAMSTAGE_SECTION_DELETE
Delete Relationship Type F_RELATIONSHIPTYPE_DELETE
Delete Report F_REPORT_DELETE
Delete Report Table F_REPORTTABLE_DELETE
Delete Section F_SECTION_DELETE
Delete SMS F_MOBILE_DELETE_SMS
Delete SQL View F_SQLVIEW_DELETE
Delete Tracked Entity F_TRACKED_ENTITY_DELETE
Delete Tracked Entity Attribute F_TRACKED_ENTITY_ATTRIBUTE_DELETE
Delete Tracked Entity Attribute Value F_TRACKED_ENTITY_ATTRIBUTEVALUE_DELET

E
Delete Tracked Entity Data Value F_TRACKED_ENTITY_DATAVALUE_DELETE
Delete Tracked Entity Form F_TRACKED_ENTITY_FORM_DELETE
Delete Tracked Entity Instance F_TRACKED_ENTITY_INSTANCE_DELETE
Delete Tracked Entity Instance Comment F_TRACKED_ENTITY_COMMENT_DELETE
Delete Tracked Entity Instance Visit F_PROGRAM_STAGE_INSTANCE_DELETE
Delete Tracked Entity Relationship F_RELATIONSHIP_DELETE
Delete User F_USER_DELETE
408
Delete User Group F_USERGROUP_DELETE
Delete User Role F_USERROLE_DELETE
Delete User Within Managed Group F_USER_DELETE_WITHIN_MANAGED_GROUP
Delete Validation Criteria F_VALIDATIONCRITERIA_DELETE
Delete Validation Rule F_VALIDATIONRULE_DELETE
Delete Validation Rule Group F_VALIDATIONRULEGROUP_DELETE
Eliminate duplicate data elements F_ELIMINATE_DUPLICATE_DATA_ELEMENTS
Excel Reporting Administration F_EXCEL_REPORT_ADMINISTRATION
Execute SQL View F_SQLVIEW_EXECUTE
Export Activity Plan to XLS file F_ACTIVITY_PLAN_EXPORT
Export data F_EXPORT_DATA
Export events F_EXPORT_EVENTS
Export meta-Data F_METADATA_EXPORT
Generate Activity Plans F_GENERATE_ACTIVITY_PLANS
Generate min-max values F_GENERATE_MIN_MAX_VALUES
Generate Program Statistics Report F_GENERATE_STATISTICAL_PROGRAM_REPOR

T
Generate Program Summary Report F_GENERATE_PROGRAM_SUMMARY_REPORT
Generate Tracked Entity Tabular report F_GENERATE_BENEFICIARY_TABULAR_REPOR

T
Import data F_IMPORT_DATA
Import events F_IMPORT_EVENTS
Import from other systems F_IMPORT_OTHER_SYSTEMS
Import GML F_IMPORT_GML
Import meta-Data F_METADATA_IMPORT
Insert custom Java script and CSS F_INSERT_CUSTOM_JS_CSS
List Excel Template F_EXCEL_TEMPLATE_MANAGEMENT_LIST
List Tracked Entity Instance F_TRACKED_ENTITY_INSTANCE_LIST
List User Groups F_USERGROUP_LIST
List User Roles F_USERROLE_LIST
Load event reminder messages F_PROGRAM_STAGE_INSTANCE_REMINDER
Load Tracked Entity Instance History F_TRACKED_ENTITY_INSTANCE_HISTORY
Lock Data Set F_DATASET_LOCK
Manage integration routes F_MANAGE_INTEGRATION_ROUTES
Manage Program Indicators F_PROGRAM_INDICATOR_MANAGEMENT
Manage Program Rule F_PROGRAM_RULE_MANAGEMENT
Manage Tracked Entities F_TRACKED_ENTITY_MANAGEMENT
Manage Tracked Entity Instance Reminders F_TRACKED_ENTITY_INSTANCE_REMINDER_M

ANAGEMENT
Map External Access F_MAP_EXTERNAL
Merge organisation units F_MERGE_ORGANISATION_UNITS
Move Organisation Unit F_ORGANISATIONUNIT_MOVE
409
Multiple Individual Data Entry F_NAME_BASED_DATA_ENTRY
Option Set Management F_OPTIONSET_MANAGEMENT
Organisation Unit Registration F_ORGANISATION_REGISTRATION
Perform maintenance tasks F_PERFORM_MAINTENANCE
Program Enrollment F_PROGRAM_ENROLLMENT
Program Event Management F_PROGRAM_INSTANCE_MANAGEMENT
Program Stage Section Management F_PROGRAMSTAGE_SECTION_MANAGEMENT
Program Tracking Management F_PROGRAM_TRACKING_MANAGEMENT
Program Un-enrollment F_PROGRAM_UNENROLLMENT
Prune organisation units F_PRUNE_ORGANISATION_UNITS
Remove Empty Tracked Entity Events F_TRACKED_ENTITY_REMOVE_EMPTY_EVENT

S
Rename Excel Template file F_EXCEL_TEMPLATE_MANAGEMENT_RENAME
Report Table External Access F_REPORTTABLE_EXTERNAL
Run validation F_RUN_VALIDATION
Scheduling Administration F_SCHEDULING_ADMIN
Scheduling case aggregate query builder F_SCHEDULING_CASE_AGGREGATE_QUERY_

BUILDER
Scheduling send messages F_SCHEDULING_SEND_MESSAGE
Search Activity Plan F_ACTIVITY_PLAN
Search events without registration F_PROGRAM_STAGE_INSTANCE_SEARCH
Search events with registration F_PROGRAM_TRACKING_SEARCH
Search Tracked Entity Instance F_TRACKED_ENTITY_INSTANCE_SEARCH
Search Tracked Entity Instance in All Org Units F_TRACKED_ENTITY_INSTANCE_SEARCH_IN_

ALL_ORGUNITS
See API Module M_dhis-web-api
See Apps Maintenance module M_dhis-web-maintenance-appmanager
See Browser Cache Cleaner module M_dhis-web-cache-cleaner
See Dashboard integration module M_dhis-web-dashboard-integration
See Dashboard module M_dhis-web-dashboard
See Data Administration module M_dhis-web-maintenance-dataadmin
See Data Elements and Indicators Maintenance M_dhis-web-maintenance-datadictionary

module
See Data Entry module M_dhis-web-dataentry
See Data Mart module M_dhis-web-datamart
See Data Set Maintenance module M_dhis-web-maintenance-dataset
See Data Visualizer module M_dhis-web-visualizer
See Event Capture module M_dhis-web-event-capture
See Event Reports module M_dhis-web-event-reports
See Event Visualizer module M_dhis-web-event-visualizer
See Excel Report module M_dhis-web-excel-reporting
See Export Data Mart Module M_dhis-web-exportdatamart
410
See FRED API Module M_dhis-web-api-fred
See GIS module M_dhis-web-gis
See GIS module M_dhis-web-mapping
See Import-Export module M_dhis-web-importexport
See Individual Records M_dhis-web-caseentry
See Light module M_dhis-web-light
See Line-listing DataEntry module M_dhis-web-dataentry-national
See Mobile Maintenance module M_dhis-web-maintenance-mobile
See NRHM Reports module M_dhis-web-reports
See Organisation Unit Maintenance module M_dhis-web-maintenance-organisationunit
See Pivot Table module M_dhis-web-pivot
See Report module M_dhis-web-reporting
See Settings Maintenance module M_dhis-web-maintenance-settings
See Smartphone module M_dhis-web-mobile
See SMS module M_dhis-web-sms
See Tracked Entity And Programs module M_dhis-web-maintenance-program
See Tracker Capture module M_dhis-web-tracker-capture
See User Maintenance module M_dhis-web-maintenance-user
See Validation Analysis module M_dhis-web-validationrule-local-in
See Validation Rule module M_dhis-web-validationrule
Send message F_SEND_MESSAGE
Send SMS F_MOBILE_SENDSMS
Set mobile settings F_MOBILE_SETTINGS
Single Event Without Registration Data Entry F_ANONYMOUS_DATA_ENTRY
Single Event With Registration Data Entry F_SINGLE_EVENT_DATA_ENTRY
Sql View External Access F_SQLVIEW_EXTERNAL
Sql View Management F_SQLVIEW_MANAGEMENT
Tracked Entity Aggregation F_TRACKED_ENTITY_AGGREGATION
Tracked Entity Form Management F_TRACKED_ENTITY_FORM_MANAGEMENT
Tracked Entity Instance Dashboard F_TRACKED_ENTITY_INSTANCE_DASHBOARD
Tracked Entity Instance Management F_TRACKED_ENTITY_INSTANCE_MANAGEMENT
Tracked Entity Relationship Management F_RELATIONSHIP_MANAGEMENT
Update Facility F_FRED_UPDATE
Update Organisation Unit Level F_ORGANISATIONUNITLEVEL_UPDATE
Update Program Rule F_PROGRAM_RULE_UPDATE
Update Relationship Type F_RELATIONSHIPTYPE_UPDATE
Update Tracked Entities F_TRACKED_ENTITY_UPDATE
Update Tracked Entity Attribute F_TRACKED_ENTITY_ATTRIBUTE_EDIT
Upload Excel Template F_EXCEL_TEMPLATE_MAMAGEMENT_UPLOAD
View and Search Tracked Entity Attributes and F_ACCESS_TRACKED_ENTITY_ATTRIBUTES

Identifiers
View data browser F_VIEW_DATABROWSER
411
View Program Stage Completeness Report F_PROGRAM_STAGE_COMPLETENESS
View program tracking F_PROGRAM_TRACKING_LIST
View Report F_REPORT_VIEW
View Tracked Entity Attribute F_TRACKED_ENTITY_ATTRIBUTE_VIEW
View unapproved data F_VIEW_UNAPPROVED_DATA
View User F_USER_VIEW
View User Group Managing Relationships F_USERGROUP_MANAGING_RELATIONSHIPS_

VIEW
View User Within Managed Group F_USER_VIEW_WITHIN_MANAGED_GROUP
Delete tracked entity instance and associated F_TEI_CASCADE_DELETE

enrollments and events
Delete enrollment and associated events F_ENROLLMENT_CASCADE_DELETE
Edit expired data F_EDIT_EXPIRED
412
About sharing of objects Sharing of objects
About sharing of objects

This chapter discusses the sharing of entities feature in DHIS2.
Sharing of objects
Many objects in DHIS2, like reports, charts, maps and indicators, can be shared. DHIS2 supports
sharing of metadata or sharing of data. Sharing of metadata means making an object, like a
report, available for reading or modification to a group of users or to everyone. Sharing of data
means making the actual data captured available to others, and controlling who can capture that
kind of data. For instance for reports, the sharing dialog can be opened by clicking on the
"Sharing settings" button next to each report in the list. Implementers can use this feature to allow
access to certain objects to only certain user groups. Users can use the feature to decide who
they would like to share objects (such as pivot tables, charts, dashboards, etc) with.
If sharing is supported for a particular class of objects, a dialog will be available called "Sharing
settings", usually available by clicking on the name of the object or in the analytics tools, through
an icon (Share with other people). Once you have accessed the sharing settings for the object
you wish to share, a dialog similar to the one below will be shown.
413
About sharing of objects Sharing of objects
You can share your report with everyone or with a number of user groups. "External access" can
be enabled to allow this resource to be shared with everyone, including users which cannot logon
to DHIS2. This is useful for sharing public resources with external systems. Note, that if objects
are shared externally, then they are visible to anyone who has access to the URL which provides
the resource without any login credentials.
Next to "Public access" you can choose your public access option under "METADATA": "No
access", "Can view only" or "Can edit and view", and under "DATA": "No access", "Can view data",
"Can capture data". Public access refers to users which are logged into the system. Edit also
implies deleting the report.
To share with a group, simply start typing the name of the group and the "Search for user groups"
input field and select your desired group. Click on the "+" icon next to the input field to share with
that group. For each group you can set an access option, similar to public access.
414
About sharing of objects Metadata sharing and access control
Sharing with a user group implies that all users in that group will get access to the shared object.
To create a user group you can go to the dashboard module and click on "Groups". This will lead
you to the list of groups where you can click "Add new" in the top right corner. Creating user
groups is open for everyone from the dashboard module.
Metadata sharing and access control
The objects which support metadata sharing are indicator, indicator group, indicator group set,
data dictionary, data set, program, standard report, resource, report table, chart, map and user
group. Out of those objects, report table, chart, map and user group are open for everyone to
create privately. Private means that the objects are available only to yourself or potentially to a
number of user groups if you choose to share the object. These objects are referred to as "open"
objects and can be created by all users. The remaining objects require that your user account
has the authority to create them. These objects are referred to as "non-open" objects.
A user can be granted the authority to create publicly accessible objects or privately accessible
objects. In order to create a publicly accessible object (available for viewing or editing by anyone)
your user account must have the authority to do so. As an example, to create a publicly
accessible chart, your user must have the "Create public chart" authority granted. The authority to
create private objects applies only to non-open objects. For example, to allow a user to create
indicators which will only be accessible to that user and not to everyone, the user can be issued
with the "Create private indicator" authority.
Sharing a non-open object with another person and let her edit the object requires that the
person's user account has the authority for updating that type of objects granted. For instance, if
you want to let another person edit your indicator, that person's user account must have the
"Update indicator" authority granted. This does not apply for open objects.
When you create a new object it will automatically become viewable for everyone if your user
account has the authority to create public objects. As an example, if you create a standard report
and you have the "Create public standard report" authority granted, the report will become
viewable for everyone. If you do not have that authority granted the report will be viewable only to
yourself. After you have created an object, you may navigate to the "Sharing settings" dialog and
set your desired access control level.
If you need a user account which is able to view absolutely all objects you can create a user role
with the "ALL" authority and assign a user to that role. If you need to switch between a "complete"
view of objects and a "personal" view of objects it is recommended to create two user accounts,
one assigned with the "ALL" authority and one without.
Metadata sharing applied
The metadata sharing functionality is useful in several scenarios. One use-case is setting up a
DHIS2 instance for a global organisation with operations in multiple countries. Typically the
organisation has a set of global data sets, indicators and reports which should apply to all
countries, while all countries will have the need for country-specific data sets, indicators and
reports. In this scenario the following approach could work:
• Set up one user group for global personnel.
• Set up a user group for personnel in each country.
• Create global data sets and reports, make them viewable for everyone and editable for the
global user group only.
• Create country-specific data sets and reports, make them viewable and editable for the
country user group and the global user group only.
415
About sharing of objects Data sharing and access control
This way, the global indicators and reports could be viewed and analysed by everyone, but
maintained by the global user group only. The country-specific data sets, indicators and reports
could be viewed and maintained by the country and global personnel, without being visible or
impacting the system for other countries in the organisation.
A similar approach could work for a scenario with a donor, multiple funding agencies and
implementing partners in a country, where user groups could be set up for each of those entities.
That way each implementing partner could create and share their reports within their organisation
without affecting or allowing access to others. Reports could also be shared with supervisors and
funding agencies at the end of reporting periods.
Another use-case is a country department of health with multiple health programs. Typically there
is a need for having general reports and charts for the department while allowing the health
programs to develop specific reports and charts for internal use. This can be achieved by creating
user groups for each health program. Later, when developing reports and charts, these can be
made viewable and editable to the program user group only. This way the reports will not be
visible to other programs and users. This is beneficial because the reports are kept internal to the
program and because the visible list of reports of other users are kept shorter and more relevant.
Data sharing and access control
The objects which support data sharing are data set, tracked entity type, program and program
stage. The purpose of data sharing is to control which users can capture data, and which users
can see the data captured.
Data sharing for event based programs
Applies to the object types of tracked entity type, program and program stage. When working with
single event programs in event capture, a user will have to possess the "DATA:Can view data"
sharing level to see the program and its data. Without this sharing level, the program and its data
will not be visible to the user. When working with tracker programs in tracker capture, the user will
need to have "DATA:Can view data" to both the tracked entity type and program. In case of a
tracker program, the user will also need "DATA:Can view data" on each program stage individually
to be able to see the data within the program. To capture data the user needs the "DATA:Can
capture data" sharing level.
Note
To see and capture data for a program, a data capture user also needs
to report for an organisation unit to where the program has been
assigned.
Data sharing for tracker programs
416
About sharing of objects Data sharing for event based programs
Object type Can view data Can capture data Comment
Tracked • Search for tracked • Edit visible tracked

entity type entities with this entity attributes for
tracked entity type. tracked entity
instances of this type.
• See tracked entity
type attribute values • Register/create new
for this tracked entity tracked entity
type. instances of this type.
• Delete tracked entity

• Deactivate/reactivate
tracked entity
Program • Search for tracked • Enroll into the Both "Can view data"
entities within this program. and "Can capture
program. data" also requires
• Edit enrollment details
the user to have "Can
• See tracked entity for the program.
view data" for the
attributes specific to
• Complete/reopen tracked entity type.
this program.
enrollments into the
• See enrollment details program.
for the program.
• Add notes for the
• See notes for the program.
enrollment.
• Edit relationships for
the program.
• Send message to
tracked entity
instance.
• Delete enrollments in
the program.
417
About sharing of objects Data sharing for data sets
Program • See the program • Add/schedule/refer a Both "Can view data"

stage stage and its events new event within the and "Can capture
and data within an program stage. data" also requires
enrollment. the user to have "Can
• Complete/reopen the
view data" for the
• See the program events within the
program and the
stage notes. program stage.
tracked entity type.
• Edit tracked entity
data values within
events in the program
stage.
• Add notes for events

in the program stage.
• Delete events in the

program stage.
Data sharing for single event programs
Program • See list of events • Add new events into

within the program. the program.
• See tracked entity • Edit data for events in

data values for events the program.
in the program.
• Delete events in the
program.
Data sharing for data sets
Applies to the object types of data set and category option . When working in Data Entry app, the
user will need to have "DATA:Can capture data" to both see and capture data in the data set. To
save data for an entry field in Data Set users need:
1. Authority: F_DATAVALUE_ADD ( Can add data value )
2. Data Set is shared with "Data: Can capture data"
3. Data Element is shared with "Metadata: Can View"
4. All Category Options used by selected Data Set are shared with "Data: Can capture data"
Note
To see and capture data for a data set, a data capture user also needs
to report for an organisation unit to where the data set has been
assigned.
Data sharing for data sets
418
About sharing of objects Data sharing for data sets
Data set • View Data Set's data • Can see DataSet in For saving data value
in Analytics Data Entry app in Data Entry app,
users also need "Can
• Can save data for
capture data" for
Data Set using API
Category Options
within selected Data
Set.
CategoryO For
• Can view data values • Can save data value
ption CategoryOptionCom
belong to shared for input fields in Data
bo and
Category Option in Entry app which
AttributeOptionComb
analytics belongs to shared
o to be writeable, all
Category Options.
belongs
CategoryOptions
must be shared with
"Can capture data".
419
Configure the Maps app Context
Configure the Maps app

Context
Setting up the Maps simply means storing coordinates for the organisation units you want to show
on the map in the database. Coordinates are often distributed in proprietary formats and will need
to be converted to a format which DHIS2 understands. ESRI shapefiles are the most common
geospatial vector data format for desktop applications. You might find shapefiles for your country
here or in many other geospatial data repositories on the web. Some amount of work needs to be
done in order to use these coordinates in DHIS2 GIS, namely transforming the data into a
suitable format and ensuring the name which are contained in the geospatial data match exactly
with the names of the organization units which they should be matched to.
Only organisation units with POINT geometry types can be edited through the Maintenance App
at this time. To modify POLYGON geometries, please us the GML import feature.
To edit the POINT coordinates of an organisation unit, open the Maintenance App and navigate to
the Organisation Unit section. Click on the Organisation Unit you would like to view or edit, you
can search or filter the list from on the left-hand side of the screen. Once an organisation unit is
selected, you can edit the Latitude and Longitude values to update the POINT coordinates. If the
Organisation Unit has a POLYGON geometry, the coordinates cannot be edited.
If you are going to add or update coordinates for a large number of units, or if you need to update
polygon geometries, you should use the automatic GML import. The following section explains
how to perform a GML import.
Important
The only co-ordinate reference system supported by DHIS2 is EPSG:
4326, also known as geographic longitude/latitude. Coordinates must be
stored with the longitude (east/west position) proceeding the latitude
(north/south position). If your vector data is in a different CRS than
EPSG 4326, you will need to re-project the data first before importing
into DHIS2.
Importing coordinates
Step 1 - Simplify/generalize your geographical data
The boundaries in geographical data files are usually very accurate, too much so for the needs of
a web-based GIS. This usually does not affect the performance when using GIS files on a local
system, but it is usually necessary to optimize the geographical data for the web-based GIS
system of DHIS2. All geographical data needs to be downloaded from the server and rendered in
a browser, so if the data is overly complex, the performance of the DHIS2 GIS will be negatively
impacted. This optimization process can be described as follows:
Coordinates: The number of significant decimal digits (e.g. 23.02937874993774) should be

shortened to fewer digits (e.g. 23.03). Although this will result in some inaccuracies on the map,
given the usual scale at which maps in DHIS2 are produced (> 1:50,000), the loss of precision
should not be noticeable. Normally, no more than four significant digits after the decimal point
should be necessary., Polygons: In addition to shortening the number of significant digits, the
actual number of points should also be reduced to an optimal level. Finding this optimal level may
take a bit of experimentation. Decreasing the precision of the points as well as the number of
points through generalization, will lead to degradation of the polygon. However, after a bit of
experimentation, an optimal level of generalization can be found, where the accuracy of the
polygon is visually acceptable, and the performance of the GIS is optimal.
420
Configure the Maps app Importing coordinates
For polygons, we need to make the boundary lines less detailed by removing some of the line
points. Make a backup of your shapefiles before you start. One possible method is the use of
MapShaper which is an online tool which can be used to generalize geographical data. To use
MapShaper, simply upload your shapefile to the site. Then, at the centre bottom you see a slider
that starts at 0%. It is usually acceptable to drag it up to about 80%. In the left menu you can
check "show original lines" to compare the result and you may want to give a different
simplification method a try. When you are happy with the result, click "export" in the top right
corner. Then check the first of the four options called "Shapefile - polygons", click "create" and
wait for the download buttons to appear. Now, download the two files to your local computer and
overwrite the existing ones. Move on to the next step with your new simplified shapefile.
Step 2 - Convert the shapefile to GML
The recommended tool for geographical format conversions is called "ogr2ogr". This should be
available for most Linux distributions sudo apt-get install gdal-bin. For Windows, go to
http://fwtools.maptools.org/and download "FWTools", install it and open up the FWTools command
shell. During the format conversion we also want to ensure that the output has the correct
coordinate projection (called EPSG:4326 with geographic longitude and latitude). For a more
detailed reference of geographic coordinates, please refer to this site. If you have already
reprojected the geographic data to the geographic latitude/longitude (EPSG:4326) system, there
is no need to explicitly define the output coordinate system, assuming that ogr2ogr can
determine the input spatial reference system. Note that most shapefiles are using the EPSG:4326
system. You can determine the spatial reference system by executing the following command.
ogrinfo -al -so filename.shp
Assuming that the projection is reported to be EPSG:27700 by ogrinfo, we can transform it to

EPSG:4326 by executing the following command.
ogr2ogr -s_srs EPSG:27700 -t_srs EPSG:4326 -f GML filename.gml filename.shp
If the geographic data is already in EPSG:4326, you can simply transform the shapefile to GML by
executing the following command.
ogr2ogr -f GML filename.gml filename.shp
You will find the created GML file in the same folder as the shapefile.
Step 3 - Prepare the GML file
Unfortunately, the GML file is not ready for importation yet. Open it in a robust text editor like
Geany (Linux) or Notepad++ (Windows). GML is an XML based format which means that you will
recognize the regular XML tag hierarchy. In the GML file an organisation unit is represented as a
\<gml:featureMember>. Inside the feature members we usually find a lot of attributes, but we are
just going to import their coordinates.
In order to import geospatial data from the feature members of the GML input, DHIS2 must match
each of them with an organisation unit in its database. The feature member element must, in other
words, contain a reference to its corresponding organisation unit. The reference itself must be
one of three possible DHIS2 identifiers: uid, code or name. The identifier of choice must be
provided as a property for each feature member element. The importer will look for a property
with the local name of either Uid, Code or Name, e.g. "ogr:Name" or "anyPrefix:Code".
421
If your feature members already contain a property of the identifier you wish to use (such as the
name of an area) you can use search and replace in a text editor to rename these elements to a
name DHIS2 will recognize (see the below table). This is typically a workflow which is applicable
when using the name as the identifier (the source shapefile or even GML will usually contain the
name for each area it defines).
Organisation unit identifiers supported for GML import
Matching priority Identifier Valid spellings Guaranteed unique
1 Uid uid, Uid, UID Yes
2 Code code, Code, CODE No
3 Name name, Name, NAME No
In the case of renaming properties one would usually find a tag named something like
"ogr:DISTRICT_NAME", "ogr:NAME_1" and rename it to "ogr:Name". If using the code or uid
identifiers on the other hand, looking up the correct values in the DHIS2 database and going
through the GML file, adding the properties for each corresponding feature member might be
necessary. In any of the cases it is important to realize that the identifier used must uniquely
identify an organisation unit (e.g. if there are two organisation units in the database of the same
name or code, these cannot be matched properly on either). As uid is the only guaranteed-to-be-
unique identifier it is the most robust choice. However, as matching on name is usually easier
(given that the name is already part of your data), a viable approach to solving uniqueness
conflicts can be to match any non-uniquely named organisation units on a different identifier (uid,
preferably) and the rest on their names.
As can be seen in the above table there is a matching priority, meaning is any two or more
identifiers are provided for the same feature member, matching will be performed on the highest
priority identifier. Note also the valid properties which can be used in you GML. The namespace
prefix is not important as only the local name is used.
A common pitfall of performing preparation of the GML files is syntax- or element naming errors.
Therefore please make sure that all properties of the GML file are started and terminated with
correctly corresponding tags. Also make sure the properties follow either of the given valid
spellings of the property name. The identifying properties are supposed to look like e.g.
\<ogr:Name>Moyamba District\</ogr:Name>, \<somePrefix:uid>x7uuia898nJ\</somePrefix:uid> or
\<CODE>OU_12345\</CODE>. Another common error is not making sure the identifier matches
exactly, especially when using the name property. All matches are performed on exact values,
meaning that "Moyamba" in a source GML file would not be matched against "Moyamba District" in
the database.
Have a brief look at the identifiers and compare them to the corresponding values in the
database. If they seem to match fairly good, it is about time to do a preview in the import-export
module.
Go to Services -> Import-Export, select "Preview", select the GML file and click "Import". Look for
new/updated organisation units. Our intention is to add coordinates to already existing
organisation units in the database, so we want as many updates as possible and 0 new. Those
listed as new will be created as root units and mess up the organisation unit trees in DHIS2. If any
listed as new, click the number and the organisation units in question will appear in the list below.
If there are any slight misspellings compared to the organisation unit names in the database - fix
them and do the preview again. Otherwise, click the "discard all" button below the list and then
the "Import all" button above the list.
If the import process completes successfully, you should now be able to utilize the geographical
data in the DHIS2 GIS. If not, check the log for hints and look for common errors such as:
422
- Name duplicates in the GML file. The name column in the database is unique and does not
accept two organisation units with the same name.
- The "shortname" column in the organisationunit table in your database has a too small varchar
definition. Increase it to 100.
- Special name characters in the GML file. Be sure to convert these to appropriate XML
equivalents or escape sequences.
- Wrongly formatted input GML, non-matching tags
423
Configure report functionality Data sources for reporting
Configure report functionality

Data sources for reporting
Types of data and aggregation
In the bigger picture of HIS terminology all data in DHIS2 are usually called aggregated as they
are aggregates (e.g. monthly summaries) of medical records or some kind of service registers
reported from the health facilities. Aggregation inside DHIS2 however, which is the topic here, is
concerned with how the raw data captured in DHIS2 (through data entry or import)are further
aggregated over time (e.g. from monthly to quarterly values) or up the organisational hierarchy
(e.g. from facility to district values).
Terminology
• Raw data refers to data that is registered into the DHIS2 either through data entry or data
import, and has not been manipulated by the DHIS2 aggregation process. All these data
are stored in the table (or Java object if you prefer) called DataValue.
• Aggregated data refers to data that has been aggregated by the DHIS2, meaning it is no
longer raw data, but some kind of aggregate of the raw data.
• Indicator values can also be understood as aggregated data, but these are special in the
way that they are calculated based on user defined formulas (factor * numerator/
denominator). Indicator values are therefore processed data and not raw data, and are
located in the aggregatedindicatorvalue table/object. Indicators are calculated at any level
of the organisational hierarchy and these calculations are then based on the aggregated
data values available at each level. A level attribute in the aggregateddatavalue table refers
to the organisational level of the orgunit the value has been calculated for.
• Period and Period type are used to specify the time dimension of the raw or aggregated
values, and data can be aggregated from one period type to another, e.g. from monthly to
quarterly, or daily to monthly. Each data value has one period and that period has one
period type. E.g. data values for the periods Jan, Feb, and Mar 2009, all of the monthly
period type can be aggregated together to an aggregated data value with the period Q1
2009 and period type Quarterly.
Basic rules of aggregation
What is added together
Data (raw) can be registered at any organisational level, e.g. at national hospital at level 2, a
health facility at level 5, or at a bigger PHC at level 4. This varies form country to country, but
DHIS2 is flexible in allowing data entry or data import to take place at any level. This means that
orgunits that themselves have children can register data, sometimes the same data elements as
their children units. The basic rule of aggregation in DHIS2 is that all raw data is aggregated
together, meaning data registered at a facility on level 5 is added to the data registered for a PHC
at level 4.
It is up to the user/system administrator/designer to make sure that no duplication of data entry is

taking place and that e.g. data entered at level 4 are not about the same services/visits that are
reported by orgunit children at level 5.
NOTE
424
Configure report functionality Types of data and aggregation
In some cases you want to have duplication of data in the system, but in
a controlled manner. E.g. when you have two different sources of data
for population estimates, both level 5 catchment population data and
another population data source for level 4 based on census data
(because sum of level 5 catchments is not always the same as level 4
census data). Then you can specify using advanced aggregation
settings (see further down) that the system should e.g. not add level 5
population data to the level 4 population data, and that level 3,2,1
population data aggregates are only based on level 4 data and does not
include level 5 data.
How data gets added together
How data is aggregated depends on the dimension of aggregation (see further down).
Along the orgunit level dimension data is always summed up; i.e. simply added together. Note that
raw data is never percentages, and therefore can be summed together. Indicator values that can
be percentages are treated differently (re-calculated at each level, never summed up).
Along the time dimension there are several possibilities, the two most common ways to aggregate
are sum and average. The user can specify for each data element which method to use by setting
the aggregation operator (see further down). Monthly service data are normally summed together
over time, e.g. the number of vaccines given in a year is the sum of the vaccines given for each
month of that year. For population, equipment, staff and other kind of what is often called semi-
permanent data the average method is often the one to use, as, e.g. 'number of nurses' working
at a facility in a year would not be the sum of the two numbers reported in the six-monthly staffing
report, but rather the average of the two numbers. More details further down under 'aggregation
operators'.
Dimensions of aggregation
Organisational units and levels
Organisational units are used to represent the 'where' dimension associated with data values. In
DHIS2, organisational units are arranged in a hierarchy, which typically corresponds to the
hierarchical nature of the organisation or country. Organisational unit levels correspond to the
distinct levels within the hierarchy. For instance, a country may be organized into provinces, then
districts, then facilities, and then sub-centres. This organisational hierarchy would have five
levels. Within each level, a number of organisational units would exist. During the aggregation
process, data is aggregated from the lower organisational unit levels to higher levels. Depending
on the aggregation operator, data may be 'summed' or 'averaged' within a given organisational
unit level, to derive the aggregate total for all the organisational units that are contained within a
higher level organisational unit level. For instance, if there are ten districts contained in a province
and the aggregation operator for a given data element has been defined as 'SUM', the aggregate
total for the province would be calculated as the sum of the values of the individual ten districts
contained in that province.
Period
Periods are used to represent the 'when' dimension associated with data values. Data can easily
be aggregated from weeks to months, from months to quarters, and from quarters to years.
DHIS2 uses known rules of how these different intervals are contained within other intervals (for
instance Quarter 1 2010 is known to contain January 2010, February 2010 an March 2010) in
425
Configure report functionality Types of data and aggregation
order to aggregate data from smaller time intervals, e.g. weeks, into longer time intervals, e.g.
months.
Data Elements and Categories
The data element dimension specifies 'what' is being recorded by a particular data value. Data
element categories are actually degenerated dimensions of the data element dimension, and are
used to disaggregate the data element dimension into finer categories. Data element categories,
such as 'Age' and 'Gender', are used to record a particular data element, typically for different
population groups. These categories can then be used to calculate the overall total for the
category and the total of all categories.
Aggregation operators, methods for aggregation
Sum
The 'sum' operator simply calculates the sum of all data values that are contained within a
particular aggregation matrix. For instance, if data is recorded on a monthly basis at the district
level and is aggregated to provincial quarterly totals, all data contained in all districts for a given
province and all weeks for the given quarter will be added together to obtain the aggregate total.
Average
When the average aggregation operator is selected, the unweighted average of all data values
within a given aggregation matrix are calculated.
It is important to understand how DHIS2 treats null values in the context of the average operator.
It is fairly common for some organisational units not to submit data for certain data elements. In
the context of the average operator, the average results from the number of data elements that
are actually present (therefore NOT NULL) within a given aggregation matrix. If there are 12
districts within a given province, but only 10 of these have submitted data, the average aggregate
will result from these ten values that are actually present in the database, and will not take into
account the missing values.
Advanced aggregation settings (aggregation levels)
Aggregation levels
The normal rule of the system is to aggregate all raw data together when moving up the
organisational hierarchy, and the system assumes that data entry is not being duplicated by
entering the same services provided to the same clients at both facility level and also entering an
'aggregated' (sum of all facilities) number at a higher level. This is to more easily facilitate
aggregation when the same services are provided but to different clients/catchment populations
at facilities on level 5 and a PHC (the parent of the same facilities) at level 4. In this way a facility
at level 5 and a PHC at level 4 can share the same data elements and simply add together their
numbers to provide the total of services provided in the geographical area.
Sometimes such an aggregation is not desired, simply because it would mean duplicating data
about the same population. This is the case when you have two different sources of data for two
different orgunit levels. E.g. catchment population for facilities can come from a different source
than district populations and therefore the sum of the facility catchment populations do not match
the district population provided by e.g. census data. If this is the case we would actually want
duplicated data in the system so that each level can have as accurate numbers as possible, but
then we do NOT want to aggregate these data sources together.
426
Configure report functionality Resource tables
In the Data Element section you can edit data elements and for each of them specify how
aggregation is done for each level. In the case described above we need to tell the system NOT
to include facility data on population in any of the aggregations above that level, as the level
above, in this case the districts have registered their population directly as raw data. The district
population data should then be used at all levels above and including the district level, while
facility level should use its own data.
How to edit data element aggregation
This is controlled through something called aggregation levels and at the end of the edit data
element screen there is a tick-box called Aggregation Levels. If you tick that one you will see a list
of aggregation levels, available and selected. Default is to have no aggregation levels defined,
then all raw data in the hierarchy will be added together. To specify the rule described above, and
given a hierarchy of Country, Province, District, Facility: select Facility and District as your
aggregation levels. Basically you select where you have data. Selecting Facility means that
Facilities will use data from facilities (given since this is the lowest level). Selecting District means
that the District level raw data will be used when aggregating data for District level (hence no
aggregation will take place at that level), and the facility data will not be part of the aggregated
District values. When aggregating data at Province level the District level raw data will be used
since this is the highest available aggregation level selected. Also for Country level aggregates
the District raw data will be used. Just to repeat, if we had not specified that District level was an
aggregation level, then the facility data and district data would have been added together and
caused duplicate (double) population data for districts and all levels above.
Resource tables
Resource tables provide additional information about the dimensions of the data in a format that
is well suited for external tools to combine with the data value table. By joining the data value
table with these resource tables one can easily aggregate along the data element category
dimension or data element/indicator/organisation unit groups dimensions. E.g. by tagging all the
data values with the category option male or female and provide this in a separate column
'gender' one can get subtotals of male and female based on data values that are collected for
category option combinations like (male, \<5) and (male,>5). See the Pivot Tables section for
more examples of how these can be used. orgunitstructure is another important table in the
database that helps to provide the hierarchy of orgunits together with the data. By joining the
orgunitstructure table with the data values table you can get rows of data values with the full
hierarchy, e.g. on the form: OU1, OU2, OU3, OU4, DataElement, Period, Value (Sierra Leone, Bo,
Badija, Ngelehun CHC, BCG \<1, Jan-10, 32) This format makes it much easier for e.g. pivot
tables or other OLAP tools to aggregate data up the hierarchy.
Report tables
Report tables are defined, cross-tabulated reports which can be used as the basis of further
reports, such as Excel Pivot Tables or simply downloaded as an Excel sheet. Report tables are
intended to provide a specific view of data which is required, such as "Monthly National ANC
Indicators". This report table might provide all ANC indicators for a country, aggregated by month
for the entire country. This data could of course be retrieved from the main datamart, but report
tables generally perform faster and present well defined views of data to users.
How to create report tables
To create a new report table, go to the Report tables section of the Reports module (Reports ->
Report Table). Above the list of standard reports, use the "Add report table" or "Add Dataelement
Dimension Table" buttons. A regular report table can be used to hold data on data elements,
indicators or dataset completeness, while Dataelement dimension tables are used to include data
427
Configure report functionality General options
element categories in report tables. Creating the tables are done in the same way, however, the
only exception being when choosing data.
To create a report table, you start by making some general choices for the table, the most
important of which is the crosstab dimension. Then, you choose which data elements, indicators,
datasets or data element dimensions you want to include. Finally you select which organisation
units and time periods to use in the report table. Each of these steps are described in detail
below.
General options
Cross tab dimensions
You can cross-tab one or more of the following dimensions: data element/indicator, orgunit, and
period, which means that columns will be created based on the values of the dimensions chosen,
e.g. if indicators is selected you will get column names in the table reflecting the names of the
selected indicators.
For example, if you cross-tab on indicators and periods, the column headers will say "\<indicator
title> \<period>". The organisation units will be listed as rows. See screenshot for clarification:
If you cross-tab on indicators and organisation units, the column headers of the table will say
"\<indicator title> \<organisation unit>". Now the periods will be listed as rows. See screenshot for
clarification:
Note that the options made here regarding crosstab dimensions may have consequences for
what options are available when using the report table as a data source later, for example for
standard reports.
Sort order
Affects the rightmost column in the table, allows you to choose to sort it low to high or high to low.
428
Configure report functionality Selecting data
Top limit
Top limit allow you to set a maximum number of rows you want to include in the report table.
Include regression
This adds additional columns with regression values that can be included in the report design,
e.g. in line charts.
Selecting data
Indicators/Data elements
Here you select the data elements/indicators that you want to include in the report. Use the group
filter to more easily find what you are looking for and double click on the items you want to
include, or use the buttons to add/remove elements. You can have both data elements and
indicators in the same report.
Data sets
Here you select the data sets that you want to include in the report. Including a data set will give
you data on the data completeness of the given set, not data on its data elements. Double click
on the items you want to include, or use the buttons.
Selecting report parameters
429
Configure report functionality Selecting report parameters
There are two ways to select both what organisation units to include in a report, and what time
periods should be included: relative, or fixed. Fixed organisation units and/or periods means that
you select the units/periods to include in the report table when you create the report table. Using
relative periods, you can select the time and/or units as parameters when the report table is
populated, for example when running a standard report or creating a chart. A combination is also
possible, for example to add some organisation units in the report permanently while letting the
users choose additional. Report parameters is discussed below. In general, using fixed
organisation units and/or time periods are an unnecessary restriction.
Fixed Organisation Units
To add fixed organisation units, click "Toggle fixed organisation units". A panel will appear where
you can choose orgunits to always include in the report. If you leave it blank, the users select
orgunits when running the report through the use of report parameters. Use the drop down menu
to filter organisation units by level, double click or use the buttons to add/remove.
Fixed Periods
To add fixed periods, click "Toggle fixed organisation units". A panel will appear where you can
choose periods to always include in the report. If you leave it blank, the users select periods
when running the report through the use of report parameters. Use the drop down menu to
choose period type (week, month, etc), the Prev and Next button to choose year, and double click
or use the buttons to add/remove.
Relative periods
Instead of using fixed/static periods like 'Jan-2010' or 'Q1-2010', more generic periods can be
used to create reusable report tables, e.g. for monthly reports the period 'Reporting month' will
simply pick the current reporting month selected by the user when running the report. Note that
all relative periods are relative to a "reporting month". The reporting month is either selected by
the users, otherwise the current month is used. Here is a description of the possible relative
periods:
• Reporting month:
Use this for monthly reports. The month selected in the reporting month parameter will be
used in the report.
• Months/Quarters this year:
This will provide one value per month or quarter in the year. This is well suited for standard
monthly or quarterly reports where all month/quarters need to be listed. Periods that still
have no data will be empty, but will always keep the same column name.
• This year:
This is the cumulative so far in the year, aggregating the periods from the beginning of the
year up to and including the selected reporting month.
• Months/Quarters last year:
This will provide one value per month or quarter last year, relative to the reporting month.
This is well suited for standard monthly or quarterly reports where all month/quarters need
to be listed. Periods that still have no data will be empty, but will always keep the same
column name.
• Last year:
430
Configure report functionality Selecting report parameters
This is the cumulative last year, relative to the reporting month, aggregating all the periods
from last year.
Example - relative periods
Let's say we have chosen three indicators: A, B and C, and we have also chosen to use the
relative periods 'Reporting month' and 'This year' when we created the report table. If the
reporting month (selected automatically or by the user) is for example May 2010, the report table
will calculate the values for the three selected indicators for May 2010 (= the 'Reporting month')
and the accumulated values for the three selected indicators so far in 2010 (= so far 'This year').
Thus, we will end up with six values for each of the organisation units: "Indicator A May 2010",
"Indicator B May 2010" "Indicator C May 2010", "Indicator A so far in 2010", "Indicator B so far in
2010" and "Indicator C so far in 2010".
Report parameters
Report parameters make the reports more generic and reusable over time and for different
organisation units. These parameters will pop up when generating the report table or running a
report based on the report table. The users will select what they want to see in the report. There
are four possible report parameters, and you can select none, all, or any combination.
• Reporting month:
This decides which month will be used when the system is choosing the relative periods. If
the box it not checked, the user will not be asked for the reporting month when the report is
generated - the current month will then be used.
• Grand parent organisation unit:
Select the grand parent of all the orgunit children and grand children you want listed in the
report. E.g. a selected region will trigger the use of the region itself, all its district, and all
their sub-districts.
• Parent organisation unit:
Select the parent of all the orgunit children you want listed in the report. E.g. a selected
district will trigger the use of the district itself and all its children/sub-districts.
• Organisation unit:
This triggers the use of this orgunit in the report. No children are listed.
Example - report parameters
Continuing with the example on relative periods just above, let's say that in addition to 'Reporting
month', we have chosen 'Parent organisation unit' as a report parameter when we created the
report table. When we're running the report table, we will be asked to select an organisation unit.
Now, let's say we choose "Region R" as the organisation unit. "Region R" has the children
"District X" and "District Y".
When the report is run, the system will aggregate data for both "District X" and "District Y". The
data will be aggregated from the lowest level where they have been collected. The values for the
districts will be aggregated further to give an aggregated value for "Region R".
Thus, the report table will generate the six values presented in the previous example, for "District
X", "District Y" and "Region R".
431
Configure report functionality Data element dimension tables
Data element dimension tables
These tables enable the use of data element categories in report tables. There are two
differences from regular report tables. The first is that it is not possible to select crosstab
dimensions, as the columns will always be the disaggregations from the category combinations.
The other is the actual choice of data. Only one category combination can be added per report,
and only data elements from the same category combo can be selected.
Subtotals and the total will also be included in the table, e.g. a gender (male, female) + EPI
age(\<1, >1) category combo would give the following columns: male+\<1, male+>1, Female+\<1,
female+>1, male, female,\<1, >1, total.
Selecting data
Use the drop down menu to choose category combinations. The data elements using this
category combination will be listed. Double click to add to the report, or use the buttons.
Report table - best practices
To make the report tables reusable over time and across orgunits they can have parameters.
Four types of parameters are allowed; orgunit, parent orgunit (for listing of orgunits in one area),
grand parent orgunit and reporting month. As a side note it can be mentioned that we are looking
into expanding this to include reporting quarter and year, or to make that period parameter more
generic with regard to period type somehow. The ability to use period as a parameter makes the
report table reusable over time and as such fits nicely with report needs such as monthly,
quarterly or annual reports. When a report is run by the user in DHIS2, the user must specify the
values for the report tables that are linked to the report. First the report table is re-generated
(deleted and re-created with updated data), and then the report is run (in the background, in
Jasper report engine).
Report tables can consist of values related to data elements, indicators or data completeness,
which is related to completeness of reporting across orgunits for a given month. Completeness
reports will be covered in a separate section.
There are three dimensions in a report table that identify the data; indicators or data elements,
orgunits and periods. For each of these dimensions the user can select which metadata values to
include in the report. The user must select one or more data elements or indicators to appear in
the report. The orgunit selection can be substituted with a parameter, either one specific orgunit
432
Configure report functionality Report table outcome
or an orgunit parent (making itself and all its children appear in the report). If one or more
orgunits are selected and no orgunit parameter is used, then the report is static with regard to
which orgunits to include, which in most cases is an unnecessary restriction to a report.
Using relative periods
The period selection is more advanced as it can in addition to specific periods like Jan-09, Q1-08,
2007 also contain what is called relative periods. As report usually is run routinely over time a
specific period like Jan-09 is not very useful in a report. Instead, if you want to design a monthly
report, you should use the relative period called Reporting Month. Then you must also include
Reporting Month as one of your report parameters to let the system know what exactly is the
Reporting Month on the time of report generation. There are many other relative periods
available, and they all relate to the report parameter Reporting Month. E.g. the relative period
called So far this year refers to the accumulative value for the year incl. the Reporting Month. If
you want a trend report with multiple periods in stead of one aggregated period, you can select
e.g. 'Months this year', which would give you values for each month so far in the year. You can do
a similar report with quarters. The idea is to support as many generic report types as possible
using relative periods, so if you have other report needs, please suggest new relative periods on
the mailing list, and they might be added to the report table options.
Cross-tabbing dimensions
Cross tabbing is a very powerful functionality in report design, as the typical DHIS2 data table
with references to period, data element/indicator and orgunit makes more advanced report design
very difficult, as you cannot put e.g. specific indicators, periods or orgunits on specific columns.
E.g. by cross-tabbing on the indicator dimension in an indicator report table you will get the
indicator names on the column headers in your report, in addition to a column referencing orgunit,
and another column referencing period. With such a table design you could drag and drop
indicator names to specific columns or chart positions in the iReport software. Similarly you can
cross tab on orgunits or periods to make their names specifically available to report design. E.g.
by cross-tabbing on periods and selecting the two relative periods 'Reporting month' and 'This
year', you can design reports with both the last month and the accumulative annual value for
given month as they will be available as column headers in your report table. It is also possible to
combine two dimensions in cross-tabbing, e.g. period and indicator, which makes it possible to
e.g. look at three selected indicators for two specific relative periods. This would e.g. make it
possible to make a table or chart based report with BCG, DPT3 and Measles coverage, both for
the last month and the accumulative coverage so far in the year.
All in all, by combining the functionality of cross tabbing, relative periods and report table
parameters you should have a tool to support most report scenarios. If not, we would be very
happy to receive suggestions to further improvements to report tables. As already mentioned, we
have started to look at more fine-grained parameters for the period dimension as the 'Reporting
month' does not cover enough, or at least is not intuitive enough, when it comes to e.g. quarterly
reports.
Report table outcome
When the report table is run, the system will calculate values for specified indicators/data
elements/data sets, orgunits and periods. The data will be presented in DHIS2 in a table layout.
The column headers will correspond to the cross-tab dimension you have selected. An example
report table showing ANC coverage for a district in The Gambia, is shown below. Here the
indicator and the periods are cross-tabbed, as can be seen from the column headers.
433
Configure report functionality Standard reports
Above the table there are six buttons; five download buttons and one Back button. Clicking the
Back button will simply take you back to the previous screen. The function of the five download
buttons, are presented below the screenshot:
The five download buttons
• Download as Excel:
Downloads a generated Excel file you can open in Excel.
• Download as CSV:
Downloads a generated .csv file. CSV stands for **C**omma **S**eparated **V**alues. It's a
text file with the file ending .csv. Each line in the file corresponds to a row in the table, while
the columns are separated with semi colons (;). The file can be opened in a text editor as
well as in a spread sheet program (such as Excel).
• Download as PDF:
Downloads a generated PDF file. The data will be presented in a similar layout as the
generated table you are already viewing in DHIS2.
• Download as Report:
Downloads a "styled" PDF file. In addition to present the data in a table layout, this file also
presents a chart, showing the aggregated data from all the chosen periods and the parent
organisation unit chosen for the report table. The report is generated using the Jasper
report engine.
• Download as JRXML:
Downloads the design file for the generated Report described in the previous bullet. The
design file (with the file ending .jrxml) can be opened in the Jasper iReport Designer
software. If you plan to design standard reports, this is the starting point.
Standard reports
What is a standard report?
A standard report is a manually designed report that presents data in a manually specified layout.
Standard reports can be based either on report tables or SQL queries. Both approaches are
described in the following sections. The main advantage of using report tables is that of simplicity
- no special development skills are required. In cases where you have special requirements or
need to utilize additional parts of the DHIS2 database you might want to use a SQL based
standard report. In any case you will be able to utilize report parameters in order to create
434
Configure report functionality Designing Standard reports in iReport
dynamic reports. The following guide will use the report table approach, while the SQL approach
is covered towards the end.
Designing Standard reports in iReport
Jasper iReport Designer is a tool for creating reports that can be used as Standard Reports in
DHIS2. The tool allows for the creation of standard report templates that can easily be exported
from DHIS2 with up to date data. The process of creating reports involves four major steps:
1. A report table must be created in DHIS2 with the indicators/data elements/datasets to be

used in the report.
2. You have to run the report table and download the design file (Click the "Download as
JRXML" button).
3. Open the downloaded .jrxml file using the free software Jasper iReport Designer to edit the
layout of the report.
4. The edited report can then be uploaded to DHIS2 to be used as a standard report.
If you want to preview your report during the design in iReport, you actually have to upload your
file to DHIS2 to see how it looks.
These four steps will be describe in detail in the coming sections. In general, when you are
making standard reports you should have a clear idea of how it should look before you even
make the report table, as how the report table is designed has implications for how the report can
be formatted in iReport. For example, what crosstab dimensions are selected in the report table
has consequences for what crosstabs are available for the standard report, and it has
consequences for what types of charts you can make.
Download and open the design file
NOTE
If you have not created a report table yet, you have to do so. See
section "How to create report tables" to do so.*
Locate your desired report table and run it by clicking the green circle with a white arrow inside.
When the report is shown, click the "Download as JRXML" button to download the design file.
Then open that file in the Jasper iReport Designer software.
Editing the report
You are now ready to edit the layout of the report. The main iReport window consists of a "Report
Inspector" to the left, the report document in the middle, a "Palette" area on the upper right hand
side and a "Properties" area on the lower right hand side. The "Report Inspector" are used for
selecting and examining the various properties of the report, and when selecting an item in the
inspector, the "Properties" panel changes to display properties relating to the selection. The
"Palette" is used for adding various elements, e.g. text boxes, images and charts to the
document.
435
NOTE
If you cannot see the Palette or Properties sidebar, you can enable
them from the menu item called "Window" on the menu bar.
The iReport document is divided into seven main bands, divided by layout separators (the blue
lines). These lines are used to decide how big each of the areas should be on the report.
The areas all have different purposes:
• Title - area for the title of the report
• Page header - area for the page header
• Column header - area for column headers (for the table)
• Detail 1 - area where the actual report data will be placed
• Column footer - area to make footer of the table
• Page footer - area for the page footer
• Summary - elements in this area will be placed at the end of the report
By default you will see that only the Title, Column Header and the Detail 1 bands have data. For
most reports this is OK. The Title band is suitable for a title and e.g. a chart. Data fields entered
into the Detail 1 area will be iterated over to create a table. For example, if a field called
"dataelementname" is placed in the Detail 1 band, all data elements in the report table will be
listed here. We'll come back to data fields management just a little below.
The unused bands in the report are contracted to add more space for your report data. You can
however increase/decrease the band height as you like. There are two ways to do that. The first
way is simply to drag the blue band-line as shown below.
436
The other way to adjust the band height is to select a band in the "Report Inspector", and then
adjust the "Band height" value in the "Detail 1 - properties" area in the lower right corner.
As the fields are already present on the report, you probably don't want to do anything than just
fix the layout and drag fields around. You can also resize the fields by dragging the side, top or
bottom lines. If you want to change the text in the column headers, you simply double click the
field and change the text.
To add the a field to the table, we simply drag it to the Detail 1 band from the "Report Inspector".
The column header will be added automatically.
By double clicking the box, the text can be edited. The format of the text, such as size, font and
alignment, can be adjusted with the tools above the document.
NOTE
Fields starting with "$F" present values that are retrieved from the
database every time the report is run. The values here will vary, so do
not change these fields unless you want a static value here!
Text
There are two types of text in iReport: «Text labels» and «Text fields» (data fields). They work in
different ways, and should be used for different purposes. The main point is that text fields are
just placeholders that will be filled with the correct text from the report table when the report is
run, while text labels will stay the way they are when the report is run.
Static text
Static text are text plain text labels that can be edited normally. There are two ways to edit text
labels:
• By double clicking in the text box
437
By using the Static text properties in the Properties panel

•
Text fields
Text fields are formulas that will be filled from the report table when the report is run. Unlike static
text, these can not be edited in a normal way. However, they can be manipulated in various ways
to ensure that the desired output will be produced. There are three ways to edit the text fields:
• By right clicking on the text box and selecting Edit expression
• By double clicking the text field (not recommended, as this will not bring up the expression
editor)
• By using the Text field properties in the Properties panel
Text fields can represent either numbers or text, so that they can be used both for showing for
example names of district or for numeric values. It is therefore important the Expression class,
seen in the Text field properties matches the Text field expression. For the default text fields in the
.jrxml file downloaded from DHIS2 this is not a problem, but it is important when making new text
fields. The two most important Expression classes are java.lang.Double for numbers and
java.lang.String for text.
Example
For example, let us say you have a quarterly report where you would like to add a new column
with the yearly total. You therefore add a new Static text field to the column header band, and a
Text field to the details band in. By default, new Text fields are set to java.lang.String (text).
However, the yearly total column will be filled with numbers. We therefore have to change the
Expression class for the new text field to java.lang.Double:
438
Configure report functionality Filtering the table rows
When we edit the text field expression, we see the Expression editor window with all the available
columns from the report table. We can see here that each of these are marked with what type
they are - text or number. What we need to make sure of is therefore that the expression class we
choose for the text field matches the actual expression.
Filtering the table rows
In the default table exported from DHIS2, there are some rows that it might be better to leave out
of the table, and some that it would be preferable to have at the end. For example, when making
a table based on a report table with the «parent organisation unit» parameter, the default table
might have a row with the national level somewhere in between all the regions. In iReport, this
can be changed so that the «parent organisation unit» appears at the bottom of the table. This
439
involves two steps that will be explained below. Note that this will not work where there is only one
organisation units, and it is therefore most useful when using the «parent organisation unit» or
«grand parent organisation unit» parameters in the report table.
Hiding the «parameter organisation unit» from the table
We exclude the "parameter organisation unit" from the table by using a property in the Details
band called "Print when expression". To set a Print when expression, start by selecting the Detail
band in the Report inspector, then edit the Print when expression in the properties panel.
The Expression editor window should now appear. What we must do is to create an expression
that checks if the row being generated is the row with the organisation unit given as a parameter.
The report table contains a column that we can use for this called organisation_unit_is_parent. To
exclude the row with the parameter organisation unit, double click on organisation_unit_is_parent
in the list to copy it to the expression area, then add .equals("No") at the end so that the code
is:
$F{organisation_unit_is_parent}.equals("No")
440
This tells the report engine to only print table rows where the organisation unit is not the parent
organisation unit.
Putting the "param organisation unit" at the bottom of the table
Instead of removing the "param organisation unit" from the table entirely, it is also possible to put
it at the bottom (or top) of the table. This is done by using the sort functionality explained in the
next section, and choosing to sort first by "organisation_unit_is_parent". Other sorting options
can be added in addition to this, for example to make a list where the param organisation unit is
at the bottom of the table, with the other organisation units listed alphabetically above it.
Hiding other rows
Using the expression editor it is also possible to exclude other rows from the table, in addition to
the parent organisation unit as was explained above. In Ghana, for example, all regions have a
«fake district» which is the name of the region in square brackets. This can also be excluded from
the table using the Print when expression that was introduced above. To to this, follow the
instructions above to bring up the Expression editor window. Then, we use Java expressions to
test whether or not the row should be hidden.
Example - removing rows with organisation units starting with [
Example - removing rows with organisation units starting with [
($F{organisationunitname}.charAt( 0 ) != '[')
This makes the report skip any rows where the first character of the organisation unit name is [.
It is also possible to combine several of these expressions. To do this we put the expressions in a
parenthesis with the two characters && in between. For example, to make a table that leaves both
organisation units whose name starts with [ and the parent organisation unit, we can use the
following expression:
441
Configure report functionality Sorting
($F{organisationunitname}.charAt( 0 ) != '[')&&$F{organisation_unit_is_parent}.equals("No")
Sorting
Often you will be making reports where the first column is organisation unit names. However, it
can be a problem that the list of organisation units are not sorted alphabetically. This can be fixed
in iReport through a few simple steps.
In the report inspector, right click on the name of the report (by default this is dpt) and select Edit
query.
A Report query window will appear. Click on the Sort options button.
442
Configure report functionality Sorting
A Sorting window as show below will appear. Here, we can add our sorting options. Click the Add
field button. Another small window will show up, with a drop down menu where you can choose
Sort by organisationunitname to have the table sorted alphabetically by name.
443
Configure report functionality Changing indicator/data element names
Click OK - Close - OK to close the three windows. The table should now be sorted.
Changing indicator/data element names
By default, the reports from DHIS2 uses the short names for indicators and data elements in
reports and charts. In some cases these are not always very meaningful for third parties, but with
some work they can be given custom names through iReport. This is useful for example if you are
making a report with indicators as rows and periods as column, or for charts with indicators.
To change the names of an indicator or data element, we have to edit its «expression» or formula,
for example by right clicking the text box and choosing Edit expression to bring up the Expression
editor.
Next, we have to insert some Java code. In the following example, we will be replacing the
shortname of three indicators with their proper names. The code searches for the shortname, and
then replaces it with a proper name.
444
Configure report functionality Adding horizontal totals
($F{indicatorname}.equals("Bed Util All")) ? "Bed Utilisation - All Wards"

:
($F{indicatorname}.equals("Bed Util Mat")) ? "Bed Utilisation - Maternity"
:
($F{indicatorname}.equals("Bed Util Ped")) ? "Bed Utilisation - Paediatric"
:
$F{indicatorname}
From this, we can see a pattern that is reusable for more general cases.
• For each indicator or data element we want to change the name for, we need one line
• Each line is separated by a colon :
• We finish the expression with a «regular» line
Each line has the same format, where the red text is the shortname, the blue text is what we want
to insert instead.
The same expressions can be used for example when having indicator names along the category
axis of a chart.
Adding horizontal totals
By using the expression editor, it is possible to add a column to the table with totals for each row.
In the following example, we will make a table with three months as columns as well as a column
with the totals for the three months.
445
Configure report functionality Groups of tables
We start by dragging a text label into the table header and changing its text to "Total", and
dragging a text field into the details row.
As was discussed in the section on "Text field", we have to change the properties of the new text
field so that it can display numbers. To do this, change the "Expressions Class" in the properties
panel to "java.lang.Double".
Right click the text field and choose "Edit Expression". This will bring up the "Expressions editor".
As the expression, we want to sum up all the columns. In this case we have three value
expressions we want to sum up: "September", "October 2010", "November 2010". The name of
these fields will vary depending on the crosstab dimension you have chosen in the report table. In
our case, the expression we make is
$f{September}+$f{October 2010}+$f{November 2010}
Each row of the table will have a totals column to the right.
Groups of tables
There are cases when it can be useful to have several tables in one report. This can be done
using Report groups. Using this functionality, one can for example create a report one table for
each indicator, or one table of each organisation unit. In the following, we will go through the
steps needed to make a report with three indicators, each represented in one table. It is important
that the report table does not crosstab on indicators when we want to make groups of tables
based on indicators.
In our example, the .jrxml file downloaded from DHIS2 will by default have one column for
organisation unit and on for indicators (assuming we have chosen periods as the only crosstab
dimension). We start by removing the indicator column, since this in not needed in our case, and
realign the other fields to fit the report.
Next, we create out Report group. Go to the report inspector, right click on the report name (dpt is
the default) and choose Add Report Group.
446
A window will appear, with a report group wizard. Select a name for the group, in this case we
choose «Indicator». In the drop down menu, we can select what columns in the report table we
want the groups to be based on. So, if we wanted one table for each organisation unit, we would
choose organisation unit name as the report object to group according to. However, since we are
grouping by indicators in this example, we choose indicatorname. Then click next.
The next step is to select whether or not we want a separate Group header and Group footer
band for each report group. In this case, we choose to include both. Click Finish, and the group
bands should appear in the report.
447
If you upload and run the report, it will now create one table for each indicator. However, it will not
look very good as there will be no header row over each table - only one header at the top of
each page. Also, there is no indication as to which table is showing which indicator. In the
following, we will fix this.
Instead of having the title row in the column header, we can instead move it to the Group header.
This will make the heading show up above each individual table. Furthermore, we can add a
heading to each table with the name of the indicator.
Move the column headers from the Column header band to the Indicator group header band.
Next, add a text field to the Indicator group heading band, and edit it’s expression to display the
indicator name.
448
The report should now have three tables, one for each indicator. Each table will have a heading
with the name of the indicator, and also a table header row.
Sorting and grouping
When using grouping, some precautions must be taken with regards to sorting. Notably, when
adding sorting parameters, whatever parameter is used as basis for the grouping must come first.
Thus if you are grouping the report by indicator, and want sort the organisation units
alphabetically, you have to choose to sort first by indicator, then by organisation unit name as
shown below. For instructions on how to add sorting, see the sorting section above.
449
Configure report functionality Charts
Charts
By default, a 3D bar chart is included in the .jrxml file that is downloaded from DHIS 2. This is set
up so that only data from the «parameter organisation unit» (often the parent or grand parent) is
used. Usually, this is a good solution. Since it is the default, we will start by looking at bar charts,
before looking at line charts.
Bar charts
Bar charts are the default chart type in DHIS2. In this section, we will look at how to make a bar
charts like the one above, comparing the value of one indicator in several districts. To edit the
default chart in iReport, right click on it and choose Chart data.
450
Configure report functionality Bar charts
A window will appear. By default, the Filter expression is filled in so that only data for the parent
organisation unit will be displayed. If for some reason you do not want this, simply delete the text
in the text box. In this case we do NOT want the filter, as we are making a chart showing a
comparison across districts. To continue, click the details tab.
451
Under details, you see the list of series for the chart. By default, one series is created per
crosstab column. In this case, we are looking at data for one indicator for the whole of 2010, for a
number of districts. The indicator is along the crosstab dimension.
452
To make changes to a series, select it and click modify. Another window will appear where there
are four areas that can be edit. The three first are required, but it is sufficient to add an empty
quote («») in one of the first two.
453
The first box is a text field where the name of the series can be inserted or edited. This is the field
that will be used to fill the text in the legend box (shown below).
However, if you want to have the name of each bar along the x-axis of the chart instead of using
the legend, this can be done by adding whatever text you want to present in the Category
expression field, or by inserting an expression to have it filled automatically when the report is
run. In this case, we want to have one bar for each organisation unit. We therefore edit the
category expression by clicking on the button to the right.
454
As the expression, we chose organisationunitname, as shown below.
When we are finished, the series editor should look like below. Click OK, then Close to close the
Chart Details window.
455
If you add a good description in the Category expression area, you can leave out the legend box.
This is done in the Report properties panel of iReport, where you can also edit many other details
of the chart.
We can also add a title to the chart, for example the name of the indicator. This is also done in the
Chart properties panel, under Title expression.
456
Configure report functionality Line charts
The Expression editor window will appear, where you can enter the title. Note that the title must
be in quotes, as shown below.
The chart is now ready.
Line charts
Line charts can be useful in many circumstances. However, to make line charts the report data
(report table) must be suited for it. Thus if you want to make a line chart, it is important that the
report table does not have periods in the crosstab dimension. Examples where this is useful is if
you are making a report for a single organisation unit with one or more indicators, or if you are
making a report with one indicator and one or more organisation units.
Below, we will go though the steps needed to make a report with a line chart showing the
development of three indicators over one year, for one organisation unit. We start by making a
report table with the choices shown below:
457
When we open the resulting .jrxml-file in iReport, the default line chart is included. Since we want
to make a line chart, we delete this chart and drag a new chart element into the report from the
Palette panel.
458
As soon as we drag the Chart element into the report, a window will appear. We choose the Line
chart, as shown below.
A chart wizard will appear. Click next in the first step, then Finish in the next - we will add the data
later.
459
460
Next, adjust the size and position of the chart in your report. Then, we will add one data series for
each of our three indicators. Right-click on the chart and choose Chart data. If you are making a
chart with one indicator and several organisation units, you probably want to make a filter
expression so that only data from the parameter/parent organisation unit is used in the chart. To
do this, add this line to the Filter expression area:
$F{organisation_unit_is_parent}.equals("Yes")
In our example, we only have on organisation unit, so this is not necessary. Next, click the details
tab to see a list of the series in the chart. For now, this list is empty, but we will add one series for
each of our three indicators. To add a series, click the Add button.
461
462
In the window that appears, enter the name of the first of the indicators in the Series expression
window. Remember to put the name in quotes. In the category expression (along the x-axis) we
want the months, so we use the button next to the field to open the Expression editor and add
periodname.
463
In the value expression, we add the actual data values for our first indicator. Use the Expression
editor again to do this. When we are finished, the window should look like the one below, only
with different names according to the indicator.
464
You can then Click OK to close the window. Follow the same steps to add a series for the other
indicators.
465
Close the window, and the data for the line chart should be ready. However, some additional
adjustments might be needed - most of these can be found in the Line chart properties panel. For
example, when making a month by month chart as we have in example, there is often not enough
space for the month names along the category axis. This can be fixed by rotating the labels by for
example -40 degrees, by using the property Category Axis Tick Label Rotation.
Many other options are available to give the chart the desired look.
466
Configure report functionality Adding the Report to DHIS2
Adding the Report to DHIS2
We can now switch to DHIS2 and import our report. Go to the Report Module in DHIS2, and
select "Standard Report". In the "Standard Report" screen, click "Add new", or edit an existing
one.
In the following screen, there are several actions we need to take. First, enter a name for the new
"Standard Report". Second, for design, click "Choose File" and find the .jrxml-file you have edited
in iReport. Then we select the report table that we used as a basis for the report in iReport. Click
add, and it should move to the "Selected report tables" area. Finally, click save.
467
Configure report functionality Some final guidelines
The report is now available as a "Standard Report" in DHIS2:
Some final guidelines
• Use the same version of iReport and DHIS2's version of Jasper reports. See the About
page in DHIS2 for the Jasper version in use.
• Use report tables with cross tab dimensions as your data source for your report designs.
This will make it a lot easier to design reports where you need to put specific indicators,
periods, or orgunits on columns.
• Learn from others, there are many DHIS2 report designs for Jasper on launchpad, see
http://bazaar.launchpad.net/~DHIS2-devs-core/DHIS2/trunk/files/head:/resources/
468
Configure report functionality Designing SQL based standard reports
Designing SQL based standard reports
A standard report might be based on SQL queries. This is useful when you need to access
multiple tables in the DHIS2 database and do custom selects and joins.
- This step is optional, but handy when you need to debug your reports and when you have direct
access to the database you want to use. Click on the "report datasources" button, "New",
"Database JDBC connection" and click "next". In this window you can give you connection a name
and select the JDBC driver. PostgreSQL and MySQL should come included in your iReport. Then
enter the JDBC connection URL, username and password. The last three refers to your database
and can be retrieved from your DHIS2 configuration file (hibernate.properties). Click "save". You
have now connected iReport to your database.
- Go to standard reports and click "add new", then "get report template". Open this template in
iReport. This template contains a series of report parameters which can be used to create
dynamic SQL statements. These parameters will be substituted based on the report parameters
which we will later select and include in the standard report. The parameters are:
• periods - string of comma-separated identifiers of the relative periods
• period_name - name of the reporting period
• organisationunits - identifier of the selected organisation units
• organisationunit_name - name of the reporting organisation unit
• organisationunit_level - level of the reporting organisation unit
• organisationunit_level_column - name of the corresponding column in the _orgunitstructure

resource table
These parameters can be included in SQL statements using the $P\!{periods} syntax, where
"periods" represents the parameter.
- To create a SQL query in iReport, click on the "report query" button. Write or paste your query
into the textarea. An example SQL query using parameters which will create a report displaying
raw data values at the fourth level in the org unit hierarchy is:
select district.name as district, chiefdom.name as chiefdom, ou.name as facility,

bcg.value as bcg, yellowfever.value as yellowfever, measles.value as measles
from organisationunit ou
left outer join _orgunitstructure ous
on (ou.organisationunitid=ous.organisationunitid)
left outer join organisationunit district
on (ous.idlevel2=district.organisationunitid)
left outer join organisationunit chiefdom
on (ous.idlevel3=chiefdom.organisationunitid)
left outer join (
select sourceid, sum(cast(value as double precision)) as value
from datavalue
where dataelementid=359706
and periodid=$P!{periods}
group by sourceid) as bcg on bcg.sourceid=ou.organisationunitid
left outer join (
select sourceid, sum(cast(value as double precision)) as value
from datavalue
where dataelementid=35
and periodid=$P!{periods}
group by sourceid) as yellowfever on yellowfever.sourceid=ou.organisationunitid
where ous.level=4
469
Configure report functionality Designing HTML based standard reports
and ous.$P!{organisationunit_level_column}=$P!{organisationunits}
order by district.name, chiefdom.name, ou.name;
Notice how all parameters are used in the query, along with SQL joins of resource tables in the
DHIS2 database.
- Finally, back in the add new report screen, we click on "Use JDBC data source". This enables
you to select any relative period and report parameters for your report. Relative periods are
relative to today's date. Report parameters will cause a prompt during report creation and makes
it possible to dynamically select organisation units and periods to use for your report during
runtime. For the example above, we must select "reporting month" under relative periods and
both "reporting month" and "organisation unit" under report parameters. Click save. This will
redirect you to the list of reports, where you can click the green "create" icon next to your report
to render it.
Designing HTML based standard reports
A standard report can be designed using purely HTML and JavaScript. This requires a little bit of
development experience in the mentioned subjects. The benefit of HTML based standard reports
is that it allows for maximum flexibility. Using HTML you can design exactly the report you want,
positioning tables, logos and values on the page according to your design needs. You can write
and save your standard report design in a regular text file. To upload your HTML based standard
report to DHIS2 do the following:
• Navigate to standard reports and click "Add new".
• Give the report a name.
• Select "HTML report" as type.
• If you want to you can download a report template by clicking on "Get HTML report
template".
• Select desired relative periods - these will be available in JavaScript in your report.
• Select report parameters - these will be available in JavaScript in your report.
The report template, which you can download after selecting report type, is a useful starting point
for developing HTML based standard reports. It gives you the basic structure and suggests how
you can use JavaScript and CSS in the report. JavaScript and CSS can easily be included using
standard script and style tags.
If you selected relative periods when creating the standard report you can access these in
JavaScript like this:
var periods = dhis2.report.periods; // An array with period identifiers

var period = periods[0];
If you selected the organisation unit report parameter when creating the standard report you can
access the selected organisation unit in JavaScript like this:
var orgUnit = dhis2.report.organisationUnit; // An object

var id = orgUnit.id;
var name = orgUnit.name;
var code = orgUnit.code;
470
Configure report functionality Designing HTML based standard reports
When designing these reports you can utilize the analytics Web API resource in order to retrieve
aggregated data in JavaScript. Have a look in the Web API chapter in this guide for a closer
description. As a complete, minimal example you can retrieve analytics data after the report has
been loaded and use that data to set the inner text of an HTML element like this:
<script type="text/javascript">
$( document ).ready( function() {
$.get( "../api/analytics?
dimension=dx:FnYCr2EAzWS;eTDtyyaSA7f&dimension=pe:THIS_YEAR&filter=ou:ImspTQPwCqd",
function( json ) {
$( "#bcg" ).html( json.rows[0][2] );
$( "#fic" ).html( json.rows[1][2] );
} );
} );
</script>
<div>BGG coverage: <span id="bcg"></span></div>

<div>FIC coverage: <span id="fic"></span></div>
A few other tips: To include graphics you can convert an image to SVG and embed that SVG
content directly in the report - DHIS2 is based on HTML 5 where SVG tags are valid markup. To
include charts and maps in your report you can use the charts and maps resources in the Web
API. You can use the full capability of the Web API from JavaScript in your report - it may be
useful to read through the Web API chapter to get an overview of all available resources.
471
System settings General settings
System settings
General settings
General settings
Setting Description
Maximum number of analytics records Increase this number to provide more records from
the analytics.
The default value is 50,000.
Warning
Use the setting Unlimited carefully, it might

result in a very high load on your server.
Maximum number of SQL view records Set the maximum number of records in a SQL view.
The default value is Unlimited.
Infrastructural indicators Defines an indicator group where the member

indicators should describe data about the
organisation units' infrastructure.
You can view the infrastructural data in the GIS app:

right-click a facility and click Show information.
Infrastructural data elements Defines a data element group where the member
data elements should describe data about the
organisation units' infrastructure.
Infrastructural data elements can be population,

doctors, beds, Internet connectivity and climate.

Infrastructural period type Sets the frequency for which the data elements in
the infrastructural data elements group are
captured.
This will typically be yearly. When viewing the

infrastructural data you will be able to select the
time period of the data source.

472
System settings General settings
Setting Description
Default relative period for analysis Setting this value will determine which relative
period is selected as the default in the analytics
apps.
Feedback recipients Defines a user group where the members will

receive all messages sent via the feedback function
This will typically be members of the super user

team who are able to support and answer questions
coming from end-users.
Max offline organisation unit levels Defines how many levels in the organisation unit
hierarchy will be available offline in the organisation
unit tree widget.
Under normal circumstances you can leave this on

the lowest level, which is default is the default
setting.
It can be useful to set it to a higher level to reduce

initial load time in cases where you have a large
number of organisation units, typically more than 30
000.
Data analysis std dev factor Sets the number of standard deviations used in the
outlier analysis performed on the captured data in
the Data Entry app.
The default value is 2. A high value will catch less

outlier values than a low value.
Phone number area code The area code for the area in which your
deployment is located.
Used for sending and receiving SMS. Typically, this

is a country code.
+260 (country code for Zambia)
Enable multi-organisation unit forms Enables support to enter data forms for multiple
organisation units at the same time in the Data
Entry app.
If you've enabled this setting, you can in the Data

Entry app, click on the parent organisation unit for
the children that you want to enter data for, and the
data set list will include data sets that are assigned
to the children of that parent.
473
System settings Analytics settings
Setting Description
Acceptance required before approval When this setting is selected, acceptance of data
will be required first before submission to the next
approval level is possible.
Analytics settings
Analytics settings
Setting Description
Default relative period for analysis Defines the relative period to use by default in
analytics app: Data Visualizer, Event Reports, Ev
ent Visualizer, GIS and Pivot Table apps. The
relative period will be automatically selected when
you open these apps.
Recommended setting: the most commonly used

relative period among your users.
Hide daily periods Hide daily periods in the analysis tools
Hide weekly periods Hide weekly periods in the analysis tools
Hide monthly periods Hide monthly periods in the analysis tools
Hide bimonthly periods Hide bimonthly periods in the analysis tools
Financial year relative start month Defines which month (April, July or October) the the
relative financial year in the analytics apps should
begin on.
Cacheability Sets whether analytics data responses should be

served with public or private visibility.
Private: Any node or server between the DHIS2

server and the end user which has the ability to
cache can NOT cache the web page. This is useful
if the page served can or do contain sensitive
information. This means that each time you want a
web page, either you get a new page from the
DHIS2 server, or the DHIS2 server caches the page.
No other server than the DHIS2 server are allowed
to cache the page.
Public: Any node or server between the DHIS2

server and the end user which has the ability to
cache can cache the web page. This relives the
traffic to the DHIS2 server and potentially speeds up
the subsequent page loading speed.
474
System settings Analytics settings
Setting Description
Cache strategy Decides for how long reports analytics responses

should be cached.
If you use the scheduled, nightly analytics update,

select Cache until 6 AM tomorrow. This is because
data in reports change at that time, and you can
safely cache data up to the moment when the
analytics tables are updated.
If you are loading data continuously into the

analytics tables, select No cache.
Max number of years to hide unapproved data in Sets whether and for how long back in time
analytics analytics should respect the approval level of the
data. Typically, data which is several years old
would be considered to be approved by default. In
order to speed up analytics requests, you can
choose to ignore the actual approval level of
historical data.
Never check approval: no data will be hidden,

irrespective of its data approval status.
Check approval for all data: approval status will

always be checked.
Other options, for example Last 3 years: approval

status will be checked for data which is newer than
3 years old; older data will not be checked.
Threshold for analytics data caching Sets whether to enable caching data older than the
specified number of years only.
This allows for returning the most recent data

directly with no caching, while serving cached
version of older data for performance concerns.
Respect category option start and end date in This setting controls whether analytics should filter
analytics table export data which is associated with a category option with
a start and end date, but which is not associated
with a period within the category options interval of
validity.
475
System settings Server settings
Setting Description
Places the analytics and web API of DHIS2 in

Put analytics in maintenance mode
maintenance mode. This means that "503 Service
Unavailable" will be returned for all requests.
This is useful when you need to perform

maintenance on the server, for example rebuilding
indexes while the server is running in production, in
order to reduce load and more efficiently carry out
the maintenance.
Skip zero data values in analytics tables Does not include in analytics tables any aggregate
data values that are zero. This can reduce analytics
tables sizes, and speed up the building and
accessing of the analytics tables, if you have
aggregate data values that are zero and stored (the
data element is configured to store zero values).
Server settings
Server settings
Setting Description
Number of database server CPUs Sets the number of CPU cores of your database
server.
This allows the system to perform optimally when

the database is hosted on a different server than the
application server, since analytics in DHIS2 scales
linearly with the number of available cores.
System notifications email address Defines the email address which will receive system
notifications.
Notifications about failures in processes such as

analytics table generation will be sent here. This is
useful for application monitoring.
Google Analytics (Universal Analytics) key Sets the Google UA key to provide usage analytics
for your DHIS2 instance through the Google
Analytics platform. It should be noted that currently,
not all apps in DHIS2 support Google Analytics, so
certain activity of your users may not appear in this
platform.
You can read more about Google Analytics at http://

google.com/analytics.
476
System settings Appearance settings
Setting Description
Google Maps API key Defines the API key for the Google Maps API. This is
used to display maps within DHIS2.
Bing Maps API key Defines the API key for the Bing Maps API. This is
used to display maps within DHIS2.
Appearance settings
Appearance settings
Setting Description
Select language Sets the language for which you can then enter
translations of the following settings:
• Application introduction
• Application title
• Application notification
• Application left-side footer
• Application right-side footer
Application title Sets the application title on the top menu.
Application introduction Sets an introduction of the system which will be

visible on the top-left part of the login page.
Application notification Sets a notification which will be visible on the front

page under the login area.
Application left-side footer Sets a text in the left-side footer area of the login
page.
Application right-side footer Sets a text in the right-side footer area of the login
page.
477
System settings Appearance settings
Setting Description
Style Sets the style (look-and-feel) of the system.
The user can override this setting in the Settings

app: User settings > Style.
Note
Due to technical reasons, it's not possible to

change the color of the newest version of the
header bar. The apps with the newest header
bar will retain the blue header bar.
Start page Sets the page or app which the user will be
redirected to after log in.
Recommended setting: the Dashboard app.
Help page link Defines the URL which users will see when they
click Profile >Help.
Flag Sets the flag which is displayed in the left menu of

the Dashboard app.
Interface language Sets the language used in the user interface.

app: User settings > Interface language.
Database language Sets the language used in the database.

app: User settings > Database language.
Property to display in analysis modules Sets whether you want to display the metadata
objects' names or short names in the analytics apps:
Data Visualizer, Event Reports, Event Visualizer,
GIS and Pivot Table apps.

app: User settings > Property to display in
analysis modules.
Default digit group separator to display in Sets the default digit group separator in the
analysis modules analytics apps: Data Visualizer, Event Reports, Ev
ent Visualizer, GIS and Pivot Table apps.
478
System settings Email settings
Setting Description
Require authority to add to view object lists If you select this option, you'll hide menu and index
page items and links to lists of objects if the current
user doesn't have the authority to create the type of
objects (privately or publicly).
Custom login page logo Select this option and upload an image to add your
logo to the login page.
Custom top menu logo Select this option and upload an image to add your
logo to the left in the top menu.
Email settings
Email settings
Setting Description
Host name Sets the host name of the SMTP server.
When you use Google SMTP services, the host

name should be smtp.gmail.com.
Port Sets the port to connect to the SMTP server.
User name The user name of the user account with the SMTP
server.
mail@dhis2.org
Password The password of the user account with the SMTP

server.
TLS Select this option if the SMPT server requires TLS

for connections.
Email sender The email address to use as sender when sending

out emails.
Send me a test email Sends a test email to the current user logged into
DHIS2.
Access settings
Access settings
479
System settings Access settings
Setting Description
Self registration account user role Defines which user role should be given to self-
registered user accounts.
To enable self-registration of users: select any user

role from the list. A link to the self-registration form
will be displayed on the login page.
Note
To enable self-registration, you must also select

a Self registration account organisation unit.
To disable self-registration of users: select Disable

self registration.
Self registration account organisation unit Defines which organisation unit should be
associated with self-registered users.
Note
To enable self-registration, you must also select

a Self registration account user role.
Do not require reCAPTCHA for self registration Defines whether you want to use reCAPTCHA for
user self-registration. This is enabled by default.
Enable user account recovery Defines whether users can restore their own
passwords.
When this setting is enabled, a link to the account

recovery form will be displayed on the front page.
Note
User account recovery requires that you have

configured email settings (SMTP).
Lock user account temporarily after multiple Defines whether the system should lock user
failed login attempts accounts after five successive failed login attempts
over a timespan of 15 minutes.
The account will be locked for 15 minutes, then the

user can attempt to log in again.
480
System settings Calendar settings
Setting Description
Allow users to grant own user roles Defines whether users can grant user roles which
they have themselves to others when creating new
users.
Allow assigning object to related objects during Defines whether users should be allowed to assign
add or update an object to a related object when they create or
You can allow users to assign an organisation unit

to data sets and organisation unit group sets when
creating or editing the organisation unit.
Require user account password change Defines whether users should be forced to change
their passwords every 3, 6 or 12 months.
If you don't want to force users to change password,

select Never.
Enable password expiry alerts When set, users will receive a notification when
their password is about to expire.
Minimum characters in password Defines the minimum number of characters users

must have in their passwords.
You can select 8 (default), 10, 12 or 14.
OpenID provider Defines the OpenID provider.
OpenID provider label Defines the label to display for the specified OpenID
provider.
CORS whitelist Whitelists a set of URLs which can access the

DHIS2 API from another domain. Each URL should
be entered on separate lines. Cross-origin resource
sharing (CORS) is a mechanism that allows
restricted resources (e.g. javascript files) on a web
page to be requested from another domain outside
the domain from which the first resource was
served.
Calendar settings
Calendar settings
481
System settings Data import settings
Setting Description
Calendar Defines which calendar the system will use.
The system supports the following calendars:

Coptic, Ethiopian, Gregorian, Islamic (Lunar Hijri),
ISO 8601, Julian, Nepali, Persian (Solar Hijri) and
Thai.
Note
This is a s system wide setting. It is not possible

to have multiple calendars within a single
DHIS2 instance.
Date format Defines which date format the system will use.
The data import settings apply to extra controls which can be enabled to validate aggregate data
which is imported through the web API. They provide optional constraints on what should be
considered a conflict during import. The constraints are applied to each individual data value in
the import.
Setting Description
Require periods to match period type of data set Require period of data value to be of the same
period type as the data sets for which the data
element of data value is assigned to.
Require category option combos to match Require category option combination of data value
category combo of data element to be part of the category combination of the data
element of the data value.
Require organisation units to match assignment Require organisation unit of data value to be
of data set assigned to one or more of the data sets which the
data element of data value is assigned to.
Require attribute option combos to match Require attribute option combination of data value
category combo of data set to be part of the category combination of the data
set which the data element of data value is
assigned to.
482
System settings Synchronization settings
Setting Description
Require category option combo to be specified Require category option combination of data value
to be specified.
By default it will fall back to default category option

combination if not specified.
Require attribute option combo to be specified Require attribute option combination of data value
to be specified.
By default it will fall back to default attribute option

combination if not specified.
The following settings are used for both data and metadata synchronization.
Note
For more information about how you configure metadata
synchronization, refer to Configure metadata synchronizing
Setting Description
Remote server URL Defines the URL of the remote server running
DHIS2 to upload data values to.
It is recommended to use of SSL/HTTPS since user

name and password are sent with the request
(using basic authentication).
The system will attempt to synchronize data once

every minute.
The system will use this setting for metadata

synchronization too.
Note
To enable data and metadata synchronization,

you must also enable jobs for Data
synchronization and Metadata
synchronization in the Scheduler app.
483
System settings Synchronization settings
Setting Description
Remote server user name The user name of the DHIS2 user account on the
remote server to use for data synchronization.
Note
If you've enabled metadata versioning, you

must make sure that the configured user has the
authority "F_METADATA_MANAGE".
Remote server password The password of the DHIS2 user account on the
remote server. The password will be stored
encrypted.
Enable versioning for metadata sync Defines whether to create versions of metadata
when you synchronize metadata between central
and local instances.
Don't sync metadata if DHIS versions differ The metadata schema changes between versions
of DHIS2 which could make different metadata
versions incompatible.
When enabled, this option will not allow metadata

synchronization to occur if the central and local
instance(s) have different DHIS2 versions. This
apply to metadata synchronization done both via
the user interface and the API.
The only time it might be valuable to disable this

option is when synchronizing basic entities, for
example data elements, that have not changed
across DHIS2 versions.
Best effort A type of metadata version which decides how the

importer on local instance(s) will handle the
metadata version.
Best effort means that if the metadata import

encounters missing references (for example
missing data elements on a data element group
import) it ignores the errors and continues the
import.
Atomic A type of metadata version which decides how the

importer on local instance(s) will handle the
metadata version.
Atomic means all or nothing - the metadata import

will fail if any of the references do not exist.
484
System settings OAuth2 clients
OAuth2 clients
You create, edit and delete OAuth2 clients in the System Settings app.
1. Open the System Settings apps and click OAuth2 clients.
3. Enter Name, Client ID and Client secret.
4. Select Grant types.
Grant type Description
Password TBA
Refresh token TBA
Authorization code TBA
5. Enter Redirect URIs. If you've multiple URIs, separate them with a line.
485
Data Administration Data integrity
Data Administration
The data administration module provides a range of functions to ensure that the data stored in
the DHIS2 database is integral and that the database performance is optimised. These functions
should be executed on a regular basis by a data administrator to ensure that the quality of the
data stored is optimal.
Data integrity
DHIS2 can perform a wide range of data integrity checks on the data contained in the database.
Identifying and correcting data integrity issues is extremely important for ensuring that the data
used for analysis purposes is valid. Each of the data integrity checks that are performed by the
system will be described, along with general procedures that can be performed to resolve these
issues.
Data elements without data set
Each data element must be assigned to a data set. Values for data elements will not be able to be
entered into the system if a data element is not assigned to a data set. Choose Maintenance-
>Datasets->Edit from the main menu and then add the "orphaned" data element to the
appropriate data set.
Data elements without groups
Some Data Elements have been allocated to several Data Element Groups. This is currently not
allowed, because it will result in duplication of linked data records in the analytics record sets that
provide aggregated data. Go to Maintenance -> Data Element Groups to review each Data
Element identified and remove the incorrect Group allocations.
Data elements violating exclusive group sets
Some data elements have been allocated to several data element groups that are members of the
same data element group set. All group sets in DHIS2 are defined as exclusive, which means that
a data element can only be allocated to one data element group within that group set. Go to
Maintenance -> Data elements and indicators ->Data element groups to review each data
element identified in the integrity check. Either remove the data element from all groups except
the one that it should be allocated to, or see if one of the groups should be placed in a different
group set.
Data elements in data set but not in form or sections
Data elements have been assigned to a data set, but have not been assigned to any sections of
the data set forms. All data sets which use section forms, should generally have all data elements
in the data set assigned to exactly one section of the dataset.
Data elements assigned to data sets with different period types
Data elements should not be assigned to two separate data sets whose period types differ. The
recommended approach would be to create two separate data elements (for instance a monthly
and yearly data element) and assign these to respective datasets.
Data sets not assigned to organisation units
All data sets should be assigned to at least one organisation unit.
486
Data Administration Sections with invalid category combinations
Sections with invalid category combinations
Data sets which use section forms should only have a single category combination within each
section. This violation could result from assigning a data element to a section, but then changing
the category combination of this data element at a later point in time.
Indicators with identical formulas
Although this rule will not affect data quality, it generally does not make sense to have two
indicators with the exact same definition. Review the identified indicators and their formulas and
delete or modify any indicator that appears to be the duplicate.
Indicators without groups
All data elements and indicators must be assigned to at least one group, so these Indicators need
to be allocated to their correct Data Element and Indicator Group. From the main menu, go to
Data elements/Indicators -> Indicator Groups, and allocate each of the `Orphaned` indicators to
its correct group.
Invalid indicator numerators
Violations of this rule may be caused by an incorrect reference to a deleted or modified data
element. Review the indicator and make corrections to the numerator definition.
Invalid indicator denominators
Violations of this rule may be caused by an incorrect reference to a deleted or modified data
element. Review the indicator and make corrections to the denominator definition.
Indicators violating exclusive group sets
Some indicators have been allocated to several indicator groups that are members of the same
indicator group set. All group sets in DHIS2 are defined as exclusive, which means that an
indicator can only be allocated to one indicator group within that group set. Go to Maintenance ->
Data elements and indicators ->Indicator groups to review each indicator identified in the integrity
check. Either remove the indicator from all groups except the one that it should be allocated to, or
see if one of the groups should be placed in a different group set.
Duplicate periods
If periods have been imported from external applications, it may be possible that some periods will
be duplicated. If you have any periods which appear to be duplicated here, you will need to
resolve these directly in the DHIS2 database. All data which has been assigned to the duplicated
period, should be moved to the correct period, and the duplicate period should be removed.
Organisation units with cyclic references
Organisation units cannot be both parent and children of each other, directly nor indirectly. If this
situation occurs, you will need to resolve the cyclic reference directly in the DHIS2 database in
the "organisation unit" table, by reassigning the "parentid" field of the organisation units.
Orphaned organisation units
All organisation units must exist within the organisation unit hierarchy. Go to Organisation- units
>Hierarchy Operations and move the offending organisation unit into the proper position in the
hierarchy.
487
Data Administration Organisation units without groups
Organisation units without groups
All organisation units must be allocated to at least one group. The problem might either be that
you have not defined any compulsory OrgUnit Group Set at all, or that there are violations of the
compulsory rule for some OrgUnits . NOTE: If you have defined no compulsory OrgUnit Group
Sets, then you must first define them by going to Organisation units->Organisation unit group sets
and define at least one compulsory Group Set (the group set 'Type' are nearly universally
relevant). If you have the relevant group sets, go to Maintenance -> OrgUnit Groups to review
each OrgUnit identified and add the relevant Group allocation.
Organisation units violating compulsory group sets
These organisation units have not been assigned to the any organisation unit group within one of
the compulsory organisation unit group sets. When a group set is defined as compulsory, it
means that an organisation unit must be allocated to at least one organisation unit group within
that group set. For instance, all organisation units must belong to one of the groups in the 'Type'
group set. It might belong to the `Hospital` or the `Clinic` or any other 'type' group - but it must
belong to exactly one of them. Go to Organisation units->Organisation unit groups to review each
organisation unit identified in the integrity check. Allocate all organisation units to exactly one
compulsory group.
Organisation units violating exclusive group sets
Some organisation units have been allocated to several organisation unit groups that are
members of the same organisation unit group set. All group sets in DHIS2 are defined as
exclusive, which means that an organisation unit can only be allocated to one organisation unit
group within that Group Set. For instance, one organisation unit cannot normally belong to the
both the 'Hospital' and 'Clinic' groups , but rather to only to one of them. Go to Organisation unit-
>Organisation unit groups to review each organisation unit identified in the integrity check.
Remove the organisation units from all groups except the one that it should be allocated to.
Organisation unit groups without group sets
The organisation unit groups listed here have not been allocated to a group set. Go to
Maintenance->Organisation unit->Organisation unit group sets and allocate the Organisation unit
group to the appropriate group set.
Validation rules without groups
All validation rules must be assigned to a group. Go to Maintenance app > Validation rule group
and assign the offending validation rule to a group.
Invalid validation rule left side expressions
An error exists in the left-side validation rule definition. Go to Maintenance app > Validation rule
and click Edit on the offending rule. Click Left side and make the required corrections.
Invalid validation rule right side expressions
An error exists in the right-side validation rule definition. Go to Maintenance app > Validation rule
and click Edit on the offending rule. Click Right side and make the required corrections.
ProgramRules with no condition
Report will highlight all the Program rules not configured with Condition. Evaluation for rules not
having condition are always evaluated as false.
488
Data Administration ProgramRules with no priority
ProgramRules with no priority
Report will highlight all the Program rules not configured with Priority. This is optional but its
existence is very important when ProgramRuleActionType is ASSIGN. Rules with ASSIGN action
type should have higher priority then the rest of the action types.
ProgramRules with no action
Report will highlight all the Program rules not configured with any ProgramRuleAction.
ProgramRuleVariables without dataElements
Report will highlight all the Program rule variables not configured with DataElement. Report will
be based on source type configuration. DataElement should be provided when the source type of
ProgramRuleVariable is DataElement.
ProgramRuleVariables without attributes
Report will highlight all the Program rule variables not configured with TrackedEntityAttribute.
Report will be based on source type configuration. TrackedEntityAttribute should be provided
when the source type of ProgramRuleVariable is Attribute.
ProgramRuleActions with no data Objects.
Report will highlight all the Program rule actions not configured with any Data object. Data object
can be either DataElement of TrackedEntityAttribute. There are certain ProgramRuleActions
which are responsible for assinging values to either dataElement or trackedEntityAttribute.
ProgramRuleActions with no notification
Report will highlight all the Program rule actions which have ProgramRuleActionType set to
SENDMESSAGE/SCHEDULEMESSAGE where the configuration does not provide any link to
notification.
ProgramRuleActions with no section id
HIDESECTION but configuration does not provide any section id.
ProgramRuleActions with no program stage id
HIDEPROGRAMSTAGE but configuration does not provide any program stage id.
Invalid program indicator expression
Reports all the violations in program indicator expression caused by invalid DataElement or
invalid TrackedEntityAttribute.
Invalid program indicator filter expression
Reports all the violations in program indicator filter expression caused by invalid DataElement or
invalid TrackedEntityAttribute.
Maintenance
Data maintenance functions in the Data Administration app
489
Data Administration Maintenance
Clear analytics tables Completely empties the analytics tables. These

tables are used to generate aggregate data for the
pivot tables, GIS and reports.
Remove zero data values Removes zero data values from the database.
Values registered for data elements with
aggregation operator average is not removed, as
such values will be significant when aggregating
the data, contrary to values registered for data
elements with aggregation operator sum.
Reducing the number of data values will improve

system performance.
Permanently remove soft deleted data values When a data value is deleted in DHIS2, the system
will mark the corresponding database row as
deleted, and not actually delete the row.
Running this maintenance function will physically

remove these data value rows from the database.
Prune periods Removes all periods which have no registered data

values. Reducing the number of periods will
improve system performance.
Remove expired invitations Will delete users which represent user account
invitations that now have gone past their expiry
date.
Drop SQL views DHIS2 lets you set up and manage SQL views as
system objects with corresponding database SQL
views.
Running this maintenance function will drop

underlying SQL views for all system views. Use the
Create SQL views function to recreate these SQL
views.
Create SQL views Recreates all SQL views in the database.
Update category option combinations Rebuilds the category option combinations. This
may be required after altering the category options
which belong to a given category.
490
Data Administration Resource tables
Update organisation unit paths The organisation unit table in the DHIS2 database
has a column "path" which contains a concatenated
string of all ancestors in the hierarchy for each
organisation unit.
Running this maintenance function will update and

ensure that these values are in sync with the current
organisation unit hierarchy. This column is
managed by DHIS2, but a manual update might be
useful when doing data loading directly in the
database.
Clear application cache Clears the system cache.
Reload apps Manually reloads and detects installed DHIS2 apps.
The installed apps are also detected when the

system starts and when installing or uninstall apps.
Resource tables
Resource tables are supporting tables that are used during analysis of data. One would typically
join the contents of these tables with the data value table when doing queries from third-party
applications like Microsoft Excel. They are also used extensively by the analysis modules of
DHIS2. Regeneration of the resource tables should only be done once all data integrity issues
are resolved. The resource tables are also generated automatically, every time the analytics
process is run by the system.
• Organisation unit structure (_orgunitstructure)
This table should be regenerated any time there have been any changes made to the
organisational unit hierarchy. This table provides information about the organisation unit
hierarchy. It has one row for each organisation unit, one column for each organisation unit
level and the organisation unit identifiers for all parents in the lineage as values.
• Data element group set structure (_dataelementgroupsetstructure)
This table provides information about which data elements are members of which data
element group sets. The table has one row for each data element, one column for each
data element group set and the names of the data element group as values.
• Indicator group set structure (_indicatorgroupsetstructure)
This table provides information about which indicators are members of which indicator
group sets. The table has one row for each indicator, one column for each indicator group
set and the names of the indicator group as values.
• Organisation unit group set structure (_organisationunitgroupsetstructure)
This table provides information about which organisation units are members of which
organisation unit group sets. The table has one row for each organisation unit, one column
491
Data Administration Analytics tables management
for each organisation unit group set and the names of the organisation unit groups as
values.
• Category structure (_categorystructure)
This table provides information about which data elements are members of which
categories. The table has one row for each data element, one column for each category
and the names of the category options as values.
• Data element category option combo name (_categoryoptioncomboname)
This table should be regenerated any time there have been changes made to the category
combination names. It contains readable names for the various combinations of categories.
• Data element structure (_dataelementstructure)
This table provides information about all data elements and which period type (frequency)
they capture data at. The period type is determined through the data set membership and
hence relies on data elements to be member of data sets with similar period types to have
a defined behaviour.
• Period structure (_dataperiodstructure)
This table provides information about all periods and which period type they are associated
with. For each period type with lower frequency than itself, it contains information about
which period it will fall within.
• Data element category option combinations (_dataelementcategoryoptioncombo)
This table provides a mapping between data elements and all possible category option
combinations.
Analytics tables management
DHIS2 generates database tables which the system then uses as basis for various analytics
functions. These tables are also valuable if you write advanced SQL reports. In the Data
Administration app, you can execute the tables generation immediately. If you want to schedule
them to be executed at regular intervals, this can be done in the Scheduler app. This means that
you can refresh recent analytics on demand and see updated pivot tables without waiting for all of
the past years data to re-process.
Note
You can also generate the tables through the web API. This task is
typically performed by a system administrator.
1. Open the Data Administration app and click Analytics Tables.
2. Select the parts of the analytics process you want to skip:
◦ Skip generation of resource tables
◦ Skip generation of aggregate data and completeness data
◦ Skip generation of event data
◦ Skip generation of enrollment data
3. Select Number of last years of data to include.
492
Data Administration Data statistics
Click Start export.

4.
Data statistics
The data statistics module provides an overview of the number of objects stored in the DHIS2
database.
The total number of each type of object is presented in a series of tables with summary statistics
of each object.
Lock exceptions
Lock exceptions provide fine-grained control over exemption from a locked data set. After the
expiry of the data set, data entry will be denied by default, unless an exception has been granted
through the Lock exception interface. To enable a lock exception, select the desired organization
units, data sets, and time period and press "Add". By granting a lock exception, data entry will be
enabled even after the expiry period of the data set has passed.
493
Data Administration Min-Max Value Generation
In the example above, a data lock exception would be created for "ab Abundant Life
Organization" and "ab Seventh Day Hospital" for the "Care and Support" dataset for "February
2012".
Min-Max Value Generation
This administrative function can be used to generate min-max values, which are used as part of
the data quality and validation process for specific organization units and data sets. Simply select
the dataset from the left hand frame, and then select the required organisation units to generate
the min-max values for from the organisational units selector on the right. Press the "Generate"
button to generate or regenerate all min-max values. Press "Remove" to remove all min-max
values which are currently stored in the database.
494
Data Administration Cache Statistics
Cache Statistics
This option is for system administrators only to use. The cache statistics shows the status of the
application level cache. The application level cache refers to the objects and query results that
the application is caching in order to speed up performance. If the database has been modified
directly the application cache needs to be cleared for it to take effect.
495
Visualize usage statistics About the Usage Analytics app
Visualize usage statistics

About the Usage Analytics app
The Usage Analytics app lets you visualize statistics on how users are working with the
Dashboard, Pivot Table, GIS, Event Visualizer, Data Visualizer and Event Reports apps within
DHIS2. With this statistics you can answers questions such as:
• How many times people have loaded charts, pivots tables and dashboards?
• How many favorites have users created?
• How many users that are logging in versus total number of users?
• What are the most viewed favorites?
Create a usage analytics graph
1. Open the Usage Analytics app.
2. Select a Start date and End date.
3. Select an Interval: day, week month or year.
4. Select a Category.
496
Visualize usage statistics Create a usage analytics graph
There are five analytics categories:
◦ Favorite views: Provides the number of times various types of favorites have been
viewed, such as charts, pivot tables and dashboards, over time. This analysis lets
you switch between all types of favorites, the total across all types and the average
number of views.
◦ Favorites: Provides the number of favorites which have been created and stored in
the system over time.
◦ Users: Provides the number of active as well as total number of users over time.
◦ Top favorites: Shows the most viewed favorites in the system by type.
◦ Data values: Provides the number of data values stored in the system over time.
5. Click Update.
497
Datastore Manager Using the Datastore Manager
Datastore Manager
The Datastore Manager is intended for advanced-level DHIS2 users. Before you use the
Datastore Manager, you can read more about the Data store here: DHIS2 data store.
Using the Datastore Manager
The Datastore Manager lets you manage the content of the web API data stores. This is helpful
when managing apps and external scripts.
Add a new namespace and key to the Datastore Manager
Note: You have to create a namespace before you can add a key to it.
1. Click New.
2. Enter a name for the namespace you want to create.
3. Enter a key name, and select Create. The new namespace displays in the left pane.
Add a key to an existing namespace in the Datastore Manager
To add a new key to an existing namespace in the Datastore Manager,
1. Select the namespace you want to add a key to.
2. Click the options menu, and click New key.
3. Enter a key name in the New key dialog box.
4. Click Create. The new key is added to the namespace you selected.
Delete a namespace or key from the Datastore Manager
To delete a namespace, or key, click the Options menu, and then click Delete, and then Delete
again. Note that if you delete the only key in a namespace, you will also delete the namespace it
belongs to.
Search for namespaces or keys
Use the search tool in the top left corner to search for namespaces and keys as follows:
• Enter a namespace name followed by # and the key name to search for a specific key in a
namespace.
498
Datastore Manager Search your JSON library
Enter # followed by the name of a key to search for keys only.

•
Search your JSON library
Use the search tool in the workspace toolbar to search your JSON library.
Edit namespaces or keys in the Datastore Manager
Use the Search tool to find namespaces or keys in your datastore. When you edit your content,
you can toggle between the Tree view and the Code view. Use the Tree view to get an overview
of the contents of the Datastore. Use the Code view to edit your code directly in the code editor.
Remember to save your work by clicking the Save button.
In the Code view, you can edit your code. When you edit a line of code, it is highlighted in yellow.
499
Datastore Manager Edit namespaces or keys in the Datastore Manager
Any errors are marked by the editor. If you hover over the error icon, you can view a short
description of the error.
500
Scheduling Creating a job
Scheduling
The Scheduler is an application for managing background jobs in DHIS2. Background jobs can do
a number of tasks, such as running analytics, synchronizing data and meta data, or sending a
push analysis report. The application provides the ability to create, modify and delete such jobs.
The Scheduler comes bundled with DHIS2 and is accessed through the App Menu.
The start page of the Scheduler app shows an overview of existing jobs. By default, pre-defined
system jobs are hidden. To view these, toggle Show system jobs in the top right corner.
When you create or modify a job, it will be rescheduled according to selected preferences. To run
a job on demand, press the green triangle labelled "Run now". This action is only available for
enabled jobs.
Creating a job
1. Open the Scheduler app and click the add button in the bottom right corner.
2. Choose a suitable Name for the new job.
3. Select a running frequency for the job, i.e. when and how often the job should run.
1. You can either select a predefined frequency from the drop-down menu, or
2. You can give the job a custom Cron expression if you want a specific schedule,
using the Spring scheduling syntax.
3. Enabling the Continuous execution option will make the job run constantly. In other
words, as soon as the job finishes, it will be scheduled to run again right away.
Selecting this option will disable the other fields.
4. Select the Job type you want to schedule using the drop-down menu.
5. If the job type is customizable, a Parameters section will appear below. These additional
options specify the details of the scheduled job, and will vary greatly depending on the job
type.
6. Press the Add job button to confirm the job creation. The newly created job should now be
listed in the job overview, given that the Show system jobs setting is not enabled.
501
Scheduling Configuring a job
Jobs are enabled by default.
Configuring a job
With the proper permissions, you can modify the details of user-created jobs. Note that for system
jobs, only the schedule (cron expression) can be changed.
To quickly enable or disable a user created job from running, use the Enabled column on the
landing page of the Scheduler app. System jobs are always enabled.
Further configuring a job:
1. Select a job from the landing page to unveil the Attributes and change them to accordingly.
See the previous section for scheduling details.
2. If the job type supports extra options, the Parameters section will also be available.
3. When done, press the Save changes button to persist the changes.
Deleting a job
1. Select the job you want to delete.
2. Press the Delete button in the bottom right corner.
3. Confirm by pressing Delete again in the pop-up window.
502
Scheduling Job types
Job types
The following section describes the various job types.
Resource table
The resource table job is responsible for generating and updating the resource database tables.
These tables are used by various components in DHIS 2 and is meant to simplify queries against
the database.
Note that when specifying any of the analytics table jobs, resource tables can be part of the
process and it is not necessary to also specify a resource table job.
Analytics table
The analytics tables job is responsible for generating and updating the analytics tables. The
analytics tables are used as basis for data analytics queries in DHIS2. Apps such as dashboard,
visualizer and maps retrieve data from these tables through the DHIS2 analytics API, and they
must be updated in order for analytics data to become available. You can schedule this process
to run regularly through an analytics table job type.
The analytics table job will by default populate data for all years and data elements. The following
parameters are available:
• Last years: The number of last years to populate analytics tables for. As an example, if you
specify 2 years, the process will update the two last years worth of data, but not update
older data. This parameter is useful to reduce the time the process takes to complete, and
is appropriate if older data has not changed, and when updating the latest data is desired.
503
Scheduling Continuous analytics table
• Skip resource tables: Skip resource tables during the analytics table update process. This
reduces the time the process takes to complete, but leads to changes in metadata not
being reflected in the analytics data.
• Skip table types: Skip one or more analytics table types. This reduces the time the
process takes to complete, but leads to those data types not being updated in analytics
data.
Continuous analytics table
The analytics tables job is responsible for generating and updating the analytics tables. The
analytics tables are used as basis for data analytics queries in DHIS2. Apps such as dashboard,
visualizer and maps retrieve data from these tables through the DHIS2 analytics API, and they
must be updated in order for analytics data to become available. You can schedule this process
to run regularly through an analytics table job type.
The continuous analytics table job is based on two phases:
• Latest update: Update of the latest data, where latest refers to the data which has been
added, updated or removed since the last time the latest data or the full data was updated.
This process will happen frequently.
• Full update: Update of all data across all years. This process will happen once per day.
The continuous analytics table job will frequently update the latest data. The latest data process
utilizes a special database partition which is used to hold the latest data only. This partition can be
quickly refreshed due to the relatively small amount of data. The partition will grow in size until a
full update is performed. Once per day, all data for all years will be updated. This will clear out the
latest partition.
The analytics table job will by default populate data for all years and data elements. The following
parameters are available:
• Full update hour of day: The hour of the day at which the full update will be done. As an
example, if you specify 1, the full update will be performed at 1 AM.
• Last years: The number of last years to populate analytics tables for. As an example, if you
specify 2 years, the process will update the two last years worth of data, but not update
older data. This parameter is useful to reduce the time the process takes to complete, and
is appropriate if older data has not changed, and when updating the latest data is desired.
• Skip resource tables: Skip resource tables during the analytics table update process. This
reduces the time the process takes to complete, but leads to changes in metadata not
being reflected in the analytics data.
Data synchronization
DHIS2 provides synchronisation of data between remotely distributed instances and a central
instance of DHIS2. This can be useful e.g. when you have deployed multiple stand-alone
instances of DHIS2 which are required to submit data values to a central DHIS2 instance. Both
tracker data and aggregate data synchronization is supported.
These are the steps to enable data synchronization:
• Go to Synchronization Settings, enter the remote server URL, username and password.
Press the TAB button to automatically save the new password. Refresh the page and check
that the filled values are still present. Note that the password field will be empty after the
refresh, since this value is encrypted, so you can consider it saved.
• Using the Scheduler app, create a new job using the "Event Programs Data Sync" and/or
"Tracker Programs Data Sync" job type. Make sure it is enabled when you finish. (Note: If
the "Program Data Synchronization" job, available in previous versions, was set up in
504
Scheduling Data synchronization
Scheduler app before, it was automatically replaced by the two new jobs "Event Programs
Data Sync" and "Tracker Programs Data Sync" with the identical settings. )
Some aspects of the data synchronization feature to be aware of:
• The local DHIS2 instance will store the password of the user account on the remote
instance encrypted in the local database. The remote account is used for authentication
when transferring data. For security purposes make sure you set the encryption.password
configuration parameter in hibernate.properties to a strong password.
• Deploying the remote server on SSL/HTTPS is strongly recommended as the username

and password are sent in clear text using basic authentication and could be intercepted by
an attacker.
• The data synchronization uses the UID property of data elements, category option combos
and organisation units to match the meta-data. Hence the synchronization is dependent on
these three meta-data objects being harmonized on the local and remote instance in order
to work appropriately.
• The first time DHIS2 runs the synchronization job, it will include any data available. The
subsequent synchronization jobs will only include data added and changed since the last
successful job. A synchronization job is considered successful only if all the data was saved
successfully on the remote server (Any data successfully synced will remain on the
receiving instance, regardless if the job eventually fails). Whether the job was successful or
not can be decided from the import summary returned from the central server.
• The initial synchronization job may take a significant amount of time, possibly slowing down
your instance, depending on how much data is being synchronized. It could be a good idea
to configure the job to run when there are few online users, then later change this to your
own preference. If you do not want or need to synchronize all the data, there is a possibility
to skip some of the data being synchronised.
When DHIS2 synchronizes tracker data, it determines the set of data to synchronize based
on the last time it was synchronized. Each of the tracked entity instances and events have
their own records of when they where last successfully synchronized.
• The system will start a synchronization job based on the rules set in the configuration of the
job. If the synchronization job starts while there is no connection to the remote server, it will
retry up to three times before it aborts. The job will run again at a scheduled time.
• The server handles each set of programs separately, which means one set of programs
can be synchronized successfully, while the other fails. The failure or success of one
doesn't influence the other, as the last successful synchronization time is tracked
individually for each item as previously mentioned.
• The attributes of TrackedEntityInstances (TrackedEntityAttribute) and the data elements of

ProgramStages (ProgramStageDataElement) which have an option "Skip synchronization"
turned on will not be synchronized. This feature allows you to decide to not synchronize
some sensitive or not relevant data and to keep them only locally.
• The authority Ignore validation of required fields in Tracker and Event

Capture (F\_IGNORE\_TRACKER\_REQUIRED\_VALUE\_VALIDATION) should be used
when there is a requirement that some mandatory attribute / data element has at the same
time a "Skip synchronization" property turned on. Such a setting will lead to validation
failure on the central server as the given attribute / data element will not be present in the
payload.
505
Scheduling Metadata Synchronization Scheduling
The validation won't fail for the user with this authority. The authority should be assigned to
the user, on the central server, that will be used for synchronization job.
• In specific cases, the initial synchronization of all the data can be undesirable; for
example, when a database on the local instance is a fresh copy of the database present on
the central instance, or when it is preferred to not synchronize old data in favor of initial
synchronization taking less time.
The syncSkipSyncForDataChangedBefore SettingKey can be used to skip the

synchronisation of all the data (data values, Event and Tracker program data, complete
data set registrations) that were last changed before the specified date. The SettingKey
is used in the synchronization job all the time. Therefore, if you need to synchronize the old
data, you should change the SettingKey.
• Both Tracker Programs and Event Programs synchronization job supports paging in order
to avoid timeouts and to deal with unstable network. Default page size for "Event Programs
Data Sync" job is set to 60. Default page size for "Tracker Programs Data Sync" job is set
to 20.
If default values do not fit your purpose, own page size can be specified via parameter in
particular sync job in Scheduler app.
Metadata Synchronization Scheduling
DHIS2 provides a feature for synchronizing meta data from a remote instance to a local instance
of DHIS2. This can be useful when you have deployed multiple stand-alone instances of DHIS2
and you need to create meta data in all the local instances similar to the central DHIS2 instance.
These are the steps to enable meta data synchronization:
• Go to Settings > Synchronization, enter the remote server URL, username and password
and click Save.
• Go to Metadata administration > Scheduling. Under Metadata synchronization set strategy

to Enabled, select the time-period and click Start.
Some aspects of the meta data synchronization feature to be aware of:
• The local DHIS2 instance will store the password of the user account of the remote
instance in its database. The remote user account is used for authentication when
transferring/downloading data. For security purposes make sure you set the
encryption.password configuration parameter in hibernate.properties to a strong password.
• Deploying the remote server on SSL/HTTPS is strongly recommended as the username

and password are sent in clear text using basic authentication and could be intercepted by
an attacker.
• Also ensure that the remote user is not having ALL authority, instead simply create a user
with F_METADATA_MANAGE authority so that even if these details are intercepted by a
hacker, one cannot have full control of the remote system.
• The meta data synchronization relies on the underlying import layer. Each meta data
version is an export of meta data between two given timestamps. Each sync of meta data
version is an attempt to import that meta data snapshot into the local instance. The sync of
versions is incremental. The local instance will try to download the meta data versions from
the central instance one after the other. Failure to sync a specific meta data version will not
let the sync proceed to further versions. In case of failures, appropriate changes must be
made to meta data at central to ensure that the error gets resolved. Metadata configuration
506
Scheduling Metadata Synchronization Scheduling
is critical and the user should be careful while rolling out the updates to the production. It's
always recommended to have staging environments in place to ensure the sanity of the
meta data versions and their impact thereafter. The local instance will sync the meta data
from first version so that harmony is maintained and local and central instance will work
appropriately.
• The system will attempt a synchronization at the scheduled time. If the local or remote
server does not have a working Internet connection at the time, the synchronization will be
aborted and re-attempted after as per the retry count as mentioned in the dhis.conf file.
• You can see the time of last successful synchronization with remote server in the
scheduling screen next to the "Last success" label.
507
Import/Export App Importing data
Import/Export App
In a primary health system, the HMIS typically involves a distributed application, where the same
application is running in different geographical locations (PHCs,CHCs, hospitals, districts, and
state). Many of these physical locations do not have Internet connectivity, and hence they work
off-line. At some point (normally at the district level), the data needs to be synchronised in order
to have a consolidated database for the a particular geographical region. For this, it is important
to be able to export data from one location (which is working offline, say at the health facility level)
and import into another one (say at the district level). This feature of exporting and importing is
thus a crucial function of a HMIS. This feature also helps us overcome the dependency on the
Internet to some degree, as data updates can be transferred via USB key where there is no
connectivity, or through email where there is limited Internet connectivity. DHIS2 provides robust
export-import functionality to fulfil these needs.
To access the Import/Export app, search in the top header bar for Import/Export. Import/Export
app offers a number of services details for which can be found below.
Importing data
Import progress logger
No matter what you import ("Metadata", "Data", "Events" or "GML" data), you can always view the
progress of the import by opening the logger at the bottom of the screen.
• To open the logger, click on the "arrow up" icon on the right side:
• To close the logger, click on the "arrow down" icon in the top-right corner:
508
Import/Export App Import Summaries
Import Summaries
On import request completion, we show import summaries above the import form. Any conflicts or
errors are shown in a paginated table under totals.
Metadata Import
Metadata Import can be accessed from the sidebar by clicking on Metadata Import.
509
Import/Export App Metadata Import
1. Choose a file to upload
2. Select from the available formats e.g. JSON , XML or CSV
3. Choose Dry Run . Yes will do a test import without importing any data into the database.
4. Select the appropriate settings of:
◦ Idenfifier
◦ Import report mode
◦ Preheat mode
◦ Import strategy
◦ Atomic mode
◦ Merge mode
5. Click MORE OPTIONS if you want to adjust one or more of the following settings before
importing:
◦ Flush mode
◦ Skip sharing
◦ Skip validation
◦ Async
◦ Inclusive strategy
510
Import/Export App Data Import
Click on the Import button which will upload the file and start the importing process.
6.
Tip
It is highly recommend to use the Dry run option to test before
importing data; to make sure you keep control over any changes to your
Metadata, and to check for problems with out-of-sync data elements or
organisation unit names
Note
If an organisation unit e.g. Nduvuibu MCHP had a unknown reference to
an object with ID aaaU6Kr7Gtpidn, it means that the object with ID
aaaU6Kr7Gtpidn was not present in your imported file, and it was not
found in the existing database.
You can control this using Reference Mode option available under
MORE OPTIONS, to indicate if you want to allow objects with such
invalid references to be imported or not. If you choose to import invalid
references you will have to correct the reference manually in DHIS2
later.
Matching Identifiers in DXF2
The DXF2 format currently support matching for two identifiers, the internal DHIS2 identifier
(known as a UID), and also using an external identifier called called a "code". When the importer
is trying to search for references (like the one above), it will first go to the UID field, and then to
the code field. This allows you to import from legacy systems without having a UID for every meta-
data object. I.e. if you are importing facility data from a legacy system, you can leave out the ID
field completely (DHIS2 will fill this in for you) and put the legacy system's own identifiers in the
code field, this identifier is required to be unique. This not only works for organisation units, but
for all kinds of meta-data, allowing for easy import from other systems.
Data Import
Data Import can be accessed from the sidebar by clicking on Data Import.
511
Import/Export App Data Import
1. Choose a file to upload
2. Select from the available formats: JSON, XML, PDF, ADX or CSV
4. Select the appropriate settings of:
◦ Strategy
◦ Preheat cache
5. Click MORE OPTIONS if you want to adjust one or more of the following settings before
importing:
◦ Data element id scheme

◦ Org unit id scheme
◦ Id scheme
◦ Skip existing check
6. Click on the Import button which will upload the file and start the importing process.
Tip
It is highly recommend to use the Dry run option to test before
importing data; to make sure you keep control over any changes to your
Metadata, and to check for problems with out-of-sync data elements or
organisation unit names
PDF Data
DHIS2 supports import of data in the PDF format. This can be used to import data produced by
off-line PDF data entry forms. Please refer to the section Data set management for details on
how to produce a PDF form which can be used for off-line data entry.
512
Import/Export App Event Import
To import a PDF data file, navigate to the PDF Data Import item in the side menu. Upload the
completed PDF file and click Import.
Event Import
Event can be access from the sidebar by by clicking on Event import.
1. Select from the available formats e.g. JSON , XML or CSV
3. Choose Event ID Scheme.
4. Choose Org Unit ID Scheme.
GML Import
GML Import can be accessed from the sidebar by clicking on GML Import.
1. Upload a file using the GML (Geographic Markup Language) format.
513
Import/Export App Exporting data
Choose Dry Run . Yes will do a test import without importing any data into the database.
2.
Exporting data
Metadata Export
Metadata export can be accessed from the sidebar by clicking on Metadata export.
1. Choose the list of objects you would like to export.
514
Import/Export App Metadata Export with Dependencies
Choose export format JSON or XML

2.
3. Choose compression type zip , gzip or uncompressed
4. Choose option Sharing with or without sharing.
5. Click Export which will bring up the Logger at the bottom of the page to show the progress.
6. The exported file is downloaded to your local computer.
Metadata Export with Dependencies
Metadata export with dependencies lets you create canned exports for metadata objects. This
type of export will include the metadata objects and the metadata object's related objects; that is,
the metadata which belong together with the main object.
Object types and their dependencies
Object type Dependencies included in export
Data sets Data elements
Sections
Indicators
Indicator types
Attributes
Data entry forms
Legend sets
Legends
Category combinations
Categories
Category options
Category option combinations
Option sets
515
Programs Data entry form
Tracked entity
Program stages
Program attributes
Program indicators
Program rules
Program rule actions
Program rule variables
Program attributes
Data elements
Categories
Category options
Option sets
Category combination Category combinations
Categories
Category options
Attributes
Dashboard Dashboard items
Charts
Event charts
Pivot tables
Event reports
Maps
Reports
Resources
516
Data element groups Data elements
Categories
Category options
Option sets
Attributes
Legend sets
Legends
OptionSets Option
517
Import/Export App Data export
1. Select an Object type : Data sets , Programs , Category combination , Dashboard , Data
element groups or OptionSets.
2. Select an Object.
3. Select a format: XML or JSON.
4. Select Compression : Zip , Gzip or Uncompressed.
Data export
Data export can be accessed from the sidebar by clicking on Data export.
518
Import/Export App Data export
1. Select the Organisation Units .
2. Select under Children if you want export to include descendants of organisation units
selected in Step 1 or only the manually selected organisation units.
3. Set the Start and End Date .
4. Choose the Data Sets
5. Select a format: XML or JSON .
519
Import/Export App Event export
Select Compression : Zip , Gzip or Uncompressed.

6.
7. Click MORE OPTIONS If you want to adjust Data Element ID Scheme, Org. Unit ID Scheme
or ID Scheme before export.
Event export
Event export can be accessed from the sidebar by clicking on Event export.
You can export event or tracker data in XML , JSON or CSV formats.
2. Select a program and a program stage (if applicable).
3. Select the ID scheme to use for export: UID (default) or CODE .
If you select CODE but the object's attribute does not have code, it will not be included in
the return payload.
4. Select Start date and End date .
520
Import/Export App Event export
Select the Inclusion:

5.
◦ Selected organisation unit : Export event data only for the selected organisation
unit
◦ Include children of organisation unit : Export event data for the children of the
organisation unit as well as the selected organisation unit itself.
◦ Include descendants of organisation unit : Export event data for the descendants
of the organisation unit as well as the selected organisation unit itself.
6. Select a format: XML , JSON or CSV.
7. Select Compression : Zip , Gzip or Uncompressed.
521
Configure metadata synchronizing About data and metadata synchronization
Configure metadata synchronizing

About data and metadata synchronization
You can synchronize data and metadata between different DHIS2 instances. Given two instances
in a central-local deployment strategy, metadata created at the central system can be
synchronized with the local system and the data created at local system can be synchronized with
the central system. This can be useful when you've multiple stand-alone instances of DHIS2 and
global metadata needs to be created at all the local instances.
If metadata creation and update take place at the central system and if the metadata
synchronisation task is enabled, the metadata gets synchronized down to all the local instances
which are bound to the central instance. These local instances will in turn push data values, Event
and Tracker program data and complete data registration sets to the central instance. Enabling or
disabling versioning of metadata synchronization at local instance, will not hinder the metadata
synchronization process. This is because the metadata synchronization interacts with versioning
end points of the central instance and not with end points of the local instance.
Each snapshot of metadata export generated is referred to a metadata version. A new metadata
version contains only the changes between the previous version and the current version, that is
it's an export between two timestamps. All metadata versions are maintained in the DHIS2
database and are available to all local instances that connect to it. You can schedule each of the
local instances to download new metadata versions. It is recommended to keep the metadata
versions' sizes small and logical.
Warning
Each instance of DHIS2, whether central or local, can create metadata
versions. The local instance is meant to synchronize metadata from a
central system and not create metadata on its own.
If a new metadata version is created on the local instance, this instance
can't receive new metadata versions from the central instance, since the
content of the metadata versions will be out of synchronization.
If you've created metadata versions on a local instance, you must
manually deleted these versions from the database before you can
synchronize with the central instance.
522
Configure metadata synchronizing Workflow
Assume the central and local DHIS2 instances have identical metadata
snapshots until version 10. Then the local instance creates a new
snapshot called version 11. After that, the central instance creates a
new snapshot called version 11. When the local instance attempts to
synchronize metadata, version 11 is not downloaded. However, the
content of version 11 on the local instance is not identical to the content
of version 11 on the central instance.
Note
You can also use the Import-Export app to synchronize metadata
manually.
Workflow
1. On the central instance, configure metadata versioning. You should do this once the central
instance contains metadata.
2. Connect local instance(s) to the central instance.
3. On local instance(s), configure automatic synchronization.
Configure metadata versioning on central instance
Note
To synchronize metadata, the user account of the central system must
have the following authority:
F_METADATA_MANAGE
Only users with this authority will then be able to create and download
metadata. This is to ensure security of the central system where the
metadata is created. Instead of giving the credentials of user having ALL
authority to the field instances, you need to create a user having this
specific authority only.
1. On the central instance, open the System Settings app and click Synchronization.
2. Go to the Metadata versioning section and select Enable versioning for metadata sync.
3. (Optional) Select Don't sync metadata if DHIS2 versions differ.
4. Select a type of metadata version: Best effort or Atomic.
◦ Best effort means that if the metadata import encounters missing references (for
example missing data elements on a data element group import) it ignores the errors
and continues the import.
523
Configure metadata synchronizing Connect local instance to central instance
Atomic means all or nothing - the metadata import will fail if any of the references do
◦ not exist.
Note
Each metadata entity is associated with a "User" object. If this "User"
reference is missing while importing metadata version of type ATOMIC,
the import will fail at the validation phase itself. This means that the user
who creates metadata also needs to synchronize down to local
instances to successfully import the metadata version of type ATOMIC.
5. Click Create new version. The new version is added to the versioning table.
Connect local instance to central instance
To enable metadata synchronization, you must configure the connection between the local
instance and the central instance.
1. On the local instance, open the System Settings app and click Synchronization.
2. Add the central DHIS2 instance's details to the local instance:
◦ Remote server URL
◦ Remote server user name
◦ Remote server password
4. (Optional) Select Don't sync metadata if DHIS2 versions differ.
The metadata schema changes between versions of DHIS2 which could make different
metadata versions incompatible.
When enabled, this option will not allow metadata synchronization to occur if the central
and local instance(s) have different DHIS2 versions. This apply to metadata
synchronization done both via the user interface and the API.
The only time it might be valuable to disable this option is when synchronizing basic
entities, for example data elements, that have not changed across DHIS2 versions.
5. (Optional) Configure email notifications to notify users about successful or unsuccessful

metadata synchronization:
1. Open the System Settings app and click Email.
2. Enter Host name, Port, User name, Password and Email sender.
3. Click Server and enter a System notifications email address.
This email address will receive notifications about the metadata synchronization
status.
Tip
When you receive email notification about a metadata synchronization failure,
check which metadata version that causes the error and resolve it. Then you
avoid future errors when the system downloads new metadata versions.
524
Configure metadata synchronizing Configure automatic metadata synchronization on local instance
Configure automatic metadata synchronization on local instance
Once you have configured automatic metadata synchronization (scheduling) on local instance(s),
the scheduler will run at that specific time and synchronize (download and import) the metadata
from the central instance. No manual intervention is required from the users at the local
instance(s).
After the scheduler has completed the metadata synchronization, the local instance will have the
metadata exactly as created on the central system.
Note
Passwords of users are not synchronized. They are nullified for security
reasons. After metadata synchronization, the Admin user must reset
these passwords.
1. On the local instance, open the Data Administration app and click Scheduling.
2. In the Metadata Synchronization section, select Enabled.
3. Select a time period: Daily, Weekly, Monthly or Yearly.
4. Click Start.
Create a new metadata version manually on central or local instance
1. Open the System Settings app and click Synchronization.
525
Configure metadata Create a new metadata version manually on central or local
synchronizing instance
(Optional) Select Don't sync metadata if DHIS2 versions differ.
3.
4. Select Best effort or Atomic.
5. Click Create new version. The new version is added to the versioning table.
When the system is a central instance, you'll see three columns in the versioning table:
Object Description
Master version The latest version in the system.
Version Name of the version. The name is automatically

generated by system.
When The timestamp of the metadata version creation at

the central instance.
Type Type of metadata version.
526
Configure metadata Create a new metadata version manually on central or local
synchronizing instance
When system is a local instance, you'll see four columns in the versioning table:
Object Description
Master version The latest version of the central instance.
Note
The master version information is the central

instance's latest version. This is important to
look at the difference between the versions of
metadata that exist at central and at local.
Last sync attempt If the last sync attempt is a failure, this will be
displayed.
Version Name of the version. The name is automatically

generated by system.
When The timestamp of the metadata version creation at

the central instance.
Type Type of metadata version.
527
Configure metadata Reference information: metadata synchronization configuration
synchronizing parameters
Object Description
Last sync Timestamp of when the last sync happened for this
version in this system.
Reference information: metadata synchronization configuration parameters
The process which performs metadata synchronization is called Metadata Sync Task. This task
performs a series of steps before syncing of metadata:
• Push data (aggregate data and anonymous events data) from local instance to central
instance.
• Gets the current metadata version of the local instance. Then uses this version information
as a baseline to fetch the list of metadata versions created after the baseline.
• If there are new versions created at central instance, it performs the synchronization of
metadata versions one after the other. A mail will be sent to the configured user (if any)
after each successful synchronization of metadata version at the local instance.
Once the Metadata Sync Task has run at the scheduled time, the task can retry (if any of the
steps fail) based on the configuration of the following parameters defined in dhis.conf file:
Parameter Default value
metadata.sync.retry 3
metadata.sync.retry.time.frequency.mill 30000
isec
Each retry will be made after the time (in millisecond) as specified. If the steps still fail even after
all the retries, then the scheduler stops its execution and then a mail will be sent to the configured
user (if any). If no values are specified then the default values will be used.
metadata.sync.retry = 5
metadata.sync.retry.time.frequency.millisec = 10000
528
Mobile DHIS2 Mobile Introduction
Mobile
This chapter covers various mobile technologies including Web, J2ME, SMS Service and SMS
Command.
DHIS2 Mobile Introduction
DHIS2 provides a range of options to allow data entry from mobile devices, including a dedicated
GPRS/3G J2ME client and two versions of DHIS2 which have been optimized specifically for
mobile browsers. Each of these solutions will be described in detail in the following sections.
DHIS2 offers several Android clients, which are described in detail in other sections of this guide.
Collection of data in the field can be technically challenging and expensive. Mobile phone
solutions have the potential to significantly reduce the complexity of deploying a distributed data
collection system. Using a simple Java client installed on a mobile phone or a web browser which
works on the mobile phone, field workers can report directly to the DHIS2 database through their
mobile device.
While mobile phone solutions have a great potential, there are complexities with such
deployments. Phones lack processing power and have a small display, they need to be charged,
and often such deployments make the most sense in areas with poor or intermittent network
coverage.
Each of the mobile solutions are introduced briefly below, and the discussed in separate sections
in detail:
• DHIS2 Light: A mobile browser optimized data entry module for all devices
This module allows for data entry directly with the browser of the mobile device. A wide
range of devices and mobile browsers are supported including: Opera mini 3 & 4 (basic
and advanced) - Opera mini 4, Nokia S40 mobiles ,Windows Phone 7, Window Mobile 6,
Palm Pre, Blackberry (v5 and v6), Firefox mobile, iOS devices (iPhone) and Android
devices. This client does not have offline-support, and an active GPRS/3G connection is
required. It does not require a new application installation on the phone to support new
features, but does require a stable data connection for use. This solution is described in
• DHIS2 Smartphone client: A mobile browser optimized data entry module for Smartphone
devices
This module allows for data entry directly with the browser of a Smartphone. Offline data
entry is supported and it does not require any installation of a special client on the phone
itself.
• J2ME GPRS/3G client
DHIS-mobile includes two separate J2ME clients supporting GPRS/EDGE/3G as a transport

mechanism. One clients supports facility aggregate reporting and the second client
supports name-based program tracking. These clients are split into separate applications to
make deployment easier. Some health workers may have both applications installed on
their phone. Both of these clients support offline-storage of data and work on J2ME
enabled devices (feature phones). .?>
An active GPRS/3G connection is required in order to send data to the DHIS2 database,
but data can be entered offline and transmitted when a connection is present. This client is
intended primarily for low-end devices which support J2ME applications, although the
offline-supports adds some memory requirements which limits the handset selection. While
529
Mobile Mobile browser based data entry
the solution is primarily tested on Nokia phones, it also works on several other J2ME
capable handsets.
The facility reporting J2ME client is described in the chapter "J2ME GPRS/3G Client"
Getting started with mobile browser data entry
This approach is for data-entry on a smart phone with a mobile browser by navigating to the URL
of the DHIS2 instance, for example: the full URL link for demo on dhis2.org http://apps.dhis2.org/
dev/mobile/index.action . And your mobile browser will automatically detect the DHIS2 application
where the server URL is given (e.g.: http://apps.dhis2.org/dev). Here is the login form to access
the application with user-name and password. Click on "Login" to continue or "Reset" to reset:
After logging in, there are the list of functions:
530
Mobile Getting started with mobile browser data entry
- Aggregate Reporting: Entries for aggregate data with defined/assigned dataset by

organisation-units
- Tracking:
• Find Person: find person based on Name, Phone Number or ID, and Organization unit.
• Activity Plan: Entries data for the persons by organisation-units, persons and programs/
program-stages
• Person Registration: Registry a new person
• Anonymous: Entries for anonymous person based on programs
- Messages: Manage the messages and discussions from the server. Message reply is available.
User can send feedback message in Messages.
- Reports: The output reports from the server.
- Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the Interface
language.
- Logout: to log out the application.
- Desktop version: navigate to the desktop version of DHIS2 for administration. This require a lot
of resources from the client mobile, for example: the sufficient memory to load the pages. Not
recommended for the normal GPRS/3G/... phones.
The list above will be explained in details:
1. Aggregate Reporting: Entries for aggregate data with defined/assigned dataset by

organisation-units.
531
Click on the "Aggregate Reporting", then choose an Organisation Unit from the list and the
list of the datasets will be appeared for entering aggregate data. See the below example:
Step 1: Select an Organisation Unit from the list
Step 2: Select a Dataset (entry form) from the list
532
Step 3: Select a period (based on the period type of the chosen dataset) from the list
Step 4: Entering the data
533
Step 5: Save the data entered after completing the data, choose the option for data
completeness if having.
534
2. Tracking: Find/Add Person, Visit Schedule, Person Registration, Anonymous
535
2.1 Find/Add Person: find person based on Name, Phone Number or ID, and Organization
unit.
◦ Step 1: insert Name, Phone Number or ID and select the Organization Unit, then
click Search.
◦ Step 2: select a person
536
Then all the information of that person will be displayed
◦ Step 3: choose the next program stage for entering the data
To view all the program stages, click on the name of that program (Child Heath
Program as the screen shot)
537
2.2: *Visit Schedule:*Choose An Organization Unit
538
◦ Current Activity Plan: the list of the beneficiaries registered, enrolled, not yet finish/
complete a/many program and there is at least a program-stage open for data-entry.
+ Step 1: Choose a Person for entry
+ Step 2: Choose a current and active program-stage for entering the data
539
You can also see the person's information (ID, gender, Date of Birth, and Blood
Group) by clicking on the Details (on top of the list appeared)
The details information of the chosen person:
540
◦ All Activity Plan: the list of all beneficiaries registered, enrolled, not yet finish/
complete a/many program.
◦ Single Event:
2.3: Person Registration: Registry a new Person
◦ Step 1: Entry personal information
541
◦ Step 2: Enrol program for the person just been registered, then click "Enroll".
542
◦ Step 3: Entry required information for the chosen program, then click "Enroll"
Here is the result:
543
2.4: Anonymous: Entries for anonymous person based on specific programs
3. Messages: Manage the messages and discussions from the server. Message reply is
available.
544
The number showed is the unread messages. Click on that to view the list of the messages
(the unread messages are in bold and dark blue color):
545
Then you can pick up the message/topic for the discussions by leaving the reply message,
see this example:
546
User can create and send a feedback to server in messages section. After sending out the
new feedback, the message (feedback) will be listed under "Messages" for further following
up.
4. Reports: The output reports from the server
547
(will be updated)
5. Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the
Interface language.
548
Here is the form for setting the user account/access and the interface language. Click on
"SAVE" for completing the settings, see the example below:
6. Logout: to log out the application
549
7. Desktop version: navigate to the desktop version of DHIS2 for administration.
Here is the GUI of the desktop version (which require much memory for loading), not
recommended for normal mobile. The example with DHIS2 Demo (from dhis2.org)
550
1.
After clicking on the "Namebased Data Entry", the next will guiding to the selections in the
following steps:
Step 1: Choose an Organisation Unit
551
Step 2: Choose the Activity Type
(the screen-shot with an example with "Current Activity Plan" option)
There will be normally these two type of Activity:
+ "Current Activity Plan": the list of the beneficiaries registered, enrolled, not yet finish/
complete a/many program and there is at least a program-stage open for data-entry.
+ "All Activity Plan": the list of all beneficiaries registered, enrolled, not yet finish/complete a/
many program.
Step 3: Choose a Beneficiary for entry
552
(the screen-shot with an example with "Hybia Welde" option)
Step 4: Choose a current and active program-stage for entering the data
(the screen-shot with an example with "16-24 months after birth" option)
You can also see the beneficiary's information (ID, gender, Date of Birth, and Blood Group)
by clicking on the Details (on top of the list appeared)
553
The details information of the chosen beneficiary:
2. Beneficiary Registration: Registry a new beneficiary
554
Step 1: Choose an OrganisationUnit
Step 2: Fill in the Beneficiary Registration form
555
There necessary information: Full Name, Gender, Date of Birth (and Blood Group).
Click on "SAVE" to register a new beneficiary.
A message "Successfully Saved" will appear when the beneficiary is created/registered

successfully.
556
3. Beneficiary Enrollment: Enrol a beneficiary to one or many programs
557
Before enrolling a beneficiary to a program, the search function for a beneficiary is

provided:
If the beneficiary is found, the result will be listed. The simply click on the beneficiary name
for navigating to the programs in which the beneficiary enrolled:
The below screen-shot example describes the beneficiary named "Nguyen Van A":
- Has not enrolled any programs before
- There is one program: "Child Health Program" available for enrolment
The list of the available programs for enrolment will be listed. Just click on the program for
enrolment by specifying the date of enrolment and the date of incident. See the example:
After clicking on the "ENROLL" button, if successful, the program enrolled will be listed
under "Enrolled Programs for" + \<Name of the beneficiary>, see the example:
4. Messages: Manage the messages and discussions from the server. Message reply is
available.
558
The number showed is the unread messages. Click on that to view the list of the messages
(the unread messages are in bold and dark blue color):
559
Then you can pick up the message/topic for the discussions by leaving the reply message,
see this example:
5. Reports: The output reports from the server
560
(will be updated)
6. Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the
Interface language.
561
Here is the form for setting the user account/access and the interface language. Click on
"SAVE" for completing the settings, see the example below:
7. Feedback: the extra function for creating a new message to send to the server. The new
created feedback from this will be listed under "Messages"
562
After clicking on the "Feedback", there will be a form for editing/sending out a new
message/discussion. See the example below:
After sending out the new feedback, the message (feedback) will be listed under
"Messages" for further following up.
563
8. Logout: to log out the application
9. Desktop version: navigate to the desktop version of DHIS2 for administration.
564
Mobile J2ME GPRS/3G Client
Here is the GUI of the desktop version (which require much memory for loading), not
recommended for normal mobile. The example with DHIS2 Demo (from dhis2.org)
J2ME GPRS/3G Client
The DHIS2 GPRS/3G mobile module provides a mechanism for remote clients using mobile
phones to enter data directly into the DHIS2 system. There are two functions of the client, namely:
The solution relies on the mobile phone having a data connection available (i.e. GPRS, Edge,
3G), over which it communicates with a DHIS2 instance which must be publicly available on the
internet, as any other web server. The client application on the phone downloads the data entry
forms to the phone from the server, and the forms can therefore be updated without installing a
565
Mobile Data connection availability
new application. This is also a crucial feature for community reporting, which relies on regularly
downloading activity plans from the server.
• Facility reporting, for data entry and reporting of regular DHIS2 aggregate data,
• Activity reporting, for supporting individual activity reporting with the Community module.
Data connection availability
Data connection availability can be a problem in many of the contexts where DHIS2 mobile
reporting would otherwise be a good solution for getting data directly into DHIS2. If that is the
case for you, you might want to consider trying the SMS based solution described in a separate
document. Keep in mind that even though a data connection is currently required for
communication between the server and the mobile phone, it is only required when initializing or
updating the mobile application and when sending reports to the server. The phone stores all
entered data locally, so it can work fine with only temporary access to a data connection on a
regular basis.
J2ME GPRS 3G facility reporting client
The server side component of the web based solution is included in the general build of DHIS2.
In order to configure the DHIS2 web-based mobile reporting, you should follow the following
steps.
• Set the "Available for Mobile Reporting" flag for the data sets you want reported: Under
Maintenance->DataSet->Edit mark the “Available for Mobile Reporting” check box and
save.
• Create a user role for the mobile user. Select Maintenance->Users->User Role->Add new.
Add a user role name and description. Add the desired data sets for the role. The mobile
user role will need to have at least privileges for DHIS2 Web API. Save the user role by
clicking "Save".
• Create a user which will be used by the client to login from Maintenance->Users->User -
>Add new. Fill in all of the required details, keeping in mind that the password must be at
least 8 digits long, contain one capital letter,and one digit. Assign the desired user role to
the user which was created in the previous step.
Important
Assign the user to exactly one organisation unit. Each mobile reporting client
will need their own user name and password.
Detailed configuration of data sets and reporting forms
Though the previous steps is all that should be needed for testing the solution more detail
configuration of the datasets may be required and are described in the following sections.
The mapping of data sets to form layout on the phone
By default, a data set is mapped to a single form on the phone. If the data set is divided into
sections, each section is displayed as a separate page on the phone. If a data element has more
than one category option combo it will be displayed as a heading with the category combination
options following.
Form design element DHIS2 Metadata Metadata element
566
Mobile Detailed configuration of data sets and reporting forms
Form title Data set Short Name if it exists, otherwise

Name
Page tile Section Section name (or form name if no

sections)
Question Data element Alternative name if it exists,

otherwise Name
Question name if combos Category option combo name
Sorting of forms
By default, data elements will be sorted according to the global sorting assigned in DHIS2. If
sections are used, their section specific sorting order will be used. In some cases, when sections
are not used, a data element might be used in multiple data sets, and conflict in the way it should
be sorted in individual data sets. A work around for this situation is to wrap the whole dataset in
one section (note that this will only work if the data elements have the same category option
combo)
Versioning of data sets
To make it possible to compare and update the data sets on the mobile phone with the version on
the server, data sets are automatically versioned when you edit the data set structure. Some
changes which occur on the DHIS2 server, will cause the mobile client to update its forms with a
new version.
• Create DataSet
• Edit DataSet
• Create/edit/delete Section in DataSet
• Sort Section Order
• Update DataElement (affect many related DataSets)
• Delete DataElement (affect many related DataSets)
• Edit DataElement Category
• Edit DataElement Category Combo
Language support
Multi-language support is available.
DataSet and DataElement are translated through web-based function. Default language on
server is used on mobile in cases requested language from mobile is not available.
567
Mobile Mobile application setup
Mobile application setup
Installation and initialization
Installation
Download the jar packages from the DHIS2 homepage: www.dhis2.org/downloads
Initialization
Initialization should be performed before the phones are delivered end-users. Given the large
variation in possible phone configurations, it is impossible to describe the exact steps which are
required in order to enable the client on the phone. However, for most phones, simply copying the
DHIS2 Web Mobile client "JAR" file to the phone with a USB cable or via Bluetooth is sufficient. Of
course, GPRS/3G connectivity must be enabled. Contact your mobile service provider for exact
details on the configuration of the phones and networks.
Once the client has been installed on the phone, an initialization process must occur by providing
a user name, password and server URL.
1. Logging into the server for the first time.
The first time the client logins to the server, or if the client is reinitialized, the username,
password and server URL must be entered.
If the client is unable to login, there could be several possible error messages which you
see.
◦ Connection Not Found: The specified server URL is not correct. Check the server
address, ensure that the server is actually reachable, and try again.
◦ Invalid User Name Or Password: the username or password is incorrect
568
Application not authorized to access restricted APIs : The server can be contacted,
◦ but the user does not have the necessary permissions to access the mobile reporting
module
2. Setting the PIN number: After the initial login process, a PIN number can be entered by the
user. This will make the login process much easier, as the user only has to remember the
four digit pin number, as opposed to typing in the user name and password each time. The
PIN number can be preset if the phone is initialized prior to delivery, or it can be set by the
users themselves if they have been provided with usernames and passwords.
After entering the PIN, press (Menu)->Next.
3. Download all forms: After the PIN has been specified, all forms will be downloaded from the
server and stored locally on the phone..
If the user has been configured to report on aggregate datasets, a list of appropriate
datasets will be displayed. If the user is responsible for community based reporting, the list
of assigned activities is displayed.
Notes: If the Health Worker is responsible for both Facility Reporting and Community
Reporting, DHIS2 server will send all forms of both Facility Reporting and Community
Reporting to mobile and on mobile, there will be a screen to choose whether displaying
Facility Reporting or Community Reporting.
Errors:
Logging in (for regular use)
After starting the application, the PIN form is displayed.
• PIN: Enter the four digit number PIN.
• Reinitialize Command: this function will clear all data on mobile and we start from the login
screen with username and password.
• Errors: Invalid PIN: If the user has entered an invalid PIN, they will need to enter the
correct PIN, or reinitialize the application with the correct username and password.
Facility Reporting Module
Entering data
After selecting an aggregate dataset from the "Select report form" window, the user will need to
select an appropriate time period. A list of available time periods is automatically generated.
1. After the user has entered their PIN, they can select from a list of available datasets. Select
the appropriate dataset and press "Next".
569
2. Choosing periods: A list of available periods will be automatically displayed to the user.
They can select the appropriate period from the list.
3. Fill in values: After choosing the period, the form can be displayed in two modes, depending
on the
◦ Form with sections
Each form section is displayed in a single screen with the name of the section in the
title window.
To navigate from screen to screen, push "Next".
◦ Forms without section (Datasets without sections)
570
All fields are displayed on one screen with the title that is the name of DataSet
The user simply fills in each data element with the appropriate value.
4. Save and Complete:
After finishing data entry, the user can choose to save the data locally on the phone or to
upload the data directly to the DHIS2 server.
If the user saves the data form, they can edit the form at a later point in time if they need to.
When selecting a period once again, the period will be marked as "Saved' as seen in the
next screen shot.
571
If the user selects "Complete", and the data entry form is not complete, the user will be
asked if they are certain they wish to submit the form as incomplete. Once the form has
been submitted, a message should be displayed informing the user that the transmission
was successful.
Notes
1. Period list:
Periods marked with an asterisk (*) is the period that is completed or saved, depending on
the status of the data entry.
All periods that are not in period list are considered old and will be deleted automatically.
2. Storing values duration
The number of saved forms on mobile are limited only by the effective amount of storage of
the mobile device.
572
Forms are saved for limited period only, depending on the frequency of collection of the
particular dataset.
◦ Daily Forms: 2 months (current and previous month)
◦ Weekly Forms: 4 weeks (current and 3 previous week)
◦ Monthly Forms: 2 months (current and previous month)
◦ Quarterly Forms: 2 quarters (current and previous quarter)
◦ Yearly Forms: 2 years (current and previous year)
3. Completed forms - Uneditable forms
If the form has been completed, the user can view the form on their phone, but they cannot
make any subsequent edits to the form. Each field is greyed out and inactive for editing.
4. Re-Edit completed forms
If the user wishes to edit data which has already been submitted to the server, they can do
so by pressing the "Edit" button. They are allowed to do this assuming that the dataset has
not been locked for the period in question. If they attempt to upload the data, the user will
be informed that the dataset has been locked, and it is not possible to upload the data.
5. Update Forms:
This function is used to synchronize the forms on mobile and on server. The process is
automatically triggered after entering PIN number.
Note: Checking and downloading updated forms process run in background. After finished,
prompt is displayed to ask user whether refresh form list or stay where they are.
6. Multi-Language Support:
This function help user to choose language of mobile's GUI (graphical user interface) and
content's language (Forms).
The forms must be translated on server, otherwise, default language is used.
Default language of first login is English. Change language in Setting menu will affect both
interface and content.
573
Multi-Language Interface: In Setting menu, there are list of supported language

(downloaded from server). Language of GUI is only changed after restart application.
574
Mobile SMS Command
Multi-Language Content (forms): Form's language is change after click "Save". In case
there are many forms, it take several minutes to save setting.
Troubleshooting
• Data has been entered on the phone but does not appear on the server
This usually occurs when users enter data on the phone, but cannot send it to the server.
This may be because of the configuration of the phone, lack of credit on the phone, or lack
of coverage. Usually an error message is displayed as shown below.
Users should be informed that if they see this error, then it means that their data has not
been transmitted.
SMS Command
SMS command feature helps DHIS2 system receiving SMS from users, patients, or even
anonymous. A SMS command is an object containing the configurations for each SMS form:
reporting data from phones or j2me apps, alerting users, registering patient or user, etc.
Set up SMS command
This is where you can create a new SMS command
575
Mobile Set up SMS command
Usually each SMS command has it own property, then the setting up process may be different
from each other. Currently, we have 4 types of SMS command:
576
Mobile Set up SMS command
With KEY_VALUE_PARSER and J2ME_PARSER, the SMS command will have dataset because
those are used for reporting data. If data is reported for a Period which is already approved then
SMS response will be sent back containing information about approval status of the period.
With ALERT_PARSER and UNREGISTERED_PARSER, the SMS command will have user group
because those are used for sending message such as SMS, DHIS2 conversation, email.
There are certain parameters which are common to all SMS Command types. These parameters
have default values configured in the system, if user does provide any value to these parameters
then those default ones will be used. Here is the list of those parameters
Common Parameters
Paramet
Type Description
er
Code String To provide custom code value separator. Default is "="

Value
Separator
Field String To provide custom field separator. Default is "|"

Separator
Reply String To provide message if no code is found in SMS text input. Default is
message "Parameter missing"
if no
codes are
sent (only
the
comman
d)
577
Mobile SMS Command Type
Paramet
Type Description
er
Wrong String To provide message if command is not formatted correctly. Command should
format be formatted as per code value separator. This message will also be sent back
message if any mandatory parameter is missing.
No user String To provide message if sending phone number is not registered in DHIS2.
message
User String Certain SMS command types require user ( retrieved from sending phone
belong to number ) to be associated with only one organization unit. This message can
more than be configured to be sent back in case that requirement is not fullfilled.
one
OrgUnit
message
Success String To provide message that will be sent upon successful completion of the
Message process.
SMS Command Type
The SMS command is basically defined by its parser type. In other word, each SMS command has
one unique parser to parse the plain text SMS, then the result will be used for the purpose of that
SMS command.
SMS Command for Reporting Data
In order to report data for example data set (aggregation), we use SMS commands which have
KEY_VALUE_PARSER (for phone's plain text), or J2ME_PARSER (for j2me apps)
If the command has name "report", and a list of data element with code like above. The format
should be: [command's name] [code][value] [code][value] [code][value]....,the [value] of course
might be changed depends on real data, so you have to prepare an SMS text like this example:
report vo2 vn5 a2 b6 z3 x1
In case the command has a separator for instance ".", the SMS text should be:
report vo.2.vn.5.a.2.b.6.z.3.x.1
578
or report vo.2|vn.5|a.2|b.6|z.3|x.1
Moreover in SMS text input, orgUnit can be specified like this org orgUnitCode If no orgUnit is
specified in SMS then user is retrieved first from the sending phoneNumber and then orgUnit from
that user. As far as PeriodType is concerned it should be specified in this format "ddMM" for
example 3108, but in case its not specified then PeriodType will be retrieved from DataSet
attached to SMSCommand
With the J2ME_PARSER, you don't need to prepare those SMS text, because the J2ME will do
this job
User can set the custom response message for "Wrong format message", "No User Message",
"User belong to more than one OrgUnit message" and "Success message". If no custom message
is being set, system will use the default message.
SMS Command for Entity Enrollment
TRACKED_ENTITY_REGISTRATION_PARSER can be used to enrol tracked entity into the

system.
579
Command name will be followed by tracked entity attributes pertaining to specific program which
this command is associated with. Program selection will be done while creating this command.
Default text pattern ( if field separator and codevalue separator is not provided ) for this parser
would look like this. childProgram fn=xmen|ln=xmen2|age=4
In case field separator is for example "," then text would look like this.childProgram
fn=xmen,ln=xmen2,age=4
Rest of the behavior is same as for other commands. If user does not provide those parameters
then default ones will be used.
SMS Command for Program Stage Data Entry
PROGRAM_STAGE_DATAENTRY_PARSER can be used to enter program stage related data for

a specific tracked entity instance.
580
Command name will be followed by data elements pertaining to specific program stage which this
command is associated with. Program and program stage selection will be done while creating
this command.
Default text pattern ( if field separator and codevalue separator is not provided ) for this parser
would look like this. programstage bcgd=1|opvd=2|wght=34
In case field separator is for example "," then text would look like this.programstage
bcgd=1,opvd=2,wght=34
Rest of the behavior is same as for other commands. If user does not provide those parameters
then default ones will be used.
SMS Command for Alerting, Registering
In order to alert users, we use SMS commands which have ALERT_PARSER (for phone's plain
text), or UNREGISTERED_PARSER (for j2me apps). UNREGISTERED_PARSER can also be
used for registering IDSR rumour.
581
Mobile SMS Service
The format of those command will be: [command's name] [text], for example:
alert one emergency case in A town
Commands which has ALERT_PARSER will be received from users only
SMS Command for Event Registration
Event Registration can be used to register anonymous event into the system based on the data
collected through SMS. This command type is associated with Programs of type
WITHOUT_REGISTRATION. For example Birth events can be tracked using this parser.
The format of those command will be: [command's name] [code][separator][value], for example:
birth A=1,B=2,G=Male
Code/Value separator is configurable. Pipe "|" is by default taken as field separator. Commands
which has EVENT_REGISTRATION_PARSER will be received from DHIS2 users only. Once
command is successfully received then data received in SMS will be parsed and event will be
registered in DHIS2.
SMS Service
SMS Service is a generic service used for sending/receiving SMS. Any other DHIS2 module can
include this service and utilize it to send and receive SMS from users or workers in the field.
582
Mobile Setting up SMS service
Setting up SMS service
There are few pre-requisites in order to make this service functional. There are two ways to
complete these steps. One way is to configure gateway from the GUI in Mobile Configuration
Module. The other way is to use SMS Web Api.
• Configure SMS Gateway
Configure SMS Gateway
There are five different types of Gateways supported by SMS Service. SMS can be sent if any
one of the gateway is configured. If more than one gateways are present, then they will be used
in round-robin fashion for load balancing. There are different parameters for different type of
gateway. The Gateway can be configured in GUI in Mobile Configuration Module as shown in the
figure. More information about parameters needed to configure gateway can be found in Gateway
Configurations
Configure GenericHttp Gateway
Many DHIS2 instances are using GenericHttpGateway to connect to their local gateways. These
local gateways provides HTTP APIs for sending SMS. In new GenericHttpGateway it is now
possible to configure url parameters provided in their APIs. For example http://gateway.com/
sendMessage?username=AA&password=xxxxx&message=testing&msisdn=9999. In this url
username, password, message, msisdn are parameters that are required by external gateways.
Now in GenericHttp these parameters are configurable which was not possible in previous
releases. Making is configurable will help DHIS2 to interact with other gateways which have
different url formats.
583
Mobile Gateway Configurations
Gateway Configurations
Below table shows the parameters required for configuring gateway.
Gateway Configuration Parameters
BulkSMS Clickatell Generic HTTP

Parameter SMPP Gateway Description
Gateway Gateway Gateway
Gateway Name Optional Optional Optional Optional Used as gatew
User Name Required Optional (if token Required Required Used for API a
is used)
Password Required Optional (if token Required Required Used for API a
is used)
Auth-Token N/A Optional (if N/A N/A Used for API a

password is
used)
MessageParame N/A N/A Required N/A Message quer

ter message=Hi
RecipientParam N/A N/A Required N/A Recipient quer

eter phoneNumber
URL Template N/A N/A Required Required Url Tempalte is
Headers N/A N/A Optional N/A Header option
useGet N/A N/A Optional N/A HTTP POST m
systemType N/A N/A N/A Required SystemType p
typeOfNumber N/A N/A N/A Required TypeOfNumbe
numberPlanIndic N/A N/A N/A Required NumberPlanIn

ator
bindType N/A N/A N/A Required BindType para
compressed N/A N/A N/A Optional Compressed p
584
About data dimensions Data dimensions: Core building blocks in DHIS2
About data dimensions

Data dimensions: Core building blocks in DHIS2
A data value in DHIS2 is described by at least three dimensions: 1) data element, 2) organisation
unit, and 3) period. These dimensions form the core building blocks of the data model.
As an example, if you want to know how many children that were immunised for measles in
Gerehun CHC in December 2014, the three dimensions which describe that value are the data
element "Measles doses given", the organisation unit "Gerehun CHC", and the period "December
2014". All data values have at least these three dimensions describing what, where, and when.
In addition to the data element, organisation unit, and period dimensions, data values may also
be associated with additional data dimensions. A common use of this feature is to describe data
values which are reported by multiple partners in the same location for the same data element
and time period. In principle, it can be used as a "free-form" dimension, to describe multiple
observations of the same phenomena at the same place and time. For more information about
this, see Chapter 34: Additional data dimensions.
Organisation Unit Data Element Period Value
Gerehun CHC Measles doses given Dec-09 22
Tugbebu CHP Measles doses given Dec-09 18
Data elements: the what dimension
Data element categories
The data element mentioned above ,"Measles doses given", can be further disaggregated into by
combinations of data element categories. Each system administrator of DHIS2 is free to define
any data element category dimensions for data elements. There are however, certain best
practices which should generally be followed.
Given the example of Measles vaccination, if you want to know whether these vaccines were
given at the facility (fixed) or out in the community as part of the outreach services then you could
add a dimension called e.g. "Place of service" with the two possible options "Fixed" and
"Outreach". Then all data collected on measles immunisation would have to be disaggregated
along these to options. In addition to this you might be interested in knowing how many of these
children who were under 1 year or above 1 year of age. If so you can add an Age dimension to
the data element with the two possible options "\<1 y" and ">1 y". This implies further detail on the
data collection process. You can also apply both categories "Place of service" and "Age" and
combine these into a data element category combination e.g. called "EPI disaggregation". You
would then be able to look at four different more detailed values in stead of only one as in the
example above for the data element "Measles doses given": 1) "Fixed and \<1 y, 2) Fixed and >1
y, 3) Outreach and \<1 y, and 4) Outreach and >1 y. This adds complexity to how data is collected
585
About data dimensions Data element group sets
by the health facilities, but at the same time opens up for new possibilities of detailed data
analysis of Measles immunisation.
Example of detailed storage of data values when using data element categories "Place of Service" and
"Age" (simplified for readability compared to the actual database table)
Organisation Place of
Data Element Age Period Value
Unit service
Gerehun Measles Fixed <1 y Dec-09 12

CHC doses given
Gerehun Measles Outreach <1 y Dec-09 4

CHC doses given
Gerehun Measles Fixed >1 y Dec-09 4

CHC doses given
Gerehun Measles Outreach >1 y Dec-09 2

CHC doses given
Tugbebu Measles Fixed <1 y Dec-09 10

CHP doses given
Tugbebu Measles Outreach <1 y Dec-09 4

CHP doses given
Tugbebu Measles Fixed >1 y Dec-09 3

CHP doses given
Tugbebu Measles Outreach >1 y Dec-09 1

CHP doses given
Data element group sets
While the data element categories and their options described above provide the level of detail
(disaggregation) at the point of data collection and how data values get stored in the database,
the data element group sets and groups can be used to add more information to data elements
after data collection. As an example, if you are analysing many data elements at the same time in
a report, you would want to group these based on some criteria. Instead of looking at all the data
captured in a form for immunisation and nutrition, you might want to separate or group data
elements along a programme dimension (known as a data element group set in DHIS2) where
"Immunisation" (or EPI) and "Nutrition" would be the two groups.
Expanding the report to include data from other programs or larger themes of health data would
mean more groups to such a group set dimension, like "Malaria", "Reproductive Health", "Stocks".
For this example, you would create a data element group set called "Programme" (or whatever
name you find appropriate), and to represent the different programmes in this dimension you
would define data elements groups called "EPI", "Nutrition", "Malaria", "Reproductive health" and
so on, and add all these groups to the "Programme" group set. To link or tag the data element
"Measles doses given" to such a dimension you must (in our example) add it to the "EPI" group.
Which groups you add "Measles doses given" to does not affect how health facilities collect the
data, but adds more possibilities to your data analysis. So for the group set dimensions there are
three levels; the group set (e.g. "Programme"), the group (e.g. "EPI"), and the data element (e.g.
"Measles doses given").
Indicators can be grouped into indicator groups and further into indicator group sets (dimensions)
in exactly the same way as data elements.
586
About data dimensions Organisation units: the where dimension
Organisation
Data Element Programme Period Value
Unit
Gerehun CHC Measles doses EPI Dec-09 22

given
Gerehun CHC Vitamin A given Nutrition Dec-09 16
Tugbebu CHP Measles doses EPI Dec-09 18

given
Tugbebu CHP Vitamin A given Nutrition Dec-09 12
Gerehun CHC Malaria new Malaria Dec-09 32

cases
Tugbebu CHP Malaria new Malaria Dec-09 23

cases
Organisation units: the where dimension
Organisation units in DHIS2 should typically represent a location, such as a Community Health
Centre or referral hospitals, or an administrative unit like "MoHS Sierra Leone", "Bo District" or
"Baoma Chiefdom". In non-health sector applications, they could be "schools" or "water points".
Orgunits are represented in a default hierarchy, usually the default administrative hierarchy of a
country or region, and are therefore assigned an organisational level. As an example, Sierra
Leone has four organisation unit levels; National, District, Chiefdom, and PHU, and all orgunits
are linked to one of these levels. An orgunit hierarchy in DHIS2 can have any number of levels.
Normally data is collected at the lowest level, at the health facility, but can be collected at any
level within the hierarchy, such as both the districts as well as the facility level.
When designing reports at higher levels with data aggregated at the district or province level,
DHIS2 will use the hierarchy structure to aggregate all the health facilities' data for any given unit
at any level. The organisation unit level capturing the data always represents the lowest level of
detail that is possible to use in data analysis, and the organisational levels define the available
levels of aggregation along a geographical dimension.
Organisation unit group sets and groups
While facility level is typically the lowest geographical level for disaggregation in DHIS2, there are
ways to flexibly group organisation units into any number of dimensions by using the organisation
unit groups and group set functionality. As an example, if all facilities are given an official type like
"Community health center" or "District Hospital, it is possible to create an organisation unit group
set called "Type" and add groups with the names of the types mentioned above. In order for the
group sets to function properly in analysis, each organisation unit should be a member of a single
group (compulsory and exclusive) within a group set. Stated somewhat differently, a facility should
not be both a "Community health center" as well as a "District hospital".
Inherit the values of an organisation unit group set
You can improve the completeness of your aggregated data by inheriting the settings of a
"parent" organisation unit in your organisation unit hierarchy. This is particularly helpful if you are
aggregating the data of more than 100 organisation units. See the Maintenance app
documentation for more details.
Alternative organisation unit hierarchies - advanced use of group sets and groups
A more advanced use of organisation unit group sets is to create alternative hierarchies e.g. use
administrative borders from other ministries. In Sierra Leone that could mean an alternative
587
About data dimensions Best practice on the use of group sets and groups
hierarchy of 1:MoHS, 2:Districts, and 3: Local councils, instead of the four-level hierarchy with
chiefdoms and PHUs. For instance, if all PHUs are linked to a specific local council, it would be
possible to look at data aggregated by local council instead of chiefdom. Then you would first
need to create a group set called "Local council" and then create one organisation unit group for
every local council, and finally link all PHUs to their corresponding local council group.
District OrgUnit Type Data Element Period Value
Bo CHC Measles doses Dec-09 121

given
Bo CHP Measles doses Dec-09 98

given
Bo MCHP Measles doses Dec-09 87

given
Bombali CHC Measles doses Dec-09 110

given
Bombali CHP Measles doses Dec-09 67

given
Bombali MCHP Measles doses Dec-09 59

given
Best practice on the use of group sets and groups
As mentioned above, all organisation units should be a member of a single group within a group
set. If an organisation unit is not present in any group or is present in multiple group members in
a group set, this can lead to unexpected results in the analysis modules. DHIS2 has integrity
checks to identify organisation units which are not present in any organisation unit group set
member, or which is present in multiple groups.
Period: the when dimension
The period dimension becomes an important factor when analysing data over time e.g. when
looking at cumulative data, when creating quarterly or annual aggregated reports, or when doing
analysis that combines data with different characteristics like monthly routine data, annual
census/population data or six-monthly staff data.
Period types
In DHIS2, periods are organised according to a set of fixed period types described below. The
following list is for the default ISO 8601 calendar type.
1. Daily
2. Weekly: The system supports various weekly period types, with Monday, Wednesday,
Thursday, Saturday and Sunday as the first day of the week. You collect data through data
sets configured to use the desired weekly period type. The analytics engine will attribute
weekly data to the month which contains four days or more of the week.
3. Bi-weekly: Two week periods beginning with the first week of the year.
4. Monthly: Refers to standard calendar months.
5. BiMonthly: Two-month periods beginning in January.
6. Quarterly: Standard ISO quarters, beginning in January.
588
About data dimensions Relative periods
SixMonthly: Six-month periods beginning in January

7.
8. Yearly: This refers to a calendar year.
9. Financial April: Financial year period beginning on April 1 st and ending on March 31 st of the
calendar next year
10. Financial July: Financial year period beginning on July 1 st and ending on June 31 st of the
calendar next year
11. Financial Oct: Financial year period beginning on October 1 st and ending on September
31 st of the calendar next year
12. Six-monthly April: Six-month periods beginning on April 1 st with a duration of six calendar
months.
As a general rule, all organisation units should collect the same data using the same frequency or
periodicity. A data entry form therefore is associated with a single period type to make sure data is
always collected according to the correct and same periodicity across the country.
It is possible however to collect the same data elements using different period types by assigning
the same data elements to multiple data sets with different period types, however then it becomes
crucial to make sure no organisation unit is collecting data using both data sets/period types as
that would create overlap and duplication of data values. If configured correctly the aggregation
service in DHIS2 will aggregate the data together, e.g. the monthly data from one part of the
country with quarterly data from another part of the country into a national quarterly report. For
simplicity and to avoid data duplication it is advised to use the same period type for all
organisation units for the same data elements when possible.
Relative periods
In addition to the fixed period types described in the previous section, DHIS2 also support relative
periods for use in the analysis modules.
When creating analytical resources within DHIS2 it is possible to make use of the relative periods
functionality. The simplest scenario is when you want to design a monthly report that can be
reused every month without having to make changes to the report template to accommodate for
the changes in period. The relative period called "Last month" allows for this, and the user can at
the time of report generation through a report parameter select the month to use in the report.
A slightly more advanced use case is when you want to make a monthly summary report for
immunisation and want to look at the data from the current (reporting) month together with a
cumulative value for the year so far. The relative period called "This year" provides such a
cumulative value relative to the reporting month selecting when running the report. Other relative
periods are the last 3,6, or 12 months periods which are cumulative values calculated back from
the selected reporting month. If you want to create a report with data aggregated by quarters (the
ones that have passed so far in the year) you can select "Last four quarters". Other relative
periods are described under the reporting table section of the manual.
Organisation Reporting month

Data Element Reporting month So far this year
Unit name
Gerehun CHC Measles doses 15 167 Oct-09

given
Tugbebu CHP Measles doses 17 155 Oct-09

given
589
About data dimensions Aggregation of periods
Aggregation of periods
While data needs to be collected on a given frequency to standardise data collection and
management, this does not put limitations on the period types that can be used in data analysis
and reports. Just like data gets aggregated up the organisational hierarchy, data is also
aggregated according to a period hierarchy, so you can create quarterly and annual reports
based on data that is being collected on a Monthly basis. The defined period type for a data entry
form (data set) defines the lowest level of period detail possible in a report.
Sum and average aggregation along the period dimension
When aggregating data on the period dimension there are two options for how the calculation is
done, namely sum or average. This option is specified on a per data element in DHIS2 through
the use of the 'aggregation operator' attribute in the Add/Edit Data Elements dialog.
Most of the data collected on a routinely basis should be aggregated by summing up the months
or weeks, for instance to create a quarterly report on Measles immunisation one would sum up
the three monthly values for "Measles doses given".
Other types of data that are more permanently valid over time like "Number of staff in the PHU" or
an annual population estimate of "Population under 1 year" need to be aggregated differently.
These values are static for all months as long as there are valid data. For example, the "Estimated
population under 1", calculated from the census data ,is the same for all months of a given year,
or the number of nurses working in a given facility is the same for every month in the 6 months
period the number is reported for.
This difference becomes important when calculating an annual value for the indicator morbidity
service burden for a facility. The monthly head-counts are summed up for the 12 months to get
the annual headcount, while the number of staff for the PHU is calculated as the average of the
two 6-monthly values reported through the 6-monthly staff report. So in this example the data
element "OPD headcount" would have the aggregation operator "SUM" and the data element
"Number of staff" would have it set to "AVERAGE".
Another important feature of average data elements is the validity period concept. Average data
values are standing values for any period type within the borders of the period they are
registered for. For example, an annual population estimate following the calendar year, will have
the same value for any period that falls within that year no matter what the period type. If the
population under 1 for a given facility is 250 for the year of 2015 that means that the value will be
250 for Jan-15, for Q3-15, for Week 12 of 2015 and for any period within 2015. This has
implications for how coverage indicators are calculated, as the full annual population will be used
as denominator value even when doing monthly reports. If you want to look at an estimated
annual coverage value for a given month, then you will have the option of setting the indicator to
"Annualised" which means that a monthly coverage value will be multiplied by a factor of 12, a
quarterly value by 4, in order to generate an effective yearly total. The annualised indicator
feature can therefore be used to mimic the use of monthly population estimates.
Data collection vs. data analysis
Data collection and storage
Datasets determine what raw data that is available in the system, as they describe how data is
collected in terms of periodicity as well as spatial extent. Data sets define the building blocks of
the data to be captured and stored in DHIS2. For each data dimension we decide what level of
detail the data should be collected at namely 1) the data element (e.g. diagnosis, vaccine, or any
event taking place) and its categories (e.g. age and gender), 2) the period/frequency dimension,
and 3) the organisation unit dimension. For any report or data analysis you can never retrieve
more detailed data than what is defined in the data sets, so the design of the datasets and their
590
About data dimensions Input does not equal Output
corresponding data entry forms (the data collection tools) dictate what kind of data analysis will
be possible.
Input does not equal Output
It is important to understand that the data entry forms or datasets themselves are not intrinsically
linked to the underlying data value and that the meaning of data is only described by the data
element (and its categories). This makes it perfectly safe to modify datasets and forms without
altering the data (as long as the data elements stay the same). This loose coupling between
forms and data makes DHIS2 flexible when it comes to designing and changing new forms and in
providing exactly the form the users want.
Another benefit of only linking data to data elements and not to forms, is the flexibility of creating
indicators and validation rules based on data elements, and also in providing any kind of output
report (in pivot tables, charts, maps etc.) that can combine data individually or across forms, e.g.
to correlate data from different health programs. Due to this flexibility of enabling integration of
data from various programs (forms) and sources (routine and semi permanent (population, staff,
equipment)) a DHIS2 database is used as an integrated data repository for many or all parts of
the aggregated data in a larger HIS. The figure below illustrates this flexibility.
In this example, we see that data elements from multiple forms can be combined to create a given
indicator. As a more concrete example, one might collect "Population under one year of age" in an
annual data set by district, and then collect a data element like "Fully immunized children" by
month at the facility level. By annualizing the population, we can generate an approximation of the
effective monthly population, and combining this with the aggregate total of the number of fully
immunized children by month, it would be possible to generate an indicator "Fully immunized
coverage", consisting of the aggregated total of children who are fully immunized, divided by the
effective monthly population.
591
About data dimensions Extended examples of data elements and forms
Extended examples of data elements and forms
The table below combines data element the two group sets Diagnosis (all the diseases) and
Morbidity/Mortality (New cases, Follow-ups, Referrals, Deaths) with the data element category
PHU/Community. Deaths are captured in a separate form with other dimensions (e.g. the PHU/
Community) than morbidity.
This output table combines the two data element categories HIV_Age and Gender with the data
element group set ART Group. The group enables subtotals for staging and entry points summing
up the data elements in that group. Subtotals for either age groups and gender would be other
possible columns to easily include here.
592
About data dimensions How this works in pivot tables
How this works in pivot tables
When doing data analysis in Excel pivot tables or any other OLAP based tool the dimensions
become extremely powerful in providing many different views into the data. Each data element
category or group set become a pivot field, and the options or groups become values within each
of these fields. In fact categories and groupsets are treated exactly the same way in pivot tables,
and so are orgunits, periods, and data elements. All these become dimensions to the data value
that can be used to rearrange, pivot, filter, and to drill down into the data. Here we will show some
examples of how the data dimensions are used in pivot tables.
Using the example of morbidity and mortality data, a pivot table can show how the dimensions can
be used to view data for different aggregation levels.
The completely aggregated number is viewed when none of the pivot fields are arranged in the
table area, as column or row fields, but are listed above the table itself as page field (filter).
593
Here we have selected to look at the Morbidity total. The various data elements on morbidity have
been ordered into the main_de_groups Morbidity (we will get back to Mortality later). The fields
above the table itself are all set to "All", meaning that the totals in the table will contain data from
all Countries, Districts, Chiefdom, ou_type, year, months, the various categories as listed in the
red fields, and all data elements in the Morbidity group.
As we have seen, this is not a very useful representation, as Morbidity is organized into new
cases, follow-ups, referrals, and then again in age groups. Also, we do not see the various
diagnoses. The first step is to include the diagnoses field (which is a group set), which is done by
dragging the "diagnosis" field down to be a row field, as shown in the figure below, and to add the
group set called "morbiditymortality" in the column field to display new cases, follow-up, and
referrals.
Contrast this figure above to the one below.
594
They both show the same data (some of the rows have been cut in the screenshot due to image
size), albeit in a different way.
• The "dataelement" field, used in the bottom figure, displays each diagnosis as three
elements; one follow-up, one new, and one referrals. This is the way the data elements
have been defined in DHIS2, as this makes sense for aggregation. You would not like to
aggregate follow-ups and new, thus these have not been made as categories, the whole
point of is to ease aggregation and disaggregation.
• The "diagnosis" group set has instead been made to lump these three (follow-up, new,
referrals) together, which can then be split with another group set, namely the one called
"morbiditymortality". This allows us to organize the data as in the first of the two figures,
where we have the single diagnosis per row, and the groups new, follow-up, referrals as
rows.
The idea of using group sets is that you can combine, in any set, different data elements. Thus, if
we add the mortality data (by checking it from the drop-down menu of the main_de_groups field,
and moving this field out of the table) we can see also the deaths, since the mortality data
elements have been included as a "death" group in the "morbiditymortality" group set. The result
is shown below.
595
The result is a much more user-friendly pivot table. Now, another figure shows the relationship
between the group sets and elements (these are fake data values).
This small detail of the pivot table show how the actual data elements link to the group sets:
• The four data elements, as defined in DHIS2, are Measles death, Measles follow-up,
Measles new, and Measles referrals
• They all belong to the group set "diagnosis", where they have been lumped together in the
group Measles
• The group set "morbiditymortality" contains the groups New cases, Follow-up, Referrals,
and Deaths.
• Only the data element Measles deaths has data related to the group Deaths, thus this is
where the data value (20) is shown, at the upper right corner. The same for Measles new;
the value (224) is shown at the intersection of the data element Measles new and the
group New cases (in the group set morbiditymortality)
• All the intersections where the data element does not link with the groups in
morbiditymortality are left blank. Thus in this case we would get a nice table if we excluded
the data element from the table, and just had diagnosis and the group set
morbiditymortality, as in the figure shown earlier
Now lets see how the data element categories can be used. In the data entry form for Morbidity
the new cases and follow-ups use one age category, the referral data another,, and the mortality
data a third age breakup, so these are available as three individual age group fields in the pivot
tables called morbidity_age, referrals_age and mortality_age. It doesn't make sense to use these
while looking at these data together (as in the examples above), but e.g. if we only want to look at
the only the new cases we can put the MobidityMortalityGroups field back up as a page field and
there select the New cases group as a filter. Then we can drag the Morbidity_age field down to
the column area and we get the following view:
596
The following table illustrates the benefits of reusing data element categories across datasets and
category combinations. The VCCT, ART and PMTCT data are collected in three different datasets,
the first two with both gender and age breakdown, and the PMTCT only age (gender is given). All
three share the same age groups and therefore it is possible to view data elements from all these
three datasets in the same table and use the age dimension. In the previous example with
morbidity and mortality data this was not possible since new cases, referrals and deaths all have
different age groups.
597
In the table below PMTCT data has been removed from the table and the gender category added
to the column area so that you can analyse the data for VCCT and ART by age and gender. An
optional subtotal for gender has also been added, as well as a grand total for all age and gender.
598
About data dimensions Case study: From paper forms to multidimensional datasets - lessons learned
Case study: From paper forms to multidimensional datasets - lessons learned
Typically the design of a DHIS2 dataset is based on some requirements from a paper form that is
already in use. The logic of paper forms are not the same as the data element and data set model
of DHIS2, e.g. often a field in a tabular paper form is described both by column headings and text
on each row, and sometimes also with some introductory table heading that provides more
context. In the database this is captured in one atomic data element with no reference to a
position in a visual table format, so it is important to make sure the data element with the optional
data element categories capture the full meaning of each individual field in the paper form.
Another important thing to have in mind while designing datasets is that the dataset and the
corresponding data entry form (which is a dataset with layout) is a data collection tool and not a
report or analysis tool. There are other far more sophisticated tools for data output and reporting
in DHIS2 than the data entry forms. Paper forms are often designed with both data collection and
reporting in mind and therefore you might see things such as cumulative values (in addition to the
monthly values), repetition of annual data (the same population data reported every month) or
even indicator values such as coverage rates in the same form as the monthly raw data. When
you store the raw data in DHIS2 every month and have all the processing power you need within
the computerised tool there is no need (in fact it would be stupid and most likely cause
inconsistency) to register manually calculated values such as the ones mentioned above. You
only want to capture the raw data in your datasets/forms and leave the calculations to the
computer, and presentation of such values to the reporting tools in DHIS2.
From tables to category combinations - designing multi-dimensional data sets
As we have seen in the examples above, data element categories and category options are
helpful in representing tabular data, when adding dimensions to a field in a paper form. We have
also seen how the data element is one of the required dimensions which describe data in DHIS2.
As we will see in the example below there are often more than one way to represent a paper form
in DHIS2 , and it can be difficult to know which dimension to represent with a data element name
599
About data dimensions From tables to category combinations - designing multi-dimensional data sets
and which to represent as categories, or even as groups as we have seen above. Here are some
general lessons learned from working with data element and category combinations:
• Design your dimensions with data use in mind, not data collection. This means that
disaggregation of data values at collection time should be easily aggregated up along the
various dimensions, as in adding up to a meaningful total.
• Reuse dimensions as much as possible as this increases the ability to compare

disaggregated data (e.g. age groups, fixed/outreach, gender).
• Disaggregation dimensions should add up to a total. In certain cases, data elements may
be collected a subsets of each other. In this case, use of categories to disaggregate the
data element should not be used. As an example, we might collect "Number of confirmed
malaria cases" and disaggregate this by "Under 5" and "Over 5". A third data element
"Number of confirmed malaria cases under 1" might also exist on the form. It would seem
reasonable then to create three age groups : Under 1, Under 5 and Over 5, to describe the
disaggregation. However, the Under 1 is actually a subset of the Under 5 group, and when
totalled, would result in duplication. Thus, categories should be generally be composed of
mutually exclusive category options, such that the sum of individual category options
results in a coherent total.
• Different levels of dimensions; 1) disaggregation and 2) grouping. Disaggregation

dimensions dictate how you collect and how detailed you store your data, so plan these
carefully. The group dimension is more flexible and can be changed and added to even
after data collection (think of it as tagging).
• It is best to think of how the data would be used in an integrated data repository and not
how it will actually be collected on forms or by programs when designing the meta-data
model. Ideally, the same type of disaggregation should be used across forms and datasets
for data elements which will be analysed together, or used to build indicators. Reuse
definitions so that the database can integrate even though the forms themselves might be
duplicated (which in practice, is often the case).
In order to better explain the approach and the possibilities we present an example paper form
and will walk through it step by step and design data elements, categories, category options and
category combinations.
600
This form has many tables and each of them potentially represent a data element category
combination (from now on referred to as a catcombo). As such there is no restriction on a dataset
to only have one set of dimensions or catcombo, it can have many and as we see above this is
necessary as the dimensions are very different from table to table. In the following paragraphs,
we will analyse how to break down this form into its component pieces and suggest an
implementation pathway in DHIS2.
ANC table. This table in the top left corner is one the simpler ones in this form. It has two
dimensions, the first column with the ANC activity or service (1 st visit, IPT 2 nd dose etc) and the
601
second and third column which represent the place where the service was given with the two
options "Fixed" and "Outreach". Since the ANC service is the key phenomena to analyse here,
and often there is a need for looking at the total of "ANC 1 st visits" no matter where they actually
took placed, it makes a lot of sense to use this dimension as the data element dimension.
Thus, all items on the first column from "1 st ANC" visit to "2 nd IPT dose given by TBA" are
represented as individual data elements. The "where" dimension is represented as a data
element category (from now on referred to as category) with the name "fixed/outreach" with the
two data element category options (from now on catoptions) "fixed" and "outreach". There is no
other dimension here so we add a new catcombo with the name "Fixed/Outreach" with one
category "Fixed/Outreach". Strictly speaking there is another dimension in this table, and that is
the at PHU or by TBA dimension which is repeated for the two doses of IPT, but since none of the
other ANC services listed have this dimension it does not seem like a good idea to separate out
two data elements from this table and give them another catcombo with both fixed/outreach and
at PHU/by TBA. reusing the same catcombo for all the ANC services makes more sense since it
will be easier to look at these together in reports etc. and also the fact that there is not much to
lose by repeating the at PHU or by TBA information as part of the data element name when it is
only for four data elements in a table of eleven data elements.
DELIVERY table. This table is more tricky as it has a lot of information and you can see that not
all the rows have the same columns (some columns are merged and a one field is greyed out/
disabled.). If we start by looking at the first column "Deliveries assisted by" that seems to be one
dimension, but only down to the "Untrained TBA" row, as the remaining three rows are not related
to who assisted the delivery at all. Another dimension is the place of delivery, either In PHU or in
Community as stated on the top column headings. These deliveries are further split into the
outcome of the delivery, whether it is a live or still birth, which seems to be another dimension. So
if we disregard the three bottom rows for a moment there seems to be 3 dimensions here, 1)
assisted by, 2) place of delivery, and 3) delivery outcome. The key decision to make is what to use
as the data element, the main dimension, the total that you will most often use and want easily
available in reports and data analysis.
In this case, the outcome dimension as "Total live births" is a very commonly used value in many
indicators (maternal mortality ratio, births attended by skilled health personnel etc.). In this case
the "Assisted By" dimension could also have been used without any problem, but the added value
of easily getting the total live births information was the decisive point for us. This means that from
this table (or sub-table of row 1 to 6) there are only two data elements; "Live births" and "Still
births".
Next, there are two more dimensions, the "PHU/Community" with its two options and a "Births
attended by" with options ("MCH Aides", "SECHN", "Midwives", "CHO", "Trained TBA", "Untrained
TBA"). These two categories make up the catcombo "Births" which is assigned to the two data
elements "Live births" and "Still births". Considering the final three rows of the delivery table we
can see that "Complicated Deliveries" does not have the assisted by dimension, but has the place
and the outcome. "Low birth weight" also does not have the assisted by dimension and not the
outcome either. The LLITN given after delivery does not have any additional dimension at all.
Since not any of the three rows can share catcombo with any other row we decided to represent
these fields as so called flat data elements, meaning data elements with no categories at all, and
simply adding the additional information from the column headings to the data element name, and
therefore ended up with the following data elements with the default (same as none) catcombo;
"Complicated deliveries in PHU live birth", "Complicated deliveries in PHU still births",
"Complicated deliveries in community live birth", "Complicated deliveries in community still births",
"Low birth weight in PHU", "Low birth weight in community", and "LLITN given after delivery".
POST-NATAL CARE table This table is simple and we used the same approach as for the ANC
table. 3 data elements listed in the first column and then link these to the catcombo called "fixed/
602
outreach". Reusing the same category fixed/outreach for these data elements enables analysis
on fixed/outreach together with ANC data and other data using the same category.
TT table This table is somewhat more complex than the previous examples.We decided to use
"TT1", "TT2" ... "TT5" as data elements which makes it easy to get the total of each one of these.
There is fixed/outreach dimension here, but there is also the "In school place" that is only applied
to the Non-Pregnant, or more correctly to any of the two as the school immunisation is done
whether the girls are pregnant or not. We consulted the program people behind the form and
found out that it would be OK to register all school TT immunisations as non-pregnant, which
simplifies the model a bit since we can reuse the "TT1" to "TT5" data elements. So we ended up
with a new category called "TT place" with the three options (Fixed, Outreach, In School), and
another category called "Pregnant/Non-pregnant" with two options. The new catcombo "TT" is
then a combination of these two and applied to the 5 TT data elements. Since we agreed to put all
In Schools immunisations under Non-pregnant in means that the combination of options
(Pregnant+In School) will never be used in any data entry form, and hence become a possible
optioncombo, which is OK. As long as the form is custom designed then you can choose which
combinations of options to use or not, and therefore it is not a problem to have such passive or
unused catoptions. Having school as one option in the TT place category simplifies the model and
therefore we thought it was worth it. The alternative would be to create 5 more data elements for
"TT1 in school" ... "TT5 in school", but then it would be a bit confusing to add these together with
the "TT1" ..."TT5" plus TT catcombo. Having school as a place in the TT place category makes it a
lot easier to get the total of TT1.. TT5 vaccines given, which are the most important numbers and
most often used values for data analysis.
Complications of early and late pregnancy and labour tables We treat these two tables as one,
and will explain why. These two tables are a bit confusing and not the best design. The most
important data coming out of these tables are the pregnancy complications and the maternal
deaths. These data elements contain further detail on the cause of the complication or death (the
first column in both tables), as well as a place of death (in PHU or community), and an outcome of
the complication (when its not a death) that can be either "Managed at PHU" or " Referred". We
decided to create two data elements for these two tables; "Pregnancy complications", and
"Maternal Deaths", and two category combinations, one for each of the data elements. For the
Pregnancy Complications data element there are two additional dimensions, the cause of the
complication (the combined list of the first column in the two tables) and the outcome (managed at
PHU or Referred), so these are the categories and options that make up that category
combination. For the "Maternal deaths" data element the same category with the different causes
are used and then another category for the place of death (in PHU or In community). This way the
two data elements can share one category and it will be easy to derive the total number of
pregnancy complications and maternal deaths. While the list of complications on the paper form is
divided into two (early and late/labour) you can see that e.g. the malaria in 2 nd and 3 rd trimester
are listed under early, but in fact are for a later phase of the pregnancy. There is no clear divide
between early and late complications in the form, and therefore we gave up trying to make this
distinction in the database.
Family Planning Services table This table has 2 dimensions, the family planning method
(contraceptive) and whether the client is new or continuing. We ended up with one data element
only "Family planning clients" and then added two categories "FP method" with all the
contraceptives as options, and another category "FP client type" with new or continuing as
options. This way it will be easy to get the total number of family planning clients which is the
major value to look at in data analysis, and from there you can easily get the details on method or
how many new clients there are.
603
About data dimensions Step-by-step approach to designing datasets
Step-by-step approach to designing datasets
1. Identify the different tables (or sub datasets) in the paper form that share the same
dimensions
2. For each table identify the dimensions that describe the data fields
3. Identify the key dimension, the one that makes most sense to look at in isolation (when the
others are collapsed, summed up). This is your data element dimension, the starting point
and core of your multidimensional model (sub dataset). The data element dimension can be
a merger of two or more dimensions if that makes more sense for data analysis. The key is
to identify which total that makes most sense to look at alone when the other dimensions
are collapsed.
4. For all other/additional dimensions identify their options, and come up with explanatory
names for dimensions and their options.
5. Each of these additional dimensions will be a data element category and their options will
be category options.
6. Combine all categories for each sub dataset into one category combination and assign this
to all the data elements in your table (or sub dataset if you like).
7. 7. When you are done with all the tables (sub datasets), create a new dataset and add all
the data elements you have identified (in the whole paper form) to that dataset.
8. 8. Your dataset will then consist of a set of data elements that are linked to one or more
category combinations.
604
Additional data dimensions About additional data dimensions
Additional data dimensions

About additional data dimensions
DHIS2 has the ability to add dimensions to data in addition to what was described in the previous
chapter. We will call these dimensions "attribute categories" (ACs). The categories described in
the previous chapter we will call "disaggregation categories" (DCs) to differentiate them from ACs.
ACs and DCs are quite similar—they work in much the same way, are accessed through the same
part of the maintenance interface, and exist in the same part of the database. The main difference
between them is what they are connected to: a DC is attached to a data element. An AC,
however, is attached to a data set. This means values for all DC options can be entered on the
same data entry screen, whereas you must choose the AC option before you begin to enter data.
In setting up a system, you could just use DCs and ignore ACs altogether. However, ACs are a
way to simplify data entry screens or reduce the size of the cross-product of category option
combos.
When you’re deciding which categories should be DCs and which should be ACs, here’s a good
rubric:
• Use DCs when you want to use different combinations of categories on different data
elements within a data set
• Use DCs when you want to enter all the category option combinations on one data entry
screen
• Use ACs when you want to use the same combination of categories for all the data in a
data set
• Use ACs when you want to enter only one category option combination on one data entry
screen
While we referred to DCs as part of the what dimension for simplicity in the former chapter, it’s
actually more complex. Either DCs or ACs can answer any question about a data element,
including what (of course), who, why, how, or even a where or a when beyond the organisation
unit and period dimensions.
Create or edit an attribute category and its options
For the process of creating an attribute category as well as options and combinations, see the
section of this manual named Manage categories.
605
Relationship model Relationship Type
Relationship model
A relationship represents a link between two entities in the Tracker-model. A relationship is
considered data in DHIS2 and is based on a Relationship Type, similar to how a Tracked Entity
Instance is based on a Tracked Entity Type.
Relationships always include two entities, and these entities can include Tracked Entity Instances,
Enrollments and Events, and any combination of these. Note that not all of these combinations
are available in the current apps.
In addition, relationships can be defined as unidirectional or bidirectional. The only functional

difference is currently that these requires different levels of access to create. Unidirectional
relationships requires the user to have data write access to the "from" entity and data read
access for the "to" entity, while bidirectional relationships require data write access for both sides.
Relationship Type
A Relationship Type is the definition of the properties a relationship have. Relationships always
consists of two sides, referred to as "from" and "to", and what entities can be contained for each
side is determined by the Relationship Type. The properties that determine what each can contain
are called constraints, fromConstraint and toConstraint respectively. These constraints are
significant when working with the data later, to understand what a relationship can and cannot
contain.
Each of the constraints defined in the Relationship Type consists of several properties. The
primary property is the relationship entity, which decides what kind of entities the relationship can
contain. The entities can be one of the following for each constraint:
• Tracked Entity Instance

• Enrollment
• Event
Depending on the kind of relationship entity you select, you can choose additional limitations for
each constraint. The following table explains the different combinations you can configure:
Tracked Entity
Enrollment Event
Instance
Tracked Entity Type Required Optional -
Program - Required -
Program Stage - Required Optional
These additional limitations, will require the entity to match the limitation set before it can be
created. For example, if your relationship is between a mother and a child, both constraints would
have their required Tracked Entity Type set to Person and could optionally set the Enrollment to
Maternal Health Program and Child Program respectively. This way, only Tracked Entity Instances
who are of type Person and who is enrolled in the required program is allowed to be included in
these relationships.
In addition to the constrains a Relationship Type can have, each relationship can be set to
bidirectional, true or false. If the property is set to false, the relationships are treated as
unidirectional. As previously mentioned, the only functional difference between these relationships
are how strict the access is when creating or updating them - bidirectional being the strictest.
Relationships are also presented differently in the UI based on whether or not the relationship is
bidirectional or unidirectional.
606
Relationship model Relationship Type
One important thing to note about bidirectional relationships, are that the "from" and "to" sides are
still significant in the database, meaning each entity must match the constraint for that side.
However, from a user perspective, which side each entity is stored as is insignificant.
607
DHIS2 Glossary A
DHIS2 Glossary
A
Aggregation : In the context of DHIS2, aggregation refers to how data elements are combined
within a particular hierarchical relationship. As an example, all the health facilities in a particular
district would contribute to the total value for the particular district in question. Different
aggregation operators are supported within DHIS2, such as SUM, AVERAGE, and COUNT.
Analytics : Analytics refers to the process which processes and prepares data which has been
entered into DHIS2 into a format which is more suitable for retrieving indicators and aggregated
data. When data is entered into DHIS2, it is stored in a format which is optimized for writing the
data. However, when data needs to be processed into indicators or aggregated (e.g from months
to quarters), it is more efficient to transform and store this data in a different format which is
optimized for read-only operations. The analytics system of DHIS2 is used extensively by the
analytics apps (GIS, Pivot Table, Event reports, etc.).
It is important to keep in mind that because the data which has been
entered into DHIS2 must be processed into the analytics format, the
data which appears in the analytics apps only represents the data
which was present in the system the last time analytics was run. If
data has been entered after that, analytics will need to be run
again for this data to appear in the analytics apps.
Aggregate data : In the context of DHIS2, aggregate data refers to either data elements or
indicators that have been derived from other hierarchical data sources. For instance, aggregate
facility data would result from the aggregate totals of all patients that have attended that facility
for a particular service. Aggregate district data would result from the aggregate totals of all
facilities contained with a particular district.
Application programming interface : An application programming interface is a specification of how

different software components should interact with each other. The DHIS2 API (or WebAPI) can
be used to interface DHIS2 with other software, to build reports or custom data entry forms.
Approvals : Approvals can be used to control the visibility and editibility of data. When data is
submitted from the lowest reporting level, it can be approved by the next higher level. This
approval has two effects:
1. Data is no longer able to be edited in the data entry screens at

the lower level.
2. Depending on the system settings which have been enabled, the

data will become visible at the approval level.
As an example, data is entered at the facility level, and the

submitted for approval. Once the data has been approved at the
district level, the data will become locked in the data entry
screens for the facility level. It will also become visible in the
analytics apps to district users.
Bi-monthly : Refers to a two-month period, such as January 1 st to February 28 th.
608
DHIS2 Glossary C
Category : Categories are groups of category options. The are used in combinations to
disaggregate data elements. Categories are typically a single type of concept, such as "Age" or
"Gender".
Category combinations : Category combinations are used to disaggregate data elements. As an

example, the data element "Number of confirmed cases of malaria" could be disaggregated
subdivided into to categories: "Age" and "Gender". In turn each of these categories, would consist
of several category options, such as "Male" and "Female" for the gender category. Category
combinations may consist of one or several categories.
Category combination options : Category combination options are dynamically composed of all of
the different combinations of category options which compose a category combination. As an
example, two categories "Gender" and "Age", might have options such as "Male" or "Female" and
"<5 years" or ">5 years". The category combination options would then consist of:
- Male <5 years

- Male >5 years
- Female <5 years
- Female >5 years
Category option : Category options are atomic elements that are grouped into categories.
Comma separated values : Comma separated values are series of tabular data stored in a plain-
text format. They are commonly used with DHIS2 to export and import data values.
Data dictionary : A collection of data elements and indicators, which can be exchanged with other
DHIS2 systems. Typically used to define a set of data elements and indicators when setting up
the DHIS2 system.
Data exchange format : In the context of DHIS2, the "data exchange format" refers to a XML
schema that enables the transportation of data and meta-data between disconnected DHIS2
instances, as well as between different applications that support the DXF schema.
Datamart : A set of database tables in DHIS2 that contains processed data elements and indicator
values that is generated based on aggregation rules and calculated data element and indicator
formulae. Datamart tables are used for analysis and report production. Typically, users should not
work directly with unaggregated data values, but rather with values that have resulted from a
datamart export for analysis.
Data element : A data element is the fundamental building block of DHIS2. It is an atomic unit of
data with well-defined meaning. Essentially it is a data value that has been actually observed or
recorded which is further characterized by a number of dimensions. As an example the data
element "Number of fully immunized children" would refer to the number of children that received
this particular service. Data elements are always linked to a period as well as an organizational
unit. They optionally may be linked to other dimensions.
Data element group : Data element groups are used to categorize multiple data elements
according to a common theme, such as "Immunization" or "ART". Typically, they are used during
reporting and analysis to allow related data elements to be analysed together.
Data element group sets : Data element groups are used to categorize multiple data element
groups into a common theme.
609
DHIS2 Glossary H
Dimension : A dimension is used to categorize data elements during analysis. Dimensions provide
a mechanism to group and filter data based on common characteristics. Typically, related data
elements may be aggregated or filtered during analysis with the use of dimensions. Dimensions
may be a member of a hierarchy. For instance the "Period" dimension may be broken down into
"Day->Month->Quarter->Year".
DXF
Health management information system : Typically, an electronic database system that is used to
record aggregated data on service delivery, disease incidence, human resource data and other
information used to evaluate the performance of delivery of health services. Typically, an HMIS
does not contain the highly detailed data of electronic medical record systems or individual patient
data.
Indicator : The divisor of an indicator. Can be composed of multiple data elements with the use of
an indicator formula.
\[
Indicator = {\frac{Numerator}{Denominator}}
\]
This is obviously a very generalized example. The numerator and

indicator themselves can be composed of various data elements,
factors, and the four basic operands (addition, multiplication,
division and subtraction).
Numerator : The dividend of a indicator. Can be composed of multiple data elements and factors
with the use of indicator formulas.
Organisational unit : An organisational unit is usually a geographical unit, which exists within a
hierarchy. As an example, in the United States, "Georgia" would be considered an organisational
unit with in the orgunit level of "State". Organizational units can also be used to specify an
administrative unit, such as a ward within a hospital. The organisational unit dimension specifies
essentially where a particular data value occurs.
Organisational unit level : Refers to a level within an organizational hierarchy. Typically, countries
are administered at different levels, such as 1) Country 2) States 3) Counties 4) Health facilities.
In the context of DHIS2, health facilities typically are the lowest orgunit level. Data is aggregated
upwards from the lowest orgunit level to the highest.
Period : A period is a specific time interval which consists of a start date and end date. For
instance "January 2011" would refer to the time interval of January 1 st 2011-January 31 st 2011.
Unique identifier : A unique identifier (UID) is a semi-random series of letters and numbers used
by DHIS2 to identify specific resources. UIDs begin with a letter, and are followed by exactly 10
letters or digits.
610
About demo server, live package and database design Using the DHIS2 demo server
About demo server, live package and database design

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!
Using the DHIS2 live package
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.
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.
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.
611
About demo server, live package and database design Downloading and installing the server version
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.
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.
612
About demo server, live package and database design Logging out of DHIS2
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.
Logging out of DHIS2
Just click on the Profile and the click "Log out" the top-right corner of the DHIS2 menu.
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
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
613
About demo server, live package and database design Data Elements
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 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.
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.
614
About demo server, live package and database design Datasets and data entry forms
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, 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.
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.
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.
615
About demo server, live package and database design Validation rules
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 data elements, 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.
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 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.
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.
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").
616
About demo server, live package and database design Report tables and reports
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.
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.
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.
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.
617
DHIS2 Tutorials Create Scorecards using the Pivot Table app
DHIS2 Tutorials
Create Scorecards using the Pivot Table app
*Scorecards definition: In public health settings such as Ministries of Health, scorecards offer a
useful and standardized method for combining related indicators into one table. A scorecard gives
an overall view of the performance of a health program such as a vaccination program,
highlighting successes, weaknesses, and areas for improvement Here's what a typical scorecard
looks like:*
This tutorial explains how to create a scorecard in the DHIS2 Pivot Table app. There are several
advantages to using the Pivot Table to create a scorecard, such as:
• You can save the scorecard on the dashboard and use it offline.
• You can share the scorecard with other DHIS2 users.
Let's get started!
Create a legend for your scorecard
First, we’ll create a 3-color “traffic light” legend for the scorecard. With three basic colors, the
scorecard is easy to scan and easy to understand.
1. Open the Maintenance app. Click the menu in the top right corner and select Maintenance
from the list of apps. You can also type the first letters of the word maintenance in the
search field to find the app.
618
DHIS2 Tutorials Create a legend for your scorecard
2. In the Maintenance app, scroll to the bottom of the page right down to the Other section.
3. Go to Legend and click the +.
4. In the Legend Management page, scroll to the bottom of the page and create a new
legend by clicking the blue + button.
619
DHIS2 Tutorials Create a scorecard in the Pivot Table app
5. Enter a name for the legend such as “Traffic light”, a start value and an end value in the
fields. The values you enter here depend on the performance ratings you wish to set for
the scorecard.
6. Change Number of legend items to 3 to display three colors in the scorecard. To change
the legend item colors, click the blue + button and then edit the colors.
Create a scorecard in the Pivot Table app
1. Open the Pivot Table app from the top right menu of the dashboard. You can also enter
the first letters of Pivot Table in the search field.
2. Go to Data in the pane on the left side and select Indicators in the list.
3. Select an Indicator group such as “ANC” in the second list.
4. Using the arrows, select the type of indicators you want to see in your scorecard.
620
5. Click Update. This button is in the menu at the top of the workspace
6. Go to Periods and select a period for which you want to display data. In this “traffic light”
example, we’ll use the relative period section. In Quarters, select This quarter**and **Last
quarter. Clear any other checkboxes and click Update.
621
7. Go to Organisation Units in the same left side pane, and click the arrow next to the gear
button.
8. Select Select levels.
622
DHIS2 Tutorials Organise the layout and display of your scorecard
9. Select District from the list (next to the gear button). Click Update.
As you can see, the scorecard is starting to take shape in the workspace. Now it’s time to fine-
tune the look and feel.
Organise the layout and display of your scorecard
1. In the workspace, click Layout.
623
2. In Table layout, drag Organisation units down to the Row dimensions section.
3. Drag Data to the Column dimensions section.
4. In the Column dimensions pane, drag Periods below Data, and click Update.
5. In the workspace, click Options.
624
6. Go to Data and clear all the checkboxes.
7. Go to Style > Legend set and from the list, select the legend you created in the
Maintenance app. In this example, we called it Traffic light.
8. Go to Style > Legend display style and select Background color.
9. Click Update.
The Scorecard is ready!
625
DHIS2 Tutorials Save and share your scorecard
Save and share your scorecard
1. In the workspace, go to the Favorites menu.
2. Click Save as. Enter a name for your Scorecard.
3. To share your Scorecard, select Favorites.
4. Enter the name of a user group name, and click Save. Your scorecard can be viewed by
people that you share a dashboard with.
Working with TextPattern
TextPattern was introduced in DHIS2 version 2.29, as a way of defining a pattern that includes
variables, generated values and raw text, which then could be generated into a text value. The
current use-case for TextPattern is automatically generated attributes for tracked entities, where
you want to generate for example unique ids based on a specific pattern.
This guide will cover both basic and advanced topics for working with TextPattern, but is mainly
focused on how you can define TextPatterns and which limitations and caveats exists.
TextPattern syntax
A TextPattern is a sequence of segments, joined together by the "+" character. A segment has a
specific notation and in most cases a parameter format, which allows for further manipulation of
the value.
TextPattern segments
626
DHIS2 Tutorials TextPattern syntax
Parame
Example (segment → input
Segment notation Description nter
value → result)
(format)
"Plain text" The plain text segment will remain None "Hello world" → None →
unchanged in all generated values. Hello world
This special segment is defined by
"Hello \x\x\x" → "Hello you" →
wrapping text between two double
Hello you
quotes. If your pattern should
include separation symbols like a "\d\d\d" → "123" → 123
dash, you should use this "-".
The plain text segment also allows

for placeholder text. That means you
can specify that parts of the plain text
segment should be any of a set of
characters. Currently there are 4
supported special characters you
can use:
• \d (0-9)
• \x (a-z)
• \X (A-Z)
• \w (a-zA-Z0-9)
CURRENT_DAT Current date segment will be Date CURRENT_DATE(yyyy) →

E(format) generated by the server at the time format 01-01-2018 → 2018
of generation. This is useful if you
want your patterns to have a time-
constraint that is disconnected from
the context. You should not use this
if you need to control which date is
injected into the pattern.
ORG_UNIT_COD This segment represents the Text ORG_UNIT_CODE(...) →

E(format) organisation unit code associated format OSLO → OSL
with the generation.
RANDOM(format) Random segments will be replaced Generati RANDOM(X####) → None →

by a value randomly generated by on format A1234
the server based on the format.
Generated segments, like Random,
bases its uniqueness on the rest of
the pattern. That means a random
value can appear twice, as long as
the rest of the pattern is different,
which means the generated text as a
whole will be unique.
627
DHIS2 Tutorials TextPattern syntax
Parame
Example (segment → input
Segment notation Description nter
value → result)
(format)
SEQUENTIAL(for Sequential segments will be Generati "A"+SEQUENTIAL(###) →

mat) replaced by a number, based on a on format None → A001
counting value on the server.
"A"-SEQUENTIAL(###) →
Sequential segments will start at the
None → A002
value 1, and for each generated
value count up until no more values "B"-SEQUENTIAL(###) →
are available, based on the format. None → B001
Like Random segments, uniqueness
is based on the rest of the pattern, so "B"-SEQUENTIAL(###) →
each possible version of the pattern None → B002
will have it's own sequential counter
starting from 1.
Most segments has a parameter format, except for the plain text segment. The following table lists
the available formats, how they are used and example notations using them.
Parameter formats
Format Description Example
Date This format is based directly on the java CURRENT_DATE(dd-MM-yyyy)

format SimpleDateFormat, which means any pattern valid for → 31-12-2018
SimpleDateFormat, will be valid as a date format in
CURRENT_DATE(MM-yyyy) →
TextPattern
12-2018
Text The text format allows for some basic text

ORG_UNIT_CODE(....) → OSLO
format manipulation. Leaving the format empty will return the
value unmodified, but using "^", "." and "$", you can ORG_UNIT_CODE(..) → OS
modify the value before it is returned. Each "."
represents a character, while "^" represents the start of ORG_UNIT_CODE(..$) → LO
the text and "$" represents the end. When using
ORG_UNIT_CODE(^...$) → OSLO
formats, the input value must be at least the same
length as the format. ^....$ will require the input value to
be exactly 4 characters.
Generati The generation format accepts a combination of one or RANDOM(X###) → A123

on format more of he following characters: "#", "X", "x" and "*".
RANDOM(****) → 1AbC
They respectively represent a number(0-9), an
uppercase letter (A-Z), a lowercase letter(a-z) or any of SEQUENTIAL(###) → 001
the above(0-9,a-z,A-Z). The SEQUENTIAL segment
only accepts "#", since it will only generate numbers. SEQUENTIAL(######) → 000001
The number of characters in the format decides the
size of the value generated. Using just one "#" will in
other words only allow for 10 values (0-9), while "###"
will allow for 1000 values (000-999). SEQUENTIAL
generated values have leading zeroes, so the length
of the generated value will always match the format
length.
628
DHIS2 Tutorials Designing TextPattern for generating ids
A few important things to note regarding the formats:
• Date format is very versatile, but be aware of which date or time components you are
using. Using components smaller than a day (For example hours or seconds) is not
recommended, even though available.
• Text format allows for marking both the start and end of the input value, but "^..." and "..."
will in reality give exactly the same results. The only time you would want to use "^" is when
you want to enforce the length of the input value. For example, "^....$" will accept OSLO,
since its 4 characters between the start and end, but PARIS will be rejected, since it has 5
characters.
• When text format is used for unique values, like organisation unit code, make sure that the
format does not break the uniqueness. (Example: ORG_UNIT_CODE(..) for "PARIS" and
"PANAMA CITY" would both return PA, which means these two organisation units would in
reality share generated values)
• Generation format is the primary way to understanding the capacity of your pattern. Make
sure the format is long enough to cover more values than you need.
To finish off the syntax section of the tutorial, here is a couple of example TextPattern:
ORG_UNIT_CODE(...) + "-" + CURRENT_DATE(yyyyww) + "-" + SEQUENTIAL(#####)
This pattern will have 99999 possible values (based on SEQUENTIAL. 00000 is never used since
we start at 1). In addition, the remaining pattern will change for each different organisation unit
generating values (ORG_UNIT_CODE) and for each week (CURRENT_DATE(yyyyww)
represents year and week). That effectively means every new week, each organisation unit will
have 99999 new values they can use.
"ABC_" + RANDOM(****)
The plain text segment of this pattern, will make no difference in the total capacity of the pattern,
however the generated segment (RANDOM) will allow for 14776336 possible values. The reason
for this is that * can be any one character of the 62 characters available (0-9, a-z, A-Z). You can
read more about understanding pattern capacity further down in the tutorial.
Designing TextPattern for generating ids
One use-case for TextPattern is to generate unique ids. In this section we will present guidelines
and common issues related to designing TextPatterns used for ids.
An id should never contain sensitive information, or information that in combination can identify an
individual. TextPattern does not currently support segments that uses these kind of values, but
might do so in the future.
The following list highlights some of the TextPattern specific restrictions you need to consider
when designing a TextPattern for ids:
• Make sure the capacity (number of possible values) of the TextPattern covers your use-
case. It's better to have more values than needed than less. Tracked entity attributes using
TextPattern will require that a single generated segment is present in the TextPattern.
• A TextPattern is unique in the entire system, but only for the object using it. In other words,
if you have a single tracked entity attribute with TextPattern, used by multiple Tracked
629
DHIS2 Tutorials Understanding TextPattern capacity
entities (Not to be mistaken for tracked entity instances), all values generated will be
shared between all traced entities using the attribute. This also means that if you have two
tracked entity attributes with the same TextPattern syntax, each attribute will be able to
generate the same value as the other, since uniqueness is based on the attribute.
• SEQUENTIAL segments are in the implementation numbers starting from 1, increasing by 1

for each value, sequentially until no more values are available. However, in reality you will
most likely end up with gaps when users generate and reserve values that is never used,
or if a user sends in a value where the SEQUENTIAL segment has a higher value than
recorded on the server.
• The current implementation relies on the user-client to send in the values contained in the
TextPattern when storing a new value. That means generating a correct id is depending on
the user, and user-client, to provide the correct data.
Understanding TextPattern capacity
The most important thing to keep in mind when designing a TextPattern, is the capacity - that
means the total number of potential values a TextPattern can yield.
With the current implementation of TextPattern, there are three main factors that decides the
capacity:
1. Capacity of the generated segment in the TextPattern
2. The presence of a CURRENT_DATE segment
3. The presence of a ORG_UNIT_CODE segment
The presence of a date segment (like CURRENT_DATE) will effectively reset the capacity each
time the segment changes. Depending on the date format, it can change anywhere to yearly to
daily. Important: If your date format don't contain a year, the pattern will resolve to the same
value every year. That means values will already be used. For example, if your TextPattern looks
like this:
CURRENT_DATE(ww) + "-" + RANDOM(#)
This pattern will give you up to 10 unique values for each week, but after 1 year,
CURRENT_DATE(ww) will be the same as last year, and you will have no new values available. If
you use "yyyy-ww" instead, it will be unique for every year, every week.
Organisation unit codes will make your values unique for each different organisation unit, which
means if you have a text pattern like this:
ORG_UNIT_CODE() + "-" + RANDOM(#)
This pattern will give you 10 unique values for each different organisation unit.
Calculating capacity for generated segments
Understanding how to calculate the capacity of a TextPattern is critical when designing

TextPatterns. The generated segments will be the main component of any TextPattern in terms of
capacity, then increased based on the presence of ORG_UNIT_CODE or CURRENT_DATE.
630
DHIS2 Tutorials Random segments and why you should avoid it
Let's start with SEQUENTIAL segments. Each "#" in the format represents a number between 0
and 9. To calculate the total capacity, you multiply the number of possible values for each "#".
Since it's always 10 (0-9) the maths is quite straight forward:
SEQUENTIAL(#) = 10 = 10
SEQUENTIAL(###) = 10 * 10 * 10 = 1000
SEQUENTIAL(#####) = 10 * 10 * 10 * 10 * 10 = 100000
Since SEQUENTIAL counters on the server start at 1 and not 0, the actual capacity is 999, but
that's insignificant in most cases.
As soon as we involve RANDOM, the calculation becomes a bit more complicated. Similar to
SEQUENTIAL, a "#" has 10 possible values, in addition we have "X" and "x" with 26 possible
values each, as well as "*" which can be any of the previous, which means 62 (10+26+26)
possible values.
To calculate the capacity, you need to take each character in your format and replace with the
number of possible values, then multiply them all together like we did for SEQUENTIAL:
RANDOM(#) = 10 = 10
RANDOM(X) = 26 = 26
RANDOM(*) = 62 = 62
RANDOM(X##) = 26 * 10 * 10 = 2600
RANDOM(XXxx) = 26 * 26 * 26 * 26 = 456976
RANDOM(***) = 62 * 62 * 62 = 238328
As you can see, the maths gets a bit more complicated when, but by following this recipe you can
see the number of potential values.
Random segments and why you should avoid it
There is a hidden cost of using the random segment in TextPattern in the long run, but that does
not mean you should never use it. This section will highlight the problems of using the random
segment and suggest when it might be more appropriate to use it.
This section is motivated by an issue with the previous generation strategy, where you only had
random generation. After while, instances using this feature would actually be unable to generate
and reserve new values, since it was taking to long to find available values. This section looks at
some of the problems with random generation that created this situation.
Generating random values
Before using the RANDOM segment in your TextPattern, you should consider the following
problems connected to the use of RANDOM:
• Generating values from a TextPattern with a RANDOM segment will be more complex than
other TextPatterns
Data entry for TextPattern based metadata
As previously mentioned, the only metadata currently supporting TextPattern is the tracked entity
attributes. In this section, we will describe the different ways data entry for TextPattern works,
especially for tracked entity attributes.
631
DHIS2 Tutorials Data entry for TextPattern based metadata
Validation of values using TextPattern
By default, all values sent to the server for metadata using TextPattern, will be validated.
Validation can be skipped if needed, but you should always validate input under normal
circumstances. The validation will be based on the TextPattern you have defined and will be as
strict as possible:
• Date segments must match the same format as specified in the segment parameter
• Plain text segments must match exactly
• Text segments values must be at least as long as the format string. If both "^" and "$" is
present, the value must match the exact length.
• Generated segment values must match the format exactly, character by character.
When using the server to first generate and reserve values, the server will modify the values used
in the TextPattern before injecting them, meaning you will always get a valid value when
generating it on the server.
A final exception to TextPattern validation is made for a special case: If you change a TextPattern
after reserving values for the original pattern, values sent to the server that are invalid according
to the new TextPattern, will still be accepted if it was already reserved.
Different data entry flows for TextPattern
There is currently 2 ways a client can store values for TextPattern metadata:
1. Generating and reserving values (Apps should do this for you)
2. Storing a custom value
The preferred way, is to generate and reserve the needed values (The number of values
generated and reserved is handled by the app). That means each time you are seeing and
storing a value, it has been generated and reserved by the server, and will be valid.
The other way might be useful in specific cases. The user will supply the value themselves and as
long as the value supplied is valid for the TextPattern, they can put anything they want. The
caveat of doing it this way, is that you might use values that was reserved by someone else and if
you have a SEQUENTIAL segment, the counter will not be updated.
632
DHIS2 Frequently Asked Questions Data entry for TextPattern based metadata
DHIS2 Frequently Asked Questions

Q: I have entered data into a data entry form, but I cannot see the data in any reports (pivot
tables, charts, maps). Why does data which is entered not show up immediately in my graphs in
DHIS2?
A: Data which is entered into DHIS2 must first be processed with the "analytics". This means that
data is not immediately available in the analytics resources (such as reports, pivot tables, data
visualizer, GIS, etc.) after it has been entered. If scheduling is active, the analytics process will
run automatically at midnight each day. After that, new data which was entered since the last time
the analytics process ran, will become visible.
You can trigger the analytics process manually by selecting Reports->Analytics from the main
menu and pressing the "Start export" button. Note, the process may take a significant amount of
time depending on the amount of data in your database.
Other factors which can affect the visibility of data are:
• Data approval: If data has not been approved to a level which corresponds to your users
level, the data may not be visible to you.
• Sharing of meta-data objects: If certain meta-data objects have not been shared with a
user group which you are a member of, the data may not be visible to you.
• Caching of analytics: In many cases, server administrators cache analytical objects (such
as pivot tables, maps, graphs) on the server. If you have entered data, re-run analytics,
and you are still not seeing any (updated) data, be sure that your data is not being cached
by the server.
Q: I have downloaded DHIS2 from https://www.dhis2.org/downloads but when i try to enter the
system it needs a username and password. Which should I use?
A: By default, the username will be "admin" and the password "district". Usernames and
passwords are case sensitive.
633
Release and upgrade notes Data entry for TextPattern based metadata
Release and upgrade notes

For up-to-date information about the latest DHIS 2 releases, please refer to the DHIS 2
downloads page on our website.
634

Dhis2 User Manual

Uploaded by

Copyright:

Available Formats

Dhis2 User Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Dhis2 User Manual

Uploaded by

Copyright:

Available Formats

DHIS2 User Manual

DHIS core version 2.34

DHIS2 Documentation Team

Copyright © 2008-2021 DHIS2 Team

Last update: 2021-07-13

Linking to the Tracker Capture App

Manage event layers

• What is the difference between patient based and aggregate data?

Key features and purpose of DHIS2

The key features and purpose of DHIS2 can be summarised as follows:

• Provide a comprehensive data management solution based on data warehousing principles

• Functionality to design and modify calculated indicator formulas.

• Functionalities of export-import of data and metadata, supporting synchronisation of offline

Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.

The health information cycle

DHIS2 supports the different facets of the information cycle including:

• Running quality checks.

• Data access at multiple levels.

• Making graphs and maps and other forms of analysis.

Understanding platform independence

Deployment strategies - online vs offline

• Hardware: Running stand-alone systems requires advanced hardware in terms of servers

• Hardware: Hardware requirements on the end-user side are limited to a reasonably

• **Database maintenance:**Similar to the previous point, changes to the meta-data can be

1. Internal hosting within the Ministry of Health

2. Hosting within a government data centre

3. Hosting through an external hosting company

4. Stable power supply including a backup solution.

7. Feasible, powerful and robust hardware.

Difference between Aggregated and Patient data in a HIS

Free and Open Source Software (FOSS): benefits and challenges

Using the Data Entry app

1. Custom form (if it exists)

Mobile devices do not support custom forms. In mobile-based data entry

1. Section form (if it exists)

Enter data in a data entry form

1. Open the Data Entry app.

2. In the organisation unit tree to the left, select an organisation unit.

3. Select a Data set.

5. Enter data in the data entry form.

7. (Optional) Correct validation violations.

Mark a data value for follow-up

1. Open the Data Entry app.

2. Open an existing data entry form.

4. Click the star icon.

Edit data values in a completed data entry form

1. Open the Data Entry app.

2. Open an existing data entry form.

Display a data value's history

You can display the last 12 values registered for a field.

1. Open the Data Entry app.

2. Open an existing data entry form.

Display a data value's audit trail

1. Open the Data Entry app.

2. Open an existing data entry form.

4. Click Audit trail.

Create minimum maximum value range manually

1. In the Data Entry app, open a data entry form.

3. Enter Min limit and Max limit.

6. (Optional) Click Save comment.

• Database maintenance:Similar to the previous point, changes to the meta-data can be