For the complete DHIS2 documentation index, see llms.txt.

Integrated Vector Management - Discriminating Concentration Bioassay Installation Guide¶

This document includes an installation guide for the Integrated Vector Management (IVM) Discriminating Concentration Bioassay package.

System default language: English

order is always case-sensitive¶

The metadata reference and metadata json files provide technical details on package version and content.

The metadata package consists of the following module:

ENTO - Discriminating concentration bioassay (event program)

The package does not include dashboards, visualizations, indicators or program indicators.

安装¶

模块的安装包括以下几个步骤：

It is recommended to first read through each section of the installation guide before starting the installation and configuration process in DHIS2. Identify applicable sections depending on the type of your import:

import into a blank DHIS2 instance
import into a DHIS2 instance with existing metadata.

The steps outlined in this document should be tested in a test/staging DHIS2 instance and only then applied to a production environment.

要求¶

In order to install the module, an administrator user account on DHIS2 is required.

Great care should be taken to ensure that the server itself and the DHIS2 application are well secured, access rights to collected data should be defined. Details on securing a DHIS2 system is outside the scope of this document, and we refer to the DHIS2 documentation.

Metadata files¶

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

准备元数据文件¶

It is required to apply some changes to the metadata file before it can be imported. The scope of work may vary from package to package.

默认数据维度¶

In early versions of DHIS2, the UIDs of the default data dimensions were auto-generated. Thus, while all DHIS2 instances have a default category option, data element category, category combination and category option combination, the UIDs of these defaults can be different. Later versions of DHIS2 have hardcoded UIDs for the default dimension, and these UIDs are used in the configuration packages.

To avoid conflicts when importing the metadata, it is advisable to search and replace the entire .json file for all occurrences of these default objects, replacing UIDs of the .json file with the UIDs from the instance in which the file will be imported. Table 1 shows the UIDs which should be replaced, as well as the API endpoints to identify the existing UIDs

UID \	串	API endpoint
The status code will be `204 No Content` if the data value was successfully saved or updated, or `409 Conflict` if there was a validation error (e.g. more than one `SHORT_NAME` for the same `locale`).	`GLevLNI9wkl`	`../api/categories.json?filter=name:eq:default`
Send PUT request to `api/dataElements/{dataElementUID}` with full object payload as below:	`xYerKDKCefk`	`../api/categoryOptions.json?filter=name:eq:default`
不	`bjDvmb4bfuf`	`../api/categoryCombos.json?filter=name:eq:default`
Category option combination	`HllvX50cXC0`	`../api/categoryOptionCombos.json?filter=name:eq:default`

Identify the UIDs of the default dimensions in your instance using the listed API requests and replace the UIDs in the json file with the UIDs from the instance.

NOTE

Note that this search and replace operation must be done with a plain text editor, not a word processor like Microsoft Word.

Indicator types and visualizations¶

The package does not contain indicators, indicator types, visualizations or maps. No replacement of indicator type UIDs or of the root organisation unit placeholder <OU_ROOT_UID> is therefore required.

导入元数据¶

Use Import/Export DHIS2 app to import metadata packages. It is advisable to use the "dry run" feature to identify issues before attempting to do an actual import of 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 configuring the module. In some cases, import conflicts or issues are not shown during the "dry run", but appear when the actual import is attempted. In this case, the import summary will list any errors that need to be resolved.

处理导入冲突¶

NOTE

If you are importing the package into a new DHIS2 instance, you will not experience import conflicts, as there is no metadata in the target database. After import the metadata, proceed to the “Configuration” section.

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, shortname and/or code that already exist 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.

In instances where other modules of the DHIS2 entomology and vector control toolkit are already installed, conflicts are most likely on objects with the "ENTO - " prefix that exist in several modules, such as the vector species option set and the reporting institution category. Check these objects first and decide whether to keep them separate or to re-use the existing ones, as described in the alternatives below.

备选方案1¶

Rename the existing object in your DHIS2 database for which there is a conflict. The advantage of this approach is that there is no need to modify the .json file, as changes are instead done through the 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 updates to the package are released. The original package objects are also often referenced in training materials and documentation.

备选方案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.

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.

备选3¶

A third and more complicated approach is to modify the .json file to re-use existing metadata. For example, in cases where an option set already exists for a certain concept (e.g. the vector species), that option set could be removed from the .json file and all references to its UID replaced with the corresponding option set 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. There are some key considerations to make when performing this type of modification:

它需要有关DHIS2详细元数据结构的专业知识
the approach does not work for all types of objects. In particular, certain types of objects have dependencies which are complicated to solve in this way, for example related to disaggregations.
the option codes used in the program rules and option groups of this package must exist in the re-used option set, otherwise the related calculations and filters will not work
将来对配置包的更新将很复杂。

