DHIS 2 User guide

Applicable to master version

DHIS 2 Documentation team

May 2019

Copyright © 2006-2019 DHIS 2 Documentation team

May 2019

Revision History
master@919548e2019-05-14 12:13:06 +0200

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

Table of Contents

1 About this guide

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

DHIS2 is a browser-based application. In many cases, screenshots have been included for enhanced clarity. Shortcuts to various functionalities are displayed such as Data element > Data element group. The “>” symbol indicates that you should click Data element and then click Data element group in the user interface.

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

Note

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

Tip

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

Important

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

Caution

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

Warning

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

Program listings usually contain some type of computer code.
They will be displayed with a shaded background and a different font.

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

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

2 Getting started - help to navigate the user guide

What do you want to do?

Link to documentation

Related app(s)

Enter data

Enter aggregate data

Using the Data Entry app

Data Entry

Enter data for a program without registration (event program)

Using the Event Capture app

Event Capture

Enter data for a program with registration (tracker program)

Using the Tracker Capture app

Tracker Capture

Analyse and visualize data

Analyze data in a table

Analyse data in pivot tables

Pivot Table

Visualize data in a chart

Using the Data Visualizer app

Data Visualizer

Visualize data in a map

Using the GIS app

GIS

Visualize data in a better map

Using the Maps app

Maps

Analyse data in two types of reports.

Using the Event Reports app

Event Report

Visualize program data in a chart

Using the Event Visualizer app

Event Visualizer

Create a dashboard

Manage dashboards

Dashboard

Control data quality

Control data quality

Data Quality

Manage users and authorities

Create or edit users, user roles or user groups

Manage users, user roles and user groups

Users

Look up all user authorities

Appendix A. User authorities

Users

Visualize statistics about how users work with the Dashboard, Pivot Table, GIS, Event Visualizer, Data Visualizer and Event Reports apps

Visualize usage statistics

Usage Analytics

Customize the user interface

Change your account preferences

Set user account preferences

-

Configure metadata

Create metadata, for example organisation units and data elements

Configure metadata

Maintenance

Create metadata to use in an event or a tracker program

Configure programs in the Maintenance app

Maintenance

Configure the system

Look up all system settings

Appendix B. System settings

System Settings

Perform database maintenance

Data administration

Data Administration

Set up metadata synchronization between a central instance and multiple local instances

Configure metadata synchronization

System Settings

Data Administration

Configure data approval

Data approval

System Settings

Configure data and metadata import or export

Import and export data and metadata

Import-Export

Learn more about sharing of objects

About sharing of objects

-

Import coordinates and configure the GIS app

Configure the GIS app

Manage legends

Manage external map layers

Maintenance

Set up report functionality

Configure report functionality

-

Learn about event and tracker programs

Create a program

Configure programs in the Maintenance app

Configure programs in the Programs/Attributes app (legacy app)

Maintenance

Program

Enter data for a program with registration (tracker program)

Using the Tracker Capture app

Tracker Capture

Enter data for a program without registration (event program)

Using the Event Capture app

Event Capture

Visualize data from a program in a chart

Using the Event Visualizer app

Event Visualizer

Analyze data from a program in two types of reports

Using the Event Reports app

Event Report

Learn more about DHIS2

What is DHIS2?

What is DHIS2?

-

Learn about the DHIS2 data dimensions

Data dimensions in DHIS2

-

3 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?

3.1 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.

3.2 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.).

  • 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.

3.3 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.

The health information cycle
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.

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.

3.4 Technical background

3.4.1 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.

3.4.2 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.

3.4.3 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.

3.4.3.1 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 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.

3.4.3.2 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-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.

3.4.3.3 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.

3.4.3.4 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.

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.

3.5 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.

3.6 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, 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.

4 Managing dashboards

4.1 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.

4.2 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.

4.2.1 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.

4.2.2 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.

4.3 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:

4.3.1 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:

  • Pivot tables

  • Charts

  • Maps

  • Event reports

  • Event charts

  • Report

  • Resources

  • Apps

  • Email

  • Text boxes

  • Spacer

The list of items in the drop-down initially displays the first 5 available from each category, 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 SEE MORE, and the list for that type will be extended to 15 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.

4.3.2 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:

Spacer in view mode:

4.4 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.

4.5 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.

4.6 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.

4.6.1 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.

  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

4.7 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.

4.8 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

4.8.1 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.

