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

TB Aggregate Installation Guide¶

This document includes an installation guide for TB HMIS packages.

Idioma predeterminado del sistema: Inglés

Visión general¶

The package includes metadata json files containing the following components:

TB HMIS - Complete package
TB HMIS - Dashboard package
TB Notifications and Outcomes
TB Notifications and Outcomes (dashboard)
TB Laboratory
TB Laboratory (dashboard)
TB Household Contacts
TB Household Contacts (dashboard)
TB Data Quality (dashboard)

Instalación¶

La instalación del módulo consta de varios pasos:

Se recomienda leer primero cada sección de la guía de instalación antes de comenzar el proceso de instalación y configuración en DHIS2. Identifique las secciones aplicables según el tipo de su 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 de prueba/preparación de DHIS2 y solo luego 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 garantizar que el servidor en sí y la aplicación DHIS2 estén bien protegidos, asimismo se deben definir los derechos de acceso a los datos recopilados. Los detalles sobre cómo proteger un sistema DHIS2 están fuera del alcance de este documento, por lo que remitimos a la documentación de DHIS2.

Archivos de metadatos¶

Si bien no siempre es necesario, a menudo puede resultar ventajoso realizar ciertas modificaciones en el archivo de metadatos antes de importarlo a 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¶

En las primeras versiones de DHIS2, los UID de las dimensiones de datos predeterminadas se generaban automáticamente. Por lo tanto, si bien todas las instancias de DHIS2 tienen una opción de categoría predeterminada, una categoría de elemento de datos, una combinación de categoría y una combinación de opciones de categoría, los UID de estos valores predeterminados pueden ser diferentes. Las versiones posteriores de DHIS2 tienen UID codificados para la dimensión predeterminada y estos UID se utilizan en los paquetes de configuración.

