System Administrator

User Guide
Comprehensive System Administrator
Guide for [Link]’s DHIS2 Software in
Zimbabwe

SEPTEMBER 2021

0 System Administrator User Guide

September 2021

Cover illustration credit: Gwendolyn Stinger

Suggested citation: [Link]. (2021). System Administrator User Guide: Comprehensive System Administrator
Guide for [Link]’s DHIS2 Software in Zimbabwe. Washington, DC, USA: [Link], Palladium

This report was produced for review by the U.S. Agency for International Development. It was prepared by [Link].
The information provided in this report is not official U.S. Government information and does not necessarily reflect the
views or positions of the U.S. Agency for International Development or the U.S. Government.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 1

Document Version History

Version Note/Action Taken Author/Approved By Submit Date

Number

1.0 Megan Kill August, 2021

ii System Administrator User Guide

Table of Contents
Document Version History ii

Table of Contents iii

1 | Glossary 1

2 | DHIS2 Fundamentals 2

Organisation units - “Where” 2

Data elements - “What” 3

Indicators - “What” 4

Period - “When” 4

Fixed periods 4

Relative periods 5

Aggregation of periods 5

Sum and average aggregation along the period dimension 5

Analytics 5

Web API 6

3 | Metadata Creation 6

Organisation unit 7

Create organisation units 7

Update organisation units 9

Rearrange organisation units (hierarchy operations) 11

Delete organisation units 12

Organisation levels 13

Update organisation unit levels 13

Translate organisation unit levels 14

Organisation unit groups 16

Create organisation unit groups 16

Organisation unit group sets 18

Create organisation unit group sets 19

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe iii
 Category Options, Categories and Category Combos 21

Category Options as Attributes 22

Create category options 22

Updating and Sharing category options 23

Create categories 25

Updating categories 27

Create category combinations 27

Update category combinations 28

Option sets 28

Opening Option Sets 29

Option set objects in the maintenance app 30

Create or edit an option set 30

Create or edit an option group 32

Create or edit an option group set 34

Data elements 36

Create data elements 37

Value type table 38

Aggregation type table 40

Data element groups 42

Tracked Entity Types & Tracked Entity Instances 42

Create Tracked Entity Types 43

Tracked Entity Attributes 45

Create tracked entity attributes 45

Relationships 48

Relationship Types 48

Programs 52

Event Programs 52

Tracker Programs 52

Create a Tracker Program 52

iv System Administrator User Guide

 Program details 52

Enrollment details 55

Attributes 56

Assign attributes 57

Name: TEA names 57

Create registration form 58

Section 58

Custom 58

Program stages 59

Stage Details 60

Assign data elements 61

Name 61

Create data entry form 62

Access 63

Notifications 65

What to send? 66

When to send it? 66

Who to send it to? 66

Program rules 67

Create program rule variable(s) 71

Create or edit a program rule 72

Enter program rule details 72

Enter program rule expression 74

Define program rule actions 75

Indicators 76

Create indicators 76

Indicator groups 78

Program Indicators 79

Create program indicators 80

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe v

 Program indicator details 81

Edit expression 82

Edit filter 83

Languages and Translations 84

Db languages 84

4 | Metadata Nomenclature & Structure 85

Organization Unit Hierarchy 86

Available Programs 86

5 | User Management 86

User Roles 87

Sharing 88

Sharing of Analytic Objects 89

User Account Management 89

Username Protocol 89

Analysis Org Unit Policy 89

Data Entry Org Unit Policy 89

User Roles Policy 89

6 | Metadata Import: BAO Import Foundry (BIF) 89

7 | Troubleshooting & General Admin Tasks 90

Data Integrity 91

Process for escalating problems to get support from [Link] 91

Clearing Cache 91

Forgotten password 92

vi System Administrator User Guide

1 | Glossary
For a general glossary on DHIS2 terms, see the DHIS2 online glossary. The purpose of this
glossary is to relate the DHIS2 terms to the DHIS2 system, as well as define any -specific terms
used within the system.

DHIS2 Terms Explanation

Groups of category options: for e.g., a category called ‘Age’ would group
Category
together a series of age category options.
Category
Category combinations are used to disaggregate data elements and are
combination
made up of different combinations of categories (or groups of categories).
(Cat combo)
Category options are the smallest unit of disaggregation. They correspond to
Category
each ‘option’ within a given category. For example, an ‘Age’ category might
options
have two options: <18 and 18+.
A raw unit of data within DHIS2 e.g., number of IUDs removed. Each data
element can have a full name (for database maintenance), short name (for
Data element
viewing in analytics), form name (what appears on the data entry screen) and
description.
Data element Data element groups are used to categorise data elements for data analysis.
group They are necessary for viewing data elements in analytics.
Data element Data element group sets are used to group different data element groups for
group sets extra analysis.
Data sets are a collection of data elements grouped together for the
purposes of data entry. For , a data collection form will be represented in
Data set1
DHIS2 by the data set. A data set is assigned a collection frequency and
organization units to add meaning to the data collected.
A calculated value within DHIS2, with a numerator and denominator made
Indicator
up of data elements. Note, this is different to the M&E term ‘indicator’.
Organization A geographical unit within a hierarchy. These add the ‘where’ dimension to
Unit data collection and are often called OUs or Org Units.
Organization Organization unit groups are used to categorise organizational units. One
Unit Group purpose is to be able to easily assign a group of Org Units to a data set.

Organization Organization unit group sets allow grouping of organizational unit groups for
unit group sets easy aggregation of data along lines different to the Org Unit hierarchy.

1
DHIS2 spells data set with a space (as opposed to ‘dataset’) so this is the spelling used within this document

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 1

 An 11-character code used within DHIS2 to identify any specific metadata
Unique object in the system. All UIDs commence with a letter followed by 10
Identifier alphanumeric lowercase or uppercase characters and are used for
exchanging metadata between systems.
An expression based on data elements to define a relationship between data
elements. There are multiple ways to create validation rules including from
Validation Rule
within the DHIS2 interface, by importing existing rules from a master
spreadsheet or using SQL programming.

2 | DHIS2 Fundamentals
Organisation units - “Where”
The organisation unit hierarchy defines the organisational structure of DHIS2, for example, how
health facilities, villages, administrative areas, and other geographical areas are arranged with
respect to each other. The organisation unit hierarchy is built up by parent-child relations, in a
“tree”-like format. In DHIS2, each of these nodes is an organisation unit (org unit). The [Link]
server, for example, has Regions, each of which has a number of Countries as children. Usually,
the lowest level consists of Villages/locations where data is collected as this is where activities
typically occur. Data collection can also be located at higher levels, but in the case of [Link], data
is collected at the lowest level the service delivery point.

DHIS2 is structured so that the organizational unit hierarchy is a geographical hierarchy, and the
Geographical Information System (Maps) module depends on this. Additional hierarchies (e.g.,
the sub location structure or a hierarchy based upon the type of organisation units) can be
modeled using organisational groups and group sets, but the organisational hierarchy is the main
vehicle for data aggregation on the geographical dimension.

2 System Administrator User Guide

Data elements - “What”
The data element is perhaps the most important building block of the database. It represents the
"what" dimension, explaining what is being collected - i.e., it is raw data. DHIS2 calls this unit of
collection a data element. The data element often represents a count of something, and its name
describes what is being counted, e.g., "Visits done by Health Staff to released detainees" or
"Among new cases assisted, number of Ill Treatment case". When data is collected, validated,
analysed, reported or presented it is the data elements or expressions built upon data elements
that describes the “what” of the data. As such the data element becomes important for all aspects
of the system and they decide not only how data is collected, but more importantly how the data
values are represented in the database, which again decides how data can be analysed and
presented.