4.8.2 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 (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
Adding a filter

A dialog opens where the filter selection can be made.

Org Unit filter selection
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
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.

4.9 Dashboard items with charts, pivot tables and maps

4.9.1 Switching between visualizations

Dashboard items showing charts, pivot tables and maps can be toggled between these visualizations. Click on the buttons in the upper right corner of the item to toggle between visualizations.

4.10 Interpretations

You can write interpretations for the chart, pivot table, map, event report, and event chart items. Click on the interpretations button , and the item will be expanded vertically underneath to show the 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 following character combinations: :) :-) :( :-( :+1 :-1. URLs are automatically detected and converted into a clickable link.

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.

4.11 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

All dashboards have two sharing groups set by default.

  • External access (without login)

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

  • 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

    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

5 Messaging

5.1 About messages and feedback messages

Within DHIS2 you can send messages and feedback messages to users, user groups and organisation units. When you send a feedback message, it is routed to a particular user group 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.

    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.

5.2 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.

5.3 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.

5.4 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.

5.5 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.

5.6 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.

5.6.1 All messages selected

All Messages Selected
All Messages Selected

5.6.2 All messages selected and extended choice picker 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
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 Open 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.

5.7 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.

6 Using the Data Entry app

6.1 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:

  1. Section form (if it exists)

  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.

6.2 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.

    • 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.

6.3 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.

  1. Open the Data Entry app.

  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.

6.4 Edit data values in a completed data entry form

  1. Open the Data Entry app.

  2. Open an existing data entry form.

  3. Click Incomplete.

  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.

6.5 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.

  3. Double-click the field with the value you want to view the history for.

  4. Click Data element history.

6.6 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.

  1. Open the Data Entry app.

  2. Open an existing data entry form.

  3. Double-click the field with the value you want to view the audit trail for.

  4. Click Audit trail.

6.7 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

Click the star icon to mark the value for further follow-up.

6.8 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:

6.9 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.

6.10 See also

7 Using the Event Capture app

7.1 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.

  • 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.

7.2 Register an event

  1. Open the Event 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 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 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.

7.3 Edit an event

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click the event you want to modify and select Edit.

  5. Modify the event details and click Update.

7.4 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.

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a 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.

7.5 Share events in edit mode

You can share an event in edit mode via its web address.

  1. Open the Event Capture app.

  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.

7.6 View an event audit history

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click an event and select Audit history.

7.7 Delete an event

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click an event and select Remove.

  5. Click Remove to cocnfirm the deletion.

7.8 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.

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click the Show/hide columns icon.

  5. Select the columns you want to display and click Close.

7.9 Print an event list

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click Print list.

7.10 Download an event list

  1. Open the Event Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click the Downlad icon and select a format.

    You can download an event list in XML, JSON or CSV formats.

8 Using the Tracker Capture app

8.1 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.

  • When you close an organisation unit, you can’t register or edit events to this organisation 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.

8.2 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.

8.3 Workflow

Working process of Mother and child health program

  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.

8.4 Linking to the Tracker Capture App

8.4.2 Linking to TEI dashboard

You can share a TEI dashboard via its web address.

  1. Open the Tracker Capture app.

  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.

  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.

8.5 Create a TEI and enroll it in a program

You can create a TEI and enroll that TEI to a program in one operation:

  1. Open the Tracker Capture app.

  2. In the organisation unit tree in the left hand pane, select an organisation unit.

  3. Select a program.

  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.

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.

8.6 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.

8.6.3 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.

8.7 Enroll an existing TEI in a program

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. Select a program.

  4. In the Enrollment widget, click Add new.

  5. Fill in the required information and click Enroll.

8.8 Enter event data for a TEI

8.8.1 Widgets for data entry

8.8.1.1

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

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.

8.8.2 Creating an event

You can create an event for a TEI by:

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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.

8.8.3 Schedule an event

You can shedule an event for a future date by:

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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.

8.8.4 Refer an event

Sometimes it might be nessascary to refer a patient to a different Organisation unit. To refer a TEI:

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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 and all its future events permantly to the selected Organisation Unit.

8.8.5 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.

8.9 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.

8.9.1 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

8.9.2 Capture Polygon

  1. Click on the map icon
  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

8.10 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.

8.11 Manage a TEI’s enrollments

8.11.1 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.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Enrollment widget, click Deactivate.

  4. Click Yes to confirm.

8.11.2 Activate a TEI’s enrollment

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Enrollment widget, click Activate.

  4. Click Yes to confirm.

8.11.3 Mark TEI’s enrollment as complete

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Enrollment widget, click Complete.

  4. Click Yes to confirm.

8.11.4 Reopen completed enrollment

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Enrollment widget, click Reopen.

  4. Click Yes to confirm.

8.11.5 Display TEI’s enrollment history

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Profile widget, click the Audit history icon.

8.11.6 Create a TEI enrollment note

An enrollment note is useful to record information about for example why an enrollment was cancelled.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Notes widget, type your note and click Add.

8.12 Send a message to a TEI

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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.

8.13 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.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Enrollment widget, click the Mark for follow-up icon.

8.14 Edit a TEI’s profile

You edit a TEI’s profile or tracked entity attributes in the Profile widget.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Profile widget, click Edit.

  4. Modify the profile and click Save.

8.15 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.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the Relationships widget, and click Add.

  4. Select a relationship type.

  5. Search for the relative and select it.

  6. 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.

8.16 Share a TEI dashboard

You can share a TEI dashboard via its web address.

  1. Open the Tracker Capture app.

  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.

  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.

8.17 Deactivate a TEI

If you deactivate a TEI, the TEI becomes ‘read-only’. Data associated with the TEI is not deleted.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the top right corner, click the button > Deactivate.

  4. Click Yes to confirm.

8.18 Activate a TEI

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the upper top corner, click the button > Activate.

  4. Click Yes to confirm.

8.19 Delete a TEI

Warning

When you delete a TEI, you delete all data associated with the TEI.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. In the top right corner, click the button > Delete.

  4. Click Yes to confirm.

8.20 Configure the TEI dashboard

8.20.1 Show or hide widgets

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. Click the Settings icon, and select Show/hide widgets.

  4. Select the widgets you want to show or hide.

  5. Click Close.

8.20.2 Save the dashboard’s layout as default

You can save the dashboard’s layout as default for a program.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  3. Click the Settings icon, and select Save dashboard layout as default.

8.20.3 Lock dashboard’s layout

If you are the administrator you have the option of locking the layout of the dashboard for all users.

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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.

8.20.4 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:

  1. Open the Tracker Capture app.

  2. Open an existing TEI dashboard.

  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.

8.20.5 Chage 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.

  • 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.

8.21 Create reports

  1. Open the Tracker Capture app.

  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.

    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.

9 Using the Capture app

9.1 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
    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 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.

9.2 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.

  • You now have two options: Link to an existing Tracked Entity Instance or Create new Tracked Entity Instance.
relationship options
relationship options

9.2.2 Create new Tracked Entity Instance

  1. Click Create new Tracked Entity Instance.
  • 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 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
    register new Tracked Entity Instance
  1. Fill in the desired (and possibly manditory) attributes and enrollment details.

  2. 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.

9.3 Edit an event

  1. Open the Capture app.

  2. Select an organisation unit.

  3. Select a program.

    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.

9.4 Delete an event

  1. Open the Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  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
    delete event

9.5 Modify an event lists 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.

  1. Open the Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a list.

  4. Click the gear icon on the top right of the event list.

  5. Select the columns you want to display and click Save.

    modify event list
    modify event list

Note: You can reorganize the order of the data elements by draging and dropping them in the list.

9.6 Filter an evnet list

  1. Open the Capture app.

  2. Select an organisation unit.

  3. Select a program.

    All events registered to the selected program show up in a 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.

    filter event
    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.

9.7 Sort an evnet list

  1. Open the Capture app.

  2. Select an organisation unit.

  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.

    sort event
    sort event

9.8 Download an event list

  1. Open the Capture app.

  2. Select an organisation unit.

  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.

    download event list
    download event list

Note: You can download an event list in JSON, XML or CSV formats.

10 Analyze data in pivot tables

10.1 About the Pivot Table app

With the Pivot Table app, you can create pivot tables based on all available data dimensions in DHIS2. A pivot table is a dynamic tool for data analysis which lets you summarize and arrange data according to its dimensions. Examples of data dimensions in DHIS2 are:

  • data dimension itself (for example data elements, indicators and events)

  • periods (representing the time period for 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.

10.2 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.

    You can keep the default selection if you want.

  4. Click Update.

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

10.2.1 Select dimension items

The left menu lists sections for all available data dimensions. From each section you can select any number of dimension items. As an example, you can open the section for data elements and select any number of data elements from the available list. You can select an item by 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 formula based on data elements. Coverage of immunization across a specific district.
Data elements Represents the phenomenon for which data has been captured. Number of malaria cases; number of BCG doses given.
Data sets A collection of data elements grouped for data collection. You 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.

Reporting rates for immunization and morbidity forms.
Event data items A data element that is part of a program representing events that have been captured. Average weight and height for children in a nutrition program.
Program indicators A calculated formula based on data elements in a program representing events. Average BMI score for children in a nutrition program.

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

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

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

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

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

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.

10.2.2 Modify pivot table layout

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

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 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:

10.3 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

    Show row totals

    Displays total values in the table for each row and column, as well as a total for all values in the table.

    Show column sub-totals

    Show row sub-totals

    Displays subtotals in the table for each dimension.

    If you only select one dimension, subtotals will be hidden for those columns or rows. This is because the values will be equal to the subtotals.

    Show dimension labels

    Shows the dimension names as part of the pivot tables.

    Hide empty rows

    Hides empty rows from the table. 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 Max.

    Number type

    Sets the type of value you want to display in the pivot table: Value, Percentage of row or Percentage of column.

    The options Percentage of row andPercentage 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.

    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 units

    Show hierarchy

    Shows the name of all ancestors for organisation units, for example “Sierra Leone / Bombali / Tamabaka / Sanya CHP” for Sanya CHP.

    The organisation units are then sorted alphabetically 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 Maintenance 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.

    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.

10.4 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.

10.4.1 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.

10.4.2 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.

10.4.3 Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

10.4.4 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.

    • None: The public won’t have access to the object. This setting is only applicable to Public access.

  5. Click Share.

10.4.5 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.

10.4.7 Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

10.4.8 View interpretations based on relative periods

To view interpretations for relative periods, such as a year ago:

  1. Open a favorite with interpretations.

  2. Click >>> in the top right of the workspace.

  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.

10.5 Download data from a pivot table

10.5.1 Download table layout data format

To download the data in the current pivot table:

  1. Click Download.

  2. Under Table layout, click the format you want to download: Microsoft Excel, CSV or HTML.

    The data table will have one column per dimension and contain names of the dimension items.

    Tip

    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.

10.5.2 Download plain data source format

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

To download plain data source formats:

  1. Click Download.

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

    Available formats

    Format

    Action

    Description

    JSON

    Click JSON

    Downloads JSON format based on ID property.

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

    XML

    Click XML

    Downloads XML format based on ID property.

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

    Microsoft Excel

    Click Microsoft Excel

    Downloads XML format based on ID property.

    You can also download Microsoft Excel format based on Code or Name property.

    CSV

    Click CSV

    Downloads CSV format based on ID property.

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

    JRXML

    Put the cursor on Advanced and click 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 DHIS2.

    Raw data SQL

    Put the cursor on Advanced and click Raw data SQL

    Provides the actual SQL statement used to generate the pivot table. You can use it as a data source in a Jasper report, or as the basis for an SQL view.

10.5.3 Download a CSV format without rendering data in the web browser

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

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.

10.6 Embed a pivot table in an external web page

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

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

  1. Click Embed.

  2. Click Select to highlight the HTML fragment.

10.7 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.

10.7.1 Open a pivot table as a chart

  1. Click Chart > Open this table as chart.

    Your current pivot table opens as a chart.

10.7.2 Open a pivot table selection as a chart

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

  1. In the pivot table, click a value.

  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.

10.7.3 Open a pivot table as a map

  1. Click Chart > Open this table as map

    Your current pivot table opens as a map.

10.7.4 Open a pivot table selection as a map

  1. In the pivot table, click a value.

    A menu displays.

  2. Click Open selection as map.

    Your selection opens as a map.

11 Data Visualizer

11.1 Creating and editing charts

When you open the data-visualizer app from the dhis2 menu, you are presented with a blank slate and you can start creating your chart right away.

Select the desired chart type from the selector in the upper left corner:

From the dimension menu on the left you can select the dimension you want to show in your chart, including data, period, organisation units and dynamic dimensions.

You can also change the selections by clicking on the chips in the layout area.

11.2 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” charts you can do so by clicking “Manage axes” in the series dimension’s context menu.

In the axis management dialog you can assign data items to the two axes.

11.3 Viewing chart interpretations

When viewing a chart, you can expand the interpretations on the right side by clicking on the Interpretations button in the upper right corner. The chart description will also be shown. The description suppots rich text format.

To view the chart according to the date of a particular interpretation, click on the interpretation or its “View” button. This will regenerate the chart with the relevant date, which is indicated next to the chart title.

Clicking on “Back to all interpretations” or the “Exit View” button inside the interpretations panel will clear the interpretation and regenerate the chart with the current date.

11.4 See chart as map

Sometimes it can be useful to see how visualization would look like on map. To achieve this you can select “Open as: Map” chart type after you build your chart.

12 Classic Data Visualizer (deprecated)

This chapter refers to the legacy version of the data visualizer. For the current version, please refer to the new data visualizer chapter.

12.1 About the Classic Data Visualizer app

With the ** Classic Data Visualizer** app, you can select content, for example indicators, data elements, periods and organisation units, for an analysis. The app works well over poor Internet connections and generates charts in the web browser.

Tip

  • Hide and show individual data series in the chart by clicking directly on the series label in the chart. They appear either at the top or to the right of the chart.

  • Click the triple left-arrow button on the top centre menu. This collapses the left side menu and gives more space for the chart. You can get the menu back by clicking on the same button again.

12.2 Create a chart

  1. Open the Classic Data Visualizer app and select a chart type.

  2. In the menu to the left, select the metadata you want to analyse. You must select one or more elements from all of the three dimensions - data (indicators, data elements, reporting rates), periods (relative, fixed) and organisation units (units or groups).

    Note

    If you’ve access to the system settings, you can change the default period type under General settings > Default relative period for analysis.

    Last 12 Months from the period dimension and the root organisation unit are selected by default.

  3. Click Layout and arrange the dimensions.

    You can keep the default selection if you want.

  4. Click Update.

12.3 Select a chart type

The Classic Data Visualizer app has nine 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.

    Stacked column chart

    Displays information as vertical rectangular columns, where bars representing multiple categories are stacked on top of each other.

    Useful when you want to, for example, display trends or sums of related data elements.

    Bar chart

    Same as column chart, only with horizontal bars.

    Stacked bar chart

    Same as stacked column chart, only with horizontal bars.

    Line chart

    Displays information as a series of points connected by straight lines. Also referred to as time series.

    Useful when you want to, for example, visualize trends in indicator data over multiple time periods.

    Area chart

    Is based on line chart, with the space between the axis and the line filled with colors and the lines stacked on top of each other.

    Useful when you want to compare the trends of related indicators.

    Pie chart

    Circular chart divided into sectors (or slices).

    Useful when you want to, for example, visualize the proportion of data for individual data elements compared to the total sum of all data elements in the chart.

    Radar chart

    Displays data on axes starting from the same point. Also known as spider chart.

    Speedometer chart

    Semi-circle chart which displays values out of 100 %. Also referred to as a gauge chart.

  2. Click Update.

12.4 Select dimension items

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

  • Data: Includes data elements, indicators and datasets (reporting rates), describing the phenomena or event of the data.
  • Periods: Describes when the event took place.
  • Organisation units: Describes where the event took place.

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

Note

You can select dimension items in different ways:

  • Double-click a dimension item name.

  • Highlight one or several dimension items and click the single-arrow.

  • To select all dimension items in a list, click the double-arrow.

  • To clear dimension items, use the arrows or double-click the names in the Selected list.

12.4.1 Select indicators

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

  1. Click Data and select Indicators.

  2. Select an indicator group.

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

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

    The indicator moves to the Selected list.

12.4.2 Select data elements

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

  1. Click Data and select Data elements.

  2. Select a data element group.

    The data elements in the selected group appear in the Available list.

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

    The data element moves to the Selected list.

12.4.3 Select reporting rates

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

  1. Click Data and select Reporting rates.

    The reporting rates appear in the Available list.

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

    The reporting rate moves to the Selected list.

12.4.4 Select fixed and relative periods

  1. Click Periods.

  2. Select one or several periods.

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

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

12.4.5 Select organisation units

  1. Click Organisation units.

  2. Click the gearbox icon.

  3. Select a Selection mode and an organisation unit.

    There are three different selection modes:

    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.

12.4.6 Select additional dimension items

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

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

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

12.5 Select series, category and filter

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

  1. Click Layout.

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

  3. Click Update.

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

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

  • Filter: The filter selection will filter the data displayed in the chart. 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.

</example>

12.6 Change the display of your chart

  1. Click Options.

  2. Set the options as required.

    Chart options

    Option

    Description

    Data

    Show values

    Shows the values above the series in the chart.

    Use 100% stacked values

    Displays 100 % stacked values in column charts.

    Use cumulative values

    Displays cumulative values in line charts.

    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.

    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 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 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.

    Aggregation type

    Defines how the data elements or indicators will be aggregated within the chart. Some of the aggregation types are By data element, Count, Min and Max.

    Events

    Include only completed events

    Includes only completed events in the aggregation process. This is useful when you want for example to exclude partial events in indicator calculations.

    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.

    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.

    Style

    No space between columns/bars

    Removes the space between the columns or bars in the chart. Useful for displaying the chart as an EPI curve.

    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.

12.7 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.

12.7.1 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.

12.7.2 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.

12.7.3 Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

12.7.4 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.

    • None: The public won’t have access to the object. This setting is only applicable to Public access.

  5. Click Share.

12.7.5 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.

12.7.7 Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

12.7.8 View interpretations based on relative periods

To view interpretations for relative periods, such as a year ago:

  1. Open a favorite with interpretations.

  2. Click >>> in the top right of the workspace.

  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.

12.8 Download a chart as an image or a PDF

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

  1. Click Download.

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

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

12.9 Download chart data source

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

To download plain data source formats:

  1. Click Download.

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

    Available formats

    Format

    Action

    Description

    JSON

    Click JSON

    Downloads JSON format based on ID property.

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

    XML

    Click XML

    Downloads XML format based on ID property.

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

    Microsoft Excel

    Click Microsoft Excel

    Downloads Microsoft Excel format based on ID property.

    You can also download Microsoft Excel format based on Code or Name property.

    CSV

    Click CSV

    Downloads CSV format based on ID property.

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

    JRXML

    Put the cursor on Advanced and click 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

    Put the cursor on Advanced and click 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.

12.10 Embed charts in any web page

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

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

  1. Click Share > Embed in web page.

    The Embed in web page window opens.

  2. Click Select to highlight the HTML fragment.

12.11 Open a chart as a pivot table or as a map

  • Open a Chart and click Chart or click Map.

13 Using the GIS app

13.1 About the GIS app

With the GIS 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 people.

Note

To use predefined legends in the GIS app, you need to create them first in the Maintenance app.

  • The icons in the top left of the workspace represent the map layers. They are the starting point of the GIS app.

  • The panel on the right side of the workspace shows an overview of the layers:

    • The default base map is OSM Light. It’s selected by default. If you’re online you’ll also see OpenStreetMap, Google Streets and Google Hybrid. You can use these maps as background maps and layers. Switch between them by selecting or clearing the checkbox.

    • If you want to increase or reduce the opacity of a layer, use the up and down arrows for the selected layer.

    • Use the map legends when you create a thematic map. A legend explains the link between values and colors on your map.

  • Zoom to content automatically adjusts the zoom level and map center position to put the data on your map in focus.

  • To view information for an event, simply click the event.

  • Right-click to display the longitude and latitude of the map.

13.2 Create a new thematic map

You use four vector layers to create a thematic map. The workflow for creating a new thematic map is:

  1. In the Apps menu, click GIS.

    The DHIS2 GIS window opens.

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

    • Event layer

    • Facility layer

    • Boundary layer

    • Thematic layer 1 - 4

  3. Click Edit layer and select the parameters you need..

  4. Click Update.

13.3 Manage event layers

The event layer displays the geographical location of events registered in the DHIS2 tracker. Provided that events have associated GPS 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.

13.3.1 Create or modify event layer

  1. In the top menu, click the event layer icon.

  2. Click Edit layer.

  3. Select a program and then select a program stage.

    If there is only one stage available for the selected program, the stage is automatically selected. A list of data elements and attributes will appear in the Available data items panel.

  4. Select any data element or attribute from this list as part of your query.

    • To select you can either double-click a data element or (multi) select and use the single-arrow downward button. The double-arrow button will select all data elements in the list. All selected data elements will get their own row in the Selected data items.

    • For data elements of type text you will get two choices: Contains implies that the query will match all values which contains your search value, and Is exact implies that only values which is completely identical to your search query will be returned.

    • For data elements of type option set, you can select any of the options from the drop down box by using the down-wards arrow or by start typing directly in the box to filter for options.

  5. In the Periods section, select the time span for when the events took place. You can select either a fixed period or a relative period.

    • Fixed period: In the Period field, select Start/end dates and fill in a start date and an end date.

    • Relative period: In the Period field, select one of the relative periods, for example This month or Last year.

  6. In the Organisation units section, select the organisation units you want to include in the query.

  7. In the Options section, you can:

    • 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.

    • Select or clear Clustering to group nearby events.

    • Go to Style to select a color for the cluster points or change the radius of clusters (between 1 and 20).

    Clustering if you want to group nearby events and change the style of the cluster points.

  8. Click Update.

13.3.2 Turn off cluster

By default events are clustered in a map. You can turn off this function to display all events separately.

  1. In the top menu, click the event layer icon.

  2. Click Edit layer.

  3. Click Options.

  4. Clear Group nearby events check box.

  5. Click Update.

13.3.3 Modify cluster style

  1. In the top menu, click the event layer icon.

  2. Click Edit layer.

  3. In the Options section, change the Point color and Point radius.

  4. Click Update.

13.3.4 Modify information in event pop-up windows

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

  1. Open the Programs / Attributes app.

  2. Click Program.

  3. Click the program you want to modify and select View program stages.

  4. Click the program stage name and select Edit.

  5. Scroll down to the Selected data elements section.

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

  7. Click Update.

13.4 Clear event layer

To clear all data in a map:

  1. In the top menu, click the event layer icon.

  2. Click Clear.

13.5 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. In GIS, a polygon is a shape defined by one or more rings, where a ring is a path that starts and ends at the same point.

13.5.1 Create or modify a facility layer

  1. In the top menu, click the facility layer icon.

  2. Click Edit layer.

  3. In the Organisation unit group icons section, select a Group set.

  4. In the Organisation units section, select one or several organisation units.

  5. In the Options section, select if you want to show labels and if so, how they look.

  6. In the Options section, select if you want to display a circle with a certain radius around each facility.

  7. Click Update.

13.5.2 Search for an organisation unit

To locate an organisation unit in the map:

  1. In the top menu, click the facility layer icon.

  2. Click Search.

    The Organisation unit search dialog box opens.

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

    The organisation unit is highlighted in the map.

13.5.3 Clear facility layer

To clear all data in a facility layer:

  1. In the top menu, click the facility layer icon.

  2. Click Clear.

13.6 Manage facilities in a layer

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

13.6.1 Relocate a facility

  1. Right-click a facility and click Relocate.

  2. Put the cursor in the new location.

    The new coordinate is stored permanently. This cannot be undone.

13.6.2 Swap longitude and latitude of a facility

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

    This is useful if a user inverted latitude and longitude coordinates when creating the organisation unit.

13.6.3 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 System Settings app.

13.7 Manage thematic layers 1- 4

There are four thematic layers in the GIS app. With these layers panels you can use your data for thematic mapping. Select your desired combination of indicator/data element, and period. then the 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 refresh the DHIS2 analytics tables to have aggregated data values available.

13.7.1 Create or modify a thematic layer

  1. In the top menu, click the icon of the thematic layer you want to create or modify.

  2. Click Edit layer.

  3. In the Data and periods section, select the data and periods you want to display.

  4. In the Organisation units section, select one or several organisation units.

  5. In the Options section, go to Legend type and select Automatic or Predefined.

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

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

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

      The legend appears as an even gradation from the start color to the end color.

    • If you have facilities in your thematic layer, you can set the radius for maximum and minimum values by changing the values in the Low color / size and High color size boxes.

  6. In the Options section, select if you want to show labels and if so, how they look.

  7. In the Options panel, select an aggregation type. See also Aggregation operators.

  8. Click Update.

13.7.2 Filter values in a thematic layer

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

To filter values in a thematic layer:

  1. In the top menu, click the icon of thematic layer you want to create or modify.

  2. Click Filter….

  3. Modify the Greater than and And/or lower than values.

  4. Click Update.

13.7.3 Search for an organisation unit

To locate an organisation unit in a thematic layer:

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

  2. Click Search.

    The Organisation unit search dialog box opens.

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

    The organisation unit is highlighted in the map.

13.7.5 Clear thematic layer

To clear all data in a thematic layer:

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

  2. Click Clear.

13.8 Manage boundary layers

The boundary layer displays the borders and locations of your organisation units. This layer is useful if you are offline and don’t have access to background maps.

13.8.1 Create or modify boundary layers

  1. In the top left menu, click the boundary layer icon.

  2. Click Edit layer.

  3. In the Organisation units section, select one or several organisation units.

    You can select the organisation units you want to show on the map by selecting a level and a parent. That means “show all organisations units at this level that are children of this parent”.

  4. In the Options section, select if you want to show labels and if so, how they look.

  5. Click Update.

13.8.2 Search for organisation units

To locate an organisation unit on the map:

  1. In the top menu, click the boundary layer icon.

  2. Click Search.

    The Organisation unit search dialog box opens.

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

    The organisation unit is highlighted in the map.

13.8.4 Clear boundary layer

To clear data in a boundary layer:

  1. In the top menu, click the boundary layer icon.

  2. Click Clear.

13.9 Manage Earth Engine layer

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

  • Elevation: Metres above sea level

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

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

  • Temperature, population and land cover at any location.

    Right-click on the layers to view more information, for example temperature and elevation.

</listitem> </itemizedlist>

13.9.1 Create or modify an Earth Engine layer

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

  2. Select a data set, for example “Elevation”.

  3. Select Min / max value.

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

  4. Select a Color scale.

  5. Select the number of Steps.

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

  6. Click Update.

13.10 Add external map layers

  1. In the top menu, click the External layer icon.

  2. Click Edit to add a new layer.

  3. Select a layer from the list.

  4. Click Update.

    To remove a layer, click Clear.

    To hide a layer, go to the Layer stack/opacity menu pane and clear the External layer checkbox.

Here are some examples of external layers:

Note

To define external map layers, see the Maintenance app documentation.

13.11 Manage map favorites

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

13.11.1 Save a map as a favorite

When you have created a map it is convenient to save it as a favorite:

  1. Click Favorites.

    The Manage favorites dialog box opens.

  2. Click Add new.

    The Create new favorite dialog box opens.

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

  4. Click Create.

    Your favorite is added to the list.

13.11.2 Open a favorite

  1. Click Favorites.

    The Manage favorites dialog box opens.

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

  3. Click the name.

13.11.3 Rename a favorite

  1. Click Favorites.

    The Manage favorites dialog box opens.

  2. Find the favorite you want to rename.

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

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

    The Rename favorite dialog box favorite opens.

  4. Type the new name and click Update.

13.11.4 Overwrite a favorite

To save the current map to an existing favorite (overwrite):

  1. Click Favorites.

    The Manage favorites dialog box opens.

  2. Find the favorite you want to overwrite.

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

  3. Click the green overwrite icon next to the favorite’s name.

  4. Click OK to confirm that you want to overwrite the favorite.

13.11.5 Share a map interpretation

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

To create an interpretation of a map and share it with all users of the system:

  1. Open or create a favorite map.

  2. Click Share > Write interpretation.

    The Write interpretation dialog box opens.

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

  4. Click Share.

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

13.11.6 Modify sharing settings for a favorite

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

  1. Click Favorites.

  2. Find the favorite you want to share.

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

  3. Click the blue share icon next to the favorite’s name.

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

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

    Repeat the step to add more user groups.

  5. If you want to allow external access, select the corresponding box.

  6. For each user group, choose an access setting. The options are:

    • None

    • Can view

    • Can edit and view

  7. Click Save.

13.11.7 Delete a favorite

  1. Click Favorites.

    The Manage favorites dialog box opens.

  2. Find the favorite you want to delete.

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

  3. Click the red delete icon next to the favorite’s name.

  4. Click OK to confirm that you want to delete the favorite.

13.12 Save a map as an image

  1. Take a screenshot of the map with the tool of your choice.

  2. Save the screenshot in desired format.

13.13 Embed a map in an external web page

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

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

  1. Click Share > Embed in web page.

    The Embed in web page window opens.

  2. Click Select to highlight the HTML fragment.

13.15 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 icon and click Create new measurement.

  2. Add points to the map.

  3. Click Finish measurement.

13.16 Get the latitude and longitude at any location

Right-click a map and select Show longitude/latitude. The values display in a pop-up window.

13.17 View a map as a pivot table or chart

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

13.17.1 Open a map as a chart

  1. Click Chart > Open this map as chart.

    Your current map opens as a chart.

13.17.2 Open a map as a pivot table

  1. Click Chart > Open this map as table.

    Your current map opens as a pivot table.

13.18 See also

14 Using the Maps app

14.1 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.

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, Google Streets and Google Hybrid are also available. You can use these maps as background maps and layers. Switch between them by selecting the desired image.

    • 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 can also be used for altering the zoom.

  • 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 find the distance between two locations on the map.

  • To view information for an event, simply click the event.

  • 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

14.2 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:

    In addition, there are several layers provided by Google Earth Engine and other services:

    • Population density

    • Elevation

    • Temperature

    • Precipitation

    • Landcover

    • Nighttime lights

    Labels overlay is an external layer defined in the Maintenance app.

14.3 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

  • An eye symbol for toggling the visibility of the layer

  • A slider for modifying the layer transparency

  • 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.

14.3.1 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

    • select the time span over which the thematic data is aggregated. You can select either a fixed period or a relative period.

      • Fixed period

        In the Period type field select period length, then select the target in the Period field.

      • Relative period

        In the Period type field select Relative, then select one of the relative periods, for example This month or Last year, 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:

    • 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.

  1. In the STYLE tab:

    • 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.

  2. Click ADD LAYER.

14.3.2 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.

14.3.3 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

      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.

14.3.4 Search for an organisation unit

The NAME filter field in the data table provides an effective way of searching for individual organisation units.

14.3.6 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.

14.4 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.

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:

  • 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 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:

  • An edit (pencil) button to open the layer configuration dialog

  • An eye symbol for toggling the visibility of the layer

  • A slider for modifying the layer transparency

  • A more actions (three dots) button with additional options:

    • 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.

14.4.1 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:

    • 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.

  2. In the PERIOD tab

    • 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.

  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, 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:

    • 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 og 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.

  5. In the STYLE tab:

    • 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. 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.

14.4.2 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.

  3. Click UPDATE LAYER.

14.4.3 Modify information in event pop-up windows

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

  1. Open the Programs / Attributes app.

  2. Click Program.

  3. Click the program you want to modify and select View program stages.

  4. Click the program stage name and select Edit.

  5. Scroll down to the Selected data elements section.

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

  7. Click Update.

14.4.4 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.

  • 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.

14.4.5 Clear event layer

To clear all event layer data in a map:

  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.

14.5 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:

  • An edit (pencil) button to open the layer configuration dialog

  • An eye symbol for toggling the visibility of the layer

  • A slider for modifying the layer transparency

  • A more actions (three dots) button with additional options:

    • Edit layer is the same as edit button above

    • Remove layer will remove this layer from the current map.

14.5.1 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

    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 diplay on the map from the dropdown list. Only relationships FROM the selected Tracked Entity type are available.

  3. In the PERIOD tab

    • 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.

  4. In the ORG UNITS tab:

    • 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.

  5. In the STYLE tab:

    • 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.

14.5.2 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.

  3. Click UPDATE LAYER.

14.5.3 Clear a tracked entity layer

To clear a tracked entity layer from a map:

  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.

14.6 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:

  • A grab field to allow dragging and re-ordering layers with the mouse

  • The Facilities title

  • An eye symbol for toggling the visibility of the layer

  • 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:

  • An edit (pencil) button to open the layer configuration dialog

  • A slider for modifying the layer transparency

  • 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.

14.6.1 Create a facility layer

To create facility layer, choose Facilities on the Add layerselection. 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

    • select the organisation unit level(s) and/or group(s) from the selection fields on the right hand side.

    • Select the organisation units you want to include in the layer. It is possible to select either

      • One or more specific organisation units, 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.

  3. In the STYLE tab:

    • 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.

14.6.2 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.

  3. Click UPDATE LAYER.

14.6.3 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.

The data table displays the data forming the facility 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

    • ID

      filter by IDs containing the given text

    • TYPE

      filter by GIS display types containing the given text

Note

Data table filters are temporary and are not saved with the map layers as part of the favourite.

14.6.4 Search for a facility

The NAME filter field in the data table provides an effective way of searching for individual facilities.

14.6.5 Remove facility layer

To clear all data in a facility 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.

14.6.6 Manage facilities in a layer

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

14.6.6.1 Relocate a facility

  1. Right-click a facility and click Relocate.

  2. Put the cursor in the new location.

    The new coordinate is stored permanently. This cannot be undone.

14.6.6.2 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.

14.6.6.3 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 System Settings app.

14.7 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.

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:

  • A grab field to allow dragging and re-ordering layers with the mouse

  • 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:

  • An edit (pencil) button to open the layer configuration dialog

  • An eye symbol for toggling the visibility of the layer

  • A slider for modifying the layer transparency

  • 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.

14.7.1 Create a boundary layer

To create boundary layer, choose Boundaries on the Add layerselection. This opens the Boundary layer configuration dialog.

  1. In the ORGANISATION UNITS tab

    • select the organisation unit level(s) and/or group(s) from the selection fields on the right hand side.

    • Select the organisation units you want to include in the layer. It is possible to select either

      • One or more specific organisation units, 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.

  2. In the STYLE tab:

    • 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.

14.7.2 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.

  3. Click UPDATE LAYER.

14.7.3 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.

The data table displays the data forming the boundary 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

    • LEVEL

      filter level by numbers and/or ranges, for example: 2,>3&<8

    • PARENT

      filter by parent names containing the given text

    • ID

      filter by IDs containing the given text

    • TYPE

      filter by GIS display types containing the given text

Note

Data table filters are temporary and are not saved with the map layers as part of the favourite.

14.7.4 Search for an organisational unit

The NAME filter field in the data table provides an effective way of searching for individual organisational units displayed in the boundary layer.

14.7.6 Remove boundary layer

To clear all data in a boundary 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.

14.8 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 representes the terrain in your region.

  • Temperature: Land surface temperatures collected from satellite. Blank spots will appear in areas with a persistent cloud cover.

  • Precipitation collected from satellite and weather stations on the ground. The values are in millimeters within 5 days periods. Updated monthly, during the 3rd 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).

14.8.1 Create an Earth Engine layer

To create an Earth Engine layer, choose the desired layer from the Add layerselection. 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.

14.9 Add external map layers

External map layers are represented as either:

  • Basemaps

    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:

  • A grab field to allow dragging and re-ordering layers with the mouse

  • 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 slider for modifying the layer transparency

  • A delete (trash can) icon to remove the layer from the current thematic map.

Here are some examples of external layers:

14.10 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.

14.10.1 Create a new map

Click File > New.

NB! This will clear the current map layers you have without saving.

14.10.2 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.

14.10.3 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.

14.10.4 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.

14.10.5 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.

14.10.6 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.

14.10.7 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.

  4. For each user group, choose an access setting. The options are:

    • None (for default groups only, as they cannot be removed)

    • Can view

    • Can edit and view

  5. Click CLOSE to close the dialog.

14.10.9 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.

14.11 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.

14.11.1 View interpretations based on relative periods

To view interpretations for relative periods, such as a year ago:

  1. Open a favorite with interpretations.

  2. Click Interpretations in the top right of the workspace to open the interpretations panel.

  3. Click an interpretation. Your map displays the data and the date based on when the interpretation was created. To view other interpretations, click them.

14.11.2 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.

  1. Open a favorite with interpretations.

  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.

  4. 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.

  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.

14.11.3 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:

    • Can edit and view: Everyone can view and edit the object.

    • Can view only: Everyone can view the object.

    • 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.

14.12 Save a map as an image

You can download your map as an image by clicking on the Download button in the top menu

Map download is not supported in Internet Explorer or Safari, we recommend to use Google Chrome og 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 inclide the map legend. You can position the legend in one of the 4 corners of your map.

  3. Click Download to download your map.

14.14 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.

14.15 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.

14.16 See also

15 Using the Event Reports app

15.1 About the Event Reports app

With the Event Reports 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.

15.2 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.

    You can keep the default selection if you want.

  5. Click Update.

15.3 Select dimension items

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.

    3. Select a Selection mode and an organisation unit.

      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.

15.4 Select series, category and filter

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 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.

15.5 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 totals

    Displays totals at the end of each column in the pivot table.

    Aggregated event report

    Show column sub-totals

    Displays sub-totals for each column in the pivot table.

    Aggregated event report

    Show row totals

    Displays totals at the end of each row in the pivot table.

    Aggregated event report

    Show row sub-totals

    Displays sub-totals for each row in the pivot table.

    Aggregated event report

    Show dimension labels

    Displays labels for dimensions.

    Aggregated event report

    Hide empty rows

    Hides empty rows in the pivot table.

    Aggregated event report

    Hide n/a data

    Hides data tagged as N/A from the chart.

    Aggregated event report

    Include only completed events

    Includes only completed events in the aggregation process. This is useful when you want for example to exclude partial events in indicator calculations.

    Aggregated event report

    Individual event report

    Limit

    Sets a limit of the maximum number of rows that you can display in the table, combined with a setting for showing top or bottom values.

    Aggregated event report

    Output type

    Defines the output type. The output types are Event, Enrollment andTracked entity instance.

    Aggregated event report

    Program status

    Filters data based on the program status: All, Active, Completed or Cancelled.

    Aggregated event report

    Event status

    Filters data based on the event status: All, Active, Completed, Scheduled, Overdue or Skipped.

    Aggregated event report

    Organisation units

    Show hierarchy

    Includes the names of all parents of each organisation unit in labels.

    Aggregated event report

    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.

    Aggregated event report

    Individual event report

    Font size

    Controls the size of the table text font. You can set it to Large, Normal or Small.

    Aggregated event report

    Individual event report

    Digit group separator

    Controls which character to separate groups of digits or “thousands”. You can set it to Comma, Space or None.

    Aggregated event report

    Individual event report

  3. Click Update.

15.6 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.

  2. Under Plain data source, click the format you want to 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

15.7 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.

15.7.1 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.

15.7.2 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.

15.7.3 Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

15.7.4 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.

    • None: The public won’t have access to the object. This setting is only applicable to Public access.

  5. Click Share.

15.7.5 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.

15.7.7 Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

15.7.8 View interpretations based on relative periods

To view interpretations for relative periods, such as a year ago:

  1. Open a favorite with interpretations.

  2. Click >>> in the top right of the workspace.

  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.

15.8 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.

16 Using the Event Visualizer app

16.1 About the Event Visualizer app

With the Event Visualizer app, you can create charts based on event data.

16.2 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.

    You can keep the default selection if you want.

  4. Click Update.

16.3 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.

    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.

16.4 Select dimension items

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.

      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

      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.

16.5 Select series, category and filter

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.

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

  3. Click Update.

16.6 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 values

    Displays 100 % stacked values in 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 events

    Includes only completed events in the 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.

    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 andTracked entity instance.

    Program status

    Filters data based on the program status: All, Active, Completed or Cancelled.

    Event status

    Filters data based on the event status: All, Active, Completed, Scheduled, Overdue 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.

    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.

16.7 Download a chart as an image or a PDF

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

  1. Click Download.

  2. Under Graphics, click 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.

16.8 Download chart data source

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 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

    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

16.9 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.

16.9.1 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.

16.9.2 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.

16.9.3 Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

16.9.4 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.

    • None: The public won’t have access to the object. This setting is only applicable to Public access.

  5. Click Share.

16.9.5 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.

16.9.7 Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

16.9.8 View interpretations based on relative periods

To view interpretations for relative periods, such as a year ago:

  1. Open a favorite with interpretations.

  2. Click >>> in the top right of the workspace.

  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.

16.10 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.

17 Control data quality

17.1 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.

17.2 Validation rule analysis

17.2.1 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

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.

17.2.2 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 Data Administration app, you schedule the validation rule analysis to run automatically for all validation rules included in one or several validation notifications. 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).

17.2.3 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 Data Administration app and click Scheduling.

  3. If scheduling is active, click Stop.

  4. In the Data monitoring section, select All daily.

  5. Click Start.

17.2.4 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

  7. Select a Parent organisation unit.

  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.

17.2.5 See also

17.3 Standard deviation outlier analysis

17.3.1 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, whether the data actually is normally distributed before running a standard deviation outlier analysis.

17.3.2 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.

    The analysis process duration depends on the amount of data that is being analysed. If there are standard deviations outliers, they will be presented in a list.

    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.

17.4 Minimum maximum outlier analysis

17.4.1 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.

17.4.2 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.

17.4.3 Configure a minimum maximum outlier analysis

17.4.3.1 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.

  3. Select data set(s).

  4. Select an Organisation unit.

  5. Click Generate.

    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.

17.4.3.2 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.

  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

Click the star icon to mark the value for further follow-up.

17.4.3.3 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.

  2. Select data set(s).

  3. Select an Organisation unit. Note, that the selection cascades to descendant organisation units!

  4. Click Remove.

17.4.4 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.

  5. 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.

  6. Click Start.

    The analysis process duration depends on the amount of data that is being analysed. If there are validation violations, they will be presented in a list.

  7. (Optional) Click Download as PDF, Download as Excel or Download as CSV to download the list in PDF, Excel or CSV formats.

Tip

Click the star icon to mark the value for further follow-up.

17.5 Follow-up analysis

17.5.1 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.

17.5.2 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.

    The analysis process duration depends on the amount of data that is being analysed. If 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.

  6. (Optional) Click Download as PDF, Download as Excel or Download as CSV to download the validation violations list in PDF, Excel or CSV formats.

Tip

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.

18 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 (c) 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
Approving at organisation units

18.1 Approving and accepting

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:

Approving and accepting
Approving and accepting

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.

18.2 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.

18.3 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.

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.

On the System Approval Settings page, you may select the option Hide unapproved data in analytics to hide unapproved data in reports, pivot table, data visualizer and GIS. If this option is checked, unapproved data will be hidden from users assigned to higher-level organisation units compared to where approval is required. Users who are assigned to organisation units where data is ready for approval can still view the data, as can users assigned to higher-level organisation units if they have the Approve data at lower levels authority. If this option is not checked, then all data is shown whether approved or not.

18.4 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
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.

  • 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.

18.5 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.

18.6 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.

18.6.1 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 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
Partner Partner 2 Account 2A, Account 2B

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
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

18.7 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
Partner Partner 1 Account 1A, Account 1B
Partner Partner 2 Account 2A, Account 2B
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.

19 Using reporting functionality

19.1 Reporting functionality in DHIS2

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

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

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

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

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

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

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

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

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

19.2 Using standard reports

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

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

19.3 Using dataset reports

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

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

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

Dataset: The data set you want to display.

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

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

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

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

19.4 Using resources

The resource tool allows you to upload both files from your local computer to the DHIS server and to add links to other resources on the Internet through URLs. If cloud storage is configured for your system, resources will be saved there.

To create a new resource:

  1. Open the Reports app and click Resource.

  2. Click Add new.

  3. Enter a Name.

  4. Select a Type: Upload file or External URL.

  5. Click Save.

19.5 Using reporting rate summary

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

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

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

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

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

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

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

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

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

To run the report you can follow these steps:

  • Select an orgunit from the tree.

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

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

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

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

19.6 Using organisation unit distribution reports

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

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

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

Running a report:

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

19.7 Generate analytics tables

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.

  4. Click Start export.

20 Reporting functionality in the Beta Reports app

A new Reports app (Beta) is introduced in release 2.32 and serves as an optional replacement of the original Reports app, offering a more intuitive and user-friendly interface. Unlike the previous Reports app, however, it does not support Data Approvals.

20.1 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.

20.2 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.

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.

20.3 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.

20.4 Using resources

The resource tool allows you to upload both files from your local computer to the DHIS server and to add links to other resources on the Internet through URLs. If 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.

20.5 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.

21 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.

22 Manage users, user roles and user groups

22.1 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 specific tasks

Create a new data element

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

Object type

Available functions

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

22.1.1 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.

22.1.2 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.

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.

22.1.3 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

22.2 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.

22.3 Manage users

22.3.1 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:

  • 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.

  • 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.

    In order to use this feature “Enable email message notifications” in SystemSettings -> Messaging should be checked.

    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.

  5. Select Data capture and maintenance organisation units.

    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 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.

22.3.2 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.

  3. Modify the options you want.

  4. Click Save.

22.3.3 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.

22.3.4 Display a user’s profile

  1. Open the Users app and click User.

  2. In the list, click the menu icon of the relevant user and select Profile.

22.3.5 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.

22.3.6 Clone users

  1. Open the Users app and click User.

  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.

  6. Modify the options you want.

  7. Click Save.

22.3.7 Change user password

The following rules apply when you create a new password:

  • Password must contain at least one special character, that is any character other then alphabets and digit numbers.

  • Password must contain at least one upper case character.

  • Password must contain at least one digit number.

  • Password can not contain user’s user name or email address.

  • Password can not contain generic words for example system, admin, user, login, manager etc.

  • Password can not be one of the previous 24 passwords the user has used.

    This doesn’t apply in case a super user resets the password for another user.

  • Password must contain more than minimum number of characters.

    Note

    You can configure the minimum number of characters: Open the System Settings app and click Access > Minimum characters in password.

  • Password can not contain more than 40 characters

To change a user’s password:

  1. Open the Users app and click User.

  2. In the object list, click the menu icon of the relevant user and select Edit.

  3. Enter a new password and retype it.

  4. Click Save.

22.3.8 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.

  3. Click OK to confirm.

22.3.9 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.

22.3.10 Disable a user’s Two Factor Authentication

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

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.

22.4 Manage user roles

22.4.1 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.

22.4.2 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.

  3. Modify the options you want.

  4. Click Save.

22.4.3 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.

  3. Click OK to confirm.

22.4.4 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.

22.4.5 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.

  • None
  • Can view: Everyone in the user group can view the object
  • Can edit and view: Everyone in the user group can view and edit the object
  1. Click Save.

22.5 Manage user groups

22.5.1 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.

22.5.2 Join user groups

  1. Open the Users app and click User group.

  2. In the list, click the relevant user group and select Join group.

22.5.3 Leave user groups

  1. Open the Users app and click User group.

  2. In the list, click the relevant user group and select Leave group.

22.5.4 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.

  3. Modify the options you want.

  4. Click Save.

22.5.5 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.

  3. Click OK to confirm.

22.5.6 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.

22.5.7 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.

  • None
  • Can view: Everyone in the user group can view the object
  • Can edit and view: Everyone in the user group can view and edit the object
  1. Click Save.

22.6 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.

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.

22.7 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.

22.8 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:

Position

Typical tasks

Recommended authorities

Comment

System administrators

Set up the basic structure (metadata) of the system.

Add, update and delete the core elements of the system, for example data elements, indicators and data sets.

Only system administrators should modify metadata.

If you allow users outside the system 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

Province health managers

Monitor and analyse data

Access to the reports module, the GIS, Data Quality apps and the dashboard.

Don’t need access to enter data, modify data elements or data sets.

National health information system division officers (HISO)

District health records and information officers (DHRIO)

Facility health records and information officers (HRIO)

Enter data that comes from facilities which are not able to do so directly

Monitor, evaluate and analyse data

Access to all the analysis and validation apps

Access to the Data Entry app.

-

Data entry clerks

-

-

-

23 Visualize usage statistics

23.1 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?

23.2 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.

    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.

24 Configure metadata

24.1 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.

24.2 Manage categories

24.2.1 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

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

24.2.2 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.

24.2.3 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. Short name

    3. Start date

    4. 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.

24.2.4 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.

  2. Click the add button.

  3. Fill in the form:

    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.

24.2.5 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Code

    3. Data dimension type

    4. Skip category total in reports

  4. Select categories and assign them.

  5. Click Save.

24.2.6 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Short name: Define a short name for the data element.

    3. Code

    4. Data dimension type

  4. Select Category options and assign them.

  5. Click Save.

24.2.7 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Description

    3. Data dimension

    4. Data dimension type

  4. Select Category option groups and assign them.

  5. Click Save.

24.2.8 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.

24.2.9 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.

  2. In the list, find the object you want to modify.

  3. Click the options menu and select Edit.

  4. Enter a code.

  5. Click Save.

24.2.10 Clone metadata objects

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.

24.2.11 Change sharing settings for metadata objects

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.

24.2.12 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.

24.2.13 Display details of metadata objects

  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.

24.2.14 Translate metadata objects

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.

24.3 Manage data elements

24.3.1 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

Object type

Available functions

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

24.3.2 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.

24.3.3 Create or edit a data element

  1. Open the Maintenance app and click Data elements > Data element.

  2. Click the add button.

  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. 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.

  10. In the Domain type field, select whether the data element is an aggregate or tracker type of data element.

  11. 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.

    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.

    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.

    Yes/No

    Boolean values, renders as drop-down lists in data entry.

    Yes only

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

  12. 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.

    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.

  13. 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.

  14. 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.

  15. In the Category combination field, define which category combination the data element should have. This is also known as the “disaggregation”.

  16. Select an Option set.

    Option sets are predefined lists of options which can be used in data entry.

  17. 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.

  18. Assign one or multiple Legends.

    Legends are used in for example the GIS app to display certain data elements with certain icons.

  19. 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.

  20. If applicable, enter custom attributes values, for example Classification or Collection method.

    Note

    You create custom attributes in the Maintenance app: Other > > Attributes.

  21. 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.

  22. Click Save.

24.3.4 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Short name

    3. Code

  4. Select data elements and assign them.

  5. Click Save.

24.3.5 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Code

    3. Description

    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.

24.3.6 Clone metadata objects

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.

24.3.7 Change sharing settings for metadata objects

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.

24.3.8 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.

24.3.9 Display details of metadata objects

  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.

24.3.10 Translate metadata objects

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.

24.4 Manage data sets and data entry forms

24.4.1 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
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)

  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:

  1. Section form (if it exists)

  2. Default form

