DHIS2 User guide

2.25

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.

Revision History
Revision 2.25@874b2562016-11-23 10:45:57
Version 2.25

Table of Contents

About this guide
1. What is DHIS2?
1.1. DHIS2 Background
1.2. Key features and purpose of DHIS2
1.3. Use of DHIS2 in HIS: data collection, processing, interpretation, and analysis.
1.4. Technical background
1.4.1. DHIS2 as a platform
1.4.2. Understanding platform independence
1.4.3. Deployment strategies - online vs offline
1.5. Difference between Aggregated and Patient data in a HIS
1.6. Free and Open Source Software (FOSS): benefits and challenges
2. Getting started with DHIS2
2.1. Using the DHIS2 demo server
2.2. Using the DHIS2 live package
2.2.1. Starting the DHIS2 Live package
2.2.2. Downloading and installing the server version
2.3. Logging on to DHIS2
2.4. Logging out of DHIS2
2.5. Quick intro to designing a DHIS2 database
2.5.1. The organisational hierarchy
2.5.2. Data Elements
2.5.3. Datasets and data entry forms
2.5.4. Validation rules
2.5.5. Indicators
2.5.6. Report tables and reports
2.5.7. GIS
2.5.8. Charts and dashboard
3. Data dimensions in DHIS2
3.1. Data dimensions: Core building blocks in DHIS2
3.2. Data elements: The What dimension
3.2.1. Data element categories
3.2.2. Data element group sets
3.3. The organisation unit dimension
3.3.1. Organisation unit group sets and groups
3.3.2. Best practice on the use of group sets and groups
3.4. The period dimension in DHIS2
3.4.1. Period Types
3.4.2. Relative periods
3.4.3. Aggregation of periods
3.5. Data collection vs. data analysis
3.5.1. Data collection and storage
3.5.2. Input does not equal Output
3.6. Extended examples of data elements and forms
3.7. How this works in pivot tables
3.8. Case study: From paper forms to multidimensional datasets - lessons learned
3.8.1. From tables to category combinations - designing multi-dimensional data sets
3.8.2. Step-by-step approach to designing datasets
4. User management
4.1. Creating new users and roles
4.1.1. User maintenance
4.1.2. User role management
4.1.3. User management
4.1.4. User by organisation unit
4.1.5. Managed users
4.1.6. OpenID Support
5. Sharing
5.1. Sharing of objects
5.2. Sharing and access control
5.3. Sharing applied
6. Dashboards
6.1. About dashboards
6.2. Setting up the dashboard
6.3. Change dashboards name
6.4. Add message widget to dashboards
6.5. Delete dashboards
6.6. Translate dashboard names
6.7. Dashboard Sharing
6.8. Manage messages and feedback messages
6.8.1. About messages and feedback messages
6.8.2. Create a message
6.8.3. Read a message
6.8.4. Create a feedback message
6.8.5. Configure feedback message function
6.8.6. Manage feedback messages
7. Data entry
7.1. Data entry with DHIS2
7.1.1. Selecting the data entry form
7.1.2. Entering data
7.1.3. Editing and deleting data
7.1.4. Validating data in the form
7.1.5. Off-line data entry
7.1.6. Multi-organisation unit data entry
8. Using Data Quality functionality
8.1. Overview of data quality checks
8.2. Data quality checks
8.3. Running Validation Rule Analysis
8.4. Std Dev Outlier Analysis
8.5. Min-Max Outlier Analysis
8.6. Follow-Up Analysis
9. Setting up Data Quality functionality
9.1. Overview of data quality check
9.2. Data quality checks
9.3. Data quality check at the point of data entry
9.3.1. Setting the minimum and maximum value range manually
9.3.2. Generated min-max values
9.4. Validation Rule
9.5. Validation Rule Group
9.6. Scheduled Validation Runs
10. Using the Maintenance app
10.1. Manage categories
10.1.1. About categories
10.1.2. Workflow
10.1.3. Create a category option
10.1.4. Create a category
10.1.5. Create a category combination
10.1.6. Create a category option group
10.1.7. Create a category option group set
10.1.8. Use category combinations for data sets
10.1.9. Assign a code to a category option combination
10.1.10. Edit metadata objects
10.1.11. Clone metadata objects
10.1.12. Change sharing settings for metadata objects
10.1.13. Delete metadata objects
10.1.14. Display details of metadata objects
10.1.15. Translate metadata objects
10.2. Manage data elements
10.2.1. About data elements
10.2.2. Workflow
10.2.3. Create a data element
10.2.4. Create a data element group
10.2.5. Create a data element group set
10.2.6. Edit data elements and other objects
10.2.7. Clone data elements and other objects
10.2.8. Change sharing settings for data elements and other objects
10.2.9. Delete data elements and other objects
10.2.10. Display details of data elements and other objects
10.2.11. Translate data elements and other objects
10.3. Manage data sets and data entry forms
10.3.1. About data sets and data entry forms
10.3.2. Workflow
10.3.3. Create a data set
10.3.4. Edit data sets
10.3.5. Clone data sets
10.3.6. Change sharing settings for data sets
10.3.7. Delete data sets and forms
10.3.8. Display details of data sets
10.3.9. Translate data sets
10.3.10. Override data elements' category combinations in a data set
10.3.11. Edit compulsory data elements in a data set
10.3.12. Download default data forms in PDF format
10.3.13. Manage section forms
10.3.14. Manage custom forms
10.4. Manage indicators
10.4.1. About indicators
10.4.2. Workflow
10.4.3. Create an indicator type
10.4.4. Create an indicator
10.4.5. Create an indicator group
10.4.6. Create an indicator group set
10.4.7. Edit indicators and other objects
10.4.8. Clone indicators and other objects
10.4.9. Change sharing settings for indicators and other objects
10.4.10. Delete indicators and other objects
10.5. Manage organisation units
10.5.1. About organisation units
10.5.2. Workflow
10.5.3. Create an organisation unit
10.5.4. Create an organisation unit group
10.5.5. Create an organisation unit group set
10.5.6. Edit organisation units and other objects
10.5.7. Clone organisation units and other objects
10.5.8. Change sharing settings for organisation unit groups and group sets
10.5.9. Delete organisation units and other objects
10.5.10. Display details of organisation units and other objects
10.5.11. Translate organisation units and other objects
10.5.12. Assign names to organisation unit levels
10.5.13. Move organisation units within a hierarchy
10.6. Manage program metadata
10.6.1. About program metadata
10.6.2. Create a tracked entity attribute
10.6.3. Create a tracked entity attribute group
10.6.4. Create a relationship type
10.6.5. Create a tracked entity
10.6.6. Edit metadata objects
10.6.7. Clone metadata objects
10.6.8. Delete metadata objects
10.6.9. Change sharing settings for metadata objects
10.6.10. Display details of metadata objects
10.6.11. Translate metadata objects
10.7. Manage attributes
10.7.1. About attributes
10.7.2. Create an attribute
10.7.3. Edit metadata objects
10.7.4. Clone metadata objects
10.7.5. Delete metadata objects
10.7.6. Display details of metadata objects
10.7.7. Translate metadata objects
10.8. Manage constants
10.8.1. About constants
10.8.2. Create a constant
10.8.3. Edit metadata objects
10.8.4. Clone metadata objects
10.8.5. Change sharing settings for metadata objects
10.8.6. Delete metadata objects
10.8.7. Display details of metadata objects
10.8.8. Translate metadata objects
10.9. Manage option sets
10.9.1. About option sets
10.9.2. Create an option set
10.9.3. Edit metadata objects
10.9.4. Clone metadata objects
10.9.5. Change sharing settings for metadata objects
10.9.6. Delete metadata objects
10.9.7. Display details of metadata objects
10.9.8. Translate metadata objects
10.10. Manage legends
10.10.1. About legends
10.10.2. Create a legend
10.10.3. Edit metadata objects
10.10.4. Clone metadata objects
10.10.5. Change sharing settings for metadata objects
10.10.6. Delete metadata objects
10.10.7. Display details of metadata objects
10.10.8. Translate metadata objects
10.10.9. Assign a legend to indicator or data element
10.11. Manage predictors
10.11.1. About predictors
10.11.2. Create a predictor
10.11.3. Edit metadata objects
10.11.4. Clone metadata objects
10.11.5. Delete metadata objects
10.11.6. Display details of metadata objects
10.11.7. Translate metadata objects
10.12. Manage push reports
10.12.1. About push reports
10.12.2. Create a push report
10.12.3. Preview push reports
10.12.4. Run push report jobs
10.12.5. Edit metadata objects
10.12.6. Clone metadata objects
10.12.7. Delete metadata objects
10.12.8. Display details of metadata objects
10.12.9. Translate metadata objects
10.13. Manage external map layers
10.13.1. About external map layers
10.13.2. Create an external map layer
10.13.3. Edit metadata objects
10.13.4. Clone metadata objects
10.13.5. Delete metadata objects
10.13.6. Display details of metadata objects
10.13.7. Translate metadata objects
10.14. Edit multiple object groups at once
10.14.1. Edit multiple objects in an object group
10.14.2. Edit an object in multiple object groups
11. Using reporting functionality
11.1. Reporting functionality in DHIS2
11.2. Using standard reports
11.3. Using dataset reports
11.4. Using resources
11.5. Using reporting rate summary
11.6. Using organisation unit distribution reports
12. Using the Pivot Table app
12.1. About the Pivot table app
12.2. Create a pivot table
12.2.1. Select dimension items
12.2.2. Modify pivot table layout
12.3. Change the display of your pivot table
12.4. Manage favorites
12.4.1. Open a favorite
12.4.2. Save a favorite
12.4.3. Rename a favorite
12.4.4. Write an interpretation for a favorite
12.4.5. Create a link to a favorite
12.4.6. Delete a favorite
12.4.7. View and comment interpretations
12.5. Download data from a pivot table
12.5.1. Download table layout data format
12.5.2. Download plain data source format
12.5.3. Download a CSV format without rendering data in the web browser
12.6. Embed a pivot table in an external web page
12.7. Visualize a pivot table data as a chart or a map
12.7.1. Open a pivot table as a chart
12.7.2. Open a pivot table selection as a chart
12.7.3. Open a pivot table as a map
12.7.4. Open a pivot table selection as a map
12.8. Constraints and tips
13. Using the Data Visualizer app
13.1. Data Visualizer overview
13.2. Create a chart
13.3. Select a chart type
13.4. Select dimension items
13.4.1. Select indicators
13.4.2. Select data elements
13.4.3. Select reporting rates
13.4.4. Select fixed and relative periods
13.4.5. Select organisation units
13.4.6. Select additional dimension items
13.5. Select series, category and filter
13.6. Change the display of your chart
13.7. Manage favorites
13.7.1. Open a favorite
13.7.2. Save a favorite
13.7.3. Rename a favorite
13.7.4. Write an interpretation for a favorite
13.7.5. Create a link to a favorite
13.7.6. Delete a favorite
13.7.7. View and comment interpretations
13.8. Download a chart as an image or a PDF
13.9. Download chart data source
13.10. Embed charts in any web page
13.11. Open a chart as a pivot table or as a map
14. Using the GIS app
14.1. About the GIS app
14.2. Create a new thematic map
14.3. Manage event layers
14.3.1. Create or modify event layer
14.3.2. Turn off cluster
14.3.3. Modify cluster style
14.3.4. Modify information in event pop-up windows
14.3.5. Clear event layer
14.4. Manage facility layers
14.4.1. Create or modify a facility layer
14.4.2. Search for an organisation unit
14.4.3. Clear facility layer
14.5. Manage facilities in a layer
14.5.1. Relocate a facility
14.5.2. Swap longitude and latitude of a facility
14.5.3. Display facility information
14.6. Manage thematic layers 1- 4
14.6.1. Create or modify a thematic layer
14.6.2. Filter values in a thematic layer
14.6.3. Search for an organisation unit
14.6.4. Navigate between organisation hierarchies
14.6.5. Clear thematic layer
14.7. Manage boundary layers
14.7.1. Create or modify boundary layers
14.7.2. Search for organisation units
14.7.3. Navigate between organisation hierarchies
14.7.4. Clear boundary layer
14.8. Manage Earth Engine layer
14.8.1. Create or modify an Earth Engine layer
14.9. Add external map layers
14.10. Manage map favorites
14.10.1. Save a map as a favorite
14.10.2. Open a favorite
14.10.3. Rename a favorite
14.10.4. Overwrite a favorite
14.10.5. Share a map interpretation
14.10.6. Modify sharing settings for a favorite
14.10.7. Delete a favorite
14.11. Save a map as an image
14.12. Embed a map in an external web page
14.13. Search for a location
14.14. Measure distances and areas in a map
14.15. Get the latitude and longitude at any location
14.16. View a map as a pivot table or chart
14.16.1. Open a map as a chart
14.16.2. Open a map as a pivot table
15. Setting up GIS
15.1. Context
15.2. Importing coordinates
16. Setting up report functionality
16.1. Data sources for reporting
16.1.1. Types of data and aggregation
16.1.2. Resource tables
16.1.3. Report tables
16.2. How to create report tables
16.2.1. General options
16.2.2. Selecting data
16.2.3. Selecting report parameters
16.2.4. Data element dimension tables
16.2.5. Report table - best practices
16.3. Report table outcome
16.4. Standard reports
16.4.1. What is a standard report?
16.4.2. Designing Standard reports in iReport
16.4.3. Designing SQL based standard reports
16.4.4. Designing HTML based standard reports
17. Using the Usage Analytics app
17.1. Create an usage analytics graph
18. Data approval
18.1. Approving and accepting
18.2. Authorities for approving data
18.3. Configuring data approval
18.4. Data visibility
18.5. Approving data
18.6. Approving by category option group set
18.6.1. Approving by one category option group set
18.6.2. Approving by multiple category option group sets
19. Import and export
19.1. Meta-data import
19.1.1. Meta-data import
19.1.2. Importing CSV meta-data
19.1.3. GML data import
19.2. Importing data
19.2.1. XML data import
19.2.2. Importing CSV data
19.2.3. Event data import
19.2.4. Importing PDF data
19.2.5. Importing data from DHIS2 1.4
19.3. Exporting data and meta-data
19.3.1. Metadata export
19.3.2. Meta-data detailed export
19.3.3. Data export
19.3.4. Event data export
19.3.5. Exporting data to other systems
20. Data Administration
20.1. Data integrity
20.1.1. Data elements without data set
20.1.2. Data elements without groups
20.1.3. Data elements violating exclusive group sets
20.1.4. Data elements in data set but not in form or sections
20.1.5. Data elements assigned to data sets with different period types
20.1.6. Data sets not assigned to organisation units
20.1.7. Sections with invalid category combinations
20.1.8. Indicators with identical formulas
20.1.9. Indicators without groups
20.1.10. Invalid indicator numerators
20.1.11. Invalid indicator denominators
20.1.12. Indicators violating exclusive group sets
20.1.13. Duplicate periods
20.1.14. Organisation units with cyclic references
20.1.15. Orphaned organisation units
20.1.16. Organisation units without groups
20.1.17. Organisation units violating compulsory group sets
20.1.18. Organisation units violating exclusive group sets
20.1.19. Organisation unit groups without group sets
20.1.20. Validation rules without groups
20.1.21. Invalid validation rule left side expressions
20.1.22. Invalid validation rule right side expressions
20.2. Maintenance
20.3. Resource tables
20.4. Locale Management
20.5. SQL View
20.5.1. Creating a new SQL view
20.5.2. SQL View management
20.6. Duplicate data elimination
20.7. Data statistics
20.8. Lock exceptions
20.9. Min-Max Value Generation
20.10. Cache Statistics
20.11. Scheduling
20.12. Data synchronization
20.13. Metadata Synchronization Scheduling
21. Settings
21.1. System settings
21.1.1. General settings
21.1.2. Server settings
21.1.3. Appearance settings
21.1.4. Email settings
21.1.5. Access settings
21.1.6. Approval
21.1.7. Calendar settings
21.1.8. Data import
21.1.9. Synchronization settings
22. Mobile
22.1. DHIS2 Mobile Introduction
22.2. Mobile browser based data entry
22.2.1. Getting started with mobile browser data entry
22.3. J2ME GPRS/3G Client
22.3.1. Data connection availability
22.3.2. J2ME GPRS 3G facility reporting client
22.3.3. Detailed configuration of data sets and reporting forms
22.3.4. Mobile application setup
22.4. SMS Command
22.4.1. Set up SMS command
22.4.2. SMS Command Type
22.5. SMS Service
22.5.1. Setting up SMS service
22.5.2. Gateway Configurations
23. Using the Event Capture app
23.1. About the Event Capture app
23.2. Register an event
23.3. Edit an event
23.4. Edit events in grid
23.5. Share events in edit mode
23.6. View an event audit history
23.7. Delete an event
23.8. Modify an event list's layout
23.9. Print an event list
23.10. Download an event list
24. Using the Event Reports app
24.1. Event reports overview
24.2. Create an event report
24.3. Select dimension items
24.4. Select series, category and filter
24.5. Change the display of your chart
24.6. Download chart data source
24.7. Manage event report favorites
24.7.1. Save a chart as a favorite
24.7.2. Open a favorite
24.7.3. Rename a favorite
24.7.4. Overwrite a favorite
24.7.5. Modify sharing settings for a favorite
24.7.6. Delete a favorite
24.8. Create a link to a favorite
24.9. Visualize an event report as a chart
25. Using the Event Visualizer app
25.1. Event Visualizer overview
25.2. Create a chart
25.3. Select a chart type
25.4. Select dimension items
25.5. Select series, category and filter
25.6. Change the display of your chart
25.7. Download a chart as an image or a PDF
25.8. Download chart data source
25.9. Manage chart favorites
25.9.1. Save a chart as a favorite
25.9.2. Open a favorite
25.9.3. Rename a favorite
25.9.4. Overwrite a favorite
25.9.5. Modify sharing settings for a favorite
25.9.6. Delete a favorite
25.10. Create a link to a favorite
25.11. Visualize a chart as a pivot table
26. Using the Tracker Capture app
26.1. About the Tracker Capture app
26.2. About tracked entity instance (TEI) dashboards
26.3. Workflow
26.4. Create a TEI
26.5. Create a TEI and enroll it in a program
26.6. Open an existing TEI dashboard
26.6.1. Simple TEI search
26.6.2. Advanced TEI search
26.6.3. Find a TEI outside your organisation unit
26.6.4. Download TEI search results list
26.6.5. Modify TEI search results list's layout
26.7. Enroll an existing TEI in a program
26.8. Enter event data for a TEI
26.9. Manage a TEI's enrollments
26.9.1. Deactivate a TEI's enrollment
26.9.2. Activate a TEI's enrollment
26.9.3. Mark TEI's enrollment as complete
26.9.4. Reopen completed enrollment
26.9.5. Display TEI's enrollment history
26.9.6. Create a TEI enrollment note
26.10. Send a message to a TEI
26.11. Mark a TEI for follow-up
26.12. Edit a TEI's profile
26.13. Add a relationship to a TEI
26.14. Share a TEI dashboard
26.15. Configure the TEI dashboard
26.15.1. Show or hide widgets
26.15.2. Save the dashboard's layout as default
26.16. Create reports
27. Configuring programs
27.1. About programs
27.2. Manage programs
27.2.1. Create a program
27.2.2. Assign a program to organisation units
27.2.3. Edit programs
27.2.4. Change sharing settings for programs
27.2.5. Delete programs
27.2.6. Display programs
27.2.7. Translate program names
27.3. Manage program stages
27.3.1. About program stages
27.3.2. Create a program stage
27.3.3. Create a program stage section
27.3.4. Change program stage sort order
27.3.5. Change program stage section sort order
27.3.6. Edit program stages
27.3.7. Display program stages
27.3.8. Translate program stages
27.4. Manage program indicators
27.4.1. About program indicators
27.4.2. Create a program indicator
27.4.3. Create a program indicator group
27.4.4. Edit program indicators
27.4.5. Change sharing settings for program indicators
27.4.6. Delete program indicators
27.4.7. Display program indicators
27.4.8. Translate program indicators
27.4.9. Edit program indicator groups
27.4.10. Delete program indicator groups
27.4.11. Display program indicator groups
27.4.12. Translate program indicator groups
27.5. Manage program rules
27.5.1. About program rules
27.5.2. Create a program rule
27.5.3. Edit program rules
27.5.4. Delete program rules
27.5.5. Display program rules
27.5.6. Translate program rules
27.6. Manage program validation rules
27.6.1. About program validation rules
27.6.2. Create a program validation rule
27.6.3. Edit program validation rules
27.6.4. Delete program validation rules
27.7. Manage program notifications
27.7.1. About program notifications
27.7.2. Create a program notification
27.7.3. Create a program stage notification
27.8. [Review ongoing] Manage custom registration forms
27.8.1. About program custom registration forms
27.8.2. About program stage data entry forms
27.8.3. Create a custom program registration form
27.8.4. Create a program stage data entry form
28. User account preferences
29. Synchronizing metadata
29.1. About metadata synchronization
29.2. Metadata Sync Task
29.3. Authorities to sync and create versioned metadata
29.4. Configure Central Instance
29.5. Configure Local Instance
29.6. Steps to sync metadata
29.7. Best Practices at Central Instance
29.8. Best Practices at Local Instance
30. DHIS2 Frequently Asked Questions
A. User authorities
DHIS2 Glossary
Bibliography
31. Release and upgrade notes
Index

List of Figures

1.1. The health information cycle
18.1. Approving at organisation units
18.2. Approving and accepting
18.3. Hiding of unapproved data
18.4. Example category option groups

List of Tables

3.1.
3.2. Example of detailed storage of data values when using data element categories "Place of Service" and "Age" (simplified for readability compared to the actual database table)
3.3.
3.4.
3.5.
6.1. Feedback handling tools
10.1. Category objects in the Maintenance app
10.2. Data element objects in the Maintenance app
10.3. Value types
10.4. Aggregation operators
10.5. Data entry form types
10.6. Data set objects in the Maintenance app
10.7. Data entry events
10.8. Indicator formula
10.9. Indicator objects in the Maintenance app
10.10. Organisation unit objects in the Maintenance app
10.11. Program metadata objects in the Maintenance app
10.12. Value types
10.13. Aggregation operators
10.14. Attribute objects in the Maintenance app
10.15. Constant objects in the Maintenance app
10.16. Option set objects in the Maintenance app
10.17.
10.18. Predictor objects in the Maintenance app
10.19. Push reports objects in the Maintenance app
10.20. External map layer objects in the Maintenance app
10.21. Object types in the Metadata group editor
12.1. Data dimension types
12.2. Table options
12.3. Available formats
13.1. Chart types
13.2. Selection modes
13.3. Chart options
13.4. Available formats
14.1. View organisation unit information
15.1. Organisation unit identifiers supported for GML import
18.1. Example Category Option Groups
18.2. Example Category Option Group Set approval levels
18.3. Example Multiple Category Option Group Sets
18.4. Example Multiple Category Option Group Set approval levels
20.1. Data maintenance functions in the Data Administration app
22.1.
22.2. Common Parameters
22.3. Gateway Configuration Parameters
24.1. Selection modes
24.2. Event reports options
24.3. Available formats
25.1. Chart types
25.2. Selection modes
25.3. Chart options
25.4. Available formats
26.1. Data entry widgets in the Tracker Capture app
26.2. Report types in Tracker Capture
27.1. Program metadata objects in the Program / Attributes app
27.2. Program metadata objects in the Maintenance app
27.3.
27.4.
27.5. Program indicator objects in the Programs / Attributes app
27.6. Operators
27.7. Functions
27.8. Variables
27.9. Program rule objects in the Programs / Attributes app
27.10. Operators
27.11. Functions
27.12.
27.13.
27.14.
27.15.
27.16.
A.1.
31.1. DHIS2 releases