Examples of data elements:

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 3

Indicators - “What”
Indicators are a core object of data analysis in DHIS2. An indicator consists of a formula that can
be made up of data elements, constants, organisation unit group counts and mathematical
operators. Coverage indicators (ratios, percentages, etc.) are composed of two Data Elements at
least, one representing the numerator and another representing the denominator (although
more complicated numerators and denominators can be defined using multiple DE’s). It is
possible for the denominator value to be 1, and filters can be added to expressions for the
numerator and/or denominator.

Period - “When”
The period dimension defines when a particular piece of data was collected. It is also required
when analysing data to make it comparable over time. For example, when looking at cumulative
data and creating quarterly or annual aggregated reports, or when doing analysis that combines
data with different characteristics like monthly routine data, annual census/population data or
six-monthly staff data.

Fixed periods

In DHIS2, periods are organised according to a set of fixed period types described below. These
fixed periods are used during data collection, and analysis. The following ISO 8601 calendar types
are supported:

❏ Daily
❏ Weekly: These are defined as ISO weeks, beginning on Monday and ending on Sunday.
EPI weeks are also available beginning on Wed, Thurs, Sat and Sun.
❏ Monthly: Refers to standard calendar months.
❏ Bimonthly: Two-month periods beginning from January e.g., January-February, March-
April etc.
❏ Quarterly: Standard ISO quarters, beginning in January e.g., January-March, April-June etc.
❏ Six-Monthly: Six-month periods beginning in January e.g., January-June, July-December
❏ Yearly: This refers to a calendar year, January 1st to December 31st.

4 System Administrator User Guide

 ❏ Financial April: Financial year period beginning on April 1st and ending on March 31st of
the next calendar year, e.g., April 1st 2020-March 31st 2021
❏ Financial July: Financial year period beginning on July 1st and ending on June 30th of the
next calendar year, e.g., July 1st 2020 to June 30th 2021
❏ Financial Oct: Financial year period beginning on October 1st and ending on September
30th of the next calendar year, e.g., October 1st 2020 to September 30th 2021
❏ Six-monthly April: Six-month periods beginning on April 1st with a duration of six calendar
months, i.e., April-September, October-March.

Relative periods

In addition to the fixed period types described above, DHIS2 also supports relative periods within
the analysis modules. A relative period operates with reference to the current date. The simplest
scenario is when you want to design a monthly report that can be reused every month without
having to make changes to the report date to accommodate for the changes in period. The
relative period called "Last month" will mean every month the report moves forward relative to
the current date; thus, DHIS2 will always show the results for the previous month with reference
to the current month.

Aggregation of periods

While data is collected at a given frequency to standardise collection and management, this does
not put limitations on the period types that can be used in data analysis and reports. Just as data
gets aggregated up the organisational hierarchy, it is also aggregated according to period, so you
can create quarterly and annual reports based on data that is being collected at the same or a
greater frequency, for e.g., on a monthly basis. The defined period type for a data entry form
defines the lowest level of period detail possible in a report.

Sum and average aggregation along the period dimension

When aggregating data in the period dimension there are many options for how the calculation
is done, most commonly sum or average, though others like max are also used in [Link]’s global
indicators. This option is specified per data element in DHIS2 through the use of the 'aggregation
operator' property of a Data Element. Most of the data collected on a routinely basis will be
aggregated by summing up the months or weeks.

Analytics
The analytics resource is a powerful resource that lets you query and retrieve data along all
available data dimensions. For instance, you can ask the analytics resource to provide the
aggregated data values for a set of data elements, periods and organisation units. Also, you can
retrieve the data for a combination of any number of dimensions based on things like partner,

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 5

organisation unit group sets, theme or other user-defined groupings. The analytics engine is the
source for retrieving data in DHIS2 and is used by all analysis modules: Tables, Charts and Maps.
The analytics engine is exposed as the Web Application Programming Interface (web API). To
utilise any entered data in the analysis modules, therefore, the data must first be sent to the
analytics warehouse. This process occurs automatically every 24 hours, so it is important to note
the potential delay between data entry and the ability to visualise data immediately. The process
can be triggered manually. It may take a significant amount of time depending on the amount of
data in your database. During peak (busy) period, triggering the process manually may crash the
server altogether, therefore it is not recommended.

Web API
The Web Application Programming Interface is a component which makes it possible for external
systems to access and manipulate data stored in an instance of DHIS2. More precisely, it provides
a programmatic interface to a wide range of exposed data and service methods for applications
such as third-party software clients, web portals and internal DHIS2 modules. The Web API
adheres to many of the principles behind the Representational State Transfer (REST) architectural
style. It produces JSON, XML, CSV, HTML and Excel response (input/output) formats. It is the Web
API that allows for the integration of data between DHIS2 systems and between DHIS2 and the
other data warehouses.

6 System Administrator User Guide

3 | Metadata Creation
This section explains how the objects specified in the system design section are created in DHIS2.

Organisation unit
Create organisation units

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

1. Open the Maintenance app; type maintenance in the search apps box in the top right
corner of the DHIS2 window. Click on the ‘Maintenance’ app icon.

2. Click Organisation unit > Organisation unit

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 7

 3. Navigate through the organisation unit hierarchy on the left, by expanding or collapsing
the arrows, to find the parent organisation unit of the OU you would like to create. Click
the parent name so that it highlights orange.
4. Select the blue ‘+’ symbol to choose to create a new OU.
5. Enter a Name of the organisation unit. Each organisation unit must have a unique name
and the naming convention must be applied to the organisation unit name.
6. Enter a Short name for the organisation unit. Typically, the short name convention is the
name and an abbreviation of the OU type. It does not need to be ‘shorter’ than the name,
unless the name is more than 50 characters. This attribute is often used in reports to
display the name of the organisation unit, where space is limited.
7. (Optional) Assign a Code. In many countries organisation units are assigned a code, a
unique organisation-defined identifier.
8. (Optional) Type a Description of the organisation unit.
9. Select an Opening date. This date is the date for when the OU will allow data to be entered,
so it’s important that it is set to before the period you will be collecting data.
10. Other fields are optional.

8 System Administrator User Guide

 11. If you can, enter a latitude and longitude. These are needed to create maps in the Maps
app. Without this information, the Maps app cannot display the location of your org unit.
(It can still aggregate it to higher boundary level OUs.)
12. If you are creating more than ten org units, it might be more efficient to import
coordinates as a batch job using the Import-Export app. You can also use the Import-
Export app to create polygons (also known as shapefiles). A polygon is an organisation
unit that represents an administrative boundary, such as a district.
13. It is possible to assign data sets to your org unit as you create them, but we will assign
these via organisation unit groups later on in the manual.
14. Click Save.

As the Organisation Unit hierarchy is used by every user in the system, organisation units do not
require sharing - they are public objects. Users can however be restricted to which parts of the
hierarchy they can see through their user account, explained in the User account section.

Update organisation units

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

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 9

 2. In the OU hierarchy on the left of the screen, navigate to and click the parent of the
organisation unit you want to update. The child(ren) are now listed on the right-hand
pane.
3. In the organisation unit list, click the options menu (vertical dots) and select Edit.

4. Modify the field(s) to be updated.

5. Scroll to the bottom of the page, click the Save button.

10 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 11
Rearrange organisation units (hierarchy operations)

You can move organisation units within 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 that
if the selected organisation unit has sub-organisation units, all of them move also, in the
same order, 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.

Delete organisation units

You can delete organisation units if no data is associated with them. To delete organisation units:

1. Open the Maintenance app and click Organisation unit > Organisation unit.
2. Click the parent of the organisation unit you want to delete. The child(ren) are listed in the
right-hand window.
3. In the organisation unit list, click the options menu and select Delete.

12 System Administrator User Guide

 4. A black bar will appear, like that shown below. Click Confirm.

Organisation 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
4". You can replace the generic name with a contextual name, for example "Continent region" or
"Country". DHIS2 uses the contextual names anywhere levels are referred to, for example in the
Maps app.

Update organisation unit levels

1. Open the Maintenance app and click Organisation unit > Organisation unit level.
2. For the organisation unit levels you want to modify, type a name.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 13

 3. The number of offline levels can be ignored.
4. Click Save.

Translate organisation unit levels

To translate organisation unit levels:

1. Open the Maintenance app and click Organisation unit > Organisation unit level.
2. For the organisation unit level(s) you want to translate, click the Translate icon.

14 System Administrator User Guide

3. In Select locale drop down, select the language you desire.

4. Type the organisation unit level’s translated Name (naming convention is not required).

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 15

 5. Click Save.

Organisation unit groups

While the lowest geographical level for disaggregation in DHIS2 is typically the location where
data are entered, there are ways to flexibly group organisation units into any number of
dimensions by using the organisation unit groups and group set functionality. As an example, it
is possible to create an organisation unit group set called "Health district" and add groups with
the names of the various health districts, containing OUs in those districts. This allows for the
analysis and aggregation of data by health districts rather than strict geopolitical hierarchy. In
order for the groups to show up as a unit of analysis in the apps, they must be part of a group
set. For a group set to function properly in analysis, each organisation unit should only be a
member of a single group (exclusive) within a group set. Stated with an example, an OU cannot
be part of more than one health district. You can group organisation units as many ways as are
meaningful - by type, by ownership, by donor, by alternative administrative organisation, etc.

Create organisation unit groups

Organisation unit groups allow you to classify related organisation units into a common theme.
You can for example group all organisation units that particular partners report at in separate
groups.

1. Open the Maintenance app and click Organisation unit > Organisation unit group.
2. Click the add button ‘+’.

16 System Administrator User Guide

3. Fill in the form:
a. Name: Provide a precise, unique and descriptive name for the organisation unit
group.
b. Short name: The short name should be less than 50 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, such as pivot tables and charts.
c. Code: assign code; mainly used to exchange data with an external system; this is
optional.
d. Symbol: Select a symbol which will be used to display the organisation units within
this group (points only) when displayed in the Maps app.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 17

 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.
5. The selected organisation units display in orange.
6. Click Save.

Organisation unit group sets

18 System Administrator User Guide

Organisation unit group sets allow 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
can easily filter, organise or aggregate data by groups within a group set.

Create organisation unit group sets

1. Open the Maintenance app and click Organisation unit > Organisation unit group set.
2. Click the add button ‘+’.

3. Fill in:
a. Name: Type a naming convention and provide a precise name for the organisation
unit group set.
b. Code: assign code; mainly used to exchange data with an external system
c. Description: Describe what the organisation unit group set measures or captures.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 19

 4. If you want all organisation units to be members of a group within the group set, select
Compulsory. If you want only a few - leave unselected.
5. (Optional) Select Data dimension: This allows the group set to be available as a dimension
in reporting apps (Pivot table, Data visualizer and Maps).

6. Select organisation unit groups and assign them.

a. In the left-hand list (1.), you find the available organisation unit groups. Use the
arrows (2.) to move selected groups between the two lists.

20 System Administrator User Guide

Example, not [Link] specific:

7. Click Save.

Category Options, Categories and Category Combos

In the Maintenance app, you manage all categories through the ‘Category’ module.

The below options are relevant to the DHIS2 system:

Object type Available functions

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 21

 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

This module is important when you need to create disaggregations to apply to data elements. As
an example, this would be where you create options like ‘Male’ or ‘Female’ when disaggregating
your aggregated data for collection.

Category Options as Attributes

In the [Link] server, category options are also used as dataset attributes to distinguish data
submitted by different projects. If creating a category option for a project, add it as you would
normally to the [Link]’s Projects category. You will need to run Category Option Combination
maintenance before continuing.

Create category options

Where possible, try to recycle category options. For instance, there might be two categories which
share a particular category option (e.g., ‘5-15 years’). Rather than creating it twice, reuse the
option. This actually becomes important if there is a need to cross-analyze data elements using
the same options.

To create a category option:

1. Open the Maintenance app and click Category > Category option.
2. Click the add button ‘+’.
3. Fill in the form:
a. Name - there is no strict naming convention for category options, but it is
important to remain consistent. For e.g., if using “Years”, do not to use ‘’Yrs” later.
b. Short name.
c. Code (optional): assign code; mainly used to exchange data with an external
system.
d. Start date (optional). This allows for aggregation in analysis within the correct time
boundary.
e. End date (optional). This allows proper aggregation in analysis.
f. Select the related Organisation Unit and assign them specifically for the actors.

22 System Administrator User Guide

 4. Click Save.

Example:

Updating and Sharing category options

Updating category options is not recommended as it can introduce errors in disaggregation into
the system. If possible, it is best practice to remove the unwanted option and create a new one,
which is not possible if data has already been collected. Speak to the overall DHIS2 System
administrator before editing.

Category options do not get shared as other objects. As they are reused throughout the system,
it makes sense for them to remain as ‘public’ objects but not editable. To share data and metadata
for a category option:

1. Right click on the category option you desire to share

2. Choose Sharing Settings from the menu that appears.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 23

 3. In the sharing screen that appears, as shown below, edit the sharing settings by clicking
on the pen or eye icons. In order to enter data for the option, the user or user group
needs to have “Data - Can capture and view” as their setting.

24 System Administrator User Guide

 4. Click Close to save the updated sharing settings.

Create categories

When you have created all category options for a particular disaggregation or attribute, you can
add them to a category. A category, literally, is a collection of category options. To create a
category:

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

2. Click the add button ‘+’.
3. Fill in the form:
a. Name including naming convention.
b. Code (optional) assign code; mainly used to exchange data with an external
system.
c. Data dimension type: select ‘Disaggregation’ for Data sets and ‘Attribute’ if
category combination is assigned to a data set.
d. Data dimension: by selecting/ticking Data dimension, the category will be available
to the analytics as another dimension to analyse by, in addition to the standard
dimensions of "Period" and "Organisation unit".

Example only, not [Link] specific

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 25

 4. Select category options and assign them moving from the left to the right window with
the arrows or by double clicking.

Example only, not [Link] specific

26 System Administrator User Guide

 5. Move the category options within the right-hand side window, up and down in order using
the up and down arrows. This will determine the order they appear within the category.
6. Click Save.

Updating categories

As with category options, serious thought should be given before editing categories as it has the
potential to disrupt cross-analysis of data using the same category before and after the edit.
Speak to the DHIS2 System administrator before proceeding.

Create category combinations

Category combinations let you combine multiple categories into a related set. This means a given
data element can be disaggregated by multiple categories. It should be noted that it is a ‘category
combination’ which is applied to a data element, so even if there is only one category within the
category combination, this is necessary for the category to be applied to the data element. To
create category combinations:

1. Open the Maintenance app and click Category > Category combination.
2. Click the add button ‘+’.
3. Fill in the form:
a. Name including naming convention.
b. Code (optional) - assign code; mainly used to exchange data with an external
system.
c. Data dimension type. Select ‘disaggregation’ if it is to be applied to a data element,
select ‘attribute’ if it is to be applied to a data set.
d. Skip category total in reports (It is recommended that you leave this unchecked).

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 27