In the Maintenance app, you manage the following data set objects:

Data set objects in the Maintenance app

Object type

Available functions

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

24.4.2 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.

24.4.3 Create or edit a data set

  1. Open the Maintenance app and click Data set > Data set.

  2. Click the add button.

  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.

  5. (Optional) In the Code field, assign a code.

  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.

  8. If you want it to be possible to enter data for future periods, type the number of periods in 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.

    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.

  24. Select data elements and assign them.

    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).

24.4.4 Create or edit Data set Notification

  1. Open the Maintenance app and click Data set > Data set notification.

  2. Click the add button.

24.4.4.1 What to send?

  1. In the Name field, type the precise name of the data set notification.

  2. (Optional) In the Code field, assign a code.

  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.

24.4.4.2 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

24.4.4.3 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 address exist for that user and SMS/EMAIL notifications are enabled in SystemSettings

24.4.5 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.

  1. Open the Maintenance app and click Data set > Data set.

  2. In the list, find the data set you want to modify.

  3. Click the options menu and select Edit.

  4. Go to the data elements section and click the spanner icon.

  5. Select new category combinations and click Close.

  6. Click Save.

24.4.6 Edit compulsory data elements in a data set

You can add or remove data elements which will be marked as compulsory during data entry.

  1. Open the Maintenance app and click Data set > Data set.

  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.