List of Examples

6.1.
10.1. Three age categories
10.2. Category combination
10.3. Category options groups and group sets
10.4. Use category combination for a data set
10.5. Categories for data sets
10.6. Open future periods for data entry
10.7.
10.8. Section form example
10.9.
10.10. Classify facilities based on ownership
10.11.
10.12. Vaccination coverage legends
10.13.
10.14.
10.15.
10.16.
10.17. Push report
12.1. Pivot table based on the demo database.
13.1. Chart illustrating the concepts of series, categories and filter
26.1.
26.2.
26.3. Mother-Child relationship
26.4. Program summary report
27.1.
27.2.
27.3.
27.4.
27.5.
27.6.
27.7.
27.8.
27.9.
27.10.
27.11.
27.12.
27.13.
27.14.
27.15.
27.16.
27.17.

About this guide

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

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

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

[Note]Note

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

[Tip]Tip

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

[Important]Important

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

[Caution]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]Warning

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

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

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

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

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

Chapter 1. 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?

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

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

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

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

1.4. Technical background

1.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 artifacts, 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.

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

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

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

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

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

1.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 wort-while 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.

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

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

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

Chapter 2. Getting started with DHIS2

2.1. Using the DHIS2 demo server

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

[Note]Note

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

2.2. Using the DHIS2 live package

2.2.1. Starting the DHIS2 Live package

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

2.2.1.1. Prerequisites for DHIS2 Live

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

2.2.1.2. Starting up with a blank database

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

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

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

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

4) Save and close the hibernate.properties file.

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

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

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

2.2.2. Downloading and installing the server version

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

2.3. Logging on to DHIS2

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

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

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

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

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

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

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

2.4. Logging out of DHIS2

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

2.5. Quick intro to designing a DHIS2 database

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

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

1. Set up an organisational hierarchy

2. Define data elements

3. Define data sets and data entry forms

4. Define validation rules

5. Define indicators

6. Define report tables and design reports

7. Set up the GIS module

8. Design charts and customise the dashboard

2.5.1. The organisational hierarchy

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

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

Typically there is a geographical hierarchy defined by the health system. e.g. where the administrative offices are located (e.g. MoH, province, district), but often there are other administrative boundaries in the country that might or might not be added, depending on how its boundaries will improve data analysis. When designing the hierarchy the number of children for any organisational unit may indicate the usefulness of the structure, e.g. having one or more 1-1 relationships between two levels is not very useful as the values will be the same for the child and the parent level. On the other extreme a very high number of children in the middle of the hierarchy (e.g. 50 districts in a province) might call for an extra level to be added in between to increase the usefulness of data analysis. The lowest level, the health facilities will often have a large number of children (10-60), but for other levels higher up in the hierarchy approx. 5-20 children is recommended. Too few or too many children might indicate that a level should be removed or added.

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

2.5.2. Data Elements

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

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

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

Common properties of data elements can be modelled through what is called data element groups. The groups are completely flexible in the sense that they are defined by the user, both their names and their memberships. Groups are useful both for browsing and presenting related data, but can also be used to aggregate data elements together. Groups are loosely coupled to data elements and not tied directly to the data values which means they can be modified and added at any point in time without interfering with the raw data.

2.5.3. Datasets and data entry forms

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

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

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

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

2.5.3.1. Data entry forms

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

2.5.3.1.1. Section forms

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

2.5.3.1.2. Custom Forms

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

2.5.4. Validation rules

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

2.5.5. Indicators

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

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

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

2.5.6. Report tables and reports

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

2.5.7. GIS

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

2.5.8. Charts and dashboard

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

Chapter 3. Data dimensions in DHIS2

3.1. Data dimensions: Core building blocks in DHIS2

A data value in DHIS2 is described by at least three dimensions: 1) data element, 2) organisation unit, and 3) period. These dimensions form the core building blocks of the data model.

As an example, if you want to know how many children that were immunised for measles in Gerehun CHC in December 2014, the three dimensions which describe that value are the Data Element "Measles doses given", the Organisation Unit "Gerehun CHC", and the Period "Dececmber 2014". All data values have at least these three dimensions describing What, Where and When.

In addition to the organisation unit, period and data element dimensions, data values may also be associated with a custom dimension consisting of attributes. A common use of this dimension is to describe data values which are reported by multiple partners in the same location for the same data element and time period. In principle, it can be used as a "free-form" dimension, to describe multiple observations of the same phenomena at the same place and time.

Table 3.1. 

Organisation UnitData ElementPeriodValue
Gerehun CHCMeasles doses givenDec-0922
Tugbebu CHPMeasles doses givenDec-0918


3.2. Data elements: The What dimension

3.2.1. Data element categories

The data element mentioned above ,"Measles doses given", can be further disaggregated into by combinations of data element categories. Each system administrator of DHIS2 is free to define any data element category dimensions for data elements. There are however, certain best practices which should generally be followed.

Given the example of Measles vaccination, if you want to know whether these vaccines were given at the facility (fixed) or out in the community as part of the outreach services then you could add a dimension called e.g. "Place of service" with the two possible options "Fixed" and "Outreach". Then all data collected on measles immunisation would have to be disaggregated along these to options. In addition to this you might be interested in knowing how many of these children who were under 1 year or above 1 year of age. If so you can add an Age dimension to the data element with the two possible options "<1 y" and ">1 y". This implies further detail on the data collection process. You can also apply both categories "Place of service" and "Age" and combine these into a data element category combination e.g. called "EPI disaggregation". You would then be able to look at four different more detailed values in stead of only one as in the example above for the data element "Measles doses given": 1) "Fixed and <1 y, 2) Fixed and >1 y, 3) Outreach and <1 y, and 4) Outreach and >1 y. This adds complexity to how data is collected by the health facilities, but at the same time opens up for new possibilities of detailed data analysis of Measles immunisation.

Table 3.2.  Example of detailed storage of data values when using data element categories "Place of Service" and "Age" (simplified for readability compared to the actual database table)

Organisation UnitData ElementPlace of serviceAgePeriodValue
Gerehun CHCMeasles doses givenFixed<1 yDec-0912
Gerehun CHCMeasles doses givenOutreach<1 yDec-094
Gerehun CHCMeasles doses givenFixed>1 yDec-094
Gerehun CHCMeasles doses givenOutreach>1 yDec-092
Tugbebu CHPMeasles doses givenFixed<1 yDec-0910
Tugbebu CHPMeasles doses givenOutreach<1 yDec-094
Tugbebu CHPMeasles doses givenFixed>1 yDec-093
Tugbebu CHPMeasles doses givenOutreach>1 yDec-091


3.2.2. Data element group sets

While the data element categories and their options described above provide the level of detail (disaggregation) at the point of data collection and how data values get stored in the database, the data element group sets and groups can be used to add more information to data elements after data collection. As an example, if you are analyzing many data elements at the same time in a report, you would want to group these based on some criteria. Instead of looking at all the data captured in a form for immunisation and nutrition, you might want to separate or group data elements along a programme dimension (known as a data element group set in DHIS2) where "Immunisation" (or EPI) and "Nutrition" would be the two groups.

Expanding the report to include data from other programs or larger themes of health data would mean more groups to such a group set dimension, like "Malaria", "Reproductive Health", "Stocks". For this example, you would create a data element group set called "Programme" (or whatever name you find appropriate), and to represent the different programmes in this dimension you would define data elements groups called "EPI", "Nutrition", "Malaria", "Reproductive health" and so on, and add all these groups to the "Programme" group set. To link or tag the data element "Measles doses given" to such a dimension you must (in our example) add it to the "EPI" group. Which groups you add "Measles doses given" to does not affect how health facilities collect the data, but adds more possibilities to your data analysis. So for the group set dimensions there are three levels; the group set (e.g. "Programme"), the group (e.g. "EPI"), and the data element (e.g. "Measles doses given").

Indicators can be grouped into indicator groups and further into indicator group sets (dimensions) in exactly the same way as data elements.

Table 3.3. 

Organisation UnitData ElementProgrammePeriodValue
Gerehun CHCMeasles doses givenEPIDec-0922
Gerehun CHCVitamin A givenNutritionDec-0916
Tugbebu CHPMeasles doses givenEPIDec-0918
Tugbebu CHPVitamin A givenNutritionDec-0912
Gerehun CHCMalaria new casesMalariaDec-0932
Tugbebu CHPMalaria new casesMalariaDec-0923


3.3. The organisation unit dimension

Organisation units in DHIS2 should typically represent a location, such as a Community Health Centre or referral hospitals, or an administrative unit like "MoHS Sierra Leone", "Bo District" or "Baoma Chiefdom". In non-health sector applications, they could be "schools" or "water points". Orgunits are represented in a default hierarchy, usually the default administrative hierarchy of a country or region, and are therefore assigned an organisational level. As an example, Sierra Leone has four organisation unit levels; National, District, Chiefdom, and PHU, and all orgunits are linked to one of these levels. An orgunit hierarchy in DHIS2 can have any number of levels. Normally data is collected at the lowest level, at the health facility, but can be collected at any level within the hiearchy, such as both the districts as well as the facility level.

When designing reports at higher levels with data aggregated at the district or province level, DHIS2 will use the hierarchy structure to aggregate all the health facilities' data for any given unit at any level. The organisation unit level capturing the data always represents the lowest level of detail that is possible to use in data analysis, and the organisational levels define the available levels of aggregation along a geographical dimension.

3.3.1. Organisation unit group sets and groups

While facility level is typically the lowest geographical level for disaggregation in DHIS2, there are ways to flexibly group organisation units into any number of dimensions by using the organisation unit groups and group set functionality. As an example, if all facilities are given an official type like "Community health center" or "District Hospital, it is possible to create an organisation unit group set called "Type" and add groups with the names of the types mentioned above.In order for the group sets to function properly in analysis, each organisation unit should be a member of a single group (compulsory and exclusive) within a group set. Stated somewhat differently, a facility should not be both a "Community health center" as well as a "District hospital".

3.3.1.1. Alternative orgunit hierarchies - advanced use of group sets and groups

A more advanced use of organisation unit group sets is to create alternative hierarchies e.g. use administrative borders from other ministries. In Sierra Leone that could mean an alternative hierarchy of 1:MoHS, 2:Districts, and 3: Local councils, instead of the four-level hierarchy with chiefdoms and PHUs. For instance, if all PHUs are linked to a specific local council, it would be possible to look at data aggregated by local council instead of chiefdom. Then you would first need to create a group set called "Local council" and then create one orgunit group for every local council, and finally link all PHUs to their corresponding local council group.

Table 3.4. 

DistrictOrgUnit TypeData ElementPeriodValue
BoCHCMeasles doses givenDec-09121
BoCHPMeasles doses givenDec-0998
BoMCHPMeasles doses givenDec-0987
BombaliCHCMeasles doses givenDec-09110
BombaliCHPMeasles doses givenDec-0967
BombaliMCHPMeasles doses givenDec-0959


3.3.2. Best practice on the use of group sets and groups

As mentioned above, all organisation units should be a member of a single group within a group set. If an organisation unit is not present in any group or is present in multiple group members in a group set, this can lead to unexpected results in the analysis modules. DHIS2 has integrity checks to identify organisation units which are not present in any organisation unit group set member, or which is present in multiple groups.

3.4. The period dimension in DHIS2

The period dimension becomes an important factor when analysing data over time e.g. when looking at cumulative data, when creating quarterly or annual aggregated reports, or when doing analysis that combines data with different characteristics like monthly routine data, annual census/population data or six-monthly staff data.

3.4.1. Period Types

In DHIS2, periods are organised according to a set of fixed period types described below. The following list is for the default ISO 8601 calendar type.

  1. Daily

  2. Weekly: These are defined as ISO weeks, beginning on Monday and and ending on Sunday. Note that other week definitions are not currently supported.

  3. Monthly: Refers to standard calendar months.

  4. BiMonthly: Two-month periods beginning in January.

  5. Quarterly: Standard ISO quarters, beginning in January.

  6. SixMonthly: Six-month periods beginning in January

  7. Yearly: This refers to a calendar year.

  8. Financial April: Financial year period beginning on April 1st and ending on March 31st of the calendar next year

  9. Financial July: Financial year period beginning on July 1st and ending on June 31st of the calendar next year

  10. Financial Oct: Financial year period beginning on October 1st and ending on September 31st of the calendar next year

  11. Six-monthly April: Six-month periods beginning on April 1st with a duration of six calendar months.

As a general rule, all organisation units should collect the same data using the same frequency or periodicity. A data entry form therefore is associated with a single period type to make sure data is always collected according to the correct and same periodicity across the country.

It is possible however to collect the same data elements using different period types by assigning the same data elements to multiple data sets with different period types, however then it becomes crucial to make sure no organisation unit is collecting data using both data sets/period types as that would create overlap and duplication of data values. If configured correctly the aggregation service in DHIS2 will aggregate the data together, e.g. the monthly data from one part of the country with quarterly data from another part of the country into a national quarterly report. For simplicity and to avoid data duplication it is advised to use the same period type for all organisation units for the same data elements when possible.

3.4.2. Relative periods

In addition to the fixed period types described in the previous section, DHIS2 also support relative periods for use in the analysis modules.

When creating analytical resources within DHIS2 it is possible to make use of the relative periods functionality. The simplest scenario is when you want to design a monthly report that can be reused every month without having to make changes to the report template to accommodate for the changes in period. The relative period called "Last month" allows for this, and the user can at the time of report generation through a report parameter select the month to use in the report.

A slightly more advanced use case is when you want to make a monthly summary report for immunisation and want to look at the data from the current (reporting) month together with a cumulative value for the year so far. The relative period called "This year" provides such a cumulative value relative to the reporting month selecting when running the report. Other relative periods are the last 3,6, or 12 months periods which are cumulative values calculated back from the selected reporting month. If you want to create a report with data aggregated by quarters (the ones that have passed so far in the year) you can select "Last four quarters". Other relative periods are described under the reporting table section of the manual.

Table 3.5. 

Organisation UnitData ElementReporting monthSo far this yearReporting month name
Gerehun CHCMeasles doses given15167Oct-09
Tugbebu CHPMeasles doses given17155Oct-09


3.4.3. Aggregation of periods

While data needs to be collected on a given frequency to standardise data collection and management, this does not put limitations on the period types that can be used in data analysis and reports. Just like data gets aggregated up the organisational hierarchy, data is also aggregated according to a period hierarchy, so you can create quarterly and annual reports based on data that is being collected on a Monthly basis. The defined period type for a data entry form (data set) defines the lowest level of period detail possible in a report.

3.4.3.1. Sum and average aggregation along the period dimension

When aggregating data on the period dimension there are two options for how the calculation is done, namely sum or averge. This otion is specified on a per data element in DHIS2 through the use of the 'aggregation operator' attribute in the Add/Edit Data Elements dialog.

Most of the data collected on a routinely basis should be aggregated by summing up the months or weeks, for instance to create a quarterly report on Measles immunisation one would sum up the three monthly values for "Measles doses given".

Other types of data that are more permanently valid over time like "Number of staff in the PHU" or an annual population estimate of "Population under 1 year" need to be aggregated differently. These values are static for all months as long as there are valid data. For example, the "Estimated population under 1", calculated from the census data ,is the same for all months of a given year, or the number of nurses working in a given facility is the same for every month in the 6 months period the number is reported for.

This difference becomes important when calculating an annual value for the indicator morbidity service burden for a facility. The monthly head-counts are summed up for the 12 months to get the annual headcount, while the number of staff for the PHU is calculated as the average of the two 6-monthly values reported through the 6-monthly staff report. So in this example the data element "OPD headcount" would have the aggregation operator "SUM" and the data element "Number of staff" would have it set to "AVERAGE".

Another important feature of average data elements is the validity period concept. Average data values are standing values for any period type within the borders of the period they are registered for. For example, an annual population estimate following the calendar year, will have the same value for any period that falls within that year no matter what the period type. If the population under 1 for a given facility is 250 for the year of 2015 that means that the value will be 250 for Jan-15, for Q3-15, for Week 12 of 2015 and for any period within 2015. This has implications for how coverage indicators are calculated, as the full annual population will be used as denominator value even when doing monthly reports. If you want to look at an estimated annual coverage value for a given month, then you will have the option of setting the indicator to "Annualised" which means that a monthly coverage value will be multiplied by a factor of 12, a quarterly value by 4, in order to generate an effective yearly total. The annualised indicator feature can therefore be used to mimic the use of monthly population estimates.

3.5. Data collection vs. data analysis

3.5.1. Data collection and storage

Datasets determine what raw data that is available in the system, as they describe how data is collected in terms of periodicity as well as spaital exten. Data sets define the building blocks of the data to be captured and stored in DHIS2. For each data dimension we decide what level of detail the data should be collected at namely 1) the data element (e.g. diagnosis, vaccine, or any event taking place) and its categories (e.g. age and gender), 2) the period/frequency dimension, and 3) the organisation unit dimension. For any report or data analysis you can never retrieve more detailed data than what is defined in the data sets, so the design of the datasets and their corresponding data entry forms (the data collection tools) dictate what kind of data analysis will be possible.

3.5.2. Input does not equal Output

It is important to understand that the data entry forms or datasets themselves are not intrinsically linked to the underlying data value and that the meaning of data is only described by the data element (and its categories). This makes it perfectly safe to modify datasets and forms without altering the data (as long as the data elements stay the same). This loose coupling between forms and data makes DHIS2 flexible when it comes to designing and changing new forms and in providing exactly the form the users want.

Another benefit of only linking data to data elements and not to forms, is the flexibility of creating indicators and validation rules based on data elements, and also in providing any kind of output report (in pivot tables, charts, maps etc) that can combine data individually or across forms, e.g. to correlate data from different health programs. Due to this flexibility of enabling integration of data from various programs (forms) and sources (routine and semi permanent (population, staff, equipment)) a DHIS2 database is used as an integrated data repository for many or all parts of the aggregated data in a larger HIS. The figure below illustrates this flexibility.

In this example, we see that data elements from multiple forms can be combined to create a given indicator. As a more concrete example, one might collect "Population under one year of age" in an annual data set by district, and then collect a data element like "Fully immunized children" by month at the facility level. By annualizing the population, we can generate an approximation of the effective monthly population, and combining this with the aggregate total of the number of fully immunized children by month, it would be possible to generate an inidicator "Fully immunized coverage", consisting of the aggregated total of children who are fully immunized, divided by the effective monthly population.

3.6. Extended examples of data elements and forms

The table below combines data element the two group sets Diagnosis (all the diseases) and Morbidity/Mortality (New cases, Follow-ups, Referrals, Deaths) with the data element category PHU/Community. Deaths are captured in a separate form with other dimensions (e.g. the PHU/Community) than morbidity.

This output table combines the two data element categories HIV_Age and Gender with the data element group set ART Group. The group enables subtotals for staging and entry points summing up the data elements in that group. Subtotals for either age groups and gender would be other possible columns to easily include here.

DHIS2 Login screen

3.7. How this works in pivot tables

When doing data analysis in Excel pivot tables or any other OLAP based tool the dimensions become extremely powerful in providing many different views into the data. Each data element category or group set become a pivot field, and the options or groups become values within each of these fields. In fact categories and groupsets are treated exactly the same way in pivot tables, and so are orgunits, periods, and data elements. All these become dimensions to the data value that can be used to rearrange, pivot, filter, and to drill down into the data. Here we will show some examples of how the data dimensions are used in pivot tables.

Using the example of morbidity and mortality data, a pivot table can show how the dimensions can be used to view data for different aggregation levels.

The completely aggregated number is viewed when none of the pivot fields are arranged in the table area, as column or row fields, but are listed above the table itself as page field (filter).

Here we have selected to look at the Morbidity total. The various data elements on morbidity have been ordered into the main_de_groups Morbidity (we will get back to Mortality later). The fields above the table itself are all set to "All", meaning that the totals in the table will contain data from all Countries, Districts, Chiefdom, ou_type, year, months, the various categories as listed in the red fields, and all data elements in the Morbidity group.

As we have seen, this is not a very useful representation, as Morbidity is organized into new cases, follow-ups, referrals, and then again in age groups. Also, we do not see the various diagnoses. The first step is to include the diagnoses field (which is a group set), which is done by dragging the "diagnosis" field down to be a row field, as shown in the figure below, and to add the group set called "morbiditymortality" in the column field to display new cases, follow-up, and referrals.

DHIS2 Login screen

Contrast this figure above to the one below.

They both show the same data (some of the rows have been cut in the screenshot due to image size), albeit in a different way.

  • The "dataelement" field, used in the bottom figure, displays each diagnosis as three elements; one follow-up, one new, and one referrals. This is the way the data elements have been defined in DHIS, as this makes sense for aggregation. You would not like to aggregate follow-ups and new, thus these have not been made as categories, the whole point of is to ease aggregation and disaggregation.

  • The "diagnosis" group set has instead been made to lump these three (follow-up, new, referrals) together, which can then be split with another group set, namely the one called "morbiditymortality". This allows us to organize the data as in the first of the two figures, where we have the single diagnosis per row, and the groups new, follow-up, referrals as rows.

The idea of using group sets is that you can combine, in any set, different data elements. Thus, if we add the mortality data (by checking it from the drop-down menu of the main_de_groups field, and moving this field out of the table) we can see also the deaths, since the mortality data elements have been included as a "death" group in the "morbiditymortality" group set. The result is shown below.

DHIS2 Login screen

The result is a much more user-friendly pivot table. Now, another figure shows the relationship between the group sets and elements (these are fake data values).

This small detail of the pivot table show how the actual data elements link to the group sets:

  • The four data elements, as defined in DHIS, are Measles death, Measles follow-up, Measles new, and Measles referrals

  • They all belong to the group set "diagnosis", where they have been lumped together in the group Measles

  • The group set "morbiditymortality" contains the groups New cases, Follow-up, Referrals, and Deaths.

  • Only the data element Measles deaths has data related to the group Deaths, thus this is where the data value (20) is shown, at the upper right corner. The same for Measles new; the value (224) is shown at the intersection of the data element Measles new and the group New cases (in the group set morbiditymortality)

  • All the intersections where the data element does not link with the groups in morbiditymortality are left blank. Thus in this case we would get a nice table if we excluded the dataelement from the table, and just had diagnosis and the group set morbiditymortality, as in the figure shown earlier

