Installation guide: dashboard configuration packages

Version 1.0, updated 2018-09-24

Introduction

This document is intended to guide administrators though the process of installing standard configuration packages for DHIS2 with predefined dashboards. Good understanding of DHIS2 is required. The procedure described here applies to:

The configuration packages for DHIS2 consists of a metadata file in JSON format which can be imported into a DHIS2 instance, as well as accompanying documentation. The packages provide pre-defined, standard content according to WHO recommendations. This document is concerned with dashboard packages that include configurations indicators and dashboards (chart, map and pivot table favourites). The intended use of the dashboard packages is to complement an existing data collection/reporting in DHIS2 with a set of best-practice dashboards for analysis.

Complete packages for aggregate reporting exists as well for several diseases/programme areas. In addition to indicators and dashboards, these include configurations of data collection (data sets, data elements, validation rules).

Description of dashboard configuration packages

The configuration packages consists of three main components:

The indicators and category option groups that are included should be regarded as "placeholder" that needs to be configured, i.e., mapped to existing data elements and data element category options. The steps are described in further detail in the Configuration section.

Similarly, the analytical outputs (pivot table, data visualizer and GIS favourites) that are included in the module will in many cases have to be updated according to the availability of data and existing data elements or indicators.

Installation

Installation of the module consists of two steps:

  1. Importing a metadata file into DHIS2.
  2. Configuring the imported metadata.
  3. Package-specific modifications.

This section deals with the first step of importing the metadata file into DHIS2, whilst the configuration procedure is discussed in the next section. It is recommended to first read through both sections before starting the installation and configuration process in DHIS2. In addition to the general steps described here, some of the configuration packages have annexes to the installation guide, describing particular issues. These are listed in the appropriate section here.

The procedure outlined in this document should be tested in a test/staging environment before either being repeated or transferred to a production instance of DHIS2.

Multiple configuration packages

Some configuration packages have overlapping metadata, for example indicators. This means that in some situations, changes to metadata in configuration packages that have been imported previously may be overwritten when importing a different package. This can be avoided by importing "new only" metadata rather than "new and updates", but note that with either approach manual modifications will be needed. At a minimum, you must ensure that metadata used by multiple programmes are shared with the appropriate user groups for both programmes. If there are plans to use several dashboard configuration packages, it is advisable to import all before starting the configuration to avoid configurations being overwritten.

Requirements

In order to install the configuration package, an administrator user account in DHIS2 is required, with authorities to add/edit (public) metadata objects, including (but not limited to):

The full list of objects included in the module (for which the administrator needs authorities to manage) can be found in the Metadata reference document for the particular configuration package.

In cases where modifications to the .json metadata file of the configuration package are necessary (see below), a text editor is needed - these modifications should not be done with a word processor such as Microsoft Word.

The configuration package can be installed in DHIS2 through the DHIS2 Health App, or manually through a .json file with DHIS2 metadata using the Import/Export app of DHIS2. The procedure described in the rest of this section applies to the process of manually importing metadata. Please refer to the manual of the WHO Health App for instructions for using that app. The Configuration section applies for both methods.

Preparing the metadata file

While not always necessary, it can in some cases be advantageous to make certain modifications to the metadata file before importing it into DHIS2.

Indicator types

Indicator type is one type of object that can create import conflict because certain names are used in different DHIS2 databases (.e.g "Percentage"). Since Indicator types are defined simply by their factor and whether or not they are simple numbers without denominator, they are unambiguous and can be replaced through a search and replace of the UIDs. This avoids potential import conflicts, and avoids creating duplicate indicator types. Table 2 shows the UIDs which could be replaced, as well as the API endpoints to identify the existing UIDs.

Object UID API endpoint
Numerator only (number) kHy61PbChXr ../api/indicatorTypes.json?filter=number:eq:true&filter=factor:eq:1
Rate (factor=1) k4RGC3sMTzO ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:1
Percentage hmSnCXmLYwt ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:100
Per 1000 zpa0vUC7IWd ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:1000
Per 10 000 FWTvArgP0jt ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:10000
Per 100 000 BY11PjGMCg2 ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:100000

Note 1: by replacing the UIDs as described and importing the .json file, the name (including any translations) of the indicator types in question will be updated to those included in the configuration packages.

Note 2: An alternative approach to re-using the existing indicator types is to import those included in the configuration package, and removing the existing ones that overlap. This would require all indicators that use these existing indicator types to be updated to the newly imported indicator types, before the indicator types can be deleted.

Importing metadata

The .json metadata file is imported through the Import/Export app of DHIS2. It is advisable to use the "dry run" feature (from 2.30 known as "Validate" import mode) to identify issues before attempting to do an actual import the metadata. If "dry run" reports any issues or conflicts, see the import conflicts section below.