24.4.7 Download default data forms in PDF format

You can download a default data from in PDF format for offline data entry.

  1. Open the Maintenance app and click Data set > Data set.

  2. In the list, find the object you want to download.

  3. Click the options menu and select Get PDF for data entry.

24.4.8 Manage section forms

24.4.8.1 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.

  1. Open the Maintenance app and click Data set > Data set.

  2. In the list, find the data set you want to create a section form for.

  3. Click the options menu and select Manage sections.

  4. Click the add button.

  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.

    2. Select data elements and assign them.

  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.

24.4.8.2 Edit a section form

  1. Open the Maintenance app and click Data set > Data set.

  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.

  5. Click the options menu and select Edit.

  6. Edit the section and click Save.

  7. Repeat edit section steps for each section you want to edit.

24.4.8.3 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.

  1. Open the Maintenance app and click Data set > Data set.

  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.

  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.

24.4.8.4 Change section display order in a section form

You can control in which order sections are displayed in a section form.

  1. Open the Maintenance app and click Data set > Data set.

  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 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.

24.4.8.5 Delete a section in a section form

  1. Open the Maintenance app and click Data set > Data set.

  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 delete.

  5. Click the options menu and select Delete.

24.4.8.6 Translate a section in a section form

  1. Open the Maintenance app and click Data set > Data set.

  2. In the list, find the data set you want to edit the section form for.

  3. Click the options menu and select Translate.

  4. Select a locale.

  5. Enter the required information.

  6. Click Close.