Now lets see how the data element categories can be used. In the data entry form for Morbidity the new cases and follow-ups use one age category, the referral data another,, and the mortality data a third age breakup, so these are available as three individual age group fields in the pivot tables called morbidity_age, referrals_age and mortality_age. It doesn't make sense to use these while looking at these data together (as in the examples above), but e.g. if we only want to look at the only the new cases we can put the MobidityMortalityGroups field back up as a page field and there select the New cases group as a filter. Then we can drag the Morbidity_age field down to the column area and we get the following view:

The following table illustrates the benefits of reusing data element categories across datasets and categorycombinations. The VCCT, ART and PMTCT data are collected in three different datasets, the first two with both gender and age breakdown, and the PMTCT only age (gender is given). All three share the same age groups and therefore it is possible to view data elements from all these three datasets in the same table and use the age dimension. In the previous example with morbidity and mortality data this was not possible since new cases, referrals and deaths all have different age groups.

In the table below PMTCT data has been removed from the table and the gender category added to the column area so that you can analyse the data for VCCT and ART by age and gender. An optional subtotal for gender has also been added, as well as a grand total for all age and gender.

3.8. Case study: From paper forms to multidimensional datasets - lessons learned

Typically the design of a DHIS2 dataset is based on some requirements from a paper form that is already in use. The logic of paper forms are not the same as the data element and data set model of DHIS, e.g. often a field in a tabular paper form is described both by column headings and text on each row, and sometimes also with some introductory table heading that provides more context. In the database this is captured in one atomic data element with no reference to a position in a visual table format, so it is important to make sure the data element with the optional data element categories capture the full meaning of each individual field in the paper form.

Another important thing to have in mind while designing datasets is that the dataset and the corresponding data entry form (which is a dataset with layout) is a data collection tool and not a report or analysis tool. There are other far more sophisticated tools for data output and reporting in DHIS2 than the data entry forms. Paper forms are often designed with both data collection and reporting in mind and therefore you might see things such as cumulative values (in addition to the monthly values), repetition of annual data (the same population data reported every month) or even indicator values such as coverage rates in the same form as the monthly raw data. When you store the raw data in DHIS2 every month and have all the processing power you need within the computerised tool there is no need (in fact it would be stupid and most likely cause inconsistency) to register manually calculated values such as the ones mentioned above. You only want to capture the raw data in your datasets/forms and leave the calculations to the computer, and presentation of such values to the reporting tools in DHIS.

3.8.1. From tables to category combinations - designing multi-dimensional data sets

As we have seen in the examples above, data element categories and category options are helpful in representing tabular data, when adding dimensions to a field in a paper form. We have also seen how the data element is one of the required dimensions which describe data in DHIS2. As we will see in the example below there are often more than one way to represent a paper form in DHIS2 , and it can be difficult to know which dimension to represent with a data element name and which to represent as categories, or even as groups as we have seen above. Here are some general lessons learned from working with data element and category combinations:

  • Design your dimensions with data use in mind, not data collection. This means that disaggregation of data values at collection time should be easily aggregated up along the various dimensions, as in adding up to a meaningful total.

  • Reuse dimensions as much as possible as this increases the ability to compare disaggregated data (e.g. age groups, fixed/outreach, gender).

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

  • Different levels of dimensions; 1) disaggregation and 2) grouping. Disaggregation dimensions dictate how you collect and how detailed you store your data, so plan these carefully. The group dimension is more flexible and can be changed and added to even after data collection (think of it as tagging).

  • It is best to think of how the data would be used in an integrated data repository and not how it will actually be collected on forms or by programs when designing the meta-data model. Ideally, the same type of disaggregation should be used across forms and datasets for data elements which will be analysed together, or used to build indicators. Reuse definitions so that the database can integrate even though the forms themselves might be duplicated (which in practice, is often the case).

In order to better explain the approach and the possibilities we present an example paper form and will walk through it step by step and design data elements, categories, category options and category combinations.

This form has many tables and each of them potentially represent a data element category combination (from now on referred to as a catcombo). As such there is no restriction on a dataset to only have one set of dimensions or catcombo, it can have many and as we see above this is necessary as the dimensions are very different from table to table. In the following paragraphs, we will analyze how to break down this form into its compoenent pieces and suggest an implementation pathway in DHIS2.

ANC table. This table in the top left corner is one the simpler ones in this form. It has two dimensions, the first column with the ANC activity or service (1st visit, IPT 2nd dose etc) and the second and third column which represent the place where the service was given with the two options "Fixed" and "Outreach". Since the ANC service is the key phenomena to analyse here, and often there is a need for looking at the total of "ANC 1st visits" no matter where they actually took placed, it makes a lot of sense to use this dimension as the data element dimension.

Thus, all items on the first column from "1st ANC" visit to "2nd IPT dose given by TBA" are represented as individual data elements. The "where" dimension is represented as a data element category (from now on referred to as category) with the name "fixed/outreach" with the two data element category options (from now on catoptions) "fixed" and "outreach". There is no other dimension here so we add a new catcombo with the name "Fixed/Outreach" with one category "Fixed/Outreach". Strictly speaking there is another dimension in this table, and that is the at PHU or by TBA dimension which is repeated for the two doses of IPT, but since none of the other ANC services listed have this dimension it does not seem like a good idea to separate out two data elements from this table and give them another catcombo with both fixed/outreach and at PHU/by TBA. reusing the same catcombo for all the ANC services makes more sense since it will be easier to look at these together in reports etc. and also the fact that there is not much to lose by repeating the at PHU or by TBA information as part of the data element name when it is only for four data elements in a table of eleven data elements.

DELIVERY table. This table is more tricky as it has a lot of information and you can see that not all the rows have the same columns (some columns are merged and a one field is grayed out/disabled.). If we start by looking at the first column "Deliveries assisted by" that seems to be one dimension, but only down to the "Untrained TBA" row, as the remaining three rows are not related to who assisted the delivery at all. Another dimension is the place of delivery, either In PHU or in Community as stated on the top column headings. These deliveries are further split into the outcome of the delivery, whether it is a live or still birth, which seems to be another dimension. So if we disregard the three bottom rows for a moment there seems to be 3 dimensions here, 1) assisted by, 2) place of delivery, and 3) delivery outcome. The key decision to make is what to use as the data element, the main dimension, the total that you will most often use and want easily available in reports and data analysis.

In this case, the outcome dimension as "Total live births" is a very commonly used value in many indicators (maternal mortality ratio, births attended by skilled health personnel etc.). In this case the "Assisted By" dimension could also have been used without any problem, but the added value of easily getting the total live births information was the decisive point for us. This means that from this table (or sub-table of row 1 to 6) there are only two data elements; "Live births" and "Still births".

Next, there are two more dimensions, the "PHU/Community" with its two options and a "Births attended by" with options ("MCH Aides", "SECHN", "Midwives", "CHO", "Trained TBA", "Untrained TBA"). These two categories make up the catcombo "Births" which is assigned to the two data elements "Live births" and "Still births". Considering the final three rows of the delivery table we can see that "Complicated Deliveries" does not have the assisted by dimension, but has the place and the outcome. "Low birth weight" also does not have the assisted by dimension and not the outcome either. The LLITN given after delivery does not have any additional dimension at all. Since not any of the three rows can share catcombo with any other row we decided to represent these fields as so called flat data elements, meaning data elements with no categories at all, and simply adding the additional information from the column headings to the data element name, and therefore ended up with the following data elements with the default (same as none) catcombo; "Complicated deliveries in PHU live birth", "Complicated deliveries in PHU still births", "Complicated deliveries in community live birth", "Complicated deliveries in community still births", "Low birth weight in PHU", "Low birth weight in community", and "LLITN given after delivery".

POST-NATAL CARE table This table is simple and we used the same approach as for the ANC table. 3 data elements listed in the first column and then link these to the catcombo called "fixed/outreach". Reusing the same category fixed/outreach for these data elements enables analysis on fixed/outreach together with ANC data and other data using the same category.

TT table This table is somewhat more complex than the previous examples.We decided to use "TT1", "TT2" ... "TT5" as data elements which makes it easy to get the total of each one of these. There is fixed/outreach dimension here, but there is also the "In school place" that is only applied to the Non-Pregnant, or more correctly to any of the two as the school immunisation is done whether the girls are pregnant or not. We consulted the program people behind the form and found out that it would be OK to register all school TT immunisations as non-pregnant, which simplifies the model a bit since we can reuse the "TT1" to "TT5" data elements. So we ended up with a new category called "TT place" with the three options (Fixed, Outreach, In School), and another category called "Pregnant/Non-pregnant" with two options. The new catcombo "TT" is then a combination of these two and applied to the 5 TT data elements. Since we agreed to put all In Schools immunisations under Non-pregnant in means that the combination of options (Pregnant+In School) will never be used in any data entry form, and hence become a possible optioncombo, which is OK. As long as the form is custom designed then you can choose which combinations of options to use or not, and therefore it is not a problem to have such passive or unused catoptions. Having school as one option in the TT place category simplifies the model and therefore we thought it was worth it. The alternative would be to create 5 more data elements for "TT1 in school" ... "TT5 in school", but then it would be a bit confusing to add these together with the "TT1" ..."TT5" plus TT catcombo. Having school as a place in the TT place category makes it a lot easier to get the total of TT1.. TT5 vaccines given, which are the most important numbers and most often used values for data analysis.

Complications of early and late pregnancy and labour tables We treat these two tables as one, and will explain why. These two tables are a bit confusing and not the best design. The most important data coming out of these tables are the pregnancy complications and the maternal deaths. These data elements contain further detail on the cause of the complication or death (the first column in both tables), as well as a place of death (in PHU or community), and an outcome of the complication (when its not a death) that can be either "Managed at PHU" or " Referred". We decided to create two data elements for these two tables; "Pregnancy complications", and "Maternal Deaths", and two category combinations, one for each of the data elements. For the Pregnancy Complications data element there are two additional dimensions, the cause of the complication (the combined list of the first column in the two tables) and the outcome (managed at PHU or Referred), so these are the categories and options that make up that category combination. For the "Maternal deaths" data element the same category with the different causes are used and then another category for the place of death (in PHU or In community). This way the two data elements can share one category and it will be easy to derive the total number of pregnancy complications and maternal deaths. While the list of complications on the paper form is divided into two (early and late/labour) you can see that e.g. the malaria in 2nd and 3rd trimester are listed under early, but in fact are for a later phase of the pregnancy. There is no clear divide between early and late complications in the form, and therefore we gave up trying to make this distinction in the database.

Family Planning Services table This table has 2 dimensions, the family planning method (contraceptive) and whether the client is new or continuing. We ended up with one data element only "Family planning clients" and then added two categories "FP method" with all the contraceptives as options, and another category "FP client type" with new or continuing as options. This way it will be easy to get the total number of family planning clients which is the major value to look at in data analysis, and from there you can easily get the details on method or how many new clients there are.

3.8.2. Step-by-step approach to designing datasets

  1. Identify the different tables (or sub datasets) in the paper form that share the same dimensions

  2. For each table identify the dimensions that describe the data fields

  3. Identify the key dimension, the one that makes most sense to look at in isolation (when the others are collapsed, summed up). This is your data element dimension, the starting point and core of your multidimensional model (sub dataset). The data element dimension can be a merger of two or more dimensions if that makes more sense for data analysis. The key is to identify which total that makes most sense to look at alone when the other dimensions are collapsed.

  4. For all other/additional dimensions identify their options, and come up with explanatory names for dimensions and their options.

  5. Each of these additional dimensions will be a data element category and their options will be category options.

  6. Combine all categories for each sub dataset into one category combination and assign this to all the data elements in your table (or sub dataset if you like).

  7. 7. When you are done with all the tables (sub datasets), create a new dataset and add all the data elements you have identified (in the whole paper form) to that dataset.

  8. 8. Your dataset will then consist of a set of data elements that are linked to one or more category combinations.

Chapter 4. User management

DHIS2 allows for multiple users to access the system simultaneously, each with a defined set of permissions. These permissions can be finely tuned so that certain users can only enter data, while others may generate reports. Multiple user roles can be created, each with their own set of permissions, and then assigned to users which grant them certain privileges within the system. This chapter describes how to manage users and user roles.

4.1. Creating new users and roles

This section will describe how to add new users and manage existing users to the DHIS2 application. You can create as many user names as you need. Each user can be assigned certain privileges, and can be assigned to certain organisation units for which they will be enabled to enter data on behalf of. To access the user module, choose Users from the "Apps" menu and then click "User" from the menu items on the left-hand pane.

4.1.1. User maintenance

Select Users menu item

User acconts already registered will appear as a list as seen below.

Search by user name

You can search for specific user names in the user list by entering the name in the Filter by name field as shown above. Some non-standard functions are available by clicking on each user in the list:

  • Replicate: This will create an exact copy of the user. You will be asked to enter a new username and password for the replicated account.

  • Disable: This will disable the user, meaning that the account is not deleted, but the user will not be able to log in or use it.

4.1.2. User role management

As part of creating a user name you are required to define the user role. Do so by clicking on User Role on the left side of the displayed screen. This will lead you to the User role management page where you can click on Add new to create a new role.

Add new user role

The following screen will open and here in the first text box you need to give a Name of the Role such as Super User, Admin User, etc. The second text box called Description gives more information about the type of User Role that is being created for e.g. State Admin User, District Data Entry.

Role maintenance page

Next you will specify the particular data set(s) that are to be made available to the particular role. You will also need to specify the type of Authority to be given to the particular user. For each of the three options namely Datasets, Reports and Authorities user can select multiple options from the scroll down menu provided against each field. A user can choose multiple options either by moving them one-by-one.

In order for particular users to be able to enter data, you must add them to both a dataset as well as an organisational unit level. You can also select multiple datasets individually by pressing the Ctrl key on the keyboard and clicking on individual datasets.

Finally when you have entered the required fields click on Save which is located on the lower part of the displayed screen. The desired user role and related authorisation will be saved to the database, and can then be assigned to a particular user.

4.1.3. User management

Under particular user role there can be more than one user. To manage users, click on User on the left side of the screen. This will lead you to the User management page.

To add a new user, follow these steps:

  1. Click on the Add New button.

  2. Choose whether you want to fill in all the personal user information now, or invite the user by email to complete the rest of the user information:

    • Create account with user details - Choose this if you would like to enter all the details of the new user such as name, password, etc.

      If you choose this action, then enter the following information: user name, password, surname, first name, E-mail, OpenID account (if any) and mobile phone number (if any).

      After you finish adding the user, the account will be ready for them to use with the user name and password that you supply.

      Select Users menu item

    • Email invitation to create account - Choose this if you would like to send by email an invitation for the user to return to the system and finish setting up their user account. The user will then return to the system and fill in most of their personal information. The account that the user finishes setting up will be limited according to how you configure it below.

      Note that you may not select this option to create an account with "critical" system authorities such as All, Scheduling Administration, Perform maintenance tasks, Merge organisation units, Eliminate duplicate data elements, SQL View Management, Change system settings, and List, Add or Delete user roles.

      If you choose this action, then 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 username empty, then the user may choose their own username when they respond to the invitation (as long as it is not taken already for another user.)

      After you finish adding the new user, two emails will be sent to the address you provided. One 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 other email contains a unique code that they must enter into the system in order to complete the registration, after following the link in the first email. The user must finish setting up the account within three months, or the invitation becomes invalid.

      Select Users menu item

  3. Select the Interface language for the user. You may choose a language into which fixed elements of the DHIS2 user interface have been translated.

  4. Select the Database language for the user. You may choose a language into which implementation-supplied items have been translated in the database, for example data element names, organisation unit level names, etc.

  5. Users must be assigned to at least one data capture and maintenance organisation unit. Users will have access to all children of the organisation units which have been assigned to them. For instance, if a user has been assigned 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. The data approval organisation units control for which organisation units the user can do data entry.

  6. Users can be assigned to any number of data view organisation units. This controls which organisation units the user can view aggregated data for in analysis modules.

    [Important]Important

    Giving access to an organisation unit implicitly gives access to all organisation unit below it in the organisation unit hierarchy. Thus, you should not select the descendants of an orgunit which you have already selected. As an example, if the user has been assigned to a disitrct, you should not (and not need to) select the facilities within that district.

    Note that data view organisation units are optional. If you do not specify any, 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 analysis modules one 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 organisation units. If the user has been assigned to multiple organisation units, the use of "user organisation unit" may result in unpredictable behavior.

    User management screen

  7. (Click on Show more options.) You may optionally assign users to user groups on this page.

  8. (Click on Show more options.) You may optionally restrict the values this user sees in data analytics by selecting dimensions that will restrict the users view. For 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 insure that the user does not see totals in analytics that include values from other groups, assign Implementing Partner to this user. This insures that any data visible to the user through DHIS2 analytics will be filtered to select only the Implementing Partner category option group(s) which are visible to the user.

    User management screen

  9. Click on the Add button to complete adding the new user.

The recently created new user can be seen in main User management screen

You can edit (like password, surname, etc.) and delete the details of new/old users by selecting corresponding User’s Edit and Remove menu options.

4.1.4. User by organisation unit

The User by organisation unit function allows you see which users have been assigned to a particular organisation unit. Simply select the organisation unit from the tree on the left, and a list of users which have been assigned to this particular organisation unit will be displayed

4.1.5. Managed users

DHIS2 supports a concept for user management referred to as managed users which 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.

4.1.6. OpenID Support

DHIS2 supports the OpenID standard, which allows third party login using a OpenID provider, please see http://openid.net for more information. To create a custom OpenID URL for a username you can visit this URL and log in with your OpenID provider: http://openid-provider.appspot.com.

To enable support for this in DHIS2, two steps must be done:

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

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

Chapter 5. Sharing

This chapter discusses the sharing of entities feature in DHIS2.

5.1. Sharing of objects

Many objects in DHIS2, like reports, charts, maps and indicators, can be shared. Sharing means making an object, like a report, available for reading or modification to a group of users or to everyone. 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.

The sharing dialog.

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: "None", "Can view" or "Can edit and view". 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.

5.2. Sharing and access control

The objects which support 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.

5.3. Sharing applied

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

Chapter 6. Dashboards

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

Example 6.1. 

A user or administrator could create a dashboard called "Malaria" which might contain all relevant information on malaria. This dashboard could then be shared with the user group called "Malaria control", which might consist of all users of the malaria control program. All users within this group would then be able to view the same dashboard.


6.2. Setting up the dashboard

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

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

  • Remove

    Allows you to remove the item from the dashboard when you have the appropriate user rights.

  • Get as Image

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

  • Share interpretation

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

  • Explore

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

  • Resize

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

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

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

6.3. Change dashboards name

  1. Open a DHIS2 dashboard.

  2. Click Manage.

  3. In the Name field, type the new name of the dashboard.

  4. Click Rename.

6.4. Add message widget to dashboards

  1. Open a DHIS2 dashboard.

  2. Click Manage and click Messages.

6.5. Delete dashboards

  1. Open a DHIS2 dashboard.

  2. Click Manage and click Delete.

6.6. Translate dashboard names

  1. Open a DHIS2 dashboard.

  2. Click Manage and click Translate.

  3. Select a locale and enter the dashboard name's translation.

  4. Click Save.

6.7. Dashboard Sharing

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

All dashboards have two sharing groups set by default.

  • External access (without login)

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

  • Public access (with login)

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

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

  • Can view

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

  • Can edit and view

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

6.8. Manage messages and feedback messages

6.8.1. About messages and feedback messages

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

[Note]Note

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

6.8.2. Create a message

  1. From the Dashboard, click Messages.

  2. Click Write message.

  3. Define who you want to receive the message. You can send a message to organisation units, users and user groups.

    • In the To org unit field, select the organisation units or group of organisation units you want to send the message to.

    • In the To user field, select the users or user groups you want to send the message to.

  4. Type a subject and a message.

  5. Click Send.

6.8.3. Read a message

  1. From the Dashboard, click Messages.

  2. Click a message.

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

6.8.4. Create a feedback message

  1. From the Dashboard, click Write feedback.

  2. Type a subject and a feedback message.

  3. Click Send.

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

6.8.5. Configure feedback message function

To configure the feedback message function, you must:

  1. Create a user group (for example "Feedback recipients") that contains all the users who should receive feedback messages.

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

6.8.6. Manage feedback messages

[Note]Note

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

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

Table 6.1. Feedback handling tools

FunctionDescription

Set status

All feedback messages get the status Open when created.

To keep track of existing feedback messages, you can change the status to Invalid, Pending or Solved.

You can filter feedback messages in your inbox based on their status. This makes it easier to switch between feedback messages and normal messages.

Set priority

You can mark a feedback message with different priorities: None, Low, Medium or High.

Setting the priority makes it easier to keep track of which feedback message you need resolved first, and which feedback messages that can wait.

Write internal reply

When you work in a feedback handling team you might want to discuss the feedback before sending an answer to the sender. You can keep this discussion in the same message conversation as the feedback itself.

To send a reply that within the feedback handling user group, click Internal reply.


Chapter 7. Data entry

7.1. Data entry with DHIS2

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

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

7.1.1. Selecting the data entry form

To start entering data the first step is to open the correct form by following these steps:

  1. Locate the orgunit you want to register data for in the tree menu to the left. Expand and close branches by clicking on the +/- symbols. A quick way to find an orgunit is to use the search box just above the tree (the green symbol), but you need to write in the full name to get a match.

  2. Select a data set from the dropdown list of data sets available to your selected orgunit.

  3. Select a period to register data for. The available periods are controlled by the period type of the data set (reporting frequency). You can jump a year back or forward by using the arrows above the period.

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

Main data entry screen

7.1.2. Entering data

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

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

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

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

Data entry section form with history pop-up

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

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

7.1.3. Editing and deleting data

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

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

7.1.4. Validating data in the form

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

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

Data entry validation result

7.1.5. Off-line data entry

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

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

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

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

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

7.1.6. Multi-organisation unit data entry

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

Chapter 8. Using Data Quality functionality

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

8.1. Overview of data quality checks

Ensuring data quality is a key concern in building an effective HMIS. Data quality has different dimensions including:

  • Correctness: Data should be within the normal range for data collected at that facility. There should be no gross discrepancies when compared with data from related data elements.

  • Completeness: Data for all data elements for all health facilities should have been submitted.

  • Consistency: Data should be consistent with data entered during earlier months and years while allowing for changes with reorganization, increased work load, etc. and consistent with other similar facilities.

  • Timeliness: All data from all reporting orgunits should be submitted at the appointed time.