组态¶

Once all metadata has been successfully imported, there are a few steps that need to be taken before the module is functional.

First, you will have to use the Sharing functionality of DHIS2 to configure which users (user groups) should see the metadata and data associated with the program as well as who can register/enter data into the program. By default, sharing has been configured for the following:

IndicatorGroup
组织单位
Category options of the ENTO - Reporting institution category (ENTO - MoH, ENTO - Partner, ENTO - Publication)

Please refer to the DHIS2 documentation for more information on sharing.

Three core user groups are included in the package:

ENTO IVM - Access (view metadata/view data)
ENTO IVM - Admin (view and edit metadata/no access to data)
ENTO IVM - Data Capture (view metadata/capture and view data)

By default, the following is assigned to these user groups:

UID \	ENTO IVM - Access	ENTO IVM - Admin	ENTO IVM - Data Capture
IndicatorGroup	Metadata: can view Data: can view	Metadata: can edit and view Data: no access	Metadata: can view Data: can capture and view
组织单位	Metadata: can view Data: can view	Metadata: can edit and view Data: no access	Metadata: can view Data: can capture and view
表格对象类型和关键字	Metadata: can view Data: can view	Metadata: can edit and view Data: no access	Metadata: can view Data: can capture and view

The other metadata objects of the package (data elements, option sets, categories, program rules) can be viewed by all users and edited by the ENTO IVM - Admin group.

The users are assigned to the appropriate user group based on their role within the system. Sharing for other objects in the package may be adjusted depending on the set-up. Refer to the DHIS2 Documentation on sharing for more information.

用户角色¶

Users will need user roles in order to engage with the various applications within DHIS2. The following minimum roles are recommended:

Tracker data analysis : Can see event analytics and access dashboards, event reports, event visualizer, data visualizer, pivot tables, reports and maps.
Tracker data capture : Can add data values, update tracked entities, search tracked entities across org units and access tracker capture

Refer to the DHIS2 Documentation for more information on configuring user roles.

Organisation unit assignment¶

The program must be assigned to organisation units within the existing hierarchy in order to be accessible via the Capture app. As described in the system design guide, the organisation unit of an event should preferably be the location where the tested mosquitoes were collected rather than the laboratory that performed the test, so the program should be assigned to the organisation units that correspond to the collection sites of the national resistance monitoring plan.

重复的元数据¶

NOTE

This section only applies if you are importing into a DHIS2 database in which there is already meta-data present. If you are working with a new DHIS2 instance, please skip this section and go to Adapting the program. If you are using any third party applications that rely on the current metadata, please take into account that this update could break them

Even when metadata has been successfully imported without any import conflicts, there can be duplicates in the metadata - data elements, option sets or category options that already exist. As was noted in the section above on resolving conflict, an important issue to keep in mind is that decisions on making changes to the metadata in DHIS2 also needs to take into account other documents and resources that are in different ways associated with both the existing metadata, and the metadata that has been imported through the configuration package. Resolving duplicates is thus not only a matter of "cleaning up the database", but also making sure that this is done without, for example, breaking potential integrating with other systems, the possibility to use training material, breaking SOPs etc. This will very much be context-dependent.

One important thing to keep in mind is that DHIS2 has tools that can hide some of the complexities of potential duplications in metadata. For example, where duplicate option sets exist, they can be hidden for groups of users through sharing.

Adapting the program¶

Once the program has been imported, you might want to make certain modifications to the program. Examples of local adaptations that could be made include:

Reducing the vector species list to the species present and tested in the country, trimming the Aedes and Anopheles option groups in step with the option set.
Reducing the insecticide and discriminating concentration list to the products tested nationally, trimming the five related option groups and reviewing the program rules that assign the insecticide class, the exposure duration and the endpoint observation time.
向表单添加其他变量。
根据国家惯例修改数据元素/选项名称。
向变量和/或数据输入表单添加翻译。

These adaptations are described in the Implementation Considerations & Local Adaptation section of the system design guide.

However, it is strongly recommended to take great caution if you decide to change or remove any of the included form/metadata. Most of the calculations, the section visibility and the validation of the form rely on program rules that reference specific data elements and option codes, and modifications could break this functionality. Options that are still referenced by stored event data should be retained rather than deleted.

Removing metadata¶

In order to keep your instance clean and avoid errors, it is recommended that you remove the unnecessary metadata from your instance. Removing unnecessary metadata requires advanced knowledge of DHIS2 and various dependencies.