24.4.9 Manage custom forms

24.4.9.1 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/.

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.

24.4.9.2 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.

24.4.9.2.1 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.

Data entry events
Key Description Arguments

dhis2.de.event.formLoaded

Triggered after the data entry form is rendered, but before data values are set in entry fields.

Event | Data set ID

dhis2.de.event.dataValuesLoaded

Triggered after data values are set in entry fields.

Event | Data set ID

dhis2.de.event.formReady

Triggered when the data entry form is completely rendered and loaded with all elements.

Event | Data set ID

dhis2.de.event.dataValueSaved

Triggered when a data value is saved successfully.

Event | Data set ID | Data value object

dhis2.de.event.completed

Triggered when a data set is successfully marked as complete.

Event | Data set ID | Complete registration object

dhis2.de.event.uncompleted

Triggered when a data set is successfully marked as incomplete.

Event | Data set ID

dhis2.de.event.validationSuccess

Triggered when validation is done and there were no violations.

Event | Data set ID

dhis2.de.event.validationError

Triggered when validation is done and there were one or more violations.

Event | Data set ID

dhis2.ou.event.orgUnitSelected

Triggered when one or more organisation units are selected in the org unit web tree.

Event | Org unit IDs | Org unit names | Sub org unit 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 );
} );

</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.

24.4.9.2.2 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:

var sel = dhis2.de.api.getSelections();
 +var orgUnit = sel["ou"];
 +var partner = sel["LFsZ8v5v7rq"];

24.4.10 Change sharing settings for metadata objects

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.

24.4.11 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.

24.4.12 Display details of metadata objects

  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.

24.4.13 Translate metadata objects

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.

24.5 Manage indicators

24.5.1 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

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.

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-expr)