8.2. Data quality checks

Data quality checking can be done through various means, including:

  1. At point of data entry, the software can check the data entered to see if it falls within the min-max ranges of that data element (based on all previous data registered).

  2. Defining various validation rules, which can be run once the user has finished data entry. The user can also check the entered data for a particular period and Organization Unit(s) against the validation rules, and display the violations for these validation rules.

  3. Analysis of data sets, i.e. examining gaps in data.

  4. Data triangulation which is comparing the same data or indicator from different sources.

8.3. Running Validation Rule Analysis

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

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

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

Selecting what data to validate:

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

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

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

Run validation rule selection

Validation results:

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

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

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

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

Run validation rule results

8.4. Std Dev Outlier Analysis

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

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

Select what data to analyse:

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

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

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

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

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

Outlier analysis rule selection

Analysis result:

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

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

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

8.5. Min-Max Outlier Analysis

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

8.6. Follow-Up Analysis

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

Chapter 9. Setting up Data Quality functionality

The data quality module provides means to improve the quality of the data in the system. This can be done through validation rules and various statistical checks.

9.1. Overview of data quality check

Ensuring data quality is a key concern in building an effective HMIS. Data quality has different dimensions including:

  • Correctness: Data should be within the normal range for data collected at that facility. There should be no gross discrepancies when compared with data from related data elements.

  • Completeness: Data for all data elements for all health facilities/blocks/Taluka/districts 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 health facilities/blocks/Taluka/districts should be submitted at the appointed time.

9.2. Data quality checks

Data quality checking can be done through various means, including:

  1. At point of data entry, the software can check the data entered to see if it falls within the min-max ranges of that data element (based on all previous data registered).

  2. Defining various validation rules, which can be run once the user has finished data entry. The user can also check the entered data for a particular period and Organization Unit(s) against the validation rules, and display the violations for these validation rules.

  3. Analysis of data sets, i.e. examining gaps in data.

  4. Data triangulation which is comparing the same data or indicator from different sources.

9.3. Data quality check at the point of data entry

Data quality can be checked at the point of data entry through setting the minimum and maximum value range for each element manually or generating a range (defined by a minimum and maximum value). The min-max range can be generated automatically by the system. The auto-generated min-max 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 combination. Then the system will calculate the min-max range based on the

For data which is highly-skewed or zero inflated (as is often the case with aggregate data), the values which DHIS2 may not provide an accurate min-max range, which may then result in excessive false violations. Also note that currently, min-max values are calculated across all attribute combo options for a given data element /category option / organisation unit combination. In summary, the automatic generation of min/max values can be useful for many situations, but it would be advised to ensure that the data is actually normally distributed prior to using this function.

9.3.1. Setting the minimum and maximum value range manually

If you are using the default entry screen click on the element for which you want to set the min-max value. A pop-up window will appear in which you can enter the values. On subsequent data entry, if the values entered do not fall within the min-max range, the data entry cell will appear with an orange background, to highlight that this value does not fall within the min-max range. The min-max limits can be set in the following dialog.

In the same screen , users can comment on the reason for the discrepancy, such as an event at a facility which may have generated a large number of clients. Users may also flag the value for follow up (by pressing the star).

9.3.2. Generated min-max values

It is possible to generate and remove the min-max ranges by dataset using the "Min-max generation" function available in the data administration module. Just select a dataset and then an organisation unit from the dialog, as shown below.

Pressing "Generate" will create new min/max ranges for all data elements in the selected data sets for all orgunits (including descendants) of the selected organisation units.

Pressing "Remove" will permanently delete all min/max ranges for the selected datasetsa and organisation units.

9.4. Validation Rule

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

To add a validation rule, just follow these steps from the Data Quality -> Validation Rule dialog:

  • Click on the Add new button

  • Provide a descriptive Name for the validation rule. The name must be unique among the validation rules.

  • Provide a Description for the validation rule.

  • Select the Importance you wish to assign to the validation rule: high, medium or low.

  • Select the Rule type. For validating correct data, choose Validation. For monitoring data according to a rule, choose Surveillance and follow the extra instructions below.

  • Select the Period type for the data being validated.

  • Select an Operator. The operator options are equal (==), not equal (!=), greater than (>), greater than or equal (>=), less than (<), less than or equal to (>=), a compulsory pair or an exclusive pair.

    The compulsory pair operator allows you to require that data values must be entered for a form for both left and right sides of the expression, or for neither side. In other words, 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 operator allows you to assert that if any value exist on the left side then there should be no values on the right side (or vice versa). Stated another way, 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.

  • Define the left side and right side of the validation rule expression. First, provide a description for the expression. Second, build the expression with the expression builder. The expression is mathematical and contain data elements as well as integers and mathematical operators. Data elements can be included by double-clicking one in the available data elements list to the right. Alternatively one can select a data element and click the insert button. Mathematical operators can be included by clicking the corresponding button under the expression builder area.

    There are three states which can be set to alter how the validation rule will be evaluated if there is any missing data.

    • Skip if any value is missing: The rule will be skipped if any of the values which compose the expression are missing. This is the default option. This option should always be selected if you are using the "Exclusive" or "Compulsory" pair operator.

    • Skip if all values are missing: The rule will be skipped only if all of the operands which compose it are missing.

    • Never skip: The rule will never be skipped in case of missing data, and all missing operands will be treated effectively as a zero.

Save each expression by clicking Save, then save the validation rule by clicking Save.

To edit a validation rule, click the name the relevant validation rule in the list and select "Edit" from the context menu. Then follow the same procedures as above when creating a new rule.

To delete a validation rule, click the name of the validation rule to be deleted, and select "Remove" from the context menu.

Validation rule names can be translated to other languages by selecting the name of the validation rule and selecting "Translate" from the context menu.

To view validation rule details, click the name of the validation rule, and then select "Show details" from the context menu.

9.5. Validation Rule Group

A validation rule group provides a mechanism for classifying related validation rules. Another advantage of using validation rule groups is that it can later be run separately, instead of running all validation rules.

You can run the validation rules in a group interactively. To do so, choose Data Quality -> Validation Rule. You can choose whether to run all validation rules in the system, or just the rules in one group.

You can also run the rules in a group as part of a scheduled validation run, as described below.

For each validation rule group, you can specify one or more groups of users to be notified of validation rule exceptions. Alerts will be sent to these users from scheduled validation runs, or from interactive runs when you request to send alerts. To set this up:

  • Be sure that one or more user groups contain all the users you wish to notify.

  • Define a validation rule group for a set of validation rules. In the section User groups to alert, select one or more user groups to be notified.

By repeating these two steps, you can build any set of relations you need between validation rules and users to notify.

When you create or edit a validation rule group, there is an option called Only organisation unit related users are alerted. If this is set to Yes, then each user in the user group(s) will be alerted only for validation exceptions in an organisation unit to which the user has been assigned through user management -- or for any lower-level organisation unit under the assigned organisation unit. If this is set to No, then each user in the assigned user group(s) will be alerted for all validation exceptions in the group, regardless of their user-assigned organisation units.

9.6. Scheduled Validation Runs

To enable routine scheduling of data validation runs, choose Data Administration from the Maintenance menu. Then click on Scheduling. If scheduling is active, click on the Stop button. Then select the Data monitoring strategy of All daily. Finally enable scheduling by clicking on the Start button.

During a scheduled validation run, those validation rule groups will be evaluated that have one or more user groups defined for alerts. Validation rule groups that have no user groups defined for alerts will not be run during a scheduled run.

Chapter 10. Using the Maintenance app

Table of Contents

10.1. Manage categories
10.1.1. About categories
10.1.2. Workflow
10.1.3. Create a category option
10.1.4. Create a category
10.1.5. Create a category combination
10.1.6. Create a category option group
10.1.7. Create a category option group set
10.1.8. Use category combinations for data sets
10.1.9. Assign a code to a category option combination
10.1.10. Edit metadata objects
10.1.11. Clone metadata objects
10.1.12. Change sharing settings for metadata objects
10.1.13. Delete metadata objects
10.1.14. Display details of metadata objects
10.1.15. Translate metadata objects
10.2. Manage data elements
10.2.1. About data elements
10.2.2. Workflow
10.2.3. Create a data element
10.2.4. Create a data element group
10.2.5. Create a data element group set
10.2.6. Edit data elements and other objects
10.2.7. Clone data elements and other objects
10.2.8. Change sharing settings for data elements and other objects
10.2.9. Delete data elements and other objects
10.2.10. Display details of data elements and other objects
10.2.11. Translate data elements and other objects
10.3. Manage data sets and data entry forms
10.3.1. About data sets and data entry forms
10.3.2. Workflow
10.3.3. Create a data set
10.3.4. Edit data sets
10.3.5. Clone data sets
10.3.6. Change sharing settings for data sets
10.3.7. Delete data sets and forms
10.3.8. Display details of data sets
10.3.9. Translate data sets
10.3.10. Override data elements' category combinations in a data set
10.3.11. Edit compulsory data elements in a data set
10.3.12. Download default data forms in PDF format
10.3.13. Manage section forms
10.3.14. Manage custom forms
10.4. Manage indicators
10.4.1. About indicators
10.4.2. Workflow
10.4.3. Create an indicator type
10.4.4. Create an indicator
10.4.5. Create an indicator group
10.4.6. Create an indicator group set
10.4.7. Edit indicators and other objects
10.4.8. Clone indicators and other objects
10.4.9. Change sharing settings for indicators and other objects
10.4.10. Delete indicators and other objects
10.5. Manage organisation units
10.5.1. About organisation units
10.5.2. Workflow
10.5.3. Create an organisation unit
10.5.4. Create an organisation unit group
10.5.5. Create an organisation unit group set
10.5.6. Edit organisation units and other objects
10.5.7. Clone organisation units and other objects
10.5.8. Change sharing settings for organisation unit groups and group sets
10.5.9. Delete organisation units and other objects
10.5.10. Display details of organisation units and other objects
10.5.11. Translate organisation units and other objects
10.5.12. Assign names to organisation unit levels
10.5.13. Move organisation units within a hierarchy
10.6. Manage program metadata
10.6.1. About program metadata
10.6.2. Create a tracked entity attribute
10.6.3. Create a tracked entity attribute group
10.6.4. Create a relationship type
10.6.5. Create a tracked entity
10.6.6. Edit metadata objects
10.6.7. Clone metadata objects
10.6.8. Delete metadata objects
10.6.9. Change sharing settings for metadata objects
10.6.10. Display details of metadata objects
10.6.11. Translate metadata objects
10.7. Manage attributes
10.7.1. About attributes
10.7.2. Create an attribute
10.7.3. Edit metadata objects
10.7.4. Clone metadata objects
10.7.5. Delete metadata objects
10.7.6. Display details of metadata objects
10.7.7. Translate metadata objects
10.8. Manage constants
10.8.1. About constants
10.8.2. Create a constant
10.8.3. Edit metadata objects
10.8.4. Clone metadata objects
10.8.5. Change sharing settings for metadata objects
10.8.6. Delete metadata objects
10.8.7. Display details of metadata objects
10.8.8. Translate metadata objects
10.9. Manage option sets
10.9.1. About option sets
10.9.2. Create an option set
10.9.3. Edit metadata objects
10.9.4. Clone metadata objects
10.9.5. Change sharing settings for metadata objects
10.9.6. Delete metadata objects
10.9.7. Display details of metadata objects
10.9.8. Translate metadata objects
10.10. Manage legends
10.10.1. About legends
10.10.2. Create a legend
10.10.3. Edit metadata objects
10.10.4. Clone metadata objects
10.10.5. Change sharing settings for metadata objects
10.10.6. Delete metadata objects
10.10.7. Display details of metadata objects
10.10.8. Translate metadata objects
10.10.9. Assign a legend to indicator or data element
10.11. Manage predictors
10.11.1. About predictors
10.11.2. Create a predictor
10.11.3. Edit metadata objects
10.11.4. Clone metadata objects
10.11.5. Delete metadata objects
10.11.6. Display details of metadata objects
10.11.7. Translate metadata objects
10.12. Manage push reports
10.12.1. About push reports
10.12.2. Create a push report
10.12.3. Preview push reports
10.12.4. Run push report jobs
10.12.5. Edit metadata objects
10.12.6. Clone metadata objects
10.12.7. Delete metadata objects
10.12.8. Display details of metadata objects
10.12.9. Translate metadata objects
10.13. Manage external map layers
10.13.1. About external map layers
10.13.2. Create an external map layer
10.13.3. Edit metadata objects
10.13.4. Clone metadata objects
10.13.5. Delete metadata objects
10.13.6. Display details of metadata objects
10.13.7. Translate metadata objects
10.14. Edit multiple object groups at once
10.14.1. Edit multiple objects in an object group
10.14.2. Edit an object in multiple object groups

10.1. Manage categories

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

Example 10.1. Three age categories

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:

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


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

10.1.3. Create 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]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.

10.1.4. Create a category

When you have created all category options for a particular category, you can create that category.

To create a 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.

10.1.5. Create a category combination

Category combinations lets you combine multiple categories into a related set.

Example 10.2. Category combination

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.

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

Example 10.3. Category options groups and group sets

In a system, data is collected by "projects", where projects is modeled as category options. The system must be able to analyse data based on which donor that 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.

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

To create a category option group set:

  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.

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

Example 10.4. Use category combination for a data set

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.


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

10.1.10. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.1.11. Clone metadata 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.

10.1.12. Change sharing settings for 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 options menu and select Sharing settings.

  3. (Optional) Search for a user group and select it. The user group is added to the list.

  4. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  5. Click Close.

10.1.13. Delete metadata objects

  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.

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

10.1.15. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.2. Manage data elements

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

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


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

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

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

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

  9. In the Value type field, select the type of data that the data element will record.

    Table 10.3. Value types

    Value type

    Description

    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

    E-mail

    Email.

    File

    A file resource where you can store external files, for example documents and photos.

    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.

    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 isntances and a search field.

    Username

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


  10. In the Aggregation operator field, select the default aggregation operation that will be used on the data element.

    Most data elements should have the Sum option set. 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.

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

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

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

  14. Select an Option set.

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

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

  16. Select a Legend set.

    Legend sets are used in the GIS app to display certain data elements with certain icons.

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

    The aggregation levels option allows the data element to be aggregated at one or more 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.

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

    You set custom attributes in Data administration > Attribute. For more information about how to use attributes, refer to the "Attributes" section.

  19. Select a Main data element group.

    Data element group sets are only applicable if they have been defined. If data element group sets have been defined, they will appear in the Main data element group list. Select each data element group from the list of group sets provided. Groups can be selected based on if the data element is of aggregate or tracker type.

  20. Select Tracker-based data.

  21. Click Save.

10.2.4. Create a data element group

Data element groups lets you classify related data elements into a common theme. For instance, 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.

10.2.5. Create a data element group set

Data element group sets allows you to categorise multiple data element groups into a set. Data element group sets are used during analysis and reporting to combine similar data element groups into a common theme.

  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.

10.2.6. Edit data elements and other objects

  1. Open the Maintenance app and click Data elements.

  2. Select the object type you want to edit, for example data element or category.

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

  4. Click the options menu and select Edit.

  5. Modify the options you want.

  6. Click Save.

10.2.7. Clone data elements and other objects

Cloning a data element or other objects can save time when you create many similar objects.

  1. Open the Maintenance app and click Data elements.

  2. Select the object type you want to clone, for example data element or category.

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

  4. Click the options menu and select Clone.

  5. Modify the options you want.

  6. Click Save.

10.2.8. Change sharing settings for data elements and other objects

  1. Open the Maintenance app and click Data elements.

  2. Select an object type, for example data element or category.

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

  4. Click the options menu and select Share.

  5. (Optional) Search for a user group and select it. The user group is added to the list.

  6. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  7. Click Close.

10.2.9. Delete data elements and other objects

You can only delete a data element and other objects if no data is attached to the data element itself.

  1. Open the Maintenance app and click Data elements.

  2. Select the object type you want to delete, for example data element or category.

  3. In the list, find the object you want to delete.

  4. Click the options menu and select Delete.

  5. Click OK to confirm.

10.2.10. Display details of data elements and other objects

  1. Open the Maintenance app and click Data elements.

  2. Select the object type you want to display, for example data element or category.

  3. In the list, find the object you want to view.

  4. To display all meta data about the selected object, click the options menu and select Show details.

10.2.11. Translate data elements and other objects

DHIS2 provides functionality for translations of database content like data elements, data element groups, indicators, indicator groups, validation rules and more. You can translate these elements to any number of locales. A locale represents a specific geographical, political, or cultural region.

[Tip]Tip

To activate a translation, go to Apps > Settings > Appearance and select a language.

  1. Open the Maintenance app and click Data elements.

  2. Select the object type you want to translate, for example data element or category.

  3. In the list, find the object you want to translate.

  4. Click the options menu and select Translate.

  5. Select a locale.

  6. Enter the required information.

  7. Click Close.

10.3. Manage data sets and data entry forms

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

Example 10.5. Categories for data sets

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:

Table 10.5. Data entry form types

Data entry form typeDescription

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]A data set can have both section and custom forms

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:

Table 10.6. Data set objects in the Maintenance app

Object type

Available functions

Data set

Create, assign to organisation units, edit, clone, 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


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

10.3.3. Create 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]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.

    Example 10.6. Open future periods 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]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 DHIS 2 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) Select a Legend.

    [Tip]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.

  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.

    [Tip]Tip

    Click Add new to create indicators that you're missing. In the form that opens, create the indicators you need. When you're done, click Refresh values.

  26. In the organisation unit tree, select the organisation units you want to assign the data set to.

    [Tip]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).

10.3.4. Edit data sets

  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. Modify the options you want, for example add or remove data elements and indicators.

  5. Click Save.

10.3.5. Clone data sets

Cloning a data set can save time when you create many similar data sets.

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

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

  3. Click the options menu and select Clone.

  4. Modify the options you want.

  5. Click Save.

10.3.6. Change sharing settings for data sets

You can assign different rights to the data set based on user groups and user roles.

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

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

  3. Click the options menu and select Share.

  4. (Optional) Search for a user group and select it. The user group is added to the list.

  5. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  6. Click Close.

10.3.7. Delete data sets and forms

[Warning]Warning

Any data set which is deleted 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 click Data set > Data set.

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

  3. Click the options menu and select Delete.

    This deletes the data set and all associated data forms.

  4. Click OK to confirm.

10.3.8. Display details of data sets

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

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

  3. To display all metadata about the selected object, click the options menu and select Show details.

10.3.9. Translate data sets

DHIS2 provides functionality for translations of database content like data elements, data element groups, indicators, indicator groups, validation rules and more. You can translate these elements to any number of locales. A locale represents a specific geographical, political, or cultural region.

[Tip]Tip

To activate a translation, go to Apps > Settings > Appearance and select a language.

To translate the name of a data set:

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

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

  3. Click the options menu and select Translate.

  4. Select a locale.

  5. Enter the required information.

  6. Click Close.

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

Example 10.7. 

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

  5. Select new category combinations and click Close.

  6. Click Save.

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

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

10.3.13. Manage section forms

10.3.13.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. In the Name field, type the name of the section.

  6. In the Description field, type a description of the section.

  7. Select a Category combination.

    [Note]Note

    You can only use one category combination per section.

  8. Select data elements and assign them.

  9. (Optional) Sort the data elements within the section by using the up and down arrows to the left of the assigned data elements field.

  10. Click Save.

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

Example 10.8. Section form example

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.


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

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

  7. Click Save.

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

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

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

10.3.14. Manage custom forms

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

10.3.14.2. Scripting in custom forms

In custom data entry form you can use JavaScript to create dynamic behavior 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.

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

Table 10.7. Data entry events

KeyDescriptionArguments

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

10.3.14.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"];

10.4. Manage indicators

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

You never enter indicators directly in DHIS2, you calculate them.

An indicator formula can consist of mathematical operators, for example plus and minus, and of the following elements:

Table 10.8. Indicator formula

Formula elementTypeDescription

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.


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

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


10.4.2. Workflow

  1. Create indicator types.

  2. Create indicators.

  3. Create indicator groups.

  4. Create indicator group sets.

10.4.3. Create 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 percents) for the values to appear correctly formatted.

[Note]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. Click Apps > Maintenance > 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.

10.4.4. Create an indicator

  1. Click Apps > Maintenance > 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. In the Description field, type a brief, informative description of the indicator and how it is calculated.

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

  8. Select the number of Decimals in data output.

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

  10. (Optional) Select a Legend set.

    For more information about legend sets, see section "Using the GIS app".

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

  12. Select a Classification.

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

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

  15. Click Save.

10.4.5. Create an indicator group

  1. Click Apps > Maintenance > Indicator > Indicator group.

  2. Click the add button.

  3. Type a name.

  4. Select indicators and assign them.

  5. Click Save.

10.4.6. Create 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. Click Apps > Maintenance > 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.

10.4.7. Edit indicators and other objects

  1. Click Apps > Maintenance > Indicators.

  2. Select the object type you want to edit, for example indicator or indicator group.

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

  4. Click the options menu and click Edit.

  5. Modify the options you want.

  6. Click Save.

10.4.8. Clone indicators and other objects

Cloning an indicator or other indicator objects can save time when you create many similar objects.

  1. Click Apps > Maintenance > Indicators.

  2. Select the object type you want to clone, for example indicator or indicator group.

  3. In the list, find the object you want to clone.

  4. Click the options menu and select Clone.

  5. Modify the options you want.

  6. Click Save.

10.4.9. Change sharing settings for indicators and other objects

  1. Click Apps > Maintenance > Indicators.

  2. Select an object type, for example indicator or indicator group.

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

  4. Click the options menu and select Share.

  5. (Optional) Search for a user group and select it. The user group is added to the list.

  6. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  7. Click Close.

10.4.10. Delete indicators and other objects

  1. Click Apps > Maintenance > Indicators.

  2. Select the object type you want to delete, for example indicator or indicator group.

  3. In the list, find the object you want to delete.

  4. Click the options menu and select Delete.

  5. Click OK to confirm.

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

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

  • The organisation unit hierarchy is the main vehicle for data aggregation on the geographical dimension.

[Important]Changing the organisation unit hierarchy

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.

Example 10.9. 

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:

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


10.5.2. Workflow

The recommended workflow is:

  1. Create organisation units.

  2. Create organisation unit groups.

  3. Create organisation unit group sets.

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

To create a new organisation unit:

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

  2. In the left-hand organisation unit tree, select the organisation unit you want to add the new organisation unit to. The selected organisation unit is marked in yellow.

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

    [Note]Note

    The search is case-insensitive for organisation unit names. For codes you need to type the exact code.

  3. Click the add button.

  4. In the Name field, define the precise name of the organisation unit.

    Each organisation unit must have an unique name.

  5. In the Short name field, define 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) In the Code field, assign a code.

    In many countries organisation units are assigned a code.

  7. In the Description field, type a description of the organisation unit.

  8. Select an Opening date.

    The opening dates control which organisation units that where existing at a point in time, for example when analysing historical data. This attribute is mandatory.

  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

    This information can be vital for facilitating follow-up.

  13. If applicable, enter custom attributes values, for example HR identifier.

    You set custom attributes in Data administration > Attribute. For more information about how to use attributes, refer to the "Attributes" section.

  14. (Optional) Enter coordinates.

  15. Click Save.

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

