MPOX EPI Installation Guide¶
Package Version 0.0.1
Idioma predeterminado del sistema: Inglés
Instalación¶
La instalación del módulo consta de varios pasos:
- Preparar el archivo de metadatos.
- Importar el archivo de metadatos en DHIS2.
- Configurar los metadatos importados.
- 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:
- Importar a una instancia DHIS2 en blanco
- Import into a DHIS2 instance with existing metadata (No other versions of MPOX EPIention tracker imported previously).
- Update existing/older version of the MPOX EPIention 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¶
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.
Se debe tener mucho cuidado para garantizar que el servidor en sí y la aplicación DHIS2 estén bien protegidos, para restringir el acceso a los datos que se recopilan. 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.
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 (si corresponde)¶
En las primeras versiones de DHIS2, el UID de la dimensión de datos predeterminada se generaba 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 base de datos 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 |
Por ejemplo, si importa un paquete de configuración a https://play.dhis2.org/demo, el UID de la combinación de opciones de categoría predeterminada podría identificarse a través de https://play.dhis2.org/demo/api/categoryOptionCombos.json?filter=name:eq:default as bRowv6yZOF2.
Luego, puede buscar y reemplazar todas las apariciones de HllvX50cXC0 con bRowv6yZOF2 en el archivo .json, ya que ese es el ID predeterminado en el sistema al que está importando. 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 simplemente por su factor y si son o no números simples sin denominador, no son ambiguos y pueden reemplazarse mediante una búsqueda y reemplazo de los UID. Esto evita posibles conflictos de importación y evita la creación de tipos de indicadores duplicados. La siguiente tabla muestra los UID que podrían reemplazarse, así como los API endpoints para identificar los UID existentes.
| Objeto | UID | API endpoint |
|---|---|---|
| Porcentaje | hmSnCXmLYwt | ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:100 |
| Tasa (factor=1) | k4RGC3sMTzO | ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:1 |
| Por 10 000 | FWTvArgP0jt | ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:10000 |
| Sólo numerador (número) | kHy61PbChXr | ..api/indicatorTypes.json?filter=number:eq:true |
Tipo de entidad Tracked¶
Al igual que los tipos de indicadores, es posible que ya existan tipos de entidades tracker en su base de datos DHIS2. Las referencias al tipo de entidad tracker deben cambiarse para reflejar lo que hay en su sistema para no crear duplicados. La Tabla 3 muestra los UID que podrían reemplazarse, así como los API endpoints para identificar los UID existentes
| Objeto | UID | API endpoint |
|---|---|---|
| Persona | MCPQUTHX1Ze | ../api/trackedEntityTypes.json?filter=name:eq:Person |
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.
Algunas visualizaciones y mapas pueden contener referencias a niveles de unidades organizativas. Los mapas que constan de varias vistas de mapa pueden contener varias referencias a nivel de unidad organizativa en función de la configuración de la capa del mapa. Ajuste las referencias a nivel de unidad organizativa en el archivo json de metadatos para que coincidan con la estructura de la unidad organizativa en la instancia de destino antes de importar el archivo de metadatos.
Actualización del paquete de metadatos¶
El proceso de actualizar un paquete existente a una versión más reciente en una instancia DHIS2 en funcionamiento es una operación compleja que debe realizarse con precaución. Dicho proceso debe ejecutarse primero en una instancia de prueba, antes de actualizar la configuración en el servidor de producción. Como es posible que se hayan eliminado, agregado o modificado los objetos de metadatos, es importante asegurarse de que:
- 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¶
El archivo de metadatos .json se importa a través de la aplicación [Importar/Exportar] (https://docs.dhis2.org/master/en/user/html/import_export.html) de DHIS2. 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 de "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 a una nueva instancia de DHIS2, no tendrá que preocuparse por los conflictos de importación, ya que no hay nada en la base de datos que esté importando con lo que pueda entrar en conflicto. Siga las instrucciones para importar los metadatos y, a continuación, pase 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 vaya a utilizar material de formación y documentación basados en el paquete de configuració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.
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
Un paquete de metadatos suele contener varios grupos de usuarios:
- MPOX EPI - Access
- MPOX EPI - Admin
- MPOX EPI - Data capture
De forma predeterminada, lo siguiente está asignado a estos grupos de usuarios
| Objeto | Grupos de usuarios | Grupos de usuarios | Grupos de usuarios |
|---|---|---|---|
| MPOX EPI - Access | MPOX EPI - Admin | MPOX EPI - Data capture | |
| Tipo de entidad Tracked | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Programa | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Etapas del programa | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Tableros | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos: puede ver Datos: puede ver |
Querrá asignar sus usuarios al grupo de usuarios apropiado según su rol dentro del sistema. Es posible que desee habilitar 'compartir' para otros objetos en el paquete en función de su configuración. Consulte la Documentación de DHIS2 para obtener más información sobre cómo configurar compartir.
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 DHIS2 para obtener más información sobre la configuración de roles de usuario.
Unidades organizativas¶
Debe asignar el programa a unidades organizativas dentro de su propia jerarquía para poder ver el programa en Tracker - captura de datos.
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.
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.