TB Household Investigation Installation Guide¶

Paquete Versión 1.0.0

Idioma predeterminado del sistema: Inglés

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. Configurar los metadatos importados.
4. Adaptar el programa después de ser importado

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:

1. Importar a una instancia DHIS2 en blanco
2. Import into a DHIS2 instance with existing metadata (No other versions of TB Case Surveillance tracker imported previously).
3. Update existing/older version of the TB Case Surveillance tracker.

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¶

In order to install the module, a DHIS2 administrator user account 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 are outside the scope of this document, and we refer to the DHIS2 documentation.

Archivos de metadatos¶

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.

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

Preparar el archivo de metadatos¶

It is recommended to import the DHIS2 Common HIS metadata library into the target instance before using and adapting any DHIS2 metadata packages. Common HIS Metadata package is available for download in the supported versions of DHIS2 at Metadata Package Downloads

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

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.

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:

Option codes¶

According to the DHIS2 naming conventions, the metadata codes use capital letters, underscores and no spaces. Some exceptions that may occur are specified in the corresponding package documentation. All codes included in the metadata objects in the current package match the naming conventions. It may occur that the codes of existing metadata objects used in the target database use lower case characters. In this case, it is important to update those values directly in the database.

Important

During the import, the existing option codes will be overwritten with the updated upper case codes. In order to update the data values for existing data in the database, it is necessary to update the values stored in the database using database commands. Make sure to map existing old option codes and new option codes before replacing the values. Use staging instance first, before making adjustments on the production server.

For data element values, use:

```SQL
UPDATE programstageinstance
SET eventdatavalues = jsonb_set(eventdatavalues, '{"<affected data element uid>","value"}', '"<new value>"')
WHERE eventdatavalues @> '{"<affected data element uid>":{"value": "<old value>"}}'::jsonb
AND programstageid=<database_programsatgeid>;
```

NOTE

When updating the UID of a metadata element in the existing DHIS2 instance, you will need to run an SQL command in the database and additionally replace all occurrences and references of its UID in other metadata objects: predictor, indicator, validation rule expressions, etc.

Sort order of 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 of 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.

Make sure that no options within an option set have the same sort order. This can be checked using the following api endpoint:

../api/options.json?paging=false&fields=id,name,sortOrder&filter=optionSet.id:in:[<optionSet UID>]

In order to fix sort order in option sets containing large numbers of options, please refer to this SQL script.

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

Las visualizaciones, informes de eventos, tablas de informes y mapas que están asignados a un nivel de unidad organizativa específico o grupo de unidades organizativas tienen una referencia a la unidad organizativa raíz (nivel 1). Dichos objetos, si están presentes en el archivo de metadatos, contienen un marcador de posición <OU_ROOT_UID>. Utilice la función de búsqueda en el editor de archivos .json para identificar este marcador de posición y reemplazarlo con el UID de la unidad organizativa de nivel 1 en la instancia de destino.

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

Actualización del paquete de metadatos¶

The process of upgrading an existing package to a newer version in a working DHIS2 instance is a complex operation that has to be taken with precaution. Such process has to be run in development and staging instances first, before upgrading the configuration on the production server. As metadata objects may have been removed, added or changed, it is important to ensure that:

• el formato de los datos existentes se puede mapear y ajustar a la nueva configuración;
• los objetos de metadatos interrumpidos se eliminan de la instancia;
• Los objetos existentes se actualizan;
• se crean los nuevos objetos;
• se revisa la asignación de usuarios a los grupos de usuarios pertinentes.

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.

Linking the TB Household Contacts Investigation package to an existing TB Case Surveillance module¶

This section provides guidance on adding the TB Household Contacts Investigation packag to the functioning instance with the TB CS tracker.

For existing implementations, direct upgrade of metadata packages in the instance is not recommended.

TB Household Contacts Investigation package reuses several metadata objects from the TB Case Surveillance package. These include tracked entity type, tracked entity attributes, data elements, option sets, options and user groups. Comparing metadata reference files for both packages will help the user identify these elements before merging baseline metadata in the instance with the metadata objects in the package.

It is recommended to use version 2.1.0 of the TB Case Surveillance package when linking it with the TB Household Contacts Investigation module. The configuration of the relationship type to support enrollment of the household contacts through the relationship widget in the TB Case Surveillance tracker is described below.