To create a new organisation unit group:

  1. Open the Maintenance app and click Organisation units > 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.

10.5.5. Create 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 group set is always exclusive: an organisation unit can't be a member of more than one group in a group set.

    You can only select a single organisation group membership for each group set when you create a new organisation unit.

  • 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]Data completeness

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.

To create an organisation unit group set:

  1. Open the Maintenance app and click Organisation units > 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. 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]Note

    An organisation unit can only be a member of a single organisation unit group within an organisation unit group set.

  7. Click Save.

Example 10.10. Classify facilities based on ownership

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.


10.5.6. Edit organisation units and other objects

  1. Open the Maintenance app and click Organisation units.

  2. Select the object type you want to edit, for example organisation unit or organisation unit group.

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

  4. Click the options menu and select Edit.

  5. Modify the options you want.

  6. Click Save.

10.5.7. Clone organisation units and other objects

Cloning an organisation unit can save time when you create many similar organisation units.

  1. Open the Maintenance app and click Organisation units.

  2. Select the object type you want to clone, for example organisation unit or organisation unit group.

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

  4. Click the options menu and select Clone.

  5. Modify the options you want.

  6. Click Save.

10.5.8. Change sharing settings for organisation unit groups and group sets

  1. Open the Maintenance app and click Organisation units.

  2. Select Organisation unit group or Organisation unit group set.

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

  4. Click the options menu and select Share.

  5. (Optional) Search for a user group and select it. The user group is added to the list.

  6. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  7. Click Close.

10.5.9. Delete organisation units and other objects

  1. Open the Maintenance app and click Organisation units.

  2. Select the object type you want to delete, for example organisation unit or organisation unit group.

  3. In the list, find the object you want to delete.

  4. Click the options menu and select Delete.

  5. Click OK to confirm.

10.5.10. Display details of organisation units and other objects

  1. Open the Maintenance app and click Organisation units.

  2. Select the object type you want to display, for example organisation unit or organisation unit group.

  3. In the list, find the object you want to display.

  4. Click the options menu and select Show details.

10.5.11. Translate organisation units and other objects

DHIS2 provides functionality for translations of database content for example data elements, data element groups, indicators, indicator groups and validation rules. You can translate these objects to any number of locales. A locale represents a specific geographical, political, or cultural region.

[Tip]Tip

To activate a translation, go to Apps > Settings > Appearance and select a language.

  1. Open the Maintenance app and click Organisation units.

  2. Select the object type you want to translate, for example organisation unit or organisation unit group.

  3. In the list, find the object you want to translate.

  4. Click the options menu and select Translate.

    If you want to translate an organisation unit level, click directly on the Translate icon next to each list item.

  5. Select a locale.

  6. Enter the required information.

  7. Click Close.

10.5.12. 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 units > 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]Note

    You set the default value in the Settings app:

    Click Apps > Settings > General and select an item in the Max offline organisation unit levels list.

  4. Click Save.

10.5.13. 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 units > Hierarchy operations.

  2. In the left-hand hierarchy tree, select the organisation unit(s) you want to move.

    [Note]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.

10.6. Manage program metadata

10.6.1. About program metadata

[Note]Note

The functions you have access to depend on your user role's access permissions.

Table 10.11. Program metadata objects in the Maintenance app

Object type

Available functions

Tracked entity

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

Tracked entity attribute

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

Tracked entity attribute group

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

Relationship type

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


10.6.2. Create 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) In the Code field, assign a code.

  6. (Optional) Type a Description.

  7. Select an Option set.

  8. In the Value type field, select the type of data that the tracked entity attribute will record.

    Table 10.12. Value types

    Value type

    Description

    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.

    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.


  9. Select an Aggregation type.

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


  10. 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. Enter an amount of numbers into this field equal to the ciphers you want in the generated value. A pattern of 0000 would result in a generated value above 1000 and below 9999. The number of ciphers should at least allow 20 % more values than you expect is needed for keeping the ID unique.

    • Organisation unit: The values of the tracked entity attribute must not duplicate in the same organisation unit.

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

  12. (Optional) Select Confidential.

    This option is only available if you have configured encryption for the system.

  13. (Optional) Select Display in list without program.

  14. Select a Legend.

  15. Click Save.

10.6.3. Create a tracked entity attribute group

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

  2. Click the add button.

  3. In the Name field, type the tracked entity attribute name.

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

  5. (Optional) Type a Description.

  6. Assign Attributes.

  7. (Optional) Sort the display order of attribute groups in entity registration form:

    1. Select an assigned tracked entity attribute.

    2. Click the up or down arrows to move the tracked entity attribute to the position you want.

  8. Click Save.

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

10.6.5. Create a tracked entity

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

  2. Click the add button.

  3. Type a Name of the tracked entity.

  4. (Optional) Enter a Description of the tracked entity.

  5. (Optional) Enter an Alternative name of the tracked entity.

  6. Click Save.

10.6.6. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.6.7. Clone metadata 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.

10.6.8. Delete metadata objects

  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.

10.6.9. Change sharing settings for 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 options menu and select Sharing settings.

  3. (Optional) Search for a user group and select it. The user group is added to the list.

  4. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  5. Click Close.

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

10.6.11. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.7. Manage attributes

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

Table 10.14. Attribute objects in the Maintenance app

Object type

Available functions

Attribute

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


10.7.2. Create an attribute

To create a new metadata attribute and add it to an object:

  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.

10.7.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.7.4. Clone metadata 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.

10.7.5. Delete metadata objects

  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.

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

10.7.7. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.8. Manage constants

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

Table 10.15. Constant objects in the Maintenance app

Object type

Available functions

Constant

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


10.8.2. Create a constant

  1. Click Apps > Maintenance > 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.

10.8.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.8.4. Clone metadata 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.

10.8.5. Change sharing settings for 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 options menu and select Sharing settings.

  3. (Optional) Search for a user group and select it. The user group is added to the list.

  4. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  5. Click Close.

10.8.6. Delete metadata objects

  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.

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

10.8.8. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.9. Manage option sets

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

Example 10.11. 

An option set called "Delivery type" would have the options: "Normal", "Breach", "Caesarian" and "Assisted".


Table 10.16. Option set objects in the Maintenance app

Object type

Available functions

Option set

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


10.9.2. Create an option set

[Important]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.

To create an option set:

  1. Click Apps > Maintenance > 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.

    4. Sort the options by name, code/value or manually.

    5. Click Save.

10.9.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.9.4. Clone metadata 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.

10.9.5. Change sharing settings for 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 options menu and select Sharing settings.

  3. (Optional) Search for a user group and select it. The user group is added to the list.

  4. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  5. Click Close.

10.9.6. Delete metadata objects

  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.

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

10.9.8. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.10. Manage legends

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

[Note]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.

10.10.2.  Create a legend

[Note]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]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 handpick colors, or enter your color values.

  8. Click Save.

Example 10.12. Vaccination coverage legends

Table 10.17. 

Legend itemStart valueEnd value
Low bad050
Medium5080
High good80100
Too high1001000


10.10.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.10.4. Clone metadata 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.

10.10.5. Change sharing settings for 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 options menu and select Sharing settings.

  3. (Optional) Search for a user group and select it. The user group is added to the list.

  4. Change the settings for the user groups you want to modify.

    • Can view: Everyone in the user group can view the object

    • Can edit: Everyone in the user group can view and edit the object

    The default setting is that everyone (Public access) can view and edit objects.

  5. Click Close.

10.10.6. Delete metadata objects

  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.

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

10.10.8. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

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

10.11. Manage predictors

10.11.1. About predictors

Predictors are data elements that are automatically generated from samples of current and past data. You use predictors to analyse previous data in order to predict future values, for example for disease surveillance.

A predictor specifies an expression and a set of sample constraints, identical to the implementation of validation rules. This includes a period type, organisation unit levels, and parameters specifying past or periodic sample windows. The expression should evaluate to true or false.

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

Table 10.18. Predictor objects in the Maintenance app

Object type

Available functions

Predictor

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


10.11.2. Create 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. Select an Output data element.

  6. (Optional) Type a Description.

  7. Select a Period type.

  8. (Optional) Assign organisation unit levels.

  9. Create a Generator.

    The generator is the expression that is used to calculate the predicted value.

  10. (Optional) Click Sample skip test and create an expression which is used to exclude data from the generation process. The expression should evaluate to true or false.

    Example 10.13. 

    Use the sample skip test when you want to calculate the average number of malaria cases and you want to exclude the "spikes" you get from outbreaks.


  11. Enter a Sequential sample count value.

    This value decides for how many sequential periods the calculation should go back in time to collect data for the calculations. The sequential sample count depends on the value type.

    Example 10.14. 

    If the period type is "Monthly" and the sequential sample count is "3", the predictor calculations will include data three months back in time.


  12. Enter an Annual sample count value.

    This value decides for how many years the calculation should go back in time to collect data for the calculations. The annual sample count depends on the value type and sequential sample count.

    Example 10.15. 

    If the period type is "Monthly", the sequential sample count is "3" and the annual sample count is "4", the predictor calculations will include data three months back in time for this year and for two (3-1) years back in time:

    June, July, August 2016; June, July, August, 2015; and June, July, August 2014.


  13. (Optional) Enter a Sequential skip count value.

    This value decides how many periods the calculation should go back in time before the sequential sample count starts. The sequential skip count depends on the value type and sequential sample count.

    Example 10.16. 

    If the period type is "Monthly", the sequential sample count is "3" and the sequential sample count is " 2", the predictor calculations will go back two months in time, then include the following three months in the calculations:

    April, May and June (July and August are skipped because the sequential skip count is "2")


  14. Click Save.

10.11.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.11.4. Clone metadata 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.

10.11.5. Delete metadata objects

  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.

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

10.11.7. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.12. Manage push reports

10.12.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]Note

The data generated in the push reports is public so verify that you don't include any sensitive data.

Example 10.17. Push report


In the Maintenance app, you manage the following push reports objects:

Table 10.19. Push reports objects in the Maintenance app

Object type

Available functions

Push analysis

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


10.12.2. Create 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]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.

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

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

10.12.5. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.12.6. Clone metadata 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.

10.12.7. Delete metadata objects

  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.

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

10.12.9. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

10.13. Manage external map layers

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

10.13.2. Create an external map layer

[Note]Note

DHIS 2 only supports the Web Mercator projection (EPSG:3857) so make sure that the external service supports this projection.

Table 10.20. 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]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: places the external map layer above other DHIS2 base maps but below the thematic map layers.

    • Top - overlay: places the external map layer above the thematic map layers but below facility and event data layers.

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

10.13.3. Edit metadata objects

  1. Open the Maintenance app and find the type of metadata object you want to edit.

  2. In the object list, click the options menu and select Edit.

  3. Modify the options you want.

  4. Click Save.

10.13.4. Clone metadata 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.

10.13.5. Delete metadata objects

  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.

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

10.13.7. Translate metadata objects

  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.

  3. Select a locale.

  4. Type a Name, Short name and Description.

  5. Click Save.

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

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


10.14.1. Edit multiple objects in an object group

  1. Click Apps > Maintenance > 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.

10.14.2. Edit an object in multiple object groups

  1. Click Apps > Maintenance > 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,

Chapter 11. Using reporting functionality

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

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

Standard reports

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

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

11.4. Using resources

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

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

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

Reporting rate summary

11.6. Using organisation unit distribution reports

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

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

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

Running a report:

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

Orgunit distribution report

Chapter 12. Using the Pivot Table app

12.1. About the Pivot table app

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

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

  • periods (representing the time period for which the data represents)

  • organisation hierarchy (representing the geographical location of the data)

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

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

12.2. Create a pivot table

  1. In the Apps menu, click Pivot Table.

  2. In the menu to the left, select the dimension items you want to analyse, for example data elements or indicators.

  3. Click Layout and arrange the data dimensions as columns, rows and filters.

    You can keep the default selection if you want.

  4. Click Update.

Example 12.1. Pivot table based on the demo database.

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

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


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

Table 12.1. Data dimension types

Data dimension typeDefinitionExamples
IndicatorsAn indicator is a calculated formula based on data elements.Coverage of immunization across a specific district.
Data elementsRepresents the phenomenon for which data has been captured.Number of malaria cases; number of BCG doses given.
Data setsA 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 itemsA 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 indicatorsA 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.

Selection of fixed and relative periods.

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

[Tip]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.

12.2.2. Modify pivot table layout

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

The table layout screen.

After you have set up your pivot table you can click "Update" to render your pivot table, or click "Hide" to hide the layout screen without any changes taking effect. Since we in our example have selected both the period and organisation unit dimension as rows, the pivot table will generate all combinations of the items in these dimensions and produce a table like this:

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

12.3. Change the display of your pivot table

  1. Click Options.

  2. Set the options as required.

    Table 12.2. Table options

    OptionDescription

    Show column totals

    Show row totals

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

    Show column sub-totals

    Show row sub-totals

    Displays subtotals in the table for each dimension. In the screenshot above, notice how subtotals are generated for each of the periods in the period dimension. If you only select one dimension, subtotals will be hidden for those columns or rows. This is because the values will be equal to the subtotals.

    Show dimension labels

    Shows the dimension names as part of the pivot tables.

    Hide empty rows

    Hides empty rows from the table, which is useful when looking at large tables where a big part of the dimension items do not have data in order to keep the table more readable.

    Skip rounding

    Skips the rounding of data values, offering the full precision of data values. Can be useful for finance data where the full dollar amount is required.

    Aggregation type

    The default aggregation operator can be over-ridden here, by selecting a different aggregation operator. Some of the aggregation types are Count, Min and Max.

    Show hierarchy

    Shows the name of all ancestors for organisation units, for example "Sierra Leone / Bombali / Tamabaka / Sanya CHP" for Sanya CHP. The organisation units are then sorted alphabetically which will order the organisation units perfectly according to the hierarchy.

    Include only completed events

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

    Display density

    Controls the size of the cells in the table. You can set it to "comfortable", "normal" and "compact".

    The "compact" option is handy in order to fit large tables into the browser screen.

    Font size

    Controls the size of the table text font. Can be set to "large", "normal" and "small".

    Digit group separator

    Controls which character to separate groups of digits or "thousands". Can be set to "comma", "space" and "none".

    Legend set

    Shows a colour indicator next to the values. Currently the GIS legend sets are being used.


  3. Click Update.

12.4. Manage favorites

Saving your charts 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 can view the details and interpretations of your favorites when you open the Pivot table or Data Visualization app.

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

12.4.2. Save a favorite

  1. Click Favorites > Save as.

  2. Enter a name and if you wish to, a title and a description for your favorite.

  3. Click Save.

12.4.3. Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

12.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 on the dashboard. 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 see this information on the dashboard.

  3. Add a user group that you want to share your favorite with by clicking the + icon.

  4. Select:

    1. Allow external access if you want everyone to view this interpretation.

    2. Public access and choose a setting: None, Can view, Can edit and view.

    3. Administrators

  5. Click Share.

12.4.5. Create a link to a favorite

  1. Click Favorites > Get link.

  2. Choose one of the following:

    • Open in this app: You get a URL for the favorite which you can share with other users by email or chat.

    • Open in web api: You get a URL of the API resource. By default this is an HTML resource, but you can change the file extension to ".json" or ".csv".

12.4.6. Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

12.4.7. View and comment interpretations

  1. Open a favorite with one or more interpretations.

  2. Click <<< in the top right of the workspace to view, like and comment on interpretations.

  3. Click an interpretation. The chart or pivot table displays information based on when the interpretation was created. The date of the chart or table is visible next to the chart or table name, at the top of the workspace.

  4. Click Comment to write an interpretation, and Post comment to publish your comment on the dashboard. This information is shared with people who have saved this interpretation as a favorite.

To display a chart or table with the most recent information, click Clear interpretation.

12.5. Download data from a pivot table

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

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

12.5.2. Download plain data source format

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

To download plain data source formats:

  1. Click Download.

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

    Table 12.3. Available formats

    Format

    Action

    Description

    JSON

    Click JSON

    Downloads JSON format based on ID property.

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

    XML

    Click XML

    Downloads XML format based on ID property.

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

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


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

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

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

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

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

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

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

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

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

12.8. Constraints and tips

When selecting and arranging dimensions there are a few constraints that apply. All of these constraints are validated and the pivot table module will provide feedback if any constraint is violated.

  • At least one dimension must be selected on columns or rows.

  • At least one period must be included in the pivot table.

  • Data element group sets and reporting rates cannot appear in the same pivot table.

  • A table cannot contain more than the maximum number of analytic records which have been specified through the system settings. The maximum number of records could also be constrained by the maximum RAM which is available to your browser. Consider making smaller tables instead of one table which displays all of your data elements and indicators together.

[Tip]Tip

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

Chapter 13. Using the Data Visualizer app

13.1. Data Visualizer overview

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

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

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

13.2. Create a chart

  1. In the Apps menu, click Data Visualizer.

  2. Select a chart type.

  3. In the menu to the left, select the 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]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.

  4. Click Layout and arrange the dimensions.

    You can keep the default selection if you want.

  5. Click Update.

13.3. Select a chart type

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

    Table 13.1. Chart types

    Chart type

    Description

    Column chart

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

    Useful when you want to, for example, compare performance of different districts.

    Stacked column chart

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

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

    Bar chart

    Same as column chart, only with horizontal bars.

    Stacked bar chart

    Same as stacked column chart, only with horizontal bars.

    Line chart

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

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

    Area chart

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

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

    Pie chart

    Circular chart divided into sectors (or slices).

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

    Radar chart

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

    Speedometer chart

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


  2. Click Update.

13.4. Select dimension items

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

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

  • Periods: Describes when the event took place.

  • Organisation units: Describes where the event took place.

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

[Note]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.

13.4.1. Select indicators

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

  1. Click Data and select Indicators.

  2. Select an indicator group.

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

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

    The indicator moves to the Selected list.

13.4.2. Select data elements

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

  1. Click Data and select Data elements.

  2. Select a data element group.

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

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

    The data element moves to the Selected list.

13.4.3. Select reporting rates

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

  1. Click Data and select Reporting rates.

    The reporting rates appear in the Available list.

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

    The reporting rate moves to the Selected list.

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

13.4.5. Select organisation units

  1. Click Organisation units.

  2. Click the gearbox icon.

  3. Select a Selection mode and an organisation unit.

    There are three different selection modes:

    Table 13.2. Selection modes

    Selection mode

    Description

    Select organisation units

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

    Select User org unit to disable the organisation unit tree and only select the organisation unit that is related to your profile.

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

    Select User sub-x2-units to disable the organisation unit tree and only select organisation units two levels down from the organisation unit that is related to your profile.

    This functionality is useful for administrators to create a meaningful "system" favorite. With this option checked all users find their respective organisation unit when they open the favorite.

    Select levels

    Lets you select all organisation units at one or more levels, for example national or district level.

    You can also select the parent organisation unit in the tree, which makes it easy to select for example, all facilities inside one or more districts.

    Select groups

    Lets you select all organisation units inside one or several groups and parent organisation units at the same time, for example hospitals or chiefdoms.


  4. Click Update.

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

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

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

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

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

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


13.6. Change the display of your chart

  1. Click Options.

  2. Set the options as required.

    Table 13.3. Chart options

    OptionDescription

    Show values

    Shows the values above the series in the chart.

    Hide empty category items

    Hides the category items with no data from the chart.

    Show trend lines

    Displays the trend line which visualizes how your data evolves over time. For example if performance is improving or deteriorating. Useful when periods are selected as category.

    Target value / title:

    Displays a horizontal line at the given domain value. Useful for example when you want to compare your performance to the current target.

    Base value / title:

    Displays a horizontal line at the given domain value. Useful for example when you want to visualize how your performance has evolved since the beginning of a process.

    Sort order:

    Allows you to sort the values on your chart from either low to high or high to low.

    Aggregation type:

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

    Include only completed events

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

    Range axis min/max:

    Defines the maximum and minimum value which will be visible on the range axis.

    Range axis tick steps:

    Defines the number of ticks which will be visible on the range axis.

    Range axis decimals:

    Defines the number of decimals which will be used for range axis values.

    Range axis title:

    Type a title here to display a label next to the range axis (also referred to as the Y axis). Useful when you want to give context information to the chart, for example about the unit of measure.

    Domain axis title:

    Type a title here to display a label below the domain axis (also referred to as the X axis). Useful when you want to give context information to the chart, for example about the period type.

    Hide chart legend

    Hides the legend and leaves more room for the chart itself.

    Hide chart title

    Hides the title of your chart.

    Chart title:

    Type any title here to display it above the chart.


  3. Click Update.

13.7. Manage favorites

Saving your charts 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 can view the details and interpretations of your favorites when you open the Pivot table or Data Visualization app.

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

13.7.2. Save a favorite

  1. Click Favorites > Save as.

  2. Enter a name and if you wish to, a title and a description for your favorite.

  3. Click Save.

13.7.3. Rename a favorite

  1. Click Favorites > Rename.

  2. Enter the new name for your favorite.

  3. Click Update.

13.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 on the dashboard. 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 see this information on the dashboard.

  3. Add a user group that you want to share your favorite with by clicking the + icon.

  4. Select:

    1. Allow external access if you want everyone to view this interpretation.

    2. Public access and choose a setting: None, Can view, Can edit and view.

    3. Administrators

  5. Click Share.

13.7.5. Create a link to a favorite

  1. Click Favorites > Get link.

  2. Choose one of the following:

    • Open in this app: You get a URL for the favorite which you can share with other users by email or chat.

    • Open in web api: You get a URL of the API resource. By default this is an HTML resource, but you can change the file extension to ".json" or ".csv".

13.7.6. Delete a favorite

  1. Click Favorites > Delete.

  2. Click OK.

13.7.7. View and comment interpretations

  1. Open a favorite with one or more interpretations.

  2. Click <<< in the top right of the workspace to view, like and comment on interpretations.

  3. Click an interpretation. The chart or pivot table displays information based on when the interpretation was created. The date of the chart or table is visible next to the chart or table name, at the top of the workspace.

  4. Click Comment to write an interpretation, and Post comment to publish your comment on the dashboard. This information is shared with people who have saved this interpretation as a favorite.

To display a chart or table with the most recent information, click Clear interpretation.

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

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

    Table 13.4. Available formats

    Format

    Action

    Description

    JSON

    Click JSON

    Downloads JSON format based on ID property.

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

    XML

    Click XML

    Downloads XML format based on ID property.

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

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


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