If the "dry run"/"validate" import works without error, attempt to import the metadata. If the import succeeds without any errors, you can proceed to configure the module. In some cases, import conflicts or issues are not shown during the "dry run", but appears when the actual import is attempted. In this case, the import summary will list any errors that need to be resolved.

Handling import conflicts

There are a number of different conflicts that may occur, though the most common is that there are metadata objects in the configuration package with a name, short name and/or code that already exists in the target database. There are a couple of alternative solutions to these problems, with different advantages and disadvantages. Which one is more appropriate will depend, for example, on the type of object for which a conflict occurs.

Alternative 1

Rename the existing object for which there is a conflict. The advantage of this approach is that there is no need to modify the .json file, as changes is instead done through user interface of DHIS2. This is likely to be less error prone. It also means that the configuration package is left as is, which can be an advantage for example when training material and documentation based on the configuration package will be used.

Alternative 2

Rename the object for which there is a conflict in the .json file. The advantage of this approach is that the existing DHIS2 metadata is left as-is. This can be a factor when there is training material or documentation such as SOPs of data dictionaries linked to the object in question, and it does not involve any risk of confusing users by modifying the metadata they are familiar with. At the same time, modifying object of the .json file means that using the associated documentation and training material might become more complicated.

Note that for both alternative 1 and 2, the modification can be as simple as adding a small pre/post-fix to the name, to minimise the risk of confusion.

Alternative 3

A third and more complicated approach is to modify the .json file to re-use existing metadata. For example, in cases where an indicator already exists for a certain concept (e.g. "ANC 1 coverage"), that indicator could be removed from the .json file and all references to its UID replaced with the corresponding indicator already in the database. The big advantage of this (which is not limited to the cases where there is a direct import conflict) is to avoid creating duplicate metadata in the database. However, it is generally not recommended for several reasons:

Saving the package version

In order to document the specific version of the configuration package that has been imported, which can for example be important later when considering updates to the package, a package identifier should be saved in the database, using the dataStore API endpoint and for example Datastore Manager app or the curl command line utility.

The package identifier can be found in the .json metadata file itself, as the "package" property, or in the metadata reference under "Package info".

Package identifier in the metadata reference.
Package identifier in the metadata reference.

Using the Datastore Manager app

When installing the first package, a new namespace must be created. If a package has been installed previously, a new entry can be added to the existing one. Use packages as the namespace, and package code (e.g. TB, EPI, MAL, HIV etc) as the key.

To create a new namespace and key, click the "New" button and fill in the namespace and key in the pop-up.

Creating a new namespace, when installing the first package.
Creating a new namespace, when installing the first package.

If the packages namespace already exist, a new key can be added.

Adding a new key when the namespace exists.
Adding a new key when the namespace exists.

You can then edit the corresponding content for that key, either in the tree view or as javascript code. The format should be PROGRAMME-CODE: IDENTIFIER.

Adding the package identifier
Adding the package identifier

Using curl

Using curl, this can be done with a command like this, where USER, PASSWORD, SERVER should be replaced with a DHIS2 username, password and URL respectively, and PROGRAMME-CODE and IDENTIFIER should be replaced with the code for the health programme or area and the IDENTIFIER with the package identifier.

curl -X POST -u USER:PASSWORD -H "Content-Type: application/json" -v -d "{\"PROGRAMME-CODE\": \"IDENTIFIER\"}" "SERVER/api/dataStore/packages/PROGRAMME-CODE"

An example of this:

curl -X POST -u admin:district -H "Content-Type: application/json" -v -d "{\"MAL\": \"MAL-EL_DASHBOARD_V1.0_DHIS2.30_2018-09-20T09:47\"}" "https://play.dhis2.org/2.29/api/dataStore/packages/MAL"

Verification

To verify that this was successful, use a browser to open SERVER/api/dataStore/packages and make sure that the programme code is listed. Opening SERVER/api/dataStore/packages/CODE should show the package identifier.

Configuration

Once all metadata has been successfully imported, some configuration is required before the module is functional. The included indicators should be regarded as placeholders and must be configured once they have been imported, and similarly category option groups have to be configured if included in the configuration package. In addition, the GIS favourites might have to be modified to point to the appropriate organisation unit levels. The recommended procedure for these modifications are described here.

A Configuration checklist document is available to facilities the configuration process. This document can be printed or opened electronically and used to keep track of what metadata needs to be configured.

Configure indicators

The Manage indicators chapter of the DHIS2 manual provides general information about editing and deleting indicators.

For each indicator included in the configuration package:

Where the numerator or denominator is not available, leave the indicator as-is. It will show up as -1 in dashboards.

Completeness and timeliness indicators

