Education Toolkit Installation Guide¶

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.

Instalación¶

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

1. Preparing the metadata file with DHIS2 metadata

2. Importing the metadata file into DHIS2

3. Configuring the imported metadata

4. Adapting the program after import

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.

Warning

The steps outlined in this document should be tested in a test/staging DHIS2 instance and only then applied to a production environment.

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¶

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 that 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
Category Combination	bjDvmb4bfuf	../api/categoryCombos.json?filter=name:eq:default
Combinación de opciones de categoría	HllvX50cXC0	../api/categoryOptionCombos.json?filter=name:eq:default

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

Visualizations, event reports, report tables and maps that are assigned to a specific organisation unit level or organisation unit group, have a reference to the root (level 1) organisation unit. Such objects, if present in the metadata file, contain a placeholder <OU_ROOT_UID>. Use the search function in the .json file editor to possibly identify this placeholder and replace it with the UID of the level 1 organisation unit in the target instance.

Importar metadatos¶

Use Import/Export DHIS2 app to import metadata packages. It is advisable to use the "dry run" feature to identify issues before attempting to do an actual import of the metadata. If "dry run" reports any issues or conflicts, see the import conflicts section below.

If the "dry run"/"validate" import works without error, attempt to import the metadata. If the import succeeds without any errors, you can proceed to configuring the module. In some cases, import conflicts or issues are not shown during the "dry run", but appear when the actual import is attempted. In this case, the import summary will list any errors that need to be resolved.

Gestión de conflictos de importación¶

Note

If you are importing the package into a new DHIS2 instance, you will not experience import conflicts, as there is no metadata in the target database. After import the metadata, proceed to the “Configuration” section.

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.

Tip

Note that for both alternative 1 and 2, the modification can be as simple as adding a small pre/post-fix to the name, to minimise the risk of confusion.

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:

• It requires expert knowledge of the detailed metadata structure of DHIS2

• The approach does not work for all types of objects. In particular, certain types of objects have dependencies which are complicated to solve in this way, for example related to disaggregations.

• Future updates to the configuration package will be complicated.

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:

• Tableros
• Visualizaciones, mapas, informes de eventos y tablas de informes
• Sets de datos
• Opciones de categoría

Please refer to the DHIS2 documentation for more information on sharing.

Los paquetes incluyen tres grupos de usuarios principales:

• EMIS access (view metadata/view data)
• EMIS admin (view and edit metadata/no access to data)
• EMIS 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 setup. 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:

1. Data analysis - Can see event analytics and access dashboards, event reports, event visualizer, data visualizer, pivot tables, reports and maps.

2. Data capture - Can add data values, update tracked entities, search tracked entities across org units and access tracker capture

Refer to the DHIS2 Documentation for more information on configuring user roles.

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.

Mapeo de indicadores¶

Cuando se implementa únicamente el paquete Tablero, los numeradores y denominadores del indicador deben configurarse utilizando los objetos de metadatos en la instancia existente. La información de configuración está disponible en la documentación y la descripción de numeradores y denominadores en el archivo de metadatos.

Metadatos duplicados¶

Caution

This section only applies if you are importing into a DHIS2 database with existing metadata. If you are working with a new/blank DHIS2 instance, please skip this section and go to Adapting the toolkit. 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.

One important thing to keep in mind is that DHIS2 has tools that can hide some of the complexities of potential duplications in metadata. For example, where duplicate option sets exist, they can be hidden for groups of users through sharing.

Adapting the toolkit¶

Once the toolkit has been imported, you might want to make certain modifications to the program. Examples of local adaptations that could be made include:

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