13.11. Open a chart as a pivot table or as a map

  • Open a Chart and click Chart or click Map.

Chapter 14. Using the GIS app

Table of Contents

14.1. About the GIS app
14.2. Create a new thematic map
14.3. Manage event layers
14.3.1. Create or modify event layer
14.3.2. Turn off cluster
14.3.3. Modify cluster style
14.3.4. Modify information in event pop-up windows
14.3.5. Clear event layer
14.4. Manage facility layers
14.4.1. Create or modify a facility layer
14.4.2. Search for an organisation unit
14.4.3. Clear facility layer
14.5. Manage facilities in a layer
14.5.1. Relocate a facility
14.5.2. Swap longitude and latitude of a facility
14.5.3. Display facility information
14.6. Manage thematic layers 1- 4
14.6.1. Create or modify a thematic layer
14.6.2. Filter values in a thematic layer
14.6.3. Search for an organisation unit
14.6.4. Navigate between organisation hierarchies
14.6.5. Clear thematic layer
14.7. Manage boundary layers
14.7.1. Create or modify boundary layers
14.7.2. Search for organisation units
14.7.3. Navigate between organisation hierarchies
14.7.4. Clear boundary layer
14.8. Manage Earth Engine layer
14.8.1. Create or modify an Earth Engine layer
14.9. Add external map layers
14.10. Manage map favorites
14.10.1. Save a map as a favorite
14.10.2. Open a favorite
14.10.3. Rename a favorite
14.10.4. Overwrite a favorite
14.10.5. Share a map interpretation
14.10.6. Modify sharing settings for a favorite
14.10.7. Delete a favorite
14.11. Save a map as an image
14.12. Embed a map in an external web page
14.13. Search for a location
14.14. Measure distances and areas in a map
14.15. Get the latitude and longitude at any location
14.16. View a map as a pivot table or chart
14.16.1. Open a map as a chart
14.16.2. Open a map as a pivot table

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

Here's an overview of the GIS app workspace

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

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

14.3. Manage event layers

The purpose of the event layer is to display 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 OrgUnit under which the events are recorded.

Event layer

14.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, select if you want group nearby events and change style of the cluster points.

  8. Click Update.

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

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

14.3.4. Modify information in event pop-up windows

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

Pop-up window with event information

  1. 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.3.5. Clear event layer

To clear all data in a map:

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

  2. Click Clear.

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

Facility layer

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

14.4.2. Search for an organisation unit

To locate an organisation unit in the map:

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

  2. Click Search.

    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.

14.4.3. Clear facility layer

To clear all data in a facility layer:

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

  2. Click Clear.

14.5. Manage facilities in a layer

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

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

14.5.3. Display facility information

You can view organisation unit information set by the administrator as follows:

Table 14.1. View organisation unit information

FunctionAction

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.


14.6. 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]Note

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

Example of a thematic map

14.6.1. Create or modify a thematic layer

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

  2. Click Edit layer.

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

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

  5. In the Options section, 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.

14.6.2. Filter values in a thematic layer

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

To filter values in a thematic layer:

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

  2. Click Filter....

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

  4. Click Update.

14.6.3. Search for an organisation unit

To locate an organisation unit in a thematic layer:

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

  2. Click Search.

    The Organisation unit search dialog box opens.

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

    The organisation unit is highlighted in the map.

14.6.4. Navigate between organisation hierarchies

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

  1. Right-click one of the organisation units.

  2. Select Drill up or Drill down.

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

14.6.5. Clear thematic layer

To clear all data in a thematic layer:

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

  2. Click Clear.

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

Boundary layer

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

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

14.7.3. Navigate between organisation hierarchies

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

  1. Right-click one of the organisation units.

  2. Select Drill up or Drill down.

    The drill down option is disabled if you are on the lowest level or if there are no coordinates available on the level below. The same applies when you are drilling up.

14.7.4. Clear boundary layer

To clear all data in a boundary layer:

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

  2. Click Clear.

14.8. Manage Earth Engine layer

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

  • Elevation: Metres above sea level

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

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

  • Temperature, population and land cover at any location.

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

14.8.1. Create or modify an Earth Engine layer

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

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

  3. Select Min / max value.

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

  4. Select a Color scale.

  5. Select the number of Steps.

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

  6. Click Update.

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

Example 1: First-order administrative boundaries

Example 2: Aerial imagery of Dar-es-Salaam

Example 3: Dark basemap with nighttime lights from Google Earth Engine

Example 4: World time zones

[Note]Note

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

14.10. Manage map favorites

Favorite maps

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

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

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

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

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

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

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

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

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

14.12. Embed a map in an external web page

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

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

  1. Click Share > Embed in web page.

    The Embed in web page window opens.

  2. Click Select to highlight the HTML fragment.

14.13. Search for a location

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

  1. On the left side of the GIS window, click the magnifier icon.

  2. Type the location you're looking.

    A list of matching locations appear as you type.

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

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 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 map and select Show longitude/latitude. The values display in a pop-up window.

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

14.16.1. Open a map as a chart

  1. Click Chart > Open this map as chart.

    Your current map opens as a chart.

14.16.2. Open a map as a pivot table

  1. Click Chart > Open this map as table.

    Your current map opens as a pivot table.

Chapter 15. Setting up GIS

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

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

Table 15.1. Organisation unit identifiers supported for GML import

Matching priorityIdentifierValid spellingsGuaranteed unique
1Uiduid, Uid, UIDYes
2Codecode, Code, CODENo
3Namename, Name, NAMENo


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-unque 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, preferrably) 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

Chapter 16. Setting up report functionality

16.1. Data sources for reporting

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

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

16.1.1.2. Basic rules of aggregation

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

16.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, 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'.

16.1.1.3. Dimensions of aggregation

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

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

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

16.1.1.4. Aggregation operators, methods for aggregation

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

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

16.1.1.5. Advanced aggregation settings (aggregation levels)

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

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

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

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

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

16.2.1. General options

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

Indicators and periods are cross-tabbed

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:

Indicators and organisation units are cross-tabbed

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.

16.2.2. Selecting data

Data options

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.

16.2.3. Selecting report parameters

Report parameter options

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

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

Selecting category combinations

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.

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

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

Example report table

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

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.

16.4. Standard reports

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

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

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

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

Overview of the main iReport window

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

Drag the blue lines to change the band heights

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.

Adjust the size of layout areas by changing the Band height property

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.

Double click to edit the text, and change its appearance

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!

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

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

Click to edit text label

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

Click to open Expression editor

Click to open Expression editor

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.

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

Click to show expression class options

Choose desired class

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.

Expression editor

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

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

Select Detail 1 in the Report Inspector

Open the Expression Editor by clicking next to Print When Expression

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.

Code to skip parent organisation unit

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

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

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

Combining expressions in the Expression editor

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

Choose Edit Query

A Report query window will appear. Click on the Sort options button.

Choose Sort Options...

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.

Choose Add

Choose sort parameter

Click OK - Close - OK to close the three windows. The table should now be sorted.

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

Shortnames - before and after

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.

Choose Edit Expression

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.

Expression editor, showing replacing shortnames

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

Code for replacing shortnames. Shortname in red, new name in blue

The same expressions can be used for example when having indicator names along the category axis of a chart.

16.4.2.7. 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 have a totals column to the right.

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

Delete column

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.

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.

Choose grouping parameter - here, indicators

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.

Add group header/footer

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.

Move header row to column header

Next, add a text field to the Indicator group heading band, and edit it’s expression to display the indicator name.

Add text field to use as heading

Edit text field expression to show 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.

Example of finished report table

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

Sorting by indicator and organisation unit name

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

16.4.2.9.1. Bar charts

Example bar chart

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.

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

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

List of data series

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 data series editor

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

Chart legend

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.

Editing the category expression

As the expression, we chose organisationunitname, as shown below.

Choose organisation unit name.

When we are finished, the series editor should look like below. Click OK, then Close to close the Chart Details window.

Series editor.

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.

Checkbox to show/hide chart legend

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.

Edit chart title

The Expression editor window will appear, where you can enter the title. Note that the title must be in quotes, as shown below.

Expression editor

The chart is now ready.

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

Report table - crosstab dimensions

Report table - periods and parameters

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.

Delete the default chart

Drag in new chart element

As soon as we drag the Chart element into the report, a window will appear. We choose the Line chart, as shown below.

Choose Line chart

A chart wizard will appear. Click next in the first step, then Finish in the next - we will add the data later.

Choose Next

Choose Finish

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.

Choose the Details tab

Choose Add

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.

Edit the category expression

Choose periodname as the expression

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.

The finished category series

You can then Click OK to close the window. Follow the same steps to add a series for the other indicators.

Chart details after adding three series

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.

Changing the appearance of the category labels

Many other options are available to give the chart the desired look.

The finished line chart

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

Upload the file and choose the right report table

The report is now available as a "Standard Report" in DHIS2:

The report is available as a Standard Report

16.4.2.11. Some final guidelines

  • Use the same version of iReport and DHIS2's version of Jasper reports. See the About page in DHIS2 for the Jasper version in use.

  • Use report tables with cross tab dimensions as your data source for your report designs. This will make it a lot easier to design reports where you need to put specific indicators, periods, or orgunits on columns.

  • Learn from others, there are many DHIS2 report designs for Jasper on launchpad, see http://bazaar.launchpad.net/~DHIS2-devs-core/DHIS2/trunk/files/head:/resources/

16.4.3. Designing SQL based standard reports

A standard report might be based on SQL queries. This is useful when you need to access multiple tables in the DHIS2 database and do custom selects and joins.

- This step is optional, but handy when you need to debug your reports and when you have direct access to the database you want to use. Click on the "report datasources" button, "New", "Database JDBC connection" and click "next". In this window you can give you connection a name and select the JDBC driver. PostgreSQL and MySQL should come included in your iReport. Then enter the JDBC connection URL, username and password. The last three refers to your database and can be retrieved from your DHIS2 configuration file (hibernate.properties). Click "save". You have now connected iReport to your database.

- Go to standard reports and click "add new", then "get report template". Open this template in iReport. This template contains a series of report parameters which can be used to create dynamic SQL statements. These parameters will be substituted based on the report parameters which we will later select and include in the standard report. The parameters are:

  • periods - string of comma-separated identifiers of the relative periods

  • period_name - name of the reporting period

  • organisationunits - identifier of the selected organisation units

  • organisationunit_name - name of the reporting organisation unit

  • organisationunit_level - level of the reporting organisation unit

  • organisationunit_level_column - name of the corresponding column in the _orgunitstructure resource table

These parameters can be included in SQL statements using the $P!{periods} syntax, where "periods" represents the parameter.

- To create a SQL query in iReport, click on the "report query" button. Write or paste your query into the textarea. An example SQL query using parameters which will create a report displaying raw data values at the fourth level in the org unit hierarchy is:

select district.name as district, chiefdom.name as chiefdom, ou.name as facility,
bcg.value as bcg, yellowfever.value as yellowfever, measles.value as  measles
from organisationunit ou
left outer join _orgunitstructure ous
  on (ou.organisationunitid=ous.organisationunitid)
left outer join organisationunit district
  on (ous.idlevel2=district.organisationunitid)
left outer join organisationunit chiefdom
  on (ous.idlevel3=chiefdom.organisationunitid)
left outer join (
  select sourceid, sum(cast(value as double precision)) as value
  from datavalue
  where dataelementid=359706
  and periodid=$P!{periods}
  group by sourceid) as bcg on bcg.sourceid=ou.organisationunitid
left outer join (
  select sourceid, sum(cast(value as double precision)) as value
  from datavalue
  where dataelementid=35
  and periodid=$P!{periods}
  group by sourceid) as yellowfever on yellowfever.sourceid=ou.organisationunitid
where ous.level=4
and ous.$P!{organisationunit_level_column}=$P!{organisationunits}
order by district.name, chiefdom.name, ou.name;

Notice how all parameters are used in the query, along with SQL joins of resource tables in the DHIS2 database.

- Finally, back in the add new report screen, we click on "Use JDBC data source". This enables you to select any relative period and report parameters for your report. Relative periods are relative to today's date. Report parameters will cause a prompt during report creation and makes it possible to dynamically select organisation units and periods to use for your report during runtime. For the example above, we must select "reporting month" under relative periods and both "reporting month" and "organisation unit" under report parameters. Click save. This will redirect you to the list of reports, where you can click the green "create" icon next to your report to render it.

16.4.4. Designing HTML based standard reports

A standard report can be designed using purely HTML and JavaScript. This requires a little bit of development experience in the mentioned subjects. The benefit of HTML based standard reports is that it allows for maximum flexibility. Using HTML you can design exactly the report you want, positioning tables, logos and values on the page according to your design needs. You can write and save your standard report design in a regular text file. To upload your HTML based standard report to DHIS2 do the following:

  • Navigate to standard reports and click "Add new".

  • Give the report a name.

  • Select "HTML report" as type.

  • If you want to you can download a report template by clicking on "Get HTML report template".

  • Select desired relative periods - these will be available in JavaScript in your report.

  • Select report parameters - these will be available in JavaScript in your report.

The report template, which you can download after selecting report type, is a useful starting point for developing HTML based standard reports. It gives you the basic structure and suggests how you can use JavaScript and CSS in the report. JavaScript and CSS can easily be included using standard script and style tags.

If you selected relative periods when creating the standard report you can access these in JavaScript like this:

var periods = dhis2.report.periods; // An array with period identifiers
var period = periods[0];

If you selected the organisation unit report parameter when creating the standard report you can access the selected organisation unit in JavaScript like this:

var orgUnit = dhis2.report.organisationUnit; // An object
var id = orgUnit.id; 
var name = orgUnit.name;
var code = orgUnit.code;

When designing these reports you can utilize the analytics Web API resource in order to retrieve aggregated data in JavaScript. Have a look in the Web API chapter in this guide for a closer description. As a complete, minimal example you can retrieve analytics data after the report has been loaded and use that data to set the inner text of an HTML element like this:

<script type="text/javascript">
$( document ).ready( function() {
    $.get( "../api/analytics?dimension=dx:FnYCr2EAzWS;eTDtyyaSA7f&dimension=pe:THIS_YEAR&filter=ou:ImspTQPwCqd", function( json ) {
        $( "#bcg" ).html( json.rows[0][2] );
        $( "#fic" ).html( json.rows[1][2] );
    } );    
} );
</script>

<div>BGG coverage: <span id="bcg"></span></div>
<div>FIC coverage: <span id="fic"></span></div>

A few other tips: To include graphics you can convert an image to SVG and embed that SVG content directly in the report - DHIS2 is based on HTML 5 where SVG tags are valid markup. To include charts and maps in your report you can use the charts and maps resources in the Web API. You can use the full capability of the Web API from JavaScript in your report - it may be useful to read through the Web API chapter to get an overview of all available resources.

Chapter 17. Using 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?

17.1. Create an usage analytics graph

  1. Click Apps > Usage Analytics.

  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.

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

Figure 18.1. 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:

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

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 Settings section under System Approval Settings 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 under System Approval Settings, 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.

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

Table 18.1. Example Category Option Groups

Category option group setCategory option groupCategory options
PartnerPartner 1Account 1A, Account 1B
PartnerPartner 2Account 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:

Figure 18.4. Example category option groups

Example category option groups

[Tip]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:

Table 18.2. Example Category Option Group Set approval levels

Approval levelOrganisation unit levelCategory option group set
1CountryPartner
2DistrictPartner
3FacilityPartner

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

Table 18.3. Example Multiple Category Option Group Sets

Category option group setCategory option groupCategory options
PartnerPartner 1Account 1A, Account 1B
PartnerPartner 2Account 2A, Account 2B
AgencyAgency AAccount 1A, Account 2A
AgencyAgency BAccount 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:

Table 18.4. Example Multiple Category Option Group Set approval levels

Approval levelOrganisation unit levelCategory option group set
1Country 
2CountryAgency
3CountryPartner

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.

Chapter 19. Import and export

In a primary health system, the HMIS typically involves a distributed application, where the same application is running in different geographical locations (PHCs,CHCs, hospitals, districts, and state). Most of these physical locations do not have Internet connectivity, and hence they work off-line. At some point (normally at the district level), the data needs to be synchronised in order to have a consolidated database for the a particular geographical region. For this, it is important to be able to export data from one location (which is working offline, say at the health facility level) to another one say at the district level where the data would need to be imported. This feature of exporting and importing is thus a crucial function of a HMIS. This feature also helps us overcome the dependency on Internet to some degree, as data updates can be transferred via USB key where there is no connectivity, or through email where there is limited Internet connectivity. DHIS2 provides robust export-import functionality to fulfill these needs.

To access the main Import-Export module, choose Services->Import-Export. A number of services are available, all of which will be described in detail in respective sections below.

19.1. Meta-data import

19.1.1. Meta-data import

Meta-data objects can be easily imported by accessing Import-Export->Meta-Data import. Select the file to import by pressing "Select" and choose the file from your local file system. When importing XML and JSON files, the system will automatically detect which type of objects which should be imported. When importing CSV metadata, you will need to specify the object type. Consult the corresponding section in this manual on "CSV Metadata import" for more specific information on how the CSV file should be created.

Default import screen

There are two separate options for importing data.

  • Dry run: This is similar to the old preview option, this will do a dry run import, and give you information about any errors.

  • Strategy: There are three options here, "New and Updates", "New only", and "Update only". New and updates tells the importer to expect both new meta-data, and updates to existing ones. New only will only accept fresh meta-data, usually you would use this on a empty database. Updates only will only allow the meta-data to match meta-data that is already there (same identifiers, new name etc).

[Note]Note

It is highly recommend always using the Dry run option when importing data to make sure you keep control over any changes to your meta-data and databases being out of synch on data elements or organisation unit names

19.1.1.1. Dry run before importing

Before doing the import into your database, it is highly recommended that you run the import with the dry run option set to true first. This will enabled you to have a look at how many new, updates, and ignored meta-data there will be. After you have selected your file, set dry run to true, you can now click the import button. After doing this, you will be greeted by this window.

Here you can see a short summary of what was contained in your import file. To see further details, please click on the "Display import summary" link.

Here you can see that the import dry run was successful and the import contained 1 new organisation unit, 1332 updated, and 4 organisation unit levels.

Below you can see another example.

Here you can see that the organisation unit "Nduvuibu MCHP" had a unknown reference to an object with ID "aaaU6Kr7Gtpidn", which means that an object with this ID was not present in your imported file, and it could not be found in the existing database. Its important to note that even if a reference could not be found, the object will still be imported, but you might have to fix this directly in DHIS2 later, if the reference should have pointed to something else.

19.1.1.2. Matching identifiers in DXF2

The DXF2 format currently support matching for two identifiers, the internal DHIS2 identifier (known as a UID), and also using an external identifier called called a "code". When the importer is trying to search for references (like the one above), it will first go to the UID field, and then to the code field. This allows you to import from legacy systems without having a UID for every meta-data object. I.e. if you are importing facility data from a legacy system, you can leave out the ID field completely (DHIS2 will fill this in for you) and the put the legacy systems own identifiers in the code field, this identifier is required to be unique. This not only works for organisation units, but for all kinds of meta-data, allowing for easy import from other systems.

19.1.2. Importing CSV meta-data

To import CV meta-data go to import-export module and select CSV Meta-Data Import form the left side menu. You must select the object type which your CSV file contains. You can only upload one type of objects at the time. Upload your file and click update. For the CSV format, please visit the Web API chapter > CSV meta-data import in the developer guide.

19.1.3. GML data import

The GML import function can be used to import data prepared in the Geography Markup Language (GML). GML can be used to update the coordinates (both polygons and points). Once you have prepared your GML file as detailed in the chapter on "Importing coordinates", you can load the file with this function.

Importing the organisation unit hierarchy from GML is not supported. Therefore you should create the organisation unit hierarchy separately, and then use GML to update the coordinates once the hierarchy has been created.

19.2. Importing data

The import option allows different instance of DHIS2 to receive standardised sets of data in the absence of a networked system. The functionality can also be used to import data produced by another system (perhaps on a regular basis) or to import legacy data which has been transformed into a format which DHIS2 can understand. Typically, a data set is exported from one DHIS2 instance (e.g. a district level system) to another system (e.g. a provincial level system). DHIS2 is also capable of importing data directly from a DHIS2 1.4 Access database. Each of these options will be discussed in the following sections.

19.2.1. XML data import

To import data in XML format, simply select Services->Import-export->XML data import. Similar options to the XML meta-data import facility are available. Please refer to the Developer guide > Web API > Data values chapter on XML data import for details on the XML format which is used by DHIS2 for aggregate data import.

19.2.2. Importing CSV data

DHIS2 supports import of data in the CSV (Comma Separated Values) format. This can be used to import exchange file produced by DHIS2 itself. It also comes in handy when you want to import data from a third-party system as CSV is widely supported in applications and is easy to produce manually.

To import a CSV data exchange file navigate to the CSV Data Import item in the left-side menu. Upload the exchange file and click Import. CSV files can be imported both as plain text file or as compressed ZIP file archive.

Please refer to the Developer guide > Web API > Data values chapter on CSV data import for a description of the CSV format to use.

19.2.3. Event data import

Event data can also be easily imported with the "Event data import" function. Refer to the section in the WebAPI for more information on the format used for importing events. Otherwise, the functionality is the same as the XML data import used for aggregate data.

19.2.4. Importing PDF data

DHIS2 supports import of data in the PDF format. This can be used to import data produced by off-line PDF data entry forms. Please refer to the section "Data set management" for details on how to produce a PDF form which can be used for off-line data entry.

To import a PDF data file, navigate to the PDF Data Import item in the left-side menu. Upload the completed PDF file and click Import.

After the import process is finished, you can follow the link to the import summary, which will inform you about the outcome of the import process in terms of number of records imported, updated and ignored and potential conflicts.

19.2.5. Importing data from DHIS2 1.4

There are two ways to import data from a DHIS2 1.4 database; 1) through the 1.4 XML-based export files, or 2) directly from the DHIS2 1.4 data file (.mdb). Both are accessible from the DHIS2 1.4 Import menu under Import in the Import-Export module.

It is critical that all data integrity violations which are present in the DHIS2 1.4 database be fully resolved before attempting an import into DHIS2. You can check the data integrity of DHIS2 1.4 through the CORE Module->Advanced->Data integrity checks. A report will be generated of all data integrity violations which should be resolved prior to importing into DHIS2.

[Warning]Warning

When data is imported from DHIS2 1.4, both the meta-data as well as data are imported. You should therefore be exceedingly careful that the meta-data present in DHIS2 1.4 is compatible with your DHIS2 data, otherwise during a DHIS2 1.4 data import, the meta-data in the DHIS2 system will be potentially overwritten by the i

19.2.5.1. DHIS2 1.4 File (database) Import

This method is recommend when doing large imports from 1.4, and especially when importing into a new DHIS2 database.