Configuration packages might include indicators for reporting completeness or timeliness. While not supported in the user interface of the numerator and denominator configuration page, the number of "actual reports" and "expected reports" is available so that these indicators can be configured. First, find the UID for the data set in question, for example by clicking Show details in the Maintenance app. Then use the following formulas:

Value Formula Example formula
Actual reports #{DATASET_ID.ACTUAL_REPORTS} #{K3xmBegliQy.ACTUAL_REPORTS}
Actual reports on time #{DATASET_ID.ACTUAL_REPORTS_ON_TIME} #{K3xmBegliQy.ACTUAL_REPORTS_ON_TIME}
Expected reports #{DATASET_ID.EXPECTED_REPORTS} #{K3xmBegliQy.EXPECTED_REPORTS}

Note: You can alternatively update the report favourites in question to use the built-in reporting rate figures.

Configure category option groups

The configuration package may include category option groups and group sets that must be configured. These are most commonly for age and sex disaggregations. These group sets are used as a way to map the current disaggregation used for data collection in the DHIS2 database to the recommended disaggregations for analysis, similarly to how indicators map to data elements. Specifically, data element category options used for disaggregations on data elements should be mapped to the corresponding category option groups which are used on the dashboards for analysis. "Other age" and "Unknown sex" groups are included for use when the disaggregations used for data collection are not aligned.

For example if data is collected by "< 1 years", "1-4 years", "5-14 years", "15+ years" whilst the recommended disaggregation is "< 5 years", "5-14 years", "15-49 years", "50+ years", the "< 1 years" and "1-4 years" options could be added to the "< 5 years" group, "5-14 years" option to the "5-14 years" group, and "15+ years" could be added to "Other age" since it can not be mapped to the recommended "15-49 years" and "50+ years" category option groups.

Category option mapping
Category option mapping

The Configuration checklist includes an overview of the included category option groups and group sets. As a minimum, category options related to the data elements used mapped to indicators included in the package should be included. Note, however, that if all age/sex related options are mapped into the category option groups, the category option group set can be used as a data dimension more broadly.

There are some limitations to this approach:

  1. it assumes that data element categories are used for disaggregations. Otherwise, for example if separate data elements are used for the different age groups, this approach does not work. In those cases, it might however be possible to use data element group sets to achieve a similar result, but this would have to be done from scratch as such groups and group sets are not included in the module.
  2. it assumes that all the source data for the indicators use the same disaggregation. In some cases, data elements that are not disaggregated can be included as part of an indicator and still be usable, if the category options applied to those data elements are added to the "Other age" or "Other sex" category option group. However, this would depend on the specific indicator.

Note: after configuring the category option groups and group sets, analytics have to be run before data becomes visible in favourites using the category option group sets.

Configure favourites

Review organisation unit dimension

For the report favourites, in particular GIS, the organisation unit dimension must in some cases be reviewed and the appropriate level of disaggregations selected. The favourites by default use relative orgunits (e.g. sub-X2-units which will display organisation units two levels below the user), the configuration packages might includes some GIS favourites that should ideally always be displayed by district (or equivalent), and some that should ideally be displayed by facility. Instructions for this (where applicable) is included in the installation guide annex for the particular package.

It may not always be possible for performance reasons (depending on the number of health facilities or districts, the capacity of the server, network connectivity etc) to use the recommended geographical disaggregation. As part of the configuration, this needs to be tested and the favourites updated accordingly.

Remove empty favourites

If some or all of the underlying data for a favourite is missing, it might be useful to remove it from the dashboard. Note, however, that it can be useful to have an initial discussion of the dashboard with relevant stakeholder before removing the empty analytical outputs, as they highlight potential data gaps in the current reporting system.

Before the favourite can be deleted, it must be removed from the dashboard(s) in which it is included.

Verify outputs

Finally, open the dashboards and verify that all the favourites are now working. Indicators that have not been configured will all have the value -1.

Note: depending on the configuration of the DHIS2, the favourites on the dashboard might be cached in your web browser or on the server, which means that even if the indicators have been configured they might show the pre-configured value of -1. In this case, you can try clear the browser cache, and/or change the organisation unit of the dashboard, e.g. to a district, to make sure the outputs have not previously been displayed and cached.

Access and sharing

Optionally, you may want to use the sharing functionality of DHIS2 to configure which users (user groups) should see the metadata included in the module.

The configuration packages are by default not publicly viewable, but are shared with two user groups, one admin user groups and one access user group. Users added to the admin user group will have access to edit the included metadata, whilst users in access user group will only be able to see the metadata (and data).

Maintenance

No particular maintenance is required for the configuration packages, since they are made up of standard DHIS2 metadata objects. However, before upgrading to new versions of DHIS2, it is important to test all functionality of the system in general on a staging/test server before upgrading any production instances of the system.