WHO Anti-Tuberculosis Drugs Resistance Survey (DRS) - Tracker Installation Guide¶

Package Version 1.0.1

Idioma predeterminado del sistema: Inglés

Available translations: French, Spanish, Portuguese

Visión general¶

Los archivos json de metadatos del paquete contienen un componente "paquete" que proporciona detalles técnicos sobre la versión y el contenido del paquete. Los archivos disponibles en la versión actual del paquete se enumeran a continuación.

DHIS2.35¶

"package": {
    "DHIS2Build": "35d663a",
    "DHIS2Version": "2.35.11",
    "code": "TBDR00",
    "description": "Anti-Tuberculosis Drug Resistance Survey (DRS)",
    "lastUpdated": "20220124T083253",
    "locale": "en",
    "name": "TB_DRS_TKR_1.0.1_DHIS2.35.11-en",
    "type": "TKR",
    "version": "1.0.1"
}

DHIS2.36¶

"package": {
    "DHIS2Build": "5d136cb",
    "DHIS2Version": "2.36.6",
    "code": "TBDR00",
    "description": "Anti-Tuberculosis Drug Resistance Survey (DRS)",
    "lastUpdated": "20220124T073407",
    "locale": "en",
    "name": "TB_DRS_TKR_1.0.1_DHIS2.36.6-en",
    "type": "TKR",
    "version": "1.0.1"
}

When importing this package into a new/blank instance, please refer to the DHIS2 installation guide.

Instalación¶

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

1. Preparar el archivo de metadatos.
2. Importar el archivo de metadatos en DHIS2.
3. Configuring the imported metadata.
4. Adaptar el programa después de ser importado

It is recommended to first read through each section before starting the installation and configuration process in DHIS2. Sections that are not applicable have been identified, depending on if you are importing into a new instance of DHIS2 or a DHIS2 instance with metadata already present. 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.

Requisitos¶

Para instalar el módulo, se requiere una cuenta de usuario administrador en DHIS2. El procedimiento descrito en este documento debe probarse en un entorno de prueba/preparación antes de realizarse en una instancia de producción de DHIS2.

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

Preparar el archivo de metadatos¶

NOTA: Si está instalando el paquete en una nueva instancia de DHIS2, puede omitir la sección "Preparación del archivo de metadatos" y pasar inmediatamente a la sección Importar un archivo de metadatos a DHIS2

Si bien no siempre es necesario, a menudo puede resultar ventajoso realizar ciertas modificaciones en el archivo de metadatos antes de importarlo a DHIS2.

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

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:

Tipo de entidad Tracked¶

Like indicator types, you may have already existing tracked entity types in your DHIS2 database. The references to the tracked entity type should be changed to reflect what is in your system so you do not create duplicates. The table below contains the UIDs which could be replaced, as well as the API endpoints to identify the existing UIDs:

Sort order for options¶

Check whether the sort order sortOrder of options in your system matches the sort order of options included in the metadata package. This only applies when the json file and the target instance contain options and option sets with the same UID.

After import, make sure that the sort order for options within an option set starts at 1. There should be no gaps (eg. 1,2,3,5,6) in the sort order values.

Sort order can be adjusted in the Maintenance app.

1. Go to the applicable Option Set
2. Open the "Options" section
3. Use "SORT BY NAME", "SORT BY CODE/VALUE" or "SORT MANUALLY" alternatives.

Dashboards and visualizations¶

The dashboards and visualizations in each dashboard cannot be hidden/unhidden by constants. Therefore the unapplicable dashboards/visualizations have to be manually removed during package installation based on the selection of tests/drugs.

Visualizations in the metadata file may contain a placeholder . This placeholder in the metadata.json file has to be replaced by the Root Organisation unit UID from the target instance before the package can be imported.

Some visualizations and maps may contain references to organisation unit levels. Maps that consist of several map views may contain vaious Organisation unit level references based on the configuration of the map layer. The table below provides an overview of such items included in the package. Adjust the organisation unit level references in the metadata json file to match the organisation unit structure in the target instance before importing the metadata file.

Ejemplo:

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.

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.

Additional configuration¶

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

Compartir¶

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:

• Tipo de entidad Tracked
• Programa
• Etapas del programa
• Tableros

There are four user groups that come with the package:

• DRS - admin
• DRS - access
• DRS - data capture

By default the following is assigned to these user groups

You will want to assign your users to the appropriate user group based on their role within the system. You may want to enable sharing for other objects in the package depending on your set up. Refer to the DHIS2 Documentation for more information on configuring sharing.

User roles¶

Los usuarios necesitarán roles de usuario para poder interactuar con las diversas aplicaciones dentro de DHIS2. Se recomiendan los siguientes roles mínimos:

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

Organisation units¶

The program and the data sets must be assigned to organisation units within existing hierarchy in order to be accessible via tracker capture/capture apps.

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

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.

Constants¶

WHO Anti-Tuberculosis Drugs Resistance Survey (DRS) Tracker package includes a set of tests and a list of drugs that can be modified by the implementing country according to national context (e.g. which drugs and tests are used/available in country). The use of constants and corresponding program rules enables a system admin in an implementing country to easily ‘turn on’ or ‘turn off’ types of drugs and tests depending on availability. When the complete package is installed into a DHIS2 instance, all data elements for all tests and drugs included in this package are included in the system. All constant values are initially set to 1 (enabling the related data elements for data entry) and can be set to 0 by an implementer or system admin according to country context if not needed (disabling the related data elements for data entry). If a test or drug later becomes available, the admin can simply re-enable the data elements by changing the constant from a value of 0 to a value of 1.

Cluster Sampling / Exhaustive Sampling of all Health Facilities¶

Configure whether the country is using Cluster Sampling or Exhaustive Sampling of all Health Facilities

Number of DRS Samples sent to NRL¶

Configure the number of samples are sent to NRL processing

Initial Screening Tests¶

Configure which initial screening tests are used for bacteriological confirmation of TB: Sputum Smear Microscopy, Xpert MTB/RIF or both.

SRL Sample Processing¶

Configure whether the country has an option of sending samples to SRL (supranational lab).

Tests at NRL¶

List of Available Drugs¶

Please note, that the constants help to hide certain sections and data element from the data entry without the need to delete them from the system/metadata.json file. However, the elements are still assigned to the program and will be included when exporting all data into eg. csv files.

Configuring tracker capture interface, widgets and top bar¶

You must configure tracker capture dashboard after the package has been installed. This configuration includes data entry forms, widgets and top bar.

Data entry forms¶

• After registering the first (test) case, access the Settings menu in the tracker capture form and select Show/Hide Widgets
• Switch from Timeline Data Entry to Tabular Data Entry
• Make sure that Enrollment, Feedback and Profile widgets are selected. Click Close.
• Adjust the widgets on the screen.

Top Bar¶

• Access the Settings menu and select Top bar settings
• Select Activate top bar
• Select required information fields and assign their Sort order

• Click Save
• Return to the Settings menu. Click Saved dashboard layout as default. Lock layout for all users.

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 los indicadores del programa 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.