Example only, not [Link] specific:

4. Select categories and assign them by moving them from the left to the right windows
using the arrows or by double clicking.
5. Click Save.

Update category combinations

Updating category combinations is not recommended, as it proliferates the category option

combinations and renders former category option combinations redundant and ‘orphaned’. This
will hamper data analysis before and after the category combination is updated. Speak with the
DHIS2 System administrator before proceeding.

Option sets
Option sets provide a predefined drop-down menu for use in DHIS2. It is possible to define any
kind of options.

For example, an option set called “Case Report type” would have the options: “In person”, “Over
the phone”, “Virtual platforms”, and “Other”.

28 System Administrator User Guide

Opening Option Sets

To open the Option Sets use the ‘Search apps’ menu in the upper right corner of the home
dashboard to navigate to the Maintenance app. Then click on the Other tab from the top
horizontal menu. Either click on Option set in the left column menu, or click on the Option set
box.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 29

Option set objects in the maintenance app

Object type Available functions

Object set Create, edit, clone, share, delete, show details

and translate

Option group Create, edit, clone, share, delete, show details

and translate

Option group set Create, edit, clone, share, delete, show details
and translate

Create or edit an option set

To create or edit an option set:

1. Click the add ‘+’ button

2. In the Primary details tab, add the option set details
a. Name: type of the name of the option set.
b. Code: assign code - mainly used to exchange data with an external system.
c. Value type: select a value type.
d. Click on Save.

30 System Administrator User Guide

3. For each option
a. Click on the options tab.
b. Click on the add option button.
c. Name: enter the name of the option.
d. Code: Will be used for this option in the data capture apps.
e. Color: Will be used for this option in the data capture apps.
f. Icon: Select symbol to represent option.
g. Then click Save.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 31

Create or edit an option group

To open the Option group use the ‘Search apps’ menu in the upper right corner of the home
dashboard to navigate to the Maintenance app. Then click on the Other tab from the top
horizontal menu. Either click on Option group in the left column menu, or click on the Option
group box.

32 System Administrator User Guide

 1. Click the add ‘+’ button
2. In the Primary details tab, add the option set details
a. Name: type of the name of the option set.
b. Short name: add the option set’s short name (character limit: 50 characters)
c. Code: assign code - mainly used to exchange data with an external system.
d. Description: Add a description of the option group if necessary.
e. Option set: Add the name of the relevant option set.
f. Options:
i. Search for options to add to the group using the search field.
ii. Select the option(s) by clicking on them and then using the right arrow to
move them to the box on the right.
iii. To remove an option, click on it and use the left arrow to move it back to
the available items box.
g. Then click Save.

Example

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 33

Create or edit an option group set

34 System Administrator User Guide

To open the Option group set use the ‘Search apps’ menu in the upper right corner of the
home dashboard to navigate to the Maintenance app. Then click on the Other tab from the top
horizontal menu. Either click on Option group set in the left column menu, or click on the
Option group set box.

1. Click on the ‘+’ button

2. In the Primary details tab, add the option group set details
a. Name: type of the name of the option group set.
b. Short name: add the option group set’s short name (character limit: 50
characters max)
c. Code: assign code; mainly used to exchange data with an external system.
d. Description: Add a description of the option group set if necessary.
e. Option set: Add the name of the relevant option group set.
f. Options:
i. Search for options to add to the group using the search field.
ii. Select the options by clicking on them and then using the right arrow to
move them to the box on the right.
iii. To remove an option, click on it and use the left arrow to move it back to
the available items box.
g. Then click Save

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 35

Example, not [Link] specific:

Data elements
Data elements are the basic dimension of DHIS2. Data elements define what is actually recorded
in the system. For example, ‘’REA-Case-Incident type- COVID-19- Limitation: accessing prevention
services” tracks responses in relation to the lack of access to prevention of Covid.

Data elements can be disaggregated by a category combination if they are an aggregate data
element, or an option set if they are a tracker data element.

36 System Administrator User Guide

In the Maintenance app, you can also manage the following through the data elements module:

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 Create, edit, clone, share, delete, show details and translate
set

Create data elements

To create data elements:

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. This must be 50
characters or less. If the object name fits, there’s no need to shorten it. Otherwise, the
short name is a meaningful rewording 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 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.
6. In the Form name field, type the name of the data element exactly as it appears currently
on any existing data entry form. This may be the same or different to the data element
Name. The form name is used in the data entry screen and is what the data entry user
sees when entering data - so it is good to match exactly the wording of any pre-existing
tools.
7. In the Domain type field, select “Aggregate” if the data element will be used in an
aggregate data set, or “Tracker” if the data element will be used in an event or tracker
program.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 37

 8. In the Value type field, select the type of data that the data element will record. The table
below describes the value types available to select:

Value type table

Value type Description

Text Textual value. Max characters = 50,000

Textual value. Renders as text area with no length constraint in

Long text forms

Letter A single letter

38 System Administrator User Guide

Phone number A valid phone number

An email address in a valid format

Email

Yes/No Boolean values, renders as radio buttons in data entry

Yes only True values, renders as checkboxes in data entry

Date Date only

Date & Time Date plus time

Time Time only

Number Any valid number, including decimals

Unit interval Any decimal value between 0 and 1

Percentage Any decimal value between 0 and 100

Integer Any integer (whole numbers, no decimals)

Positive Integer Only positive integers (no zero or negative values)

Negative Integer Only negative integers (no zero or positive values)

Positive or zero integer Any positive whole number, including zero

Enables selection of an existing Tracker ‘tracked entity instance’ (e.g.,

Tracker Associate a person) as the value

Username Enables selection of a valid DHIS2 username as the value

Enables manual entry of geographical coordinates (doesn’t enable

Coordinate automatic capture of coordinates)

Organisation Unit Enables selection of a DHIS2 organisation unit as the chosen value

Enables entry of either an age in years/months/days or a date-of-

Age birth (both are stored as date-of-birth)

URL Enables manual entry of a URL

Enables upload of files in various format (requires appropriate

File storage to be configured)

Enables upload of files in various formats (requires appropriate

Image storage to be configured)

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 39

 9. In the Aggregation type field, select the default aggregation operation that will be used on
the data element. This property defines how the data element is aggregated both in time
and in the org unit hierarchy. The table below describes the aggregation types available
to select:

40 System Administrator User Guide

Aggregation type table

Aggregation type Description

Sum of data values in the period and organisation unit

Sum dimension

Average the values in both the period and the organisation unit
Average dimensions

Average (sum in org unit Average of data values in the period dimension, sum in the
hierarchy) organisation unit dimensions. For e.g., population data

Last value (sum in org unit The last value (by event date) available but sum up in the
hierarchy) organisation unit hierarchy

Last value (average in org unit The last value (by event date) available but average in the
hierarchy) organisation unit hierarchy

First value (sum in org unit The first value (by event date) but sum up in the organisation
hierarchy) unit hierarchy

First value (average in org unit The first value (by event date) but average in the organisation
hierarchy) unit hierarchy

Count Count of data values

Average the values in both the period as and the organisation

Standard deviation unit dimensions. For e.g., scorecards

Variance Variance (population-based) of data values

Min Minimum of data values

Max Maximum of data values

No aggregation is performed in any dimension. Useful for text

None or date value types

Allows for the specification of the aggregation type in-line in the

expression (as compared to the entire program indicator
Custom expression)

The default of the chosen value type. Being specific is

Default recommended, i.e., choosing another aggregation type.

10. Select Store zero data values if you want to capture the zero value in reports. By default,
analytics will skip copying zero data values from raw data into analytic tables.
11. In the Category combination field, define which category combination the data element
should have, if it is an aggregate data element. If none, leave as default.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 41

 a. Note that if the data element is a tracker data element, this field will be grayed out
and will not be open for selection.
12. For tracker data elements, if relevant, add the option set that will be available for the data
element in the program.

Other properties are optional and not covered by this manual. See the DHIS2 documentation for
more information.

13. Click Save.

Data element groups

Data element groups let you classify related data elements into a common theme. They can be
grouped together into a data element group for ease of analysis together.

A data element must be part of a data element group before it can be analysed in the analysis
apps.

To create data element groups:

1. Open the Maintenance app and click Data elements > Data element group.
2. Click the add button ‘+’.
3. Fill in the form:
a. Name including naming convention
b. Short name - must be less than 50 characters - will display in analytic modules.
4. Select data elements and assign them by moving them from the left-hand window
(available items) to the right (selected items) with the arrows or by double-clicking.

5. Click Save.

Tracked Entity Types & Tracked Entity Instances

42 System Administrator User Guide

A Tracked Entity Type (TET) is a type of entity which can be tracked through the system. It can be
anything from persons to commodities, for example medical supplies, an individual or a
household.

A tracker program must have a tracked entity type associated with it. Tracked Entity Instances
(TEIs) are registered to the program and tracked. For example, if the TET for a program was a
child, then the TEIs would be child 1, child 2, child 3, etc. who are registered to the program.

TEI =
TET = Child 1,
Child Child 2,
etc.

To enroll a tracked entity instance into a program, the tracked entity type and tracked entity type
of a program must be the same.

Create Tracked Entity Types

To create a tracked entity type:

1. Open the Maintenance app and click Program > Tracked entity type.

2. Click the add button ‘+’.

3. Name: In the Name field, type the tracked entity.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 43

 4. Select a color and an icon that will be used by data capture apps to identify the tracked
entity type (optional).
5. Enter a description of the tracked entity (optional).
6. Enable tracked entity instance audit log (optional).
7. Enter a minimum number of attributes required to search (optional).
a. This specifies the number of attributes that need to be filled out in order to be
able to search for this tracked entity type in a global search.
8. Enter a maximum number of tracked entity instances to return in search.
a. This specifies the amount of tracked entity instances that will be returned in a
global search.
9. Select a Feature type (optional): No value, None, Point, Polygon
10. Add tracked entity type attributes (optional).
a. Using the arrows, assign the Tracked Entity Type Attributes by moving them from
the left box, listing the TETs available, to the right box, listing the TETs selected.

i. Select a TET from the left box by double clicking on it or click on it once to
highlight it and using the arrow pointing right, move it to the right box.

11. Enter an Alternative name for the tracked entity.

a. For the tracked entity created, tick the boxes that apply to it:
i. Display in list
ii. Mandatory
iii. Searchable
12. Click Save.

Example

44 System Administrator User Guide

Tracked Entity Attributes
Tracked entity attributes are used to register extra information for a tracked entity. Tracked entity
attributes can be shared between programs.

Create tracked entity attributes

To create a tracked entity attribute:

1. Open the Maintenance app and click Program > Tracked entity attribute

2. Click on the add button.

3. Name: type the tracked entity attribute name.
4. Short name: Add a short name. Character limit 50.
5. Form name: Add a form name.
6. Code: assign code; mainly used to exchange data with an external system.
7. Description: Provide a description.
8. Field mask field, type a template that’s used to provide hints for correct formatting of the
attribute.
a. Note* only implemented in the DHIS2 Android Capture app
9. Select an Option Set
10. Select the relevant Value Type - See Value Type Table
11. Select the relevant Aggregation Type - See Aggregation Type Table
12. Select Unique to specific that the values of the tracked entity attribute is unique
a. There are two options for the unique setting

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 45

 i. 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.
ii. Select Automatically generate 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 works.
iii. Organisation unit: the values of the tracked entity attribute must not
duplicate in the same organisation unit
13. Select inherit to registry a new entity for relationship with an available entity.
14. Select Confidential (Optional).
a. This option is only available if you have configured encryption for the system
15. Select Display in list without program (Optional).
16. Assign one or multiple Legends (Optional).
17. Click on Save.

46 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 47
Relationships
A relationship represents a link between two entities in the Tracker-model. A relationship is
considered data in DHIS2 and is based on a Relationship Type, similar to how a Tracked Entity
Instance is based on a Tracked Entity Type.

Relationships include two entities, these can include Tracked Entity Instances, Enrollments and
Events. They can be defined as unidirectional or bidirectional, where unidirectional mean the
relationship can be only added as a one-way relationship (i.e., mother will be created in a
maternal and child health program for ANC, before child is created at birth) and bidirectional
means the relationship can be added at any point from one TEI to the other (i.e. siblings added
to a household).

Relationship Types

A relationship type is the definition of the properties a relationship has.

Relationships are made up of two sides: ‘From’ and ‘To’. The entities that can be contained for
each side are determined by the Relationship Type.

The properties that determine what each can contain are constraints, specifically, ‘from
Constraint’ and ‘to Constraint’. These are significant to the data later on when understanding
what a relationship can contain.

To create or edit a Relationship Type, open the Maintenance app and click on Program >
Relationship type

48 System Administrator User Guide

 1. Click on the add button
2. Name: Type a name for the relationship.
3. Code: assign code; mainly used to exchange data with an external system.
4. Description: add relationship description.
5. Bidirectional: Select whether the relationship should be bidirectional.
6. Relationship name seen from initiating entity: This is the name of the relationship that will
be shown in the Data Entry app at the left side of the relationship, i.e., in a mother-child
relationship this could be ‘mother of’).
7. Relationship name seen from receiving entity: this is the name of the relationship that will
be shown at the ‘right’ side of the relationship in the Data Entry app; i.e., in a mother-child
relationship, this could be ‘mother’.
8. Select a ‘from constraint’: this limits what kind of entities can be included in the
relationship.
a. See Relationship types section
9. Select a ‘to constraint’: This limits what kind of entities can be included in the relationship.
a. See Relationship types section
10. Click Save.

*Please note that even though a relationship is tagged as bidirectional, it should be used a
unidirectional in order to function well due to a bug in DHIS 2.

In the [Link] system the main relationship types include:

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 49

 Relationship Purpose

Household ‒ OVC Link a household to an OVC

Household ‒ Link a household to a caregiver

caregiver

Caregiver - OVC Link a caregiver to an OVC

50 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 51
Programs
In DHIS2 it is possible to define your own programs with stages. These programs are an essential
part of the “tracker” functionality which lets you track individual records. It is also possible to track
other ‘entities’ such as goods in logistics, insurances, etc.

There are two main program types. An Event Program or a Tracker Program.

Event Programs

An Event Program is a program that uses a single event without any registrations of tracked
entities. This means anonymous, individual events are tracked through the health system. No
person or entity is attached to these individual transactions. Examples of this type of system use
include surveys, tracking the distribution of malaria drugs and households for nutrition
programs.

Tracker Programs

A Tracker Program is a program that uses one or multiple events linked to a tracked entity
instance that needs to be registered beforehand. A program must be specified with only one
tracked entity. Only tracked entities that are the same as the tracked entity of the program can
enroll into that program. A program needs several types of metadata which can be established
in the Maintenance apps.

Create a Tracker Program

To create a tracker program:

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

2. Click on the blue plus sign and select Tracker Program.

Program details

1. Open the Maintenance app and click Program > Program

52 System Administrator User Guide

2. Enter the program details then click next

a. Name: Enter a name for the program

b. Short name: Enter the short name; it is used as the default chart or table title