Evaluates the boolean 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.

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

Object type

Available functions

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

24.5.2 Workflow

  1. Create indicator types.

  2. Create indicators.

  3. Create indicator groups.

  4. Create indicator group sets.

24.5.3 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.

  2. Click the add button.

  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.

24.5.4 Create or edit an indicator

  1. Open the Maintenance app and click Indicator > Indicator.

  2. Click the add button.

  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.

  5. (Optional) In the Code field, assign a code.

    In many countries indicators are assigned a code.

  6. (Optional) In the Color field, assign a color to reprersent the indicator.

  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.

  12. (Optional) Assign one or multiple Legends.

  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.

  18. Click Edit denominator.

    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.

24.5.5 Create or edit an indicator group

  1. Open the Maintenance app and click Indicator > Indicator group.

  2. Click the add button.

  3. Type a name.

  4. Select indicators and assign them.

  5. Click Save.

24.5.6 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.

  2. Click the add button.

  3. Fill in the form:

    1. Name

    2. Description

    3. Compulsory

  4. Select indicator groups and assign them.

    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.

24.5.7 Clone metadata objects

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.

24.5.8 Change sharing settings for metadata objects

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.

24.5.9 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.

24.5.10 Display details of metadata objects

  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.

24.5.11 Translate metadata objects

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.

24.6 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

  • Modify the organisation unit hierarchy

24.6.1 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.

  • 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.

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

Object type

Available functions

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

24.6.2 Workflow

The recommended workflow is:

  1. Create organisation units.

  2. Create organisation unit groups.

  3. Create organisation unit group sets.

24.6.3 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.

  2. Click the add button.

  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.

    You must have latitude and longitude values to create maps in the GIS app. Then your organisation units can be represented as points on a map, for example a health facility. Without this information, the GIS 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.

24.6.4 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.

  2. Click the add button.

  3. Fill in the form:

    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

    4. Symbol: Select a symbol which will be used to display the organisation unit (points only) when the layer is displayed in the GIS 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.

24.6.5 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 organisation unit group set.

  • 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 organisation unit group set.

  1. Open the Maintenance app and click Organisation unit > Organisation unit group set.

  2. Click the add button.

  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.

    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.

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 organisation unit group set.

You don’t change the organisation unit hierarchy

Scalable and dynamic

Dynamic inclusion of hierarchy

Dynamic additional classification

24.6.6 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”, “District” or “Health Facility”. DHIS2 uses the contextual names anywhere levels are referred to, for example in the GIS 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.

24.6.7 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.

24.6.8 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.

24.6.9 Clone metadata objects

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.

24.6.10 Change sharing settings for metadata objects

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.

24.6.11 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.

24.6.12 Display details of metadata objects

  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.

24.6.13 Translate metadata objects

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.

24.7 [Work in progress] Manage validation rules

24.7.1 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.

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

24.7.1.1 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 (periodType).

Data selection is always based on a period.

The position of the sliding window is alwaysrelative to the period being compared.

Data is always selected for the same period as the period being compared.

See also: How to use sliding windows when you’re Creating or editing a validation rule.

24.7.1.2 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.

24.7.1.3 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.

24.7.2 Create or edit a validation rule

  1. Open the Maintenance app and click Validation > Validation rule.

  2. Click the add button.

  3. Type a Name.

    The name must be unique among the validation rules.

  4. (Optional) In the Code field, assign a code.

  5. (Optional) Type a Description.

  6. Select an Importance: High, Medium or Low.

  7. Select a Period type.

  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.

    2. Select Sliding window if you want to view data relative to the period you are 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 Exclusive 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.

    2. 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 Exclusive 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.

    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.

24.7.3 Create or edit a validation rule group

  1. Open the Maintenance app and click Validation > Validation rule group.

  2. Click the add button.

  3. Type a Name.

  4. (Optional) In the Code field, assign a code.

  5. (Optional) Type a Description.

  6. Double-click the Validation rules you want to assign to the group.

  7. Click Save.

24.7.4 Create or edit a validation notification

  1. Open the Maintenance app and click Validation > Validation notification.

  2. Click the add button.

  3. Type a Name.

  4. (Optional) In the Code field, assign a code.

  5. Select Validation rules.

  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.

24.7.5 Clone metadata objects

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.

24.7.6 Change sharing settings for metadata objects

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.

24.7.7 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.

24.7.8 Display details of metadata objects

  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.

24.7.9 Translate metadata objects

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.

24.8 Manage attributes

24.8.1 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

Object type

Available functions

Attribute

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

24.8.2 Create or edit an attribute

  1. Open the Maintenance app and click Attribute.

  2. Click the add button.

  3. In the Name field, type the name of the attribute.

    Each attribute must have a unique name

  4. (Optional) In the Code field, assign a code.

  5. Select a Value type.

    If the value supplied for the attribute does not match the value type you will get a warning.

  6. Select an Option set.

  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.

24.8.3 Clone metadata objects

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.

24.8.4 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.

24.8.5 Display details of metadata objects

  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.

24.8.6 Translate metadata objects

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.

24.9 Manage constants

24.9.1 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.

In the Maintenance app, you manage the following constant objects:

Constant objects in the Maintenance app

Object type

Available functions

Constant

Create, edit, clone, share, delete, show details and translate

24.9.2 Create or edit a constant

  1. Open the Maintenance app and click Other > Constant.

  2. Click the add button.

  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.

  5. (Optional) In the Code field, assign a code.

  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.

24.9.3 Clone metadata objects

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.

24.9.4 Change sharing settings for metadata objects

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.

24.9.5 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.

24.9.6 Display details of metadata objects

  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.

24.9.7 Translate metadata objects

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.

24.10 Manage option sets

24.10.1 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”.

Option set objects in the Maintenance app

Object type

Available functions

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

24.10.2 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.

  2. Click the add button.

  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.

    3. Select a Value type.

    4. Click Save.

  4. For each option you need, perform the following tasks:

    1. Click the Options tab.

    2. Click the add button.

    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.

24.10.3 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.

  2. Click the add button.

  3. Fill in the form:

    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.

24.10.4 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.

  2. Click the add button.

  3. Fill in the form:

    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.

24.10.5 Clone metadata objects

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.

24.10.6 Change sharing settings for metadata objects

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.

24.10.7 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.

24.10.8 Display details of metadata objects

  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.

24.10.9 Translate metadata objects

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.

24.11 Manage legends

24.11.1 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 GIS 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.

24.11.2 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.

  2. Click the add button.

  3. In the Name field, type the legend name.

  4. (Optional) In the Code field, assign a code.

  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:

    1. Click the add button.

    2. Enter a name and select a start value, an end value and a color.

    3. Click OK.

  7. (Optional) Change the color scales.

    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

24.11.3 Clone metadata objects

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.

24.11.4 Change sharing settings for metadata objects

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.

24.11.5 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.

24.11.6 Display details of metadata objects

  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.

24.11.7 Translate metadata objects

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.

24.11.8 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 GIS app, the system automatically selects the assigned legend.

24.11.9 See also

24.12 Manage predictors

24.12.1 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

Object type

Available functions

Predictor

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

24.12.2 Sampling past periods

Predictors can generate data values for periods that are in the past, present, or future. These values are based on data sampled from periods before the predicted period, and/or data from the predicted period. When you use data sampled from past periods (periods before the predicted period), several parameters determine the choice of which past periods to sample from:

24.12.2.1 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:

24.12.2.2 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:

24.12.2.3 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 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.

24.12.2.4 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:

24.12.2.5 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:

24.12.2.6 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:

24.12.3 Create or edit a predictor

  1. Open the Maintenance app and click Other > Predictor.

  2. Click the add button.

  3. In the Name field, type the predictor name.

  4. (Optional) In the Code field, assign a code.

  5. (Optional) Type a Description.

  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. Select a Period type.

  8. 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.

  9. Create a Generator. The generator is the expression that is used to calculate the predicted value.

    1. Type a Description of the generator expression.

    2. 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:

      Aggregate function

      Means

      AVG

      Average (mean) value

      COUNT

      Count of the data values

      MAX

      Maximum value

      MEDIAN

      Median value

      MIN

      Minimum value

      STDDEV

      Standard deviation

      SUM

      Sum of the values

      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 functions in your expression, either inside or containing aggregate functions, or independent of them:

      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 false, returns the valueIfFalse expression.

      ISNULL(item)

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

      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

      AVG(#{FTRrcoaog83}) + 2 * STDDEV(#{FTRrcoaog83})

      Average of the sampled values of of data element FTRrcoaog83 (sum of all disaggregations) plus twice its 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}), 10, 20)

      If the data element T7OyqQpUpNd is null, then 10, otherwise 20.

  10. (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 functions IF() and ISNULL() as described above may also be used.

      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} || #{uF1DLnZNlWe} > 0

      The value of data element FTRrcoaog83 (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

  11. 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.

  12. 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.

  13. (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.

  14. Click Save.

24.12.4 Create or edit a predictor group

  1. Open the Maintenance app and click Other > Predictor group.

  2. Click the add button.

  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.

  5. (Optional) Type a Description.

  6. Double-click the Predictors you want to assign to the group.

  7. Click Save.

24.12.5 Clone metadata objects

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.

24.12.6 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.

24.12.7 Display details of metadata objects

  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.

24.12.8 Translate metadata objects

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.

24.13 Manage push reports

24.13.1 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.

In the Maintenance app, you manage the following push reports objects:

Push reports objects in the Maintenance app

Object type

Available functions

Push analysis

Create, edit, clone, delete, show details, translate, preview and run

24.13.2 Create or edit a push report

  1. Open the Maintenance app and click Other > Push analysis.

  2. Click the add button.

  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.

  4. (Optional) In the Code field, assign a code.

  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.

24.13.3 Preview push reports

  1. Open the Maintenance app and click Other > Push analysis.

  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.

24.13.4 Run push report jobs

  1. Open the Maintenance app and click Other > Push analysis.

  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.

24.13.5 Clone metadata objects

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.

24.13.6 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.

24.13.7 Display details of metadata objects

  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.

24.13.8 Translate metadata objects

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.

24.14 Manage external map layers

24.14.1 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.

24.14.2 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

Object type

Available functions

External map layer

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

  1. Open the Maintenance app and click Other > External map layer.

  2. Click the add button.

  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 GIS app.

  4. (Optional) In the Code field, assign a code.

  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)

  6. Enter the URL to the map service.

    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 GIS app, this places the external map layer above other DHIS2 base maps but below the thematic map layers. 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 GIS app, this places the external map layer above the thematic map layers but below facility and event data layers. 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.

24.14.3 Clone metadata objects

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.

24.14.4 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.

24.14.5 Display details of metadata objects

  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.

24.14.6 Translate metadata objects

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.

24.15 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.

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.

24.15.1 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.

24.15.2 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 view B in alphabetical order, analytics may fail, as the view with dependencies will not be dropped in the correct order.

24.16 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.

24.17 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

Object type

Available functions

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

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

24.17.1 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.

24.17.2 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.

25 Configure programs in the Maintenance app

25.1 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 program (anonymous program or SEWoR)

Anonymous, individual events are tracked through the health system. No person or entity is attached to these individual transactions.

Has only one program stage.

To record health cases without registering any information into the system.

To record survey data or surveillance line-listing.

Tracker program

Single event with registration program (SEWR)

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.

To record birth certificate and death certificate.

Multi events with registration program (MEWR)

An entity (person, commodity, etc.) is tracked through each individual transaction with the health system

Has multiple program stages.

Mother Health Program with stages as ANC Visit (2-4+), Delivery, PNC Visit.

To create a program, you must first configure several types of metadata objects. You create these metadata objects in the Maintenance app.

+ + + +
Program metadata objects in the Maintenance app

Object type

Description

Available functions

Event program

A program to record single event without registration

Create, edit, share, delete, show details and translate

Tracker program

A program to record single event without registration

Create, edit, share, delete, show details and translate

Program indicator

An expression based on data elements and attributes of tracked entities which you use to calculate values based on a formula.

Create, edit, share, delete, show details and translate

Program rule

Allows you to create and control dynamic behaviour of the user interface in the Tracker Capture and Event Capture apps.

Create, edit, delete, show details and translate

Program rule variable

Variables you use to create program rule expressions.

Create, edit, delete, show details and translate

Relationship type

Defines the relationship between tracked entity A and tracked entity B, for example mother and child.

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

Tracked entity type

Types of entities which can be tracked through the system. Can 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.

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

Tracked entity attribute

Used to register extra information for a tracked entity.

Can be shared between programs.

Create, edit, clone, share, delete, show details and translate

Program

A program consist of program stages.

Create, edit, share, delete, assign to organisation units, show details and translate

Program stage

A program stage defines which actions should be taken at each stage.

Create, edit, change sort order, delete, show details and translate

Program indicator group

A group of program indicators

Create, edit, delete, show details and translate

Validation rule

A validation rule is based on an expression which defines a relationship between data element values.

Create, edit and delete

Program notification

Automated message reminder

Set reminders to be automatically sent to enrolled tracked entity instances before scheduled appointments and after missed visits.

Create, edit and delete

Program stage notification

Automated message reminder

Set reminders to be automatically sent whenever a program stage is completed, or before or after the due date.

Create, edit and delete

25.2 Configure event programs in the Maintenance app

25.2.1 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 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.

25.2.2 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).