Para evitar conflictos al importar los metadatos, es recomendable buscar y reemplazar en todo el archivo .json todas las apariciones de estos objetos predeterminados, reemplazando los UID del archivo .json con los UID de la instancia en la que se importará el archivo. La Tabla 1 muestra los UID que deben reemplazarse, así como los API endpoints para identificar los UID existentes

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`

Identifique los UID de las dimensiones predeterminadas en su instancia utilizando las solicitudes API enumeradas y reemplace los UID en el archivo json con los UID de la instancia.

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.

Tipos de indicadores¶

El tipo de indicador es otro tipo de objeto que puede crear conflictos de importación porque ciertos nombres se utilizan en diferentes bases de datos DHIS2 (por ejemplo, "Porcentaje"). Dado que los tipos de indicadores se definen por su factor (incluido 1 para indicadores "solo numerador"), no son ambiguos y se pueden reemplazar mediante una búsqueda y reemplazo de los UID. Este método ayuda a evitar posibles conflictos de importación y evita que el implementador cree tipos de indicadores duplicados. La siguiente tabla contiene los UID que podrían reemplazarse, así como los API endpoints para identificar los UID existentes:

Objeto	UID	API endpoint
Sólo numerador (número)	`CqNPn5KzksS`	`../api/indicatorTypes.json?filter=number:eq:true&filter=factor:eq:1`

Visualizaciones utilizando el UID de la unidad organizativa raíz¶

Visualizations, report tables, maps, validation rules that reference a specific organisation unit level or organisation unit group, contain placeholders eg. <OU_ROOT_UID> or <OU_LEVEL_FACILITY_UID>. Use the search function in the .json file editor to identify such placeholders and replace <OU_ROOT_UID> with the UID of the level 1 organisation unit in the target instance and <OU_LEVEL_FACILITY_UID> with the UID of the facility organisation unit level .

Importar metadatos¶

Utilice la aplicación DHIS2 Importar/Exportar para importar paquetes de metadatos. Es recomendable utilizar la función de proceso de prueba "dry run" para identificar problemas antes de intentar realizar una importación real de los metadatos. Si el "dry run" informa algún problema o conflicto, consulte la sección conflictos de importación más abajo. Si la importación "dry run"/"validar" funciona sin errores, intente importar los metadatos. Si la importación se realiza correctamente sin errores, puede proceder a configurar el módulo. En algunos casos, los conflictos o problemas de importación no se muestran durante el proceso de prueba "dry run", pero aparecen cuando se intenta la importación real. En este caso, el resumen de la importación enumerará los errores que deben resolverse.

Updating TB HMIS to version 2.0.0 from previous versions¶

An update of the TB HMIS package from previous versions is possible with following considerations:

All existing metadata and data have to be backed up prior to the update.
Existing TB HMIS indicators have to be accessible for reference (in a separate dev instance)
TB HMIS version 2 package uses reuses a number of metadata objects from the previous package version. While UIDs of the objects remain the same, the metadata objects may have changed: data elements have new names, validation rules have been adapted for the new data sets, indicator numerators and denominators are based on the metadata, visualizations use new indicators. When importing new package into an instance with a previous version of the TB HMIS package, the existing metadata objects will be overwritten.
TB HMIS version 2.0.0 package contains additional age and sex disaggregations. The data element tr0lVojK425 TB - New episodes of TB by age and sex has been assigned a new Category Combo that contains these additional category option combinations. The data element was reused from the previous version where it had a name TB - New and relapse TB cases by age and sex. After importing the new package into an instance with the previous version of TB HMIS, please check the old data sets and use the category option override function and reassign the legacy category combo to this data element.
When planning to use the legacy data and combine it with the new data to preserve the consistency of notification and outcomes data overtime, it is important to combine legacy data elements and new data elements within the new indicators where possible. Please refer to this mapping guide when aligning old and new data.

Tracker-to-aggregate data transfer¶

If you are implementing tracker to aggregate data transfer between TB tracker and TB HMIS packages, please consider that the configuration of such transfer has to be reconfigured based on new guidelines, data element definitions, data element codes, etc.

Gestión de conflictos de importación¶

NOTA

Si está importando el paquete a 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, vaya a la sección “Configuración”.

Pueden ocurrir varios conflictos diferentes, aunque el más común es que haya objetos de metadatos en el paquete de configuración con un nombre, nombre corto y/o código que ya existe en la base de datos de destino. Hay un par de soluciones alternativas a estos problemas, con diferentes ventajas y desventajas. Cuál sea la más adecuada dependerá, por ejemplo, del tipo de objeto para el que se produce un conflicto.

Alternativa 1¶

Cambiar el nombre del 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 como está, lo que puede ser una ventaja, por ejemplo, cuando se publican actualizaciones del paquete. Con frecuencia también se hace referencia a los objetos del paquete original en la documentación y los materiales de formación.

Alternativa 2¶

Cambiar el nombre del objeto para el que existe un conflicto en el archivo .json. La ventaja de este enfoque es que los metadatos DHIS2 existentes se dejan como están. Este puede ser un factor cuando existe material de formación o documentación como SOPs 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, tanto para la alternativa 1 como para la 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¶

Un tercer enfoque, más complicado, es modificar el archivo .json para reutilizar los metadatos existentes. Por ejemplo, en los casos en los que ya existe un set de opciones para un determinado concepto (por ejemplo, "sexo"), ese set de opciones podría eliminarse del archivo .json y todas las referencias a su UID podrían reemplazarse con el set de opciones correspondiente que ya se esté en la base de datos. La gran ventaja de esto (que no se limita a los casos en los que existe un conflicto de importación directo) es evitar la creación de metadatos duplicados en la base de datos. Hay algunas consideraciones clave que se deben tener en cuenta al realizar este tipo de modificación:

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 relacionadas con desagregaciones.
las futuras actualizaciones del paquete de configuración serán complicadas.

Configuración¶

Una vez que todos los metadatos se hayan importado correctamente, hay algunos pasos que deben seguirse antes de que el módulo sea funcional.

Primero, tendrá que usar la funcionalidad Compartir de DHIS2 para configurar qué usuarios (grupos de usuarios) deben ver los metadatos y los datos asociados con el programa, así como quién puede registrar/introducir datos en el programa. De forma predeterminada, el uso compartido se ha configurado para lo siguiente:

Tableros
Visualizations, maps, report tables
Sets de datos
Opciones de categoría

Consulte la documentación DHIS2 para obtener más información sobre compartir.

Los paquetes incluyen tres grupos de usuarios principales:

TB access (view metadata/view data)
TB admin (view and edit metadata/no access to data)
TB data capture - (view metadata/capture and view data)

For TB Stock package the groups are:

TB access (view metadata/view data)
TB admin (view and edit metadata/no access to data)
TB stock data capture - (view metadata/capture and view data)

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.

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 de tracker, buscar entidades de tracker en unidades organizativas y acceder a la captura de 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 }¶

Los sets de datos deben asignarse a unidades organizativas dentro de la jerarquía existente para que sean accesibles a través de la aplicación capturar.

Indicator mapping (dashboard package)¶

When implementing the dashboard package only, the indicator numerators and denominators have to be configured using the metadata objects in the existing instance. Configuration information is available in the documentation and the description of numerators and denominators in the metadata file.

Metadatos duplicados¶

NOTE

This section only applies if you are importing into a DHIS2 database where other metadata is already present. If you are working in a new DHIS2 instance, please skip this section and go to Adapting the tracker program. If you are using any third party applications that rely on the current metadata, please take into account that this update could "break" their functionality.

Incluso cuando los metadatos se han importado exitosamente sin ningún conflicto de importación, puede haber duplicados en los metadatos: elementos de datos, atributos de entidad tracker o set de opciones que ya existen. Como se señaló en la sección anterior sobre resolución de conflictos, una cuestión importante a tener en cuenta es que las decisiones sobre la realización de cambios en los metadatos en DHIS2 también deben tener en cuenta otros documentos y recursos que están asociados de diferentes maneras tanto con los metadatos existentes, como con los metadatos que se han importado a través del paquete de configuración. Por lo tanto, resolver duplicados no es sólo una cuestión de "limpiar la base de datos", sino también de asegurarse de que esto se haga sin, por ejemplo, romper la posible integración con otros sistemas, la posibilidad de utilizar material de capacitación, romper los SOP, etc. Esto dependerá en gran medida del contexto.

Una cosa importante a tener en cuenta es que DHIS2 tiene herramientas que pueden ocultar algunas de las complejidades de posibles duplicaciones en los metadatos. Por ejemplo, cuando existen set de opciones duplicados, se pueden ocultar para grupos de usuarios mediante compartir.

Adaptar el programa¶

Una vez que se haya importado el programa, es posible que desee realizar ciertas modificaciones en él. Algunos ejemplos de adaptaciones locales que podrían realizarse son:

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.
Modificación de indicadores basados en definiciones de casos locales

Sin embargo, se recomienda fuertemente tener mucho cuidado si decide cambiar o eliminar cualquiera de los formularios/metadatos incluidos. Existe el peligro de que las modificaciones puedan alterar la funcionalidad, por ejemplo las reglas y los indicadores de programa.

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.