Integrated Vector Management - Discriminating Concentration Bioassay Installation Guide¶
This document includes an installation guide for the Integrated Vector Management (IVM) Discriminating Concentration Bioassay package.
Idioma predeterminado del sistema: Inglés
Visión general¶
Los archivos de referencia de metadatos y los archivos json de metadatos proporcionan detalles técnicos sobre la versión y el contenido del paquete.
El paquete de metadatos está compuesto por el siguiente módulo:
- ENTO - Discriminating concentration bioassay (event program)
The package does not include dashboards, visualizations, indicators or program indicators.
Instalación¶
La instalación del módulo consta de varios pasos:
- Preparar el archivo de metadatos con los metadatos de DHIS2
- Importar el archivo de metadatos en DHIS2
- Configurar los metadatos importados
- Adaptar el programa después de la importación
Se recomienda leer primero cada sección de la guía de instalación antes de iniciar el proceso de instalación y configuración en DHIS2. Identifique las secciones aplicables según el tipo de importación:
- importar a una instancia DHIS2 en blanco
- importar a una instancia DHIS2 con metadatos existentes.
Los pasos descritos en este documento deben probarse en una instancia DHIS2 de prueba/staging y solo entonces aplicarse a un entorno de producción.
Requisitos¶
Para instalar el módulo, se requiere una cuenta de usuario administrador en DHIS2.
Se debe tener mucho cuidado para asegurar que el servidor en sí y la aplicación DHIS2 estén bien protegidos, y se deben definir los derechos de acceso a los datos recopilados. Los detalles sobre la seguridad de un sistema DHIS2 están fuera del alcance de este documento, y nos remitimos a la documentación de DHIS2.
Archivos de metadatos¶
Aunque no siempre es necesario, a menudo puede ser ventajoso realizar ciertas modificaciones al archivo de metadatos antes de importarlo en DHIS2.
Preparar el archivo de metadatos¶
Es necesario aplicar algunos cambios al archivo de metadatos antes de poder importarlo. El alcance del trabajo puede variar de un paquete a otro.
Dimensión de datos predeterminada¶
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
| Objeto | UID | API endpoint |
|---|---|---|
| Categoría | GLevLNI9wkl | ../api/categories.json?filter=name:eq:default |
| Opción de categoría | xYerKDKCefk | ../api/categoryOptions.json?filter=name:eq:default |
| Combinación de categoría | bjDvmb4bfuf | ../api/categoryCombos.json?filter=name:eq:default |
| Combinación de opciones de categoría | 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.
NOTA
Tenga en cuenta que esta operación de búsqueda y reemplazo debe realizarse con un editor de texto plano, no con un procesador de textos como 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.
Importar metadatos¶
Utilice la aplicación DHIS2 Importar/Exportar para importar paquetes de metadatos. Es recomendable utilizar la función de «ejecución en seco» para identificar problemas antes de intentar realizar una importación real de los metadatos. Si la «ejecución en seco» reporta algún problema o conflicto, consulte la sección conflictos de importación a continuación. Si la importación de «ejecución en seco»/«validación» se realiza sin errores, intente importar los metadatos. Si la importación se completa sin errores, puede proceder a configurar el módulo. En algunos casos, los conflictos o problemas de importación no se muestran durante la «ejecución en seco», sino que aparecen cuando se intenta la importación real. En este caso, el resumen de importación indicará los errores que deben resolverse.
Gestión de conflictos de importación¶
NOTA
Si está importando el paquete en una nueva instancia de DHIS2, no experimentará conflictos de importación, ya que no hay metadatos en la base de datos de destino. Después de importar los metadatos, proceda a la sección «Configuración».
Pueden ocurrir varios tipos de conflictos, aunque el más común es que existan objetos de metadatos en el paquete de configuración con un nombre, nombre corto y/o código que ya existen en la base de datos de destino. Existen varias soluciones alternativas a estos problemas, con diferentes ventajas y desventajas. La solución más apropiada dependerá, por ejemplo, del tipo de objeto para el cual ocurre el conflicto.
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.
Alternativa 1¶
Renombrar el objeto existente en su base de datos DHIS2 para el cual existe un conflicto. La ventaja de este enfoque es que no es necesario modificar el archivo .json, ya que los cambios se realizan a través de la interfaz de usuario de DHIS2. Es probable que esto sea menos propenso a errores. También significa que el paquete de configuración se deja tal cual, lo que puede ser una ventaja, por ejemplo, cuando se publican actualizaciones del paquete. Los objetos del paquete original también suelen estar referenciados en materiales de capacitación y documentación.
Alternativa 2¶
Renombrar el objeto para el cual existe un conflicto en el archivo .json. La ventaja de este enfoque es que los metadatos DHIS2 existentes se dejan tal cual. Esto puede ser un factor cuando existe material de capacitación o documentación, como los POE de diccionarios de datos vinculados al objeto en cuestión, y no implica ningún riesgo de confundir a los usuarios al modificar los metadatos con los que están familiarizados.
Tenga en cuenta que para las alternativas 1 y 2, la modificación puede ser tan simple como agregar un pequeño pre-/post-fijo al nombre, para minimizar el riesgo de confusión.
Alternativa 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:
- requiere conocimiento especializado de la estructura detallada de metadatos de DHIS2
- el enfoque no funciona para todos los tipos de objetos. En particular, ciertos tipos de objetos tienen dependencias que son complicadas de resolver de esta manera, por ejemplo en lo que respecta a las desagregaciones.
- 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
- las futuras actualizaciones del paquete de configuración serán complicadas.
Configuración¶
Una vez que todos los metadatos se han importado exitosamente, es necesario realizar algunos pasos antes de que el módulo sea funcional.
Compartir¶
En primer lugar, deberá utilizar la funcionalidad de Compartir de DHIS2 para configurar qué usuarios (grupos de usuarios) deben ver los metadatos y datos asociados al programa, así como quién puede registrar/ingresar datos en el programa. Por defecto, el compartir se ha configurado para lo siguiente:
- Programa
- Program stage
- Category options of the ENTO - Reporting institution category (ENTO - MoH, ENTO - Partner, ENTO - Publication)
Consulte la documentación DHIS2 para obtener más información sobre compartir.
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:
| Objeto | ENTO IVM - Access | ENTO IVM - Admin | ENTO IVM - Data Capture |
|---|---|---|---|
| Programa | Metadata: can view Data: can view | Metadata: can edit and view Data: no access | Metadata: can view Data: can capture and view |
| Program stage | Metadata: can view Data: can view | Metadata: can edit and view Data: no access | Metadata: can view Data: can capture and view |
| Opciones de categoría | 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.
Los usuarios se asignan al grupo de usuarios apropiado según su rol dentro del sistema. El compartir de otros objetos en el paquete puede ajustarse dependiendo de la configuración. Consulte la documentación de DHIS2 sobre compartir para más información.
Roles de usuario¶
Los usuarios necesitarán roles de usuario para poder interactuar con las diversas aplicaciones dentro de DHIS2. Se recomiendan los siguientes roles mínimos:
- Análisis de datos Tracker: Puede ver análisis de eventos y acceder a tableros, informes de eventos, visualizador de eventos, visualizador de datos, tablas dinámicas, informes y mapas.
- Captura de datos Tracker: Puede agregar valores de datos, actualizar entidades rastreadas, buscar entidades rastreadas en las unidades organizativas y acceder a la aplicación de captura Tracker.
Consulte la Documentación de DHIS2 para obtener más información sobre la configuración de roles de usuario.
Asignación de unidades organizativas{ #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.
Metadatos duplicados¶
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.
Es importante tener en cuenta que DHIS2 dispone de herramientas que pueden ocultar algunas de las complejidades de las duplicaciones potenciales en los metadatos. Por ejemplo, cuando existen conjuntos de opciones duplicados, estos pueden ocultarse para grupos de usuarios a través de Compartir.
Adaptar el programa¶
Una vez importado el programa, es posible que desee realizar ciertas modificaciones. Algunos ejemplos de adaptaciones locales que podrían realizarse incluyen:
- 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.
- Añadir variables adicionales al formulario.
- Adaptar los nombres de los elementos de datos/opciones según las convenciones nacionales.
- Añadir traducciones a las variables y/o al formulario de entrada de datos.
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.
Eliminar metadatos¶
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.