25.2.3 Create or edit an event program

25.2.3.1 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.

    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

    Expiry days

    The expiry days defines for how many days after the end of the previous period, an event can be 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 10th 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.

    • 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 representing the event being captured. For tracker programs, the point will represent the enrollment.

    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.
  4. 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.
  5. 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.
  6. 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.

    1. Click next.

25.2.3.2 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.

    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.

25.2.3.3 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.

  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 next.

25.2.3.4 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.

    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.

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

25.2.3.5 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.

      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.

      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.

25.2.4 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}

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}

Organisation unit name

V{org_unit_name}

Program name

V{program_name}

Program stage name

V{program_stage_name}

25.3 Configure tracker programs in the Maintenance app

Note

From release 2.27, you create event programs (programs without registration) in the Maintenance app. You still create tracker programs (programs with registration) in the Program / Attributes app.

25.4 Configure program indicators

25.4.1 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

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

Analytics type

The available analytics types are event and enrollment.

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.

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.dataElementUid}.

      #{A03MvHHogjR.a3kGcGDCuk6}
    • Tracked entity attribute of type date: #{attributeUid}.

      A{GPkGfbmArby}
    • Presence of one event in a specific program stage: PS_EVENTDATE:programStageUid.

      PS_EVENTDATE:A03MvHHogjR

      Note

      This boundary target is only applicable to Analytics type Enrollment
  • Analytics period boundary type: Defines whether the boundary is an end boundary - starting with “before…”, or a start boundary - “after…”. Also defines whether the boundary relates to the end of the aggregate reporting period or the start of the aggregate reporting period.

  • Offset period by amount: In some cases, for example cohort analytics, the boundary should be offset relative to the aggregate reporting period when running pivots and reports. The offset period by amount is used to move the current boundary either back(negative) or forward(positive) in time. The amount and period type together will determine how big the offset will be. An example can be when making a simple enrollment cohort program indicator for a 1 year cohort, it might be enough to offset each boundary of the program indicator with “-1” and “Years”

  • Period type: See above. Can be any period, e.g. Weekly or Quarterly.

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.

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:

Object type

Available functions

Program indicator

Create, edit, clone, share, delete, show details and translate

Program indicator group

Create, edit, clone, share, delete, show details and translate

25.4.2 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.

  2. Click the add button.

  3. Select a Program and enter:

    • Name

    • Short name

    • Code

    • Color

    • 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 Legends.

  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.

25.4.3 Create or edit a program indicator group

  1. Open the Maintenance app and click Indicator > Program indicator group.

  2. Click the add button.

  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.

25.4.4 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
Value types Example syntax

Integer

Negative integer

Positive or zero integer

Positive integer

Number

Percentage

Numeric fields, can be used for aggregation as an expression, or in filters:

#{mCXR7u4kNBW.K0A4BauXJDl} >= 3

Yes/No

Yes only

Boolean fields. Yes is translated to numeric 1, No to numeric 0. Can be used for aggregation as an expression, or in filters:

#{mCXR7u4kNBW.Popa3BauXJss} == 1

Text

Long text

Phone number

Email

Text fields. Can be checked for equality in filters:

#{mCXR7u4kNBW.L8K4BauIKsl} == 'LiteralValue'

Date

Age

Date fields. Most useful when combined with a d2:daysBetween function, which produces a number that can be aggregated as an expression or used in filters:

d2:daysBetween(#{mCXR7u4kNBW.JKJKBausssl},V{enrollment_date}) > 100

Can also directly be checked for equality in filters:

#{mCXR7u4kNBW.JKJKBausssl} == '2011-10-28'

Date

Age

Date fields. Most useful when combined with a d2:daysBetween function, which produces a number that can be aggregated as an expression or used in filters:

d2:daysBetween(#{mCXR7u4kNBW.JKJKBausssl},V{enrollment_date}) > 100

Can also directly be checked for equality in filters:

#{mCXR7u4kNBW.JKJKBausssl} == '2011-10-28'

25.4.5 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:

(sum(#{mCXR7u4kNBW.K0A4BauXJDl} * #{mCXR7u4kNBW.NFkjsNiQ9PH}) / sum(#{mCXR7u4kNBW.NFkjsNiQ9PH})) * 100

Note how the “sum” aggregation operator is used inside the expression itself.

25.4.5.1 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:minutesBetween

(datetime, datetime)

Produces the number of minutes between two data 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:daysBetween

(date, date)

Produces the number of days between two data 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:weeksBetween

(date, date)

Produces the number of full weeks between two data 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:monthsBetween

(date, date)

Produces the number of full months between two data 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:yearsBetween

(date, date)

Produces the number of full years between two data 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:condition

(boolean-expr, true-expr, false-expr)

Evaluates the boolean expression and if true returns the 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 number of arguments.

d2:relationshipCount

([relationshipTypeUid])

Produces the number of relationships of the given type 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:countIfValue

(dataElement, value)

Useful only for enrollment program indicators. Counts the 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.

d2:countIfCondition

(dataElement, condition)

Useful only for enrollment program indicators. Counts the 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, false-expr)

Evaluates the boolean expression and if true returns the 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')

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)

25.4.5.2 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

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_count

The number of numeric positive values in the expression part of the event.

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_name

Can be used in filters for including only certain program stages in a filter for tracker programs. Uses the name of the program stage:

V{program_stage_name} == 'ANC first visit'

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'

reporting_period_start

Can be used in filters or expressions for comparing any date to the first date in each reporting period.

d2:daysBetween(#{WZbXY0S00lP.w4ky6EkVahL}, V{reporting_period_start})

reporting_period_end

Can be used in filters or expressions for comparing any date to the last inclusive date in each reporting period.

A filter that uses the “Reporting period end” variable to only include women who has an LMP that would be in the first trimester:

d2:daysBetween(#{WZbXY0S00lP.w4ky6EkVahL}, V{reporting_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})

25.4.5.3 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

<

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

25.5 Configure program rules

25.5.1 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 component

Description

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.

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:

Object type

Available functions

Program rule

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

Program rule variable

Create, edit, clone, share, delete, show details and translate

25.5.2 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.

  3. In the Tracker Capture or Event Capture apps, verify that the program rule behaves as expected.

25.5.3 Create or edit a program rule variable

  1. Open the Maintenance app and click Program > Program rule variable.

  2. Click the add button.

  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 program stage

    This source type works the same way as Data 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.

    Data element from the newest event in the current program

    This source type is used when a program rule 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.

    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 be populated with the newest data value 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 be populated with the newest data value collected within the 10 events preceding the current event date - not including the current event.

    The newest data value is determined with event date.

    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.

25.5.4 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.

  2. Click the add button.

  3. Enter the program rule details. These fields are not shown to the end user, they are only meant for the program administrator.

    • Program

    • 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

      Assign value

      Data element to assign value to

      Program rule variable to assign value to

      Expression to evaluate and assign

      Used to help the user calculate and fill out fields in the data entry form. The idea is that the user shouldn’t have to fill in values that the system can 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

      Static text

      Expression to evaluate and display after static text

      Used to display information that is not an error or a warning, for example feedback to the user. You can also use this action to display important information, for example the patient’s allergies, to the user.

      Display key/value pair

      Display widget

      Key label

      Expression to evaluate and display as value

      Used to display information that is not an error or a warning.

      Example: calculate number 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 error next to

      Tracked entity attribute to display error next to

      Static text

      Expression to evaluate and display after static text

      Used whenever you’ve cross-consistencies in the form that must be strictly adhered to. This action prevents the user from continuing until the error is resolved.

      This action differs from the 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.

      Hide field

      Data element to hide

      Tracked entity attribute to hide

      Custom message for blanked field

      Used when you want to hide a field from the user.

      Custom message for blanked field allows you to define a custom message 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 hide

      TBA

      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 mandatory

      Tracked entity attribute to make mandatory

      TBA

      Show error

      Data element to display error next to

      Tracked entity attribute to display error next to

      Static text

      Expression to evaluate and display after static text

      Used whenever there are rules which must strictly be adhered to. The show error action prevents the user from continuing until the error is resolved.

      Such a strict validation should only be used when 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.

      Show warning

      Data element to display warning next to

      Tracked entity attribute to display warning next to

      Static text

      Expression to evaluate and display after static text

      Used to give the user a warning about the entered data, but at the same time to allow the user to save and continue.

      You can use warnings to help the user avoid errors in the entered data, while at 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.

      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.

      Warning on complete

      Data element to display warning next to

      Tracked entity attribute to display warning next to

      Static text

      Expression to evaluate and display after static text

      Used to give the user a warning if he/she tries to complete inconsistent data, but at the same time to allow the user to continue. The warning is shown in a dialog when the user completes the form.

      Static text defines the message shown to the user when the expression is true and the action is triggered. This field is mandatory.

      You can select which data element or tracked entity attribute to link the error to. This will help the user to fix 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 when ever there is a change in data value. However this behaviour can be controlled by providing event/enrollment status in program rule expression for example.

      V{event_status} == 'COMPLETED'

      Message template will be parsed and variables will be substituted with actual values.

      Schedule Message

      Message template to send

      Data field which contains expression to evaluate the date which notification should be sent at.

      Schedule Message will schedule notification at date provided by Expression in the data field. Sample expression is given below

      d2:addDays( '2018-04-20', '2' )

      Message template will be parsed and variables will be substituted with actual values.

      Hide option

      Data element to hide option for

      Tracked entity attribute to hide option for

      Option that should be hidden

      Used to selectively hide a single option for an option set in a given data element/tracked entity attribute.

      When combined with show option group the hide option takes presedence.

      Hide option group

      Data element to hide option group for

      Tracked entity attribute to hide option group for

      Option group that should be hidden

      Used to hide all options in a given option group and data element/tracked entity attribute.

      When combined with show option group the hide option group takes precedence.

      Show option group

      Data element to show option group for

      Tracked entity attribute to show option group for

      Option group that should be shown

      Used to show only options from a given option group in a given data element/tracked entity attribute. To show an option group implicitly hides all options 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.

25.5.5 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. The full expression in the Data field:

    d2:concatenate(d2:weeksBetween(#{lmp}, V{current_date}), '+',
    d2:modulus(d2:daysBetween(#{lmp}, V{current_date}), 7))

This example shows how to configure a program rule to display text in the Feedback widget in the Tracker Capture app.

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.

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”.

25.5.6 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:

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
Operator Description

+

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.

>

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
Function Arguments Description
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.
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:concatenate (object, [,object, object,…]) Produces a string concatenated string from the input 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:daysBetween (date, date) Produces the number of days between the first and 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:weeksBetween (date, date) Produces the number of full weeks between the first and second argument. If the second argument date is before the first argument the return value will be the negative number of weeks between the two dates. The static date format is ‘yyyy-MM-dd’.
d2:monthsBetween (date, date) Produces the number of full months between the first and second argument. If the second argument date is before the first argument the return value will be the negative number of months between the two dates. The static date format is ‘yyyy-MM-dd’.
d2:yearsBetween (date, date) Produces the number of years between the first and second argument. If the second argument date is before the first argument the return value will be the negative number of years between the two dates. The static date format is ‘yyyy-MM-dd’.
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:countIfValue (sourcefield,text) Counts the number of matching values that is entered for 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:countIfZeroPos (sourcefield) Counts the number of values that is zero or positive 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')
                                    
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:validatePattern (text, regex-pattern) Evaluates to true if the input text is an exact match with 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)
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-char-num) Evaluates to the part of a string specified by the start and 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:inOrgUnitGroup (text) Evaluates whether the current organisation unit is in the 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:hasUserRole (user role) Returns true if current user has this role otherwise false

Example expression:

d2:hasUserRole('UYXOT4A3ASA')
d2:zScoreWFA Z-Score weight for age indicator Function calculates z-score based on data provided by WHO weight-for-age indicator. Its value varies between -3.5 to 3.5 depending upon the value of weight.

Example expression:

d2:zScoreWFA( ageInMonth, weight, gender )
Standard variables to use in program rule expressions
Variable Type Description
V{current_date} (date) Contains the current date whenever the rule is executed.

Example expression:

d2:daysBetween(#{symptomDate},V{current_date}) < 0 
V{event_date} (date) Contains the event date of the current event execution. Will not have a value at the moment the rule is executed as part of the registration form.
V{event_status} (string) Contains status of the current event or enrollment.

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_count} (number) Contains the total number of events in the enrollment.
V{enrollment_date} (date) Contains the enrollment date of the current enrollment. Will not have a value for single event programs.
V{incident_date} (date) Contains the incident date of the current enrollment. Will not have a value for single event programs.
V{enrollment_id} (string) Universial identifier string(UID) of the current enrollment. 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_code} (string) Contains the code of the orgunit that is linked to the 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{environment} (string) Contains a code representing the current runtime 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.
V{program_stage_id} (string) Contains the ID of the current program stage that 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_stage_name} (string) Contains the name of the current program stage that 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.

25.6 Configure relationship types

25.6.1 About relationship types

A relationship type defines the relationship between tracked entity A and tracked entity B, for example mother and child.

25.6.2 Create or edit a relationship type

  1. Open the Maintenance app and click Program > Relationship type.

  2. Click the add button.

  3. Type a Name of the relationship type.

  4. (Optional) Assign a Code.

  5. In the A is to B field, enter a description of which relationship tracked entity A has to tracked entity B, for example mother.

  6. In the B is to A field, enter a description of which relationship tracked entity B has to tracked entity A, for example child.

  7. Click Save.

25.7 Configure tracked entity types

25.7.1 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.

25.7.2 Create or edit a tracked entity attribute

  1. Open the Maintenance app and click Program > Tracked entity attribute.

  2. Click the add button.

  3. In the Name field, type the tracked entity attribute name.

  4. (Optional) Type a Short name.

  5. (Optional) Type a Form name.

  6. (Optional) In the Code field, assign a code.

  7. (Optional) Type a Description.

  8. Select an Option set.

  9. In the Value type field, select the type of data that the tracked entity attribute 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 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.

    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

    This will be populated with the username of the user which performs data entry automatically during the data entry process.

    Yes/No

    Boolean values, renders as drop-down lists in data entry.

    Yes only

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

  10. Select an Aggregation type.

    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.

    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.

  11. 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.

  12. 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.

  13. (Optional) Select Confidential.

    This option is only available if you have configured encryption for the system.

  14. (Optional) Select Display in list without program.

  15. (Optional) Assign one or multiple Legends.

  16. Click Save.

25.7.3 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.

  4. (Optional) select a Color and an Icon that will be used by the data capture apps to identify 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.

25.9 Clone metadata objects

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.

25.10 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.

25.11 Change sharing settings for metadata objects

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.

25.12 Display details of metadata objects

  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.

25.13 Translate metadata objects

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.

26 About sharing of objects

This chapter discusses the sharing of entities feature in DHIS2.

26.1 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.

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.

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.

26.2 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.

26.3 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.

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.

26.4 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.

26.4.1 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
Object type Can view data Can capture data Comment

Tracked entity type

  • Search for tracked entities with this tracked entity type.

  • See tracked entity type attribute values for this tracked entity type.

  • Edit visible tracked entity attributes for tracked entity instances of this type.

  • Register/create new tracked entity instances of this type.

  • Delete tracked entity instances of this type.

  • Deactivate/reactivate tracked entity instances of this type.

Program

  • Search for tracked entities within this program.

  • See tracked entity attributes specific to this program.

  • See enrollment details for the program.

  • See notes for the enrollment.

  • Enroll into the program.

  • Edit enrollment details for the program.

  • Complete/reopen enrollments into the program.

  • Add notes for the program.

  • Edit relationships for the program.

  • Send message to tracked entity instance.

  • Delete enrollments in the program.

Both “Can view data” and “Can capture data” also requires the user to have “Can view data” for the tracked entity type.

Program stage

  • See the program stage and its events and data within an enrollment.

  • See the program stage notes.

  • Add/schedule/refer a new event within the program stage.

  • Complete/reopen the events within the program stage.

  • 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.

Both “Can view data” and “Can capture data” also requires the user to have “Can view data” for the program and the tracked entity type.

Data sharing for single event programs
Object type Can view data Can capture data Comment

Program

  • See list of events within the program.

  • See tracked entity data values for events in the program.

  • Add new events into the program.

  • Edit data for events in the program.

  • Delete events in the program.

26.4.2 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
Object type Can view data Can capture data Comment

Data set

  • View Data Set’s data in Analytics

  • Can see DataSet in Data Entry app

  • Can save data for Data Set using API

For saving data value in Data Entry app, users also need “Can capture data” for Category Options within selected Data Set.

CategoryOption
  • Can view data values belong to shared Category Option in analytics

  • Can save data value for input fields in Data Entry app which belongs to shared Category Options.

For CategoryOptionCombo and AttributeOptionCombo to be writeable, all belongs CategoryOptions must be shared with “Can capture data”.

27 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.

27.1 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.

27.1.1 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.

27.1.2 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.

27.1.3 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.

27.1.4 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.

27.1.5 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.

27.1.6 Data sets not assigned to organisation units

All data sets should be assigned to at least one organisation unit.

27.1.7 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.

27.1.8 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.

27.1.9 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.

27.1.10 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.

27.1.11 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.

27.1.12 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.

27.1.13 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.

27.1.14 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.

27.1.15 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.

27.1.16 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.

27.1.17 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.

27.1.18 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.

27.1.19 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.

27.1.20 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.

27.1.21 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.

27.1.22 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.

27.1.23 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.

27.1.24 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.

27.1.25 ProgramRules with no action

Report will highlight all the Program rules not configured with any ProgramRuleAction.

27.1.26 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.

27.1.27 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.

27.1.28 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.

27.1.29 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.

27.1.30 ProgramRuleActions with no section id

Report will highlight all the Program rule actions which have ProgramRuleActionType set to HIDESECTION but configuration does not provide any section id.

27.1.31 ProgramRuleActions with no program stage id

Report will highlight all the Program rule actions which have ProgramRuleActionType set to HIDEPROGRAMSTAGE but configuration does not provide any program stage id.

27.2 Maintenance

Data maintenance functions in the Data Administration app

Function

Description

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.

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.

27.3 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 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.

27.4 Duplicate data elimination

This function is useful when data has been entered mistakenly for two data elements which represents the same phenomena.

Start by selecting the data element to eliminate from the list and click confirm. Then select the data element to keep and click confirm again. Finally, verify the selection and click merge.

In the situation where data exists for the data element to eliminate and not for the one to keep, the data will be moved to the one to keep. When data exists for both data elements, the data which was updated last will be used. When data exists only for the one to keep, no action will be taken. The data element to eliminate will eventually be deleted, except when it is a multidimensional data element and has other data registered.

27.5 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.

27.6 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.

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”.

27.7 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.

27.8 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.

27.9 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.

27.9.1 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 pre-defined 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.

Jobs are enabled by default.

27.9.2 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.

27.9.3 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.

27.10 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 synchronisation 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 “Program Data Synchronization”. Make sure it is enabled when you finish.

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 synchronise all the data, there is a possibility to skip some of the data being synchronised.

    When DHIS2 synchronises tracker data, it determines the set of data to synchronise based on the last time it was synchronised. Each of the tracked entity instances and events have their own records of when they where last successfully synchronised.

  • 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.

    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 synchronisation 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 synchronise old data in favor of initial synchronisation 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 synchronisation job all the time. Therefore, if you need to synchronise the old data, you should change the SettingKey.

27.11 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 is critical and the configurator 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.

28 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.

28.1 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.

28.2 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.

28.3 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.

28.4 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.

28.5 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.

  • Enter # followed by the name of a key to search for keys only.

28.6 Search your JSON library

Use the search tool in the workspace toolbar to search your JSON library.

28.7 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.

Any errors are marked by the editor. If you hover over the error icon, you can view a short description of the error.

29 Configure the GIS app

29.1 Context

Setting up the GIS simply means storing coordinates for the organisation units you want to show on the map in the database. Coordinates are often distributed in proprietary formats and will need to be converted to a format which DHIS2 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.

If you go to the organisation unit module and edit one of the units, you can see a text field called Coordinates. Here you may fill in its coordinates directly (geojson format) which is useful if you just want to update a couple of units.

An example point/facility coordinate:

[29.341,-11.154]

An example polygon/area coordinates string:

[[[[29.343,-11.154],[28.329,-11.342],[28.481,-10.239],[29.833,-10.412]]]]

However, if you are going to e.g. add coordinates for all units at a certain level you don’t want to do that manually. This is where the automatic GML import comes into play and the following section explains the preferred way of using it.

Important

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.

29.2 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.

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”.

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:

- 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

30 Configure report functionality

30.1 Data sources for reporting

30.1.1 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).

30.1.1.1 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.

30.1.1.2 Basic rules of aggregation

30.1.1.2.1 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

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.

30.1.1.2.2 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’.

30.1.1.3 Dimensions of aggregation

30.1.1.3.1 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.

30.1.1.3.2 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 order to aggregate data from smaller time intervals, e.g. weeks, into longer time intervals, e.g. months.

30.1.1.3.3 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.

30.1.1.4 Aggregation operators, methods for aggregation

30.1.1.4.1 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.

30.1.1.4.2 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.

30.1.1.5 Advanced aggregation settings (aggregation levels)

30.1.1.5.1 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.

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.

30.1.1.5.2 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.

30.1.2 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.

30.1.3 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.

30.2 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 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.

30.2.1 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.

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.

30.2.2 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.

30.2.3 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:

    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”.

30.2.4 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.

30.2.5 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 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.

30.3 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.

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 Comma Separated Values. 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.

30.4 Standard reports

30.4.1 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 dynamic reports. The following guide will use the report table approach, while the SQL approach is covered towards the end.

30.4.2 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.

30.4.2.1 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.

30.4.2.2 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.

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.

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!

30.4.2.3 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.

30.4.2.3.1 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

  • By using the Static text properties in the Properties panel

30.4.2.3.2 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.

30.4.2.3.2.1 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:

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.

30.4.3 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 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.

30.4.3.1 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")

This tells the report engine to only print table rows where the organisation unit is not the parent organisation unit.

30.4.3.2 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.

30.4.3.3 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.

30.4.3.3.1 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:

($F{organisationunitname}.charAt( 0 ) != '[')&&$F{organisation_unit_is_parent}.equals("No")

30.4.4 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.

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.

Click OK - Close - OK to close the three windows. The table should now be sorted.

30.4.5 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.

($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.

30.4.6 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.

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.

30.4.7 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.

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.

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.

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.

30.4.7.1 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.

30.5 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.

30.5.1 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.

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.

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.

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.

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.

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.

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.

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.

30.5.2 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:

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.

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.

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.

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.

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.

You can then Click OK to close the window. Follow the same steps to add a series for the other indicators.

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.

30.6 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.

The report is now available as a “Standard Report” in DHIS2:

30.7 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