c. Code: assign code; mainly used to exchange data with an external system.

d. Color: Color used for this program in the data capture apps

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

f. Description: a detailed description of the program

g. Version: The version of the program, this is use 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.

h. Tracked entity type: Client; server specific TET options

i. Category combination: The category combination you want to use. The default
setting is none.

j. Display front page list

k. First stage appears on registration page

l. Access level: no value; open; audited; protected; or closed

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 53

 m. Completed events expiry date: defines the number of days for which it is possible
to edit a completed event. If an event is completed and the specified time period
has passed, the event is then locked.

n. Expiry period type: defines for how many days after the end of the previous period
an event can be edited.

o. Minimum number of attributes required to search

p. Maximum number of tracked instances to return in search

Then click on “2 Enrollment details”.

54 System Administrator User Guide

Enrollment details

Select the options that apply to the program:

1. Allow future enrollment dates

2. Allow future incident dates
3. Only enroll once (per tracked entity instance lifetime)
4. Show incident date

Then add the following details:

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 55

 5. Description of the incident date
6. Description of the enrollment date
7. Choose whether or not to Ignore overdue events
8. Select a feature type: no value; none; point; polygon.
9. Select a related program.

Then click on “3 Attributes”.

Attributes

56 System Administrator User Guide

Assign attributes

Using the arrows, assign the Tracked Entity Attributes for the program by moving them from the
left box, listing the TEAs available, to the right box, listing the TEAs selected.

Select a TEA from the left box by double clicking on it or click on it once to highlight it and using
the arrow pointing right move it to the right box.

Then using the tick boxes, review the columns outlining the options for each TEA which are listed
in the column on the left; tick/select the options that are valid for them.

1. Name: TEA names

2. Display in list:
3. Mandatory: requires a response
4. Searchable: allow TEA to be searchable
5. Mobile render type: Can be used to select different render types for mobile devices.
Options vary depending on DE value type.
6. Desktop render type: Can be used to select render types for the desktop (i.e., the web
interface). Options vary depending on DE value type.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 57

Create registration form

Scroll down to the bottom of the page to section two to select a tab for creating either a new form
Section or the Custom form option.

Section
1. Click on the plus button under the section tab
2. Add a new Section name
3. Add a description for the section
4. Mobile render type: makes it possible to select different render types for mobile devices;
available options vary depending on the DE value type.
5. Desktop render type: Can be used to select render types for desktop. Also depend on DE
value type.

Custom
1. Use the WYSIWYG (“what you see is what you get”) editor to create an entirely customized
form. If Source is selected, past HTML code directly into the editing area. You may include
JavaScript or external libraries to enhance the User Experience–but keep in mind that
custom forms are only supported in the web version of DHIS2 and not in the Android app
(DHIS2 Capture app).

Then click Next (click on the arrow symbol).

58 System Administrator User Guide

Program stages

Click on the plus button to add a program stage.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 59

Stage Details

Complete the form with the following details:

1. Name: Enter a name for the stage

2. Color: Assign the stage a color
3. Icon: Assign the stage an icon
4. Description: Add a stage description
5. Scheduled days from start
6. Repeatable (tick or untick)
7. Period type
8. Display generate even box when completed
9. Standard interval days
10. Default next scheduled date
11. Auto-generate event: (tick or untick)
12. Open data entry from after enrollment: (tick or untick)
13. Report date to use: (tick or untick)
14. Allow user assignment of events: (tick or untick)
15. Block entry from after completed: (tick or untick)
16. Ask user to create new even when stage is complete: (tick or untick)
17. Generate events based on enrollment date: (tick or untick)
18. Hide due date: (tick or untick)
19. Feature type: None; no value; point; polygon
20. Pre-generate event UID: (tick or untick)
21. Description of report date

60 System Administrator User Guide

 22. Description of due date

Scroll down to the bottom to the page and move to section two.

Assign data elements

Using the arrows, assign the data items for the program by moving them from the left box, listing
the data items available, to the right box, listing the data items selected.

Select a data item from the left box by double clicking on it, or click on it once to highlight it and
using the arrow pointing right move it to the right box.

Then using the tick boxes, review the columns outlining the options for each data element, listed
in the column on the left, and select the options that are valid for them.

1. Name
2. Compulsory
3. Allow provided elsewhere
4. Display in reports
5. Date in future
6. Skip synchronization
7. Mobile render type: makes it possible to select different render types for mobile devices;
available options vary depending on the DE value type.
8. Desktop render type: Can be used to select render types for desktop. Also depend on DE
value type.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 61

Then scroll to the bottom to move to section three, “create data entry form”.

Create data entry form

Select options for the data entry form:

Basic: Lists all data elements which belong to the program. It is possible can change the order of
the data elements.

Section: A section groups data elements, it is possible then possible to arrange the order of the
sections to create the desired layout of the data entry form.

Custom: Defines the data entry form as an HTML page.

After completing these details, select the next phase, 5 Access.

62 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 63
Access

Select the organization units that will have access to the form by assigning organisation units.

1. In the organisation unit hierarchy tree, double-click the organisation units you want to
add the program to; expand the different levels by clicking on the arrows.

64 System Administrator User Guide

Next, scroll down to the Role and Access section:

1. The first row shows the main programs access options and each subsequent row shows
the options of one program stage,
2. Program stages with an exclamation mark mean they can be access by a different
combination of users
3. Next, select the program or program stage that requires sharing settings to be edited
4. The Sharing Settings prompt will appear
a. Use the ‘add users and user groups’ search field to search for the users or user
groups that the program or program stage is going to be shared with
b. Click on the relevant search result to add it to the Who has access section
c. Once it has been added, click on the pencil symbol to edit the sharing option for
that user or user group
i. The options for metadata: Can edit and view; can view only
ii. The options for data: Can capture and view; Can view only; no access
d. Then click on apply
5. Click apply to selected stages if the same program sharing settings are relevant for the
program stages
6. If there are different sharing settings for each stage, repeat this process (steps 1-4) for
each program stage
a. It is also possible to copy all access options from the main program to child
programs; to do so, tick the box on the right side of the program stages

Once all sharing options have been edited, click on Next to move to the next section, section 6,
Notifications.

Notifications

1. Click on the plus button in the bottom right corner.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 65

 2. Choose either program stage notifications or program notifications.

What to send?
1. Enter the name or title of the message that will appear
2. Complete the message template
a. Enter the subject template
b. Next enter the message template
i. Double click the parameters in the Template variables field to add them to
your subject. Example: “Hello Jane, you are now enrolled in
V{program_name}.”

When to send it?

1. Specify when the message appears,
a. Example: upon
i. Program completion
ii. Specified days scheduled
iii. Program rule

Who to send it to?

1. Specify who will receive the message
a. Notification recipient examples: Tracked entity instance, org unit contact, users at
org unit, user group, program attribute etc.

66 System Administrator User Guide

Example

Program rules
Program rules can be configured to add conditional behavior to tracker forms.

In this way, they produce dynamic behaviors in tracker and event capture. They belong to one
program and consist of an expression and one or more actions. They are evaluated each time
the user interface is displayed and a data element is changed.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 67

In addition to running these rules in the tracker apps, the tracker importer will also run a selection
of these rules.

Program rule component Description

Program rule action Program rules actions are activated when the
expression is true. Actions will be utilized
immediately if the expression is true and will
be reverted if the expression is not true.

Program rule expression Each program rule has a single expression

that determines whether the program rule
actions should be activated, if that expression
is true. When the expression is false, the
program rule actions are not applied.

Program rule variable Program rule variables are created for the
purpose of including data values and
attribute values in program rule expressions.
Program rule expressions usually contain at
least one data element or attribute value.