{
    "relationshipTypes": [
        {
            "code": "TB_CS_INDEX_HH",
            "name": "TB - Index case --> Household contact",
            "externalAccess": false,
            "publicAccess": "rw------",
            "userGroupAccesses": [],
            "userAccesses": [],
            "access": {
                "manage": true,
                "externalize": true,
                "write": true,
                "read": true,
                "update": true,
                "delete": true,
                "data": {
                    "write": true,
                    "read": true
                }
            },
            "favorites": [],
            "sharing": {
                "owner": "Ia1Xtxa5eG8",
                "external": false,
                "users": {},
                "userGroups": {},
                "public": "rw------"
            },
            "fromConstraint": {
                "relationshipEntity": "TRACKED_ENTITY_INSTANCE",
                "trackedEntityType": {
                    "id": "MCPQUTHX1Ze"
                },
                "program": {
                    "id": "Lt6P15ps7f6"
                },
                "trackerDataView": {
                    "attributes": [
                        "sB1IHYu2xQT",
                        "ENRjVGxVL6l",
                        "Ewi7FUfcHAD"
                    ],
                    "dataElements": []
                }
            },
            "toConstraint": {
                "relationshipEntity": "TRACKED_ENTITY_INSTANCE",
                "trackedEntityType": {
                    "id": "MCPQUTHX1Ze"
                },
                "program": {
                    "id": "cQsXTtAJ3HW"
                },
                "trackerDataView": {
                    "attributes": [
                        "Ewi7FUfcHAD",
                        "sB1IHYu2xQT",
                        "ENRjVGxVL6l"
                    ],
                    "dataElements": []
                }
            },
            "description": "Household contacts of confirmed TB cases",
            "bidirectional": true,
            "fromToName": "Household contact",
            "toFromName": "Index case",
            "referral": false,
            "displayFromToName": "Household contact",
            "displayToFromName": "Index case",
            "displayName": "TB - Index case --> Household contact",
            "favorite": false,
            "id": "l0wf8ZWv9nX",
            "attributeValues": []
        }
    ]
}

1. For the TB Case:

1. For the Household contact:

It is possible to edit the list of displayed attributes in the relationship widget.

Tracked Entity Attributes that are displayed in the relationship widget have to be assigned to the Tracked Entity Type. 'Display in list' option has to be activated for them.

Tracked Entity Attributes to be displayed in the relationship widget have to be assigned to the corresponding programmes.

'Display in list without program' option has to be activated for the relevant Tracked Entity Attributes.

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.

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:

• Dashboards (Visualizations, maps, event reports and report tables)
• Sets de datos
• Opciones de categoría
• Programs and program stages

These core user groups are included in the package:

• TB admin
• TB access
• TB data capture

By default the following is assigned to these user groups

Users need to be assigned to the aplicable user group based on their role within the system. Sharing for other objects in the package should be set up depending on requirements. Refer to the DHIS2 Documentation for more information on configuring sharing.

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:

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 DHIS2 para obtener más información sobre la configuración de roles de usuario.

Unidades organizativas¶

Program must be assigned to applicable organisation units within the organisation unit hierarchy.

Metadatos duplicados¶

NOTA

Esta sección solo se aplica si está importando a una base de datos DHIS2 en la que ya hay metadatos presentes. Si está trabajando con una nueva instancia de DHIS2, por favor omita esta sección y vaya a Adaptar el programa. Si está utilizando aplicaciones de terceros que dependen de los metadatos actuales, tenga en cuenta que esta actualización podría dañarlas

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.

Configuring tracker capture interface, widgets and top bar¶

Tracker capture dashboard must be configured 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
• Use Tabular Data Entry
• Make sure that Enrollment, Feedback, Profile and Relationships widgets are selected. Click Close.
• Click "Saved dashboard layout as default"
• Click "Lock layout for all users"

Top Bar¶

Top bar activation and configuration allows the user to have a clear overview of key case data displayed at the top of the tracker capture dashboard.

Reporting case-based data into aggregate data sets¶

The TB Household Contacts Investigation tracker includes an Aggregate Data Exchange configuration that can aggregate case-based data and populate the quarterly "TB Household Contacts" data sets included in the TB HMIS package.

The program indicators are mapped with data elements and category option combinations in the aggregate package.

The default configuration is set to internal data exchange, i.e. when the tracker and the aggregate data sets are located in the same instance. It is possible to change this configuration in the json component. The user working with data exchange has to have access to both tracker and aggregate data. More information can be found in the Data Exchange documentation

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.