DHIS2 1.4 File Configuration

Before you can start the 1.4 file import you need to provide a few details about the 1.4 database:

Datafile(#): Here you put the full path to the DHIS2 1.4 data file you want to import from, e.g. C:\DHIS14\DHIS_#LR_LIBERIA.mdb.

Username: Leave blank (unless you have set up extra security measures on the file)

Password: Leave blank (unless you have set up extra security measures on the file)

Levels: Provide the number of levels in the orgunit hierarchy in your 1.4 database, e.g. 5.

Click "Save" and you will return to the DHIS2 1.4 File Import window.

Import Type:

As with other imports you have the options to Import (directly), Preview, or Analyse the import. We recommend using the Analyse option first to check that the 1.4 database is OK and ready to be imported.

When importing a large database into a new blank DHIS2 database we recommend using the Import option to save time.

For smaller incremental imports the Preview is OK.

Last Updated:

If you want the full import, all the data in the 1.4 database you leave this field blank.

If you only want to do an incremental import into an already existing DHIS2 database you can use this field to filter which data values to import. Only values added or edited after the date you specify will be imported. This filter makes use of the LastUpdated column in the RoutineData table in the DHIS2 1.4 data file.

Import process:

When you are done selecting Method, and LastUpdated you can begin the import by clicking on the Import button. This process might take a long time, depending on how many data values you are importing. On a reasonable spec. computer the import takes about 2 million records per 30 minutes.

19.2.5.2. DHIS2 1.4 XML Import

Import though XML data from DHIS2 1.4 is also possible using the standard DHIS2 1.4 export format. Just be sure that the DHIS2 1.4 export format has been set to "DHIS 2" as illustrated in the screen shot below. After the data has been exported by DHIS2 1.4, you can import the data by choosing "Services->Import-Export->DHIS 1.4 Import->DHIS2 1.4 XML Import" and proceeding via the procedure outline in the previous section.

19.2.5.3. Limitations to DHIS2 1.4 imports

Although it is possible to import and export data between instances of DHIS2 1.4 and DHIS2, there are significant limitations. Currently, the import of some metadata is not supported from DHIS2 1.4 to DHIS2. This includes:

  • Organisational unit alternate names

  • Compulsory data element pairings

  • Custom data entry forms

  • Dataset data entry levels

It is also important that the aggregation operator defined in DHIS2 1.4 be set to the correct value. Some data, such as population, should have their aggregation operator set to "Average" in DHIS2, as this controls how the aggregation of data is handled over time (but not within the organisational unit hierarchy).

19.3. Exporting data and meta-data

DHIS2 makes it possible to export various types of data in multiple data formats. You can export your data, also referred to as measures or facts; and your meta-data, which refers to the information describing your data. Data can be exported both in raw, non-aggregated format and in aggregated format. It is also possible to export a combination of data and meta-data in case you have special requirements. This chapter covers mainly how to export data and meta-data through the user interface of the import-export DHIS2 module. Data can also be exported programmatically through the DHIS2 Web API, and it is useful to be aware of the various options available:

  • Export raw, non-aggregated data through the user interface: Covered in this chapter.

  • Export aggregated data programmatically through the Web API: Please refer to the Web API chapter, section on Analytics.

  • Export a combination of data and meta-data: Please refer to the SQL view sections in the Data administration chapter and Web API chapter.

  • Export meta-data through the user interface: Covered in this chapter.

  • Export meta-data programmatically through the Web API: Please refer to the Web API chapter, section on meta data.

Data can be exported on various formats, including DXF 2 (the DHIS2 meta-data and data exchange format based on XML), CSV, PDF, MS Excel and the DHIS2 1.4 XML format.

Another aspect of data export is the type of DHIS2 deployment. In the case of online deployment, all data is saved into a single database only. In an offline deployment, each instance will store data in a separate database in their local system. In an offline deployment, after the data entry is finished, data will have to be manually sent to the next level in the organizational hierarchy. In an on-line application this is not required, as all data is captured over an Internet connection and stored in a central location.

19.3.1. Metadata export

Meta-data is "data about data". In the context of DHIS2, meta-data consists of definitions of data elements, indicators, the structure and names contained in the organizational hierarchy, and other options. Click on the "Meta-data export" link from the main "Data export" screen in order to access this. Just select the features, format, and the compression that you want and click "Export". This metadata file can then be transmitted just like a data file, except it will contain information on the definitions of the various features, as opposed to the values of the data themselves.

Simply choose the objects which you would like to export, and click "Export".

19.3.2. Meta-data detailed export

In certain implementations, it may be useful to create groups of metadata objects which should always be exported together. To access this feature, click " Meta-data detailed export" from the left side menu of the "Import-export" dialog.

A list of available metadata export filters will be shown. Click on the name of the filter you would like to edit and then select "Edit" from the context menu. An example of the dialog is shown below.

In this example, we have created a metadata export filter, to export all "Constants" from the system. If any meta-data objects have been selected to be part of the filter, they will be highlighted in green. Click on the name of the objects you would like to export, and add them to the right side to be selected to be part of the export. Once you have composed the filter as needed, click "Save" (when editing) or "Add" (when adding a new metadata filter).

To export the filter, click on the name from the main "Meta-data detailed export" menu, and choose "Export" from the context menu. The following dialog will appear.

You can choose to export the data as XML or JSON format. You can also specify whether or not the result should be zipped or unzipped. Lastly, if you click check "Export with dependencies", all dependent meta-data objects which the ones you have selected depend upon, will also be exported.

19.3.3. Data export

To export raw data from DHIS2, choose "Import-export->Data export". Select the organisation unit(s), the start and end date, and dataset or data sets for which data export should be selected. You can also select which types of identifiers which will be exported by pressing "More options" and then selecting either UID, Code, or Name for data elements, organisation units and category options. Once you have specified all options as required, press "Export as..." along with the format which you would like to export the data as (XML, JSON or CSV).

A pop-up save option will appear on the displayed screen (see picture below) prompting the saving of the exported data. You may save the export folder on your desktop or any other folder by selecting the ‘Save to Disk’ option from the pop-up prompt.

19.3.4. Event data export

Event (or tracker) data can be exported by accessing the "Event data export" function by choosing "Services->Import-export->Event data export" from the main menu. Choose the organisation unit of interest, along with the Programs and Program stages and start and end dates. The "Inclusion" option has three options.

  • Selected organisation unit: Export event data only for the selected organisation unit

  • Include children of organisation unit: Export event data for the children of the organisation unit as well as the selected organisation unit itself.

  • Include descendants of organisation unit: Export event data for the descendants of the organisation unit as well as the selected organisation unit itself.

Event data can be exported either as XML or JSON, and either compressed or uncompressed in a ZIP file. Once you have set all options, press "Export" . The export file will now by downloaded to your local computer.

19.3.5. Exporting data to other systems

19.3.5.1. DHIS2 1.4 Meta-data export

The DHIS2 1.4 Meta-data export functionality provides the same functionality as the standard DHIS2 meta-data export, except that the resulting file can be used to transmit meta-data information to DHIS2 1.4 systems.

19.3.5.2. DHIS2 1.4 Detailed Metadata Export

The DHIS2 1.4 Metadata export functionality provides the same functionality as the detailed DHIS2 metadata export, except that the resulting file can be used to transmit meta-data information to DHIS2 1.4 systems. Simply select the data elements and indicators that you want and click "Export" to begin the export process.

19.3.5.3. DHIS2 1.4 Data export

This service allows you to export data to a format which can easily be imported into a compatible DHIS2 1.4 database.

19.3.5.4. XLS metadata export

Meta-data can be exported directly to the XLS format with this function. Simply click all of the available object which you wish to export and click "Export".

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

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

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

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

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

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

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

20.1.6. Data sets not assigned to organisation units

All data sets should be assigned to at least one organisation unit.

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

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

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

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

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

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

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

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

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

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

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

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

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

20.1.20. Validation rules without groups

All validation rules must be assigned to a group. Go to Data quality->Validation rule group and assign the offending validation rule to a group.

20.1.21. Invalid validation rule left side expressions

An error exists in the left-side validation rule definition. Go to Data quality->Validation rule and click the "Edit" icon on the offending rule. Press "Edit left side" and make the corrections that are required.

20.1.22. Invalid validation rule right side expressions

An error exists in the left-side validation rule definition. Go to Data quality->Validation rule and click the "Edit" icon on the offending rule. Press "Edit right side" and make the corrections that are required.

20.2. Maintenance

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


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

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

20.4. Locale Management

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.

20.5. SQL View

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

20.5.1. Creating a new SQL view

To create a new SQL view, click Apps > Data administration >SQL view and click Add new.

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

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

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

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

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

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

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

20.11. Scheduling

The analytics, resource tables, data sync, metadata sync and data mart can be automatically scheduled to run on regular intervals. Simply select the aggregation period types, organisation unit group set aggregation level, and strategy to configure how the scheduled job should run. If you are using surveillance rules, you can choose to run them "All daily" by selecting this option.

Pressing "Start" will enable the scheduled job to run at a pre-determined time (always at midnight based on the server time).

Starting 2.24 you can also schedule metadata synchronization on regular intervals. Simply select "Enabled" from the drop-down, select the time-period during which you want to run the task. Pressing "Start" will enable the scheduled job to run at that specific time selected.

As depicted in the screenshot, you can select the time period as daily, weekly, monthly or yearly.

  • Daily: On selecting this checkbox, you will need to select the time at which it needs to run daily.

  • Weekly: On selecting this checkbox, you need to select the day of the week and time on that day on which it needs to run.

  • Monthly: On selecting this checkbox, you need to select a day of the week, say Every 1st Sunday, Every 2nd Saturday, etc. and time on that day on which it needs to run.

  • Yearly: On Selecting this check box, you need to select the month, specific day of the month and time on that day on which it needs to run.

There is also the capability for running the meta data synchronization immediately. Using "Sync Now" button you can run the meta data synchronization task immediately even if the scheduler is scheduled to run at specific time or not.

  • If the scheduler is already enabled, you will see the "Sync Now" button on the page itself.

  • If the scheduler is not enabled, simply select "Enabled" from the drop-down for Metadata Synchronization and click "Sync Now" button.

20.12. Data synchronization

DHIS2 provides a feature for synchronizing data being captured on the local instance with a another, remote 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. Till now only aggregate data was being synced. Starting from 2.24 even non anonymous events data (line list) will also be synced.

These are the steps to enable data synchronization:

  • Go to Settings > Synchronization, enter the remote server URL, username and password and click Save. You can test your settings by clicking on the "Test settings" link.

  • Go to Data administration > Scheduling. Under Data synchronization set strategy to Enabled, and click Start.

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 "enryption.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 very first time DHIS2 attempts to synchronize data the system will include data entered during the last three days. For the subsequent attempts the system will store the time of the last successful data synchronization and only include data saved or edited since that time. A synchronization job is considered successful only if data was submitted, authenticated and saved successfully on the remote server,.

  • The system will attempt a synchronization every minute. If the local server does not have a working Internet connection at the time, the synchronization will be silenly aborted and re-attempted after a minute.

  • You can see the time of last successful synchronization with remote server in the scheduling screen next to the "Last success" label.

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

Chapter 21. Settings

The settings module provides a set of application configuration options. There are two main groups of settings: the system settings apply to the whole system and all its users while the user settings apply to the environment of the currently logged in user. The system settings can be accessed from the maintenance menu, settings module. The user settings can be accessed under the profile menu, settings page.

21.1. System settings

The system settings section provides general configuration options and options specifically for appearance and email.

21.1.1. General settings

  • Maximum number of analytics records: This number can be increased to provide more records from the analytics. The default is 50,000 and can be increased. Note that setting the maximum number of analytics records to "unlimited" should be used with caution as it might result in very high load on your server.

  • Infrastructural indicators: This setting defines an indicator group where the member indicators should describe data about the infrastructure of organisation units. This infrastructural data can currently be viewed in the GIS module in the facility information sheet.

  • Infrastructural data elements: This setting defines a data element group where the member data elements should describe data about the infrastructure of organisation units. Examples of such infrastructural data elements could be population, doctors, beds, Internet connectivity and climate. This infrastructural data can currently be viewed in the GIS module in the facility information sheet.

  • Infrastructural period type: Sets the frequency for which the data elements in the infrastructural data elements group are captured. This will typically be yearly. When viewing the infrastructural data you will be able to select the time period of the data source.

  • Default relative period for analysis: Defines the relative period to use by default in analytics apps such as pivot table, charts and GIS. This relative period will be automatically selected when the apps are opened, and should likely be the most commonly used relative period among your users.

  • Feedback recipients: This setting defines a user group where the members will receive all messages being sent through the function for writing feedback in the dashboard module. This will typically be members of the super user team who are able to support and answer questions coming from end-users.

  • Maximum offline organisation unit levels: This setting defines how many levels in the organisation unit hierarchy will be available offline in the organisation unit tree widget. Under normal circumstances you can leaves this on the lowest level, which is default behavior. Setting it to a higher level might be useful in order to reduce initial load time in cases where you have a large number of organisation units, typically more than 30 000.

  • Data analysis std dev factor: Sets the number of standard deviations for use in the outlier analysis performed on the captured data in the data entry module. The default value is 2; a high value will catch less outlier values than a low value.

  • Phone number area code: The area code for the area in which your deployment is located. Used for sending and receiving SMS.Typically, this would be a country code, for instance , +260 , which is the country code for Zambia.

  • Enable multi-organisation unit forms: Enable support for entering data forms for multiple organisation units at the same time, in data entry, click on the parent organisation unit for the children that you want to enter data for, and the dataset list will include datasets that are assigned to the children of that parent.

  • Put analytics in maintenance mode: Puts the analytics engine / Web API resource in maintenance mode, implying that 503 Service Unavailable will be returned for all requests. This is useful when you need to perform maintenance on the server like rebuilding indexes while the server is running in production, in order to reduce load and more efficiently carry out the maintenance.

  • Days after period end to qualify for timely data submission: Sets the number of days after the end of a period in which a data entry form must be marked as complete in order to be considered timely. This affects the "reporting rate" tool in the reporting module which lists forms marked as complete as well as marked as complete in time. The default value is 15.

  • Omit indicator values with zero numerator value in data mart: Defines whether aggregated indicator values with zero as the numerator value should be written to the indicator data mart table. Having such values written is required for instance when connecting Excel pivot tables to the data mart as Excel will need the numerator data to correctly aggregate up in the organisation unit hierarchy. If third-party tools like Excel are not used with the application this will reduce the total number of values written to the data mart (which again will improve performance) and could safely be set to omit.

21.1.2. Server settings

  • Cache strategy: Decides for how long reports and responses related to analysis should be cached. If you are using the scheduled, nightly data mart tasks it makes sense to put this on "Cache until 6 AM tomorrow". This is because we know that data in reports change at that time, and you can safely cache data up to the moment when the data mart is updated. If you are loading data continuously into the datamart you should set it to "No cache". If you load data very infrequently into data mart you should consider setting it to "Cache for two weeks".

  • Number of database server CPUs: The number of CPU cores of your database server can be configured as a system setting. This allows the system to perform optimally when the database is hosted on a different server than the application server, as the analytics engine scales linearly on the number of available cores.

  • System notifications email address: An email address can be specified to receive system notifications. Notifications about failures in processes such as analytics table generation will be sent here. This is useful for application monitoring.

  • Server base URL: The full, externally accessible base URL for this server. Example: https://apps.dhis2.org/demo is the server base URL for the DHIS2 demo server. The URL is used to provide links to this server from external locations such as in emails sent from the system. Note that if this URL is not present, emails sent from the messaging system will not contain a reply link.

  • Google Analytics (Universal Analytics) Key: Set your Google UA key here to provide analytics for your DHIS2 instance. Most places are covered, but it will not be provided for custom apps. You can read more about Google Analytics at http://google.com/analytics.

21.1.3. Appearance settings

  • Application title: Sets the application title on the top menu.

  • Application introduction: Sets an introduction of the system which will be visible on the top-left part of the login page.

  • Application notification: Sets a notification which should be displayed to users. Will be visible on the front page under the login area.

  • Application left-side footer: Sets a text in the left-side footer area of the login page.

  • Application right-side footer: Sets a text in the right-side footer area of the login page.

  • Style: Sets the style / look-and-feel of the system. The corresponding user style setting overrides this.

  • Start page: Sets page / module which the user will be redirected to after logging in. The dashboard module is the recommended start module.

  • Help page link: A URL can be provided for an alternative help source. This defines the URL which users will see when selecting Profile->Help.

  • Flag: Sets the flag which is displayed in the left menu of the dashboard module.

  • Require authority to add to view object lists: Will hide menu and index page items / links to lists of objects if the current user does not have the authority to create the type of objects (privately or publicly).

21.1.4. Email settings

  • Host name: Refers to the host name of the SMTP server. For instance when using Google SMTP services this should be smtp.gmail.com.

  • Port: The port to connect to the SMTP server.

  • User name: The user name of the user account with the SMTP server. For instance mail@dhis2.org.

  • Password: The password of the user account with the SMTP server.

  • TLS: Refers to whether the SMPT server requires TLS for connections.

  • Email sender: The email address to use as sender when sending out emails.

21.1.5. Access settings

  • Self registration account user role: Defines which user role should be given to self-registered user accounts. To enable self-registration of users, select any user role from the list. To disable it, select "Do not allow self registration". When enabled, a link to the self-registration form will be displayed on the login page.

  • Do not require recaptcha for self registration: Whether or not to use reCAPTCHA for user registration.

  • Self registration account organisation unit: Defines which organisation unit should be associated with self-registered users. Any organisation unit must be selected in order to enable self registration.

  • Enable user account recovery: Defines whether users are allowed to restore the password of their account if they forgotten it. When enabled, a link to the account recovery form will be displayed on the front page. User account recovery requires that you have configured email settings (SMTP).

  • Allow users to grant own user roles: Defines whether users should be allowed to grant the user roles they are granted themselves to others.

  • Allow assigning object to related objects during add or update: Defines whether to allow users to assign an object to a related object in the add or updated object screens. As an example, you can allow users to assign an organisation unit to data sets and org unit group sets when creating or updating the org unit.

  • Require user account password change: Require that users change their password every 3,6,12 months. Please note that for 2.14 release, they will have to login through the desktop to change passwords.

  • OpenID provider: Defines the OpenId provider.

  • OpenID provider label: Defines the label to display for the specified OpenID provider.

21.1.6. Approval

  • Hide unapproved data in analytics: Defines whether unapproved data should be visible or hidden in analytics.

  • Acceptance required before approval: Defines whether to include an acceptance step before the approval step in the approval workflow.

21.1.7. Calendar settings

  • Calendar: Defines which calendar system should be used throughout the system.

    There are currently eight calendar systems which are supported, namely Coptic, Ethiopic, Gregorian, Julian, Islamic, ISO, Nepal and Thai. Note that this is a system wide setting. It is not possible to have multiple calendars within a single DHIS2 instance.

  • Date format: Defines which date format should be used throughout the system.

21.1.8. Data import

These settings apply to the data import process, and provide optional constraints on what should be considered a conflict during import. The constraints are applied to each individual data value in the import.

  • Require periods to match period type of data set: Require period of data value to be of the same period type as the data sets for which the data element of data value is assigned to.

  • Require category option combos to match category combo of data element: Require category option combo of data value to be part of the category combo of the data element of the data value.

  • Require organisation units to match assignment of data set: Require organisation unit of data value to be assigned to one or more of the data sets which the data element of data value is assigned to.

  • Require attribute option combos to match category combo of data set: Require attribute option combo of data value to be part of the category combo of the data set which the data element of data value is assigned to.

  • Require category option combo to be specified: Require category option combo of data value to be specified. By default it will fall back to default category option combo if not specified.

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

21.1.9. Synchronization settings

DHIS2 provides a feature for synchronizing metadata and data. Given two instances in a central-local deployment strategy, metadata created at central can be synched to the local and the data created at local can be synced to the central. This can be useful when there are multiple stand-alone instances of DHIS2 and a global metadata needs to be created at all the local instances. So, metadata creation and update happens at the central and if the metadata sync task is enabled, the metadata gets synced down to all the local instances which are bound to the given central instance. These local instances will in turn push data values to that central instance. The following settings are used for both data and metadata synchronization.

  • Remote server URL: The URL of the remote server running DHIS2 to upload data values to. Use of SSL/HTTPS is recommended since username and password is sent with the request (using basic authentication). The system will attempt to synchronize data once every minute. Note that you must enable data sync from Data administration > Scheduling.

    [Note]Note

    The system will use this setting for metadata synchronization as well. Note that the metadata synchronization needs to be enabled from Data Administration app > Scheduling.

  • Remote server username: The username of the DHIS2 user account on the remote server to use for data synchronization. Whilst metadata versioning is enabled, there is a need to ensure that the configured user has the authority "F_METADATA_MANAGE".

  • Remote server password: The password of the DHIS2 user account on the remote server. The password will be stored encrypted.

If you are syncing metadata also, then see the below settings.

  • Enable Versioning for Metadata Sync: This is a new feature added in 2.24. If you are following model as mentioned above, then enable this setting. Otherwise you can ignore it.

  • If metadata versioning is enabled, the user gets the option to create metadata versions.

    • When system is a central instance, then you will see three columns in the Versioning table

      • Version: Name of the Version which is automatically generated by system.

      • When: The timestamp of metadata version creation at central instance.

      • Type: Type of metadata version.

      Additionally you will see the following label on top of the table:

      Master Version - this is the latest version in the system.

    • When system is field instance, then you will see four columns in the Versioning table

      • Version: Name of the Version which is automatically generated by system.

      • When: The timestamp of metadata version creation at central instance.

      • Type: Type of metadata version

      • Last Sync: Timestamp of when the last sync happened for this version in this system

      Additionally you will see the following labels on top of the table:

      Master Version - the latest version of central instance. This is important to understand that the master version information is the central instance's latest version. This is important to look at the difference between the versions of metadata that exist at central and at local.

      Last sync attempt - If the last sync attempt is a failure, this will be shown.

Chapter 22. Mobile

This chapter covers various mobile technologies including Web, J2ME, SMS Service and SMS Command.

22.1. DHIS2 Mobile Introduction

DHIS2 provides a range of options to allow data entry from mobile devices, including a dedicated GPRS/3G J2ME client and two versions of DHIS2 which have been optimized specifically for mobile browsers. Each of these solutions will be described in detail in the following sections. DHIS2 offers several Android clients, which are described in detail in other sections of this guid.

Collection of data in the field can be technically challenging and expensive. Mobile phone solutions have the potential to significantly reduce the complexity of deploying a distributed data collection system. Using a simple Java client installed on a mobile phone or a web browser which works on the mobile phone, field workers can report directly to the DHIS2 database through their mobile device.

While mobile phone solutions have a great potential, there are complexities with such deployments. Phones lack processing power and have a small display, they need to be charged, and often such deployments make the most sense in areas with poor or intermittent network coverage.

Each of the mobile solutions are introduced briefly below, and the discussed in separate sections in detail:

  • DHIS2 Light: A mobile browser optimized data entry module for all devices

    This module allows for data entry directly with the browser of the mobile device. A wide range of devices and mobile browsers are supported including: Opera mini 3 & 4 (basic and advanced) - Opera mini 4, Nokia S40 mobiles ,Windows Phone 7, Window Mobile 6, Palm Pre, Blackberry (v5 and v6), Firefox mobile, iOS devices (iPhone) and Android devices. This client does not have offline-support, and an active GPRS/3G connection is required. It does not require a new application installation on the phone to support new features, but does require a stable data connection for use. This solution is described in Section 22.2, “Mobile browser based data entry”

  • DHIS2 Smartphone client: A mobile browser optimized data entry module for Smartphone devices

    This module allows for data entry directly with the browser of a Smartphone. Offline data entry is supported and it does not require any installation of a special client on the phone itself.

  • J2ME GPRS/3G client

    DHIS-mobile includes two separate J2ME clients supporting GPRS/EDGE/3G as a transport mechanism. One clients supports facility aggregate reporting and the second client supports name-based program tracking. These clients are split into separate applications to make deployment easier. Some health workers may have both applications installed on their phone. Both of these clients support offline-storage of data and work on J2ME enabled devices (feature phones).

    An active GPRS/3G connection is required in order to send data to the DHIS2 database, but data can be entered offline and transmitted when a connection is present. This client is intended primarily for low-end devices which support J2ME applications, although the offline-supports adds some memory requirements which limits the handset selection. While the solution is primarily tested on Nokia phones, it also works on several other J2ME capable handsets.

    The facility reporting J2ME client is described in the chapter "J2ME GPRS/3G Client"

22.2. Mobile browser based data entry

22.2.1. Getting started with mobile browser data entry

This approach is for data-entry on a smart phone with a mobile browser by navigating to the URL of the DHIS2 instance, for example: the full URL link for demo on dhis2.org http://apps.dhis2.org/dev/mobile/index.action . And your mobile browser will automatically detect the DHIS2 application where the server URL is given (e.g.: http://apps.dhis2.org/dev). Here is the login form to access the application with user-name and password. Click on "Login" to continue or "Reset" to reset:

After logging in, there are the list of functions:

- Aggregate Reporting: Entries for aggregate data with defined/assigned dataset by organisation-units

- Tracking:

  • Find Person: find person based on Name, Phone Number or ID, and Organization unit.

  • Activity Plan: Entries data for the persons by organisation-units, persons and programs/program-stages

  • Person Registration: Registry a new person

  • Anonymous: Entries for anonymous person based on programs

- Messages: Manage the messages and discussions from the server. Message reply is available. User can send feedback message in Messages.

- Reports: The output reports from the server.

- Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the Interface language.

- Logout: to log out the application.

- Desktop version: navigate to the desktop version of DHIS2 for administration. This require a lot of resources from the client mobile, for example: the sufficient memory to load the pages. Not recommended for the normal GPRS/3G/... phones.

The list above will be explained in details:

  1. Aggregate Reporting: Entries for aggregate data with defined/assigned dataset by organisation-units.

    Click on the "Aggregate Reporting", then choose an Organisation Unit from the list and the list of the datasets will be appeared for entering aggregate data. See the below example:

    Step 1: Select an Organisation Unit from the list

    Step 2: Select a Dataset (entry form) from the list

    Step 3: Select a period (based on the period type of the chosen dataset) from the list

    Step 4: Entering the data

    Step 5: Save the data entered after completing the data, choose the option for data completeness if having.

  2. Tracking: Find/Add Person, Visit Schedule, Person Registration, Anonymous

    2.1 Find/Add Person : find person based on Name, Phone Number or ID, and Organization unit.

    • Step 1: insert Name, Phone Number or ID and select the Organization Unit, then click Search.

    • Step 2: select a person

      Then all the information of that person will be displayed

    • Step 3: choose the next program stage for entering the data

      To view all the program stages, click on the name of that program (Child Heath Program as the screen shot)

    2.2: Visit Schedule: Choose An Organization Unit

    • Current Activity Plan: the list of the beneficiaries registered, enrolled, not yet finish/complete a/many program and there is at least a program-stage open for data-entry.

      + Step 1: Choose a Person for entry

      + Step 2: Choose a current and active program-stage for entering the data

      You can also see the person's information (ID, gender, Date of Birth, and Blood Group) by clicking on the Details (on top of the list appeared)

      The details information of the chosen person:

    • All Activity Plan: the list of all beneficiaries registered, enrolled, not yet finish/complete a/many program.

    • Single Event:

    2.3: Person Registration: Registry a new Person

    • Step 1: Entry personal information

    • Step 2: Enroll program for the person just been registered, then click "Enroll".

    • Step 3: Entry required information for the chosen program, then click "Enroll"

      Here is the result:

    2.4: Anonymous: Entries for anonymous person based on specific programs

  3. Messages: Manage the messages and discussions from the server. Message reply is available.

    The number showed is the unread messages. Click on that to view the list of the messages (the unread messages are in bold and dark blue color):

    Then you can pick up the message/topic for the discussions by leaving the reply message, see this example:

    User can create and send a feedback to server in messages section. After sending out the new feedback, the message (feedback) will be listed under "Messages" for further following up.

  4. Reports: The output reports from the server

    (will be updated)

  5. Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the Interface language.

    Here is the form for setting the user account/access and the interface language. Click on "SAVE" for completing the settings, see the example below:

  6. Logout: to log out the application

  7. Desktop version: navigate to the desktop version of DHIS2 for administration.

    Here is the GUI of the desktop version (which require much memory for loading), not recommended for normal mobile. The example with DHIS2 Demo (from dhis2.org)

  1. After clicking on the "Namebased Data Entry", the next will guiding to the selections in the following steps:

    Step 1: Choose an Organisation Unit

    Step 2: Choose the Activity Type

    (the screen-shot with an example with "Current Activity Plan" option)

    There will be normally these two type of Activity:

    + "Current Activity Plan": the list of the beneficiaries registered, enrolled, not yet finish/complete a/many program and there is at least a program-stage open for data-entry.

    + "All Activity Plan": the list of all beneficiaries registered, enrolled, not yet finish/complete a/many program.

    Step 3: Choose a Beneficiary for entry

    (the screen-shot with an example with "Hybia Welde" option)

    Step 4: Choose a current and active program-stage for entering the data

    (the screen-shot with an example with "16-24 months after birth" option)

    You can also see the beneficiary's information (ID, gender, Date of Birth, and Blood Group) by clicking on the Details (on top of the list appeared)

    The details information of the chosen beneficiary:

  2. Beneficiary Registration: Registry a new beneficiary

    Step 1: Choose an OrganisationUnit

    Step 2: Fill in the Beneficiary Registration form

    There necessary information: Full Name, Gender, Date of Birth (and Blood Group).

    Click on "SAVE" to register a new beneficiary.

    A message "Successfully Saved" will appear when the beneficiary is created/registered successfully.

  3. Beneficiary Enrollment: Enroll a beneficiary to one or many programs

    Before enrolling a beneficiary to a program, the search function for a beneficiary is provided:

    If the beneficiary is found, the result will be listed. The simply click on the beneficiary name for navigating to the programs in which the beneficiary enrolled:

    The below screen-shot example describes the beneficiary named "Nguyen Van A":

    - Has not enrolled any programs before

    - There is one program: "Child Health Program" available for enrollment

    The list of the available programs for enrollment will be listed. Just click on the program for enrollment by specifying the date of enrollment and the date of incident. See the example:

    After clicking on the "ENROLL" button, if successful, the program enrolled will be listed under "Enrolled Programs for" + <Name of the beneficiary>, see the example:

  4. Messages: Manage the messages and discussions from the server. Message reply is available.

    The number showed is the unread messages. Click on that to view the list of the messages (the unread messages are in bold and dark blue color):

    Then you can pick up the message/topic for the discussions by leaving the reply message, see this example:

  5. Reports: The output reports from the server

    (will be updated)

  6. Settings: User-information (e.g.: First-name, Surname, Phone number, E-mail) and the Interface language.

    Here is the form for setting the user account/access and the interface language. Click on "SAVE" for completing the settings, see the example below:

  7. Feedback: the extra function for creating a new message to send to the server. The new created feedback from this will be listed under "Messages"

    After clicking on the "Feedback", there will be a form for editing/sending out a new message/discussion. See the example below:

    After sending out the new feedback, the message (feedback) will be listed under "Messages" for further following up.

  8. Logout: to log out the application

  9. Desktop version: navigate to the desktop version of DHIS2 for administration.

    Here is the GUI of the desktop version (which require much memory for loading), not recommended for normal mobile. The example with DHIS2 Demo (from dhis2.org)

22.3. J2ME GPRS/3G Client

The DHIS2 GPRS/3G mobile module provides a mechanism for remote clients using mobile phones to enter data directly into the DHIS2 system. There are two functions of the client, namely:

The solution relies on the mobile phone having a data connection available (i.e. GPRS, Edge, 3G), over which it communicates with a DHIS2 instance which must be publicly available on the internet, as any other web server. The client application on the phone downloads the data entry forms to the phone from the server, and the forms can therefore be updated without installing a new application. This is also a crucial feature for community reporting, which relies on regularly downloading activity plans from the server.

  • Facility reporting, for data entry and reporting of regular DHIS2 aggregate data,

  • Activity reporting, for supporting individual activity reporting with the Community module.

22.3.1. Data connection availability

Data connection availability can be a problem in many of the contexts where DHIS2 mobile reporting would otherwise be a good solution for getting data directly into DHIS2. If that is the case for you, you might want to consider trying the SMS based solution described in a separate document. Keep in mind that even though a data connection is currently required for communication between the server and the mobile phone, it is only required when initializing or updating the mobile application and when sending reports to the server. The phone stores all entered data locally, so it can work fine with only temporary access to a data connection on a regular basis.

22.3.2. J2ME GPRS 3G facility reporting client

The server side component of the web based solution is included in the general build of DHIS2.

In order to configure the DHIS2 web-based mobile reporting, you should follow the following steps.

  • Set the "Available for Mobile Reporting" flag for the data sets you want reported: Under Maintenance->DataSet->Edit mark the “Available for Mobile Reporting” check box and save.

  • Create a user role for the mobile user. Select Maintenance->Users->User Role->Add new. Add a user role name and description. Add the desired data sets for the role. The mobile user role will need to have at least privileges for DHIS2 Web API. Save the user role by clicking "Save".

  • Create a user which will be used by the client to login from Maintenance->Users->User ->Add new. Fill in all of the required details, keeping in mind that the password must be at least 8 digits long, contain one capital letter,and one digit. Assign the desired user role to the user which was created in the previous step.

    [Important]Important

    Assign the user to exactly one organisation unit. Each mobile reporting client will need their own user name and password.

22.3.3. Detailed configuration of data sets and reporting forms

Though the previous steps is all that should be needed for testing the solution more detail configuration of the datasets may be required and are described in the following sections.

22.3.3.1. The mapping of data sets to form layout on the phone

By default, a data set is mapped to a single form on the phone. If the data set is divided into sections, each section is displayed as a separate page on the phone. If a data element has more than one category option combo it will be displayed as a heading with the category combination options following.

Table 22.1. 

Form design element DHIS2 Metadata Metadata element
Form titleData setShort Name if it exists, otherwise Name
Page tileSectionSection name (or form name if no sections)
QuestionData element Alternative name if it exists, otherwise Name
Question name if combosCategory option comboname

22.3.3.2. Sorting of forms

By default, data elements will be sorted according to the global sorting assigned in DHIS2. If sections are used, their section specific sorting order will be used. In some cases, when sections are not used, a data element might be used in multiple data sets, and conflict in the way it should be sorted in individual data sets. A work around for this situation is to wrap the whole dataset in one section (note that this will only work if the data elements have the same category option combo)

22.3.3.3. Versioning of data sets

To make it possible to compare and update the data sets on the mobile phone with the version on the server, data sets are automatically versioned when you edit the data set structure. Some changes which occur on the DHIS2 server, will cause the mobile client to update its forms with a new version.

Changes that currently trigger a new data set version

  • Create DataSet

  • Edit DataSet

  • Create/edit/delete Section in DataSet

  • Sort Section Order

  • Update DataElement (affect many related DataSets)

  • Delete DataElement (affect many related DataSets)

  • Edit DataElement Category

  • Edit DataElement Category Combo

22.3.3.4. Language support

Multi-language support is available.

DataSet and DataElement are translated through web-based function. Default language on server is used on mobile in cases requested language from mobile is not available.

22.3.4. Mobile application setup

22.3.4.1. Installation and initialization

22.3.4.1.1. Installation

Download the jar packages from the DHIS2 homepage: www.dhis2.org/downloads

22.3.4.1.2. Initialization

Initialization should be performed before the phones are delivered end-users. Given the large variation in possible phone configurations, it is impossible to describe the exact steps which are required in order to enable the client on the phone. However, for most phones, simply copying the DHIS2 Web Mobile client "JAR" file to the phone with a USB cable or via Bluetooth is sufficient. Of course, GPRS/3G connectivity must be enabled. Contact your mobile service provider for exact details on the configuration of the phones and networks.

Once the client has been installed on the phone, an initialization process must occur by providing a user name, password and server URL.

  1. Logging into the server for the first time.

    The first time the client logins to the server, or if the client is reinitialized, the username, password and server URL must be entered.

    If the client is unable to login, there could be several possible error messages which you see.

    • Connection Not Found: The specified server URL is not correct. Check the server address, ensure that the server is actually reachable, and try again.

    • Invalid User Name Or Password: the username or password is incorrect

    • Application not authorized to access restricted APIs : The server can be contacted, but the user does not have the necessary permissions to access the mobile reporting module

  2. Setting the PIN number: After the initial login process, a PIN number can be entered by the user. This will make the login process much easier, as the user only has to remember the four digit pin number, as opposed to typing in the user name and password each time. The PIN number can be preset if the phone is initialized prior to delivery, or it can be set by the users themselves if they have been provided with usernames and passwords.

    After entering the PIN, press (Menu)->Next.

  3. Download all forms: After the PIN has been specified, all forms will be downloaded from the server and stored locally on the phone..

    If the user has been configured to report on aggregate datasets, a list of appropriate datasets will be displayed. If the user is responsible for community based reporting, the list of assigned activities is displayed.

    Notes: If the Health Worker is responsible for both Facility Reporting and Community Reporting, DHIS2 server will send all forms of both Facility Reporting and Community Reporting to mobile and on mobile, there will be a screen to choose whether displaying Facility Reporting or Community Reporting.

    Errors:

22.3.4.2. Logging in (for regular use)

After starting the application, the PIN form is displayed.

  • PIN: Enter the four digit number PIN.

  • Reinitialize Command: this function will clear all data on mobile and we start from the login screen with username and password.

  • Errors: Invalid PIN: If the user has entered an invalid PIN, they will need to enter the correct PIN, or reinitialize the application with the correct username and password.

22.3.4.3. Facility Reporting Module

22.3.4.3.1. Entering data

After selecting an aggregate dataset from the "Select report form" window, the user will need to select an appropriate time period. A list of available time periods is automatically generated.

  1. After the user has entered their PIN, they can select from a list of available datasets. Select the appropriate dataset and press "Next".

  2. Choosing periods: A list of available periods will be automatically displayed to the user. They can select the appropriate period from the list.

  3. Fill in values: After choosing the period, the form can be displayed in two modes, depending on the

    • Form with sections

      Each form section is displayed in a single screen with the name of the section in the title window.

      To navigate from screen to screen, push "Next".

    • Forms without section (Datasets without sections)

      All fields are displayed on one screen with the title that is the name of DataSet

    The user simply fills in each data element with the appropriate value.

  4. Save and Complete:

    After finishing data entry, the user can choose to save the data locally on the phone or to upload the data directly to the DHIS2 server.

    If the user saves the data form, they can edit the form at a later point in time if they need to. When selecting a period once again, the period will be marked as "Saved' as seen in the next screen shot.

    If the user selects "Complete", and the data entry form is not complete, the user will be asked if they are certain they wish to submit the form as incomplete. Once the form has been submitted, a message should be displayed informing the user that the transmission was successful.

22.3.4.3.2. Notes
  1. Period list:

    Periods marked with an asterisk (*) is the period that is completed or saved, depending on the status of the data entry.

    All periods that are not in period list are considered old and will be deleted automatically.

  2. Storing values duration

    The number of saved forms on mobile are limited only by the effective amount of storage of the mobile device.

    Forms are saved for limited period only, depending on the frequency of collection of the particular dataset.

    • Daily Forms: 2 months (current and previous month)

    • Weekly Forms: 4 weeks (current and 3 previous week)

    • Monthly Forms: 2 months (current and previous month)

    • Quarterly Forms: 2 quarters (current and previous quarter)

    • Yearly Forms: 2 years (current and previous year)

  3. Completed forms - Uneditable forms

    If the form has been completed, the user can view the form on their phone, but they cannot make any subsequent edits to the form. Each field is greyed out and inactive for editing.

  4. Re-Edit completed forms

    If the user wishes to edit data which has already been submitted to the server, they can do so by pressing the "Edit" button. They are allowed to do this assuming that the dataset has not been locked for the period in question. If they attempt to upload the data, the user will be informed that the dataset has been locked, and it is not possible to upload the data.

  5. Update Forms:

    This function is used to synchronize the forms on mobile and on server. The process is automatically triggered after entering PIN number.

    Note: Checking and downloading updated forms process run in background. After finished, prompt is displayed to ask user whether refresh form list or stay where they are.

  6. Multi-Language Support:

    This function help user to choose language of mobile's GUI (graphical user interface) and content's language (Forms).

    The forms must be translated on server, otherwise, default language is used.

    Default language of first login is English. Change language in Setting menu will affect both interface and content.

    Multi-Language Interface: In Setting menu, there are list of supported language (downloaded from server). Language of GUI is only changed after restart application.

    Multi-Language Content (forms): Form's language is change after click "Save". In case there are many forms, it take several minutes to save setting.

22.3.4.3.3. Troubleshooting
  • Data has been entered on the phone but does not appear on the server

    This usually occurs when users enter data on the phone, but cannot send it to the server. This may be because of the configuration of the phone, lack of credit on the phone, or lack of coverage. Usually an error message is displayed as shown below.

    Users should be informed that if they see this error, then it means that their data has not been transmitted.

22.4. SMS Command

SMS command feature helps DHIS2 system receiving SMS from users, patients, or even anonymous. A SMS command is an object containing the configurations for each SMS form: reporting data from phones or j2me apps, alerting users, registering patient or user, etc.

22.4.1. Set up SMS command

This is where you can create a new SMS command

Usually each SMS command has it own property, then the setting up process may be different from each other. Currently, we have 4 types of SMS command:

With KEY_VALUE_PARSER and J2ME_PARSER, the SMS command will have dataset because those are used for reporting data

With ALERT_PARSER and UNREGISTERED_PARSER, the SMS command will have user group because those are used for sending message such as SMS, DHIS2 conversation, email.

There are certain parameters which are common to all SMS Command types. These parameters have default values configured in the system, if user does provide any value to these parameters then those default ones will be used. Here is the list of those parameters

Table 22.2. Common Parameters

ParameterTypeDescription
Code and value SeparatorStringTo provide custom code value separator. Default is "="
Reply message if no codes are sent (only the command)StringTo provide message if no code is found in SMS text input. Default is "Parameter missing"
Wrong format messageStringTo provide message if command is not formatted correctly. Command should be fomatted as per code value separator. This message will also be sent back if any mandatory parameter is missing.
No user messageStringTo provide message if sending phone number is not registered in DHIS 2.
User belong to more than one OrgUnit messageStringCertain SMS command types require user ( retrived from sending phone number ) to be associated with only one organization unit. This message can be configured to be sent back in case that requirement is not fullfilled.
Success MessageStringTo provide message that will be sent upon successful completion of the process.

22.4.2. SMS Command Type

The SMS command is basically defined by its parser type. In other word, each SMS command has one unique parser to parse the plain text SMS, then the result will be used for the purpose of that SMS command.

22.4.2.1. SMS Command for Reporting Data

In order to report data for example data set (aggregation), we use SMS commands which have KEY_VALUE_PARSER (for phone's plain text), or J2ME_PARSER (for j2me apps)

If the command has name "report", and a list of data element with code like above. The format should be: [command's name] [code][value] [code][value] [code][value]....,the [value] of course might be changed depends on real data, so you have to preapre a SMS text like this example: report vo2 vn5 a2 b6 z3 x1

In case the command has a separator for instance ".", the SMS text should be:

report vo.2.vn.5.a.2.b.6.z.3.x.1

or report vo.2|vn.5|a.2|b.6|z.3|x.1

Moreover in SMS text input, orgUnit can be specified like this org orgUnitCode If no orgUnit is specified in SMS then user is retrieved first from the sending phoneNumber and then orgUnit from that user. As far as PeriodType is concerned it should be specified in this format "ddMM" for example 3108, but in case its not specified then PeriodType will be retrieved from DataSet attached to SMSCommand

With the J2ME_PARSER, you don't need to prepare those SMS text, because the J2ME will do this job

User can set the custom response message for "Wrong format message", "No User Message", "User belong to more than one OrgUnit message" and "Success message". If no custom message is being set, system will use the default message.

22.4.2.2. SMS Command for Alerting, Registering

In order to alert users or register patients, users, we use SMS commands which have ALERT_PARSER (for phone's plain text), or UNREGISTERED_PARSER (for j2me apps)

The format of those command will be: [command's name] [text], for example:

alert one emergency case in A town

Commands which has ALERT_PARSER will be received from users only

22.4.2.3. SMS Command for Event Registration

Event Registration can be used to register anonymous event into the system based on the data collected through SMS. This command type is associated with Programs of type WITHOUT_REGISTRATION. For example Birth events can be tracked using this parser.

The format of those command will be: [command's name] [code][separator][value], for example:

birth A=1,B=2,G=Male

Code/Value separator is configurable. Comma "," is by default taken as field separator. Commands which has EVENT_REGISTRATION_PARSER will be received from DHIS2 users only. Once command is successfully received then data received in SMS will be parsed and event will be registered in DHIS2.

22.5. SMS Service

SMS Service is a generic service used for sending/receiving SMS. Any other DHIS2 module can include this service and utilize it to send and receive SMS from users or workers in the field.

22.5.1. Setting up SMS service

There are few pre-requisites in order to make this service functional. There are two ways to complete these steps. One way is to configure gateway from the GUI in Mobile Configuration Module. The other way is to use SMS Web Api.

  • Configure SMS Gateway

22.5.1.1. Configure SMS Gateway

There are five different types of Gateways supported by SMS Se