Program rules components function through the action applied.

There are several types of actions, and several can be used in one program rule.

Most types of actions will take effect immediately when the user enters values in the Tracker
Capture and Event Capture apps.

Actions

Assign value Hide option Schedule message

Display key/value pair Hide option group Send message

Display text Hide program stage Show error

Error on complete Hide section Show option group

68 System Administrator User Guide

Hide field Make field mandatory Show warning

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 69

Examples of conditional behavior in tracker form

Label Behavior Program rule

Did child previously have an

1 adverse drug Reactions? yes/no

if row 1 is yes, then put reaction Display if row 1=Yes

2 Reaction Date date

The following conditions must be considered for program rules:

1. The program rule must be linked to the data being imported (program stage or data
element)
2. The program rule’s condition must be evaluated to true

The following program rule objects are managed in the maintenance app.

70 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 71
Create program rule variable(s)

Program rule variables are required to be configured prior to Program Rules, as Program Rules
draw from variables to create their logic. Program Rule Variables belong to a specific program,
have a name and a source type. Source types define where the variable draws the value from
and can be one of:

● Data element from the newest event for a program stage

● Data element from the newest event in the current program (regardless of stage)
● Data element in current event
● Data element from previous event
● Calculated value (e.g., from multiple other data elements)
● Tracked entity attribute

In case the data element or tracked entity attribute uses an option set it is recommended to ticket
“Use code for option set” as the option code is unique and usually does not change. This has the
advantage of mapping the code to the value directly.

Create or edit a program rule

1. To create program rules:

a. Open the maintenance app and click Program > Program rule
b. Click on the add button ‘+’

72 System Administrator User Guide

Enter program rule details

c. Select the program from the program drop down list

d. Trigger rule only for program stage (to declare that the rule should only run for
the selected program stage instead of every program stage of the program)
e. In the Name field, type the action name and the name of the full name of the
variable that is being referred to
f. In the Description field, type a brief, informative description of the program rule
g. Priority (to define the priority in case of conflicting program rules that would like
to act on the same data)

Example

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 73

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

74 System Administrator User Guide

Define program rule actions

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.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 75

Indicators
In DHIS2, an indicator consists of a formula that can be made up of individual or multiple data
elements, disaggregations, constants, attributes (projects), reporting rates, organisation unit
group counts and mathematical operators. The indicator consists of a numerator and
denominator, though a denominator may simply be ‘1’. Indicators are used to calculate coverage
rates, incidence, scorecard totals and other values that are meaningful as a result of data element
values that have been entered into the system.

Indicators are never entered directly in DHIS2, they are calculated from constituent parts - most
notably data elements. That is to say, indicators cannot be entered during data entry. Indicators
can be added, deleted, or modified at any time in DHIS2 without affecting the data. It follows that
indicators are not stored as values in DHIS2, but as formulas, which are calculated whenever the
user needs them. Thus, a change in the formulas will not change the underlying data values, only
the value of the indicator itself.

Before creating an indicator, you would first create indicator types. This has already been done
on the [Link] server.

Create indicators

To create indicators:

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

76 System Administrator User Guide

2. Click the add button ‘+’.

3. In the Name field, type the full name of the indicator, applying the naming convention.
a. Short name: does not include a naming convention but must be less than or equal
to 50 characters, including spaces. This can be the same as the full name, or a
meaningful shorter version.
b. In the Description field, type a brief, informative description of the indicator and
how it is calculated. It would also be a good place to provide information about
any relevant report that the indicator reports on.
c. 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.
d. Select the number of Decimals in data output. i.e., how many decimals you want
in your indicator value. Leave blank for ‘0’.
e. 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

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 77

 multiplied by a factor of 100 when exported to the data mart, so that it will display
as a percentage.
4. Click Edit numerator. A new pane will pop up.

a. Type a clear description of the numerator.

b. Define the numerator by double-clicking components in the right-hand field. The
component 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. The
formula must be mathematically valid, including correct use of parentheses when
necessary. A valid formula will show a description at the bottom of the numerator
window.
c. Click Done to save all changes to the numerator.
5. Click Edit denominator. A similar window will pop up.
a. Repeat the same steps as for step 4.
b. If there is no denominator, then a value of ‘1’ should be defined in both the
description field and the formula pane.
c. Click Done to save all changes to the denominator.
6. Click Save.

Indicator groups

78 System Administrator User Guide

An indicator group can serve two main purposes. First of all, for any indicator to be accessible
within the analytic modules, it must first be part of an indicator group. Secondly, it allows for ease
of analysis by grouping related indicators together.

As standard, all indicators relating to a particular technical area within a project should be
grouped together. It is possible to create as many groups as you have reasons to create them
beyond this.

To create indicator groups:

1. Open the Maintenance app and click Indicator > Indicator group.
2. Click the add button ‘+’.
3. In the Name field, type the full name of the indicator group and applying the naming
convention.
4. Select indicators and assign them, moving them from the left window to the right by use
of the arrows.
5. Click Save.

Program Indicators
In DHIS2 Program indicators (PI) are formulated using expressions based on tracker data
elements, tracked entity attributes, or variables. Values are based on a formula. PI are used in
aggregate event reports, event visualizer or aggregate apps. They are linked to one particular
program and are used to calculate across events or enrollments.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 79

80 System Administrator User Guide
Create program indicators

To create program indicators:

1. Open the Maintenance app and click Indicator > Program indicator
2. Click the add button ‘+’

Program indicator details

3. In the Program field, select the program from the drop-down menu.
4. In the Name field, type the full name of the program indicator, applying the naming
convention.
a. Short name: does not include a naming convention but must be less than or equal
to 50 characters, including spaces. This can be the same as the full name, or a
meaningful shorter version.
b. Code: assign code; mainly used to exchange data with an external system.
c. Color: to define a color for the Android app (Capture app)
d. Icon: to define an icon for the Android app (Capture app)
e. Description: In the Description field, type a brief, informative description of the
indicator and how it is calculated. It would also be a good place to provide
information about any relevant report that the indicator reports on.
f. Decimals in data output: Select the number of Decimals in data output, i.e., how
many decimals you want in your indicator value. Leave blank for ‘0’.
g. Aggregation type: The aggregation type determines how the program indicator
will be aggregated.

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

i. Display in form: whether you want to show the indicator calculated live in data
entry (Tracker capture)
j. Legends: to colour code your indicator
k. Category option combination for aggregate data export: used for system
integrations to map Tracker data into aggregate (data sets)

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 81

 l. Attribute option combination for aggregate data export used for system
integrations to map Tracker data into aggregate (data sets)

Edit expression

5. Click on the next stage, Edit expression

a. Color: assign a color
b. Icon: assign an icon
c. Expression: Create an expression based on mathematical operators and the
attributes, variables, and constants listed on the right -

82 System Administrator User Guide

 i. Case details
ii. Attributes
iii. Variables
iv. Constants

Edit filter

6. Click on the next stage Edit filter.

a. Color: assign a color
b. Icon: assign an icon
c. Expression: Create an expression based on mathematical operators and the
attributes, variables, and constants listed on the right -
i. Case details
ii. Attributes
iii. Variables

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 83

 iv. Constants

Then click on Save.

Languages and Translations

Additional translations may need to be added, if other languages than those included are needed.

Db languages

DHIS2 supports translations of database content, such as data elements, indicators, and
programs. All metadata objects in the Web API have properties meant to be used for display / UI
purposes, which include displayName, displayShortName and displayDescription.

84 System Administrator User Guide

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 85
4 | Metadata Nomenclature & Structure
Organization Unit Hierarchy
The organizational unit hierarchy and geospatial data was created as follows:

Level Values Geospatial

Level 1 Country n/a

Level 2 Province n/a

Level 3 District n/a

Level 4 Ward n/a

Available Programs
Below is a list of programs that are in [Link]’s DHIS2 instance:

Program Name UID Type of Program

Beneficiary rWtvW3grGDa Tracker

Household ITaqt0loQak Tracker

86 System Administrator User Guide

5 | User Management
The user management theme in [Link] is to keep things simple and straightforward in order to
avoid any user-management bottlenecks that can happen with high complex and custom user
management configurations.

User Roles
In [Link]’s DHIS2 instance, these roles are separate from each other and can be used as
standalone roles.

Description of User Groups

User Role Description

1. Dashboards “View Includes dashboard module only and ability to create private
dashboard only” - read and dashboards.
create private dashboards

2. Analytics only (with Event Includes Dashboard module, Pivot Table, Data Visualizer,
Reports): Read and create Maps and Event reports. Users with this access can create
private analytic favourites private charts and tables favourites, and share them with
others.

3. Analytics only (without Includes Dashboard module, Pivot Table, Data Visualizer and
Event Reports): Read and Maps. Users with this access can create private charts, and
create private analytic tables favourites, and share them with others.
favourites

4. [Link] role to ignore Role for [Link] to conduct data sync without filling all TEAs
validation of mandatory
TEAs

5. Data Entry (tracker data Include Add/Update and Delete of data values in Tracker
entry user): To enter and Capture app
import data, but no specific
data set access

6. Superuser/Administrator All non-server-side roles within DHIS2. (I.e., universal

(Superuser): Read and create permissions) - restricted to system administrators
public objects

For a user to be able to enter data, simply providing the ‘3. Data entry’ user role is not enough.
They would still require access to the relevant organisation units to be able to see the locations
where particular data are captured, as well as specific data capture sharing access conferred by

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 87

being part of a user group where that level of sharing is applied. This is expanded in the sections
on user groups and sharing below.

Sharing
The below tables define the level of access the various user groups are given, and how specific
objects should be shared with them.

Since there is no project-level administration, all metadata are public read and write. Access to
the applications will be done through User Roles, so even though metadata access may be public,
the user would not be able to update or create metadata in the instance since they would not
have access to the application where this function is performed.

Paired with the user roles, only the Superusers and System Administrators will be able to edit or
add new metadata.

● Metadata: None = no sharing; R = read only; R/W = read and write

● Data: None = cannot see data; V = View data; C/V = capture and view data
● All objects are metadata shareable, but only some require data sharing levels, primarily
Cat Options and Data sets.
● Cells are completed in the format “metadata / data”

Level of access for metadata in [Link]:

Object Type Public Administrators/ Project specific

Superusers teams

Category Options R/W R/W

C/V C/V

Categories R/W R/W

Project specific Category R R/W R/W their specific

Options project option

Category Combo R/W R/W

Data Elements R/W R/W

Data Element Groups R/W R/W

Indicators R/W R/W

88 System Administrator User Guide

 Indicator Groups R/W R/W

Data Sets R/W R/W

C/V C/V

Sharing of Analytic Objects

Analytic objects, which includes tables, charts, maps, etc. can also be shared among user groups.
This gives tailored access to different analytic objects based on predefined groups.

Superusers and System Administrators can create public objects. Users who are not Superusers
or System Administrators will only be able to create private objects. They will then be able to
share objects as they wish using user groups or specific users.

User Account Management

A user account brings together a unique combination of where in the organisation unit hierarchy
a user can perform their tasks, the groups with which objects are shared that a user can see and
use or edit, and the roles that provide permission for them to carry out those tasks. This nuanced
combination allows a great level of control and access to user permissions.

Username Protocol

Users will login using their [Link] or other organisational email address, all lowercase letters.

Analysis Org Unit Policy

In [Link], all users have access to view data at a country level, so the assigned organization unit
is ‘Ethiopia’.

Data Entry Org Unit Policy

In [Link], data entry is restricted by using User Roles. To ensure ease of updating users' access
if they need to enter data, all users are assigned the country organization unit (‘Ethiopia’).

User Roles Policy

User roles are assigned based on the functions the user will need to perform in [Link]. See User
Personas and User Roles sections for more details.

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 89

6 | Metadata Import: BAO Import Foundry
(BIF)
BIF is a user-friendly configuration tool used to quickly and easily create metadata objects in bulk
upload form. Using a standard format CSV file uploaded via BIF, the metadata objects are then
created in DHIS2 saving users time bypassing complex API configuration or directly using the
DHIS2 interface. BIF is made up of a series of modules, each designed to create specific metadata
objects in DHIS2 form. The tool allows users to create all of their metadata objects in one shot.

For more information on how to use the BIF tool, refer to the BIF User Guide for the most up to
date information.

We have created a series of demonstration videos to also help with understanding:

● BIF Part 1
● BIF Part 2
● BIF Part 3
● BIF Part 4

90 System Administrator User Guide

7 | Troubleshooting & General Admin Tasks
Data Integrity
DHIS2 can perform a wide range of data integrity checks on the metadata 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 are described, along with general procedures that can be performed to resolve
these issues in the DHIS2 documentation here.

Process for escalating problems to get support from [Link]

To get support from [Link], a ticket will need to be submitted via the ticketing system, Freshdesk.
This can only be done by the following system administrators at [Link]’s HQ:

● Point of contact
○ FACT and CRS to name at least one individual
● Jenny Mwanza - [Link]@[Link]
● Name - email (System administrator) (TBD)

Clearing Cache
While customizing the configuration of DHIS2, you will oftentimes run into issues with DHIS2 not
reflecting the most up to date changes. This is a side-effect of DHIS2 using the browser cache to
optimize for offline-storage features which helps preserve the system's state when offline.

When this happens, users will simply need to clear their browser cache. This can be done using
the native DHIS2 browser cache cleaning tool which can be found by searching for it in the apps
menu. Other users use the dev tools or a chrome extension to perform this task more routinely
and quickly.

To use the native browser cache cleaning tool, being by searching for it in the apps
menu:

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 91

Then use the “select all” button to toggle all items, or you can individually select each box you’d
like to clear the cache for. Generally, it is fine to clear them all.

Lastly, select the “clear” button and carry on with your previous task.

Forgotten password
If you have forgotten your password, you can always use the ‘Forgot password?’ link. This will
send an email to the email address associated with your account inviting you to reset your
password.

92 System Administrator User Guide

To avoid issues when resetting your password, double check your chosen password meets the
rules outlined here:
[Link]
sword

Comprehensive System Administrator Guide for [Link]’s DHIS2 Software in Zimbabwe 93

TL-21-23

Data for Implementation ([Link]) is a five-year cooperative agreement funded by

PEPFAR through USAID under Agreement No. 7200AA19CA0004, beginning April
FOR MORE INFORMATION
15, 2019. It is implemented by Palladium, in partnership with JSI Research &
Training Institute, Johns Hopkins University Department of Epidemiology, Right to Contact [Link] at
Care, Cooper/Smith, IMC Worldwide, Jembi Health Systems, and macro-eyes, and datafiproject@[Link], or:
supported by expert local resource partners.
Emily Harris, [Link] AOR
This publication was produced for review by PEPFAR through USAID. It was emharris@[Link]
prepared by [Link]. The information provided is not official U.S. government
information and does not necessarily reflect the views or positions of PEPFAR,
USAID, or the United States Government. Jenifer Chapman, [Link] Project Director
datafiproject@[Link]
SEPTEMBER 2021 [Link]

94 System Administrator User Guide