AEFI Tracker Installation Guide¶
Visión general¶
The AEFI tracker package was developed using DHIS2.33.2. This was done in order to support some of the latest features in DHIS2. In order to use the package, it is recommended that you install it into a DHIS2 instance using DHIS2 2.33.2 or above. If you will be setting this up on a new instance, please refer to the DHIS2 installation guide.
Instalación¶
La instalación del módulo consta de varios pasos:
- Preparing the metadata file with DHIS2 metadata.
- Importar el archivo de metadatos en DHIS2.
- Configuring the imported metadata.
- 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.
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¶
NOTE: If you are installing the package on a new instance of DHIS2, you can skip the “Preparing the metadata file” section and move immediately to the section on “Importing a metadata file into 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, 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.
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 of the database in which the file will be imported. Table 1 shows the UIDs which 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 |
| 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.
You could then search and replace all occurrences of HllvX50cXC0 with bRowv6yZOF2 in the .json file, as that is the ID of default in the system you are importing into. Note that this search and replace operation must be done with a plain text editor, not a word processor like 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 Tabla 2 muestra 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 |
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 |
Event report organisation Unit¶
In the AEFI metadata package there are event reports tied to the root level unit of the organisation unit tree. The reference to the organisation unit needs to be replaced with the UID of the root unit of the organisation unit tree in your system. Table 4 shows the UID which need to be replaced, as well as the api endpoint to identify the existing organisation unit UID
| Objeto | UID | API endpoint |
|---|---|---|
| Unidad Organizativa | GD7TowwI46c | ../api/organisationUnits.json?level=1 |
Importar metadatos¶
The .json metadata file is imported through the Import/Export app of DHIS2. 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 configure 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 into a new DHIS2 instance, you will not have to worry about import conflicts, as there is nothing in the database you are importing to to conflict with. Follow the instructions to import the metadata then please proceed to the “Additional 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 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.
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¶
First, you will have to use the Sharing functionality of DHIS2 to configure which users (user groups) should see the metadata and data associated with the programme as well as who can register/enter data into the program. By default, sharing has been configured for the following:
- Tipo de entidad Tracked
- Programa
- Etapas del programa
- Tableros
There are six user groups that come with the package, the last three are recipients of program stage notifications:
- AEFI access
- AEFI admin
- AEFI data capture
- AEFI district
- AEFI national
- AEFI first-level decision making
By default the following is assigned to these user groups
| Objeto | User Group | ||
|---|---|---|---|
| AEFI access | AEFI admin | AEFI data capture | |
| Tracked entity type | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Program | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Program Stages | Metadatos: puede ver Datos: puede ver | Metadatos : puede ver y editar Datos: puede ver | Metadatos : puede ver Datos: puede ver y capturar |
| Dashboards | Metadata : can view | Metadata : can edit and view | Metadata : none |
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¶
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.”
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.
Adaptar el programa¶
Once the programme has been imported, you might want to make certain modifications to the programme. 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.
- Modifying program indicators based on local case definitions
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.
Line Listing¶
Due to technical issues, two essential line lists are not included in the generic package. The implementers are required to configure these line lists following the steps below
AEFI Line listing (Event Report)¶
-
note: the screenshot above does not represent the full line list
-
Go to DHIS 2 Event Reports app
- Select Table style Line list
- Select Output style Event
- In Data section, select program Adverse events folloing immunization (AEFI)
- Select Stage AEFI
- Use the table below and add the Data elements / Program Attributes in the suggested order.
- In Periods section, select This Year
- In Organisation units section, select User org unit
- CLick Favourites button and Save.
- Add Name - AEFI LINE LISTING - this year
- CLick Favourites button and Save.
- Click Share. Restrict external and public access and share the event report with applicable user groups: AEFI access (can view) and AEFI admin (can edit and view)
- Go to AEFI Dashboard and add the event report to the dashboard.
| Field/column # | Variable name | Source Stage | Object Type | |
|---|---|---|---|---|
| 1 | Número | |||
| 2 | DOR (date of report - report compilation date) | |||
| 3 | DON (Date of Notification - date patient notified the event to the health system) | |||
| 4 | Incident date | |||
| 5 | Unidad Organizativa | |||
| 6 | AEFI - Reporter of case | AEFI Stage | Elemento de datos | uZ9c4fKXuNS |
| 7 | AEFI - Reporter’s address | AEFI Stage | Elemento de datos | Q20pEixZxCs |
| 8 | AEFI Case ID | Program attribute | h5FuguPFF2j | |
| 9 | Given name | Program attribute | TfdH5KvFmMy | |
| 10 | Family name | Program attribute | aW66s2QSosT | |
| 11 | Date of birth | Program attribute | BiTsLcJQ95V | |
| 12 | Sex | Program attribute | CklPZdOd6H1 | |
| 13 | AEFI - AEFI start date | AEFI Stage | Elemento de datos | vNGUuAZA2C2 |
| 14 | AEFI_Serious adverse event following immunization | AEFI Stage | Elemento de datos | kQCVFWE2MPb |
| 15 | AEFI - AEFI outcome | AEFI Stage | Elemento de datos | yRrSDiR5v1M |
| 16 | AEFI - Vaccination 1 date | AEFI Stage | Elemento de datos | dOkuCjpD978 |
| 17 | AEFI - Vaccine 1 name | AEFI Stage | Elemento de datos | uSVcZzSM3zg |
| 18 | AEFI - batch/lot number (Vaccine 1) | AEFI Stage | Elemento de datos | LNqkAlvGplL |
| 19 | AEFI - Diluent batch/lot number 1 | AEFI Stage | Elemento de datos | FQM2ksIQix8 |
| 20 | AEFI - Vaccination 2 date | AEFI Stage | Elemento de datos | VrzEutEnzSJ |
| 21 | AEFI - Vaccine 2 name | AEFI Stage | Elemento de datos | g9PjywVj2fs |
| 22 | AEFI - batch/lot number (Vaccine 2) | AEFI Stage | Elemento de datos | b1rSwGRcY5W |
| 23 | AEFI - Diluent batch/lot number 2 | AEFI Stage | Elemento de datos | ufWU3WStZgG |
| 24 | AEFI - Vaccination 3 date | AEFI Stage | Elemento de datos | f4WCAVwjHz0 |
| 25 | AEFI - Vaccine 3 name | AEFI Stage | Elemento de datos | OU5klvkk3SM |
| 26 | AEFI - batch/lot number (Vaccine 3) | AEFI Stage | Elemento de datos | YBnFoNouH6f |
| 27 | AEFI - Diluent batch/lot number 3 | AEFI Stage | Elemento de datos | MLP8fi1X7UX |
| 28 | AEFI - Abdominal pain | AEFI Stage | Elemento de datos | T6tsxbKzikz |
| 29 | AEFI - Abscess | AEFI Stage | Elemento de datos | wce39JmsjIK |
| 30 | AEFI - Anaphylaxis | AEFI Stage | Elemento de datos | MkIgCrCTFyE |
| 31 | AEFI - Bell's Palsy | AEFI Stage | Elemento de datos | BKxtyqhIDkB |
| 32 | AEFI - Chills | AEFI Stage | Elemento de datos | TPSvWhUfib3 |
| 33 | AEFI - Congenital anomaly | AEFI Stage | Elemento de datos | lSBsxcQU0kO |
| 34 | AEFI - Cough | AEFI Stage | Elemento de datos | ZdFB8xUhOUM |
| 35 | AEFI - Diarrhoea | AEFI Stage | Elemento de datos | NAiZTRCHRWL |
| 36 | AEFI - Dizziness | AEFI Stage | Elemento de datos | XluNAFG1wj6 |
| 37 | AEFI - Drowsiness | AEFI Stage | Elemento de datos | rjjRNU5yDhT |
| 38 | AEFI - Encephalopathy | AEFI Stage | Elemento de datos | pdpAEuUS1W9 |
| 39 | AEFI - Fainting | AEFI Stage | Elemento de datos | OhHYABXmGGe |
| 40 | AEFI - Fatigue | AEFI Stage | Elemento de datos | owRcSysyioE |
| 41 | AEFI - Fever | AEFI Stage | Elemento de datos | rzhHSqK3lQq |
| 42 | AEFI - Headache | AEFI Stage | Elemento de datos | HY6NIt2FX4A |
| 43 | AEFI - Injection site soreness | AEFI Stage | Elemento de datos | P4oSprWWqrn |
| 44 | AEFI - Injection site tenderness | AEFI Stage | Elemento de datos | KqlCtmOWt4G |
| 45 | AEFI - Irritability | AEFI Stage | Elemento de datos | PWOzcN7UCfW |
| 46 | AEFI - Itching | AEFI Stage | Elemento de datos | FC54HsGMErl |
| 47 | AEFI - Joint pain | AEFI Stage | Elemento de datos | vCfZD893IVe |
| 48 | AEFI - Loss of apetite | AEFI Stage | Elemento de datos | QFMRugi3fm6 |
| 49 | AEFI - Lymphadenopathy | AEFI Stage | Elemento de datos | dDWYBYUNpaQ |
| 50 | AEFI - Lymph node enlargement | AEFI Stage | Elemento de datos | GEkI9NzxTmM |
| 51 | AEFI - Mild fever | AEFI Stage | Elemento de datos | nKLO8ZNdR0B |
| 52 | AEFI - Muscle pain | AEFI Stage | Elemento de datos | pzOF4lGIyTU |
| 53 | AEFI - Nasal congestion | AEFI Stage | Elemento de datos | wWDenTQ5xBR |
| 54 | AEFI - Nausea | AEFI Stage | Elemento de datos | KOt0J61mF61 |
| 55 | AEFI - Specify other (Adverse event) | AEFI Stage | Elemento de datos | iTm5wvq16iq |
| 56 | AEFI - Specify other (Severe event) | AEFI Stage | Elemento de datos | AfrWB2ofm7l |
| 57 | AEFI - Persistent crying | AEFI Stage | Elemento de datos | GTyK3p976de |
| 58 | AEFI - Poor breast feeding | AEFI Stage | Elemento de datos | sX1SvRadOmn |
| 59 | AEFI - Seizure type | AEFI Stage | Elemento de datos | Zz4KYO4AsSY |
| 60 | AEFI - Seizures | AEFI Stage | Elemento de datos | wCGZpudXuYx |
| 61 | AEFI - Sepsis | AEFI Stage | Elemento de datos | tUmgO1Ugv6U |
| 62 | AEFI - Severe local reaction | AEFI Stage | Elemento de datos | UNmEidE6M9K |
| 63 | AEFI - Severe local reaction > 3 days | AEFI Stage | Elemento de datos | We87rvcvd8J |
| 64 | AEFI - Severe local reaction beyond nearest joint | AEFI Stage | Elemento de datos | f8hjxmHOtAB |
| 65 | AEFI - Skin rash | AEFI Stage | Elemento de datos | xgqzqv0p2Us |
| 66 | AEFI - Sore throat | AEFI Stage | Elemento de datos | seXW1hERwOo |
| 67 | AEFI - Tiredness | AEFI Stage | Elemento de datos | JaZ9yf1dDy3 |
| 68 | AEFI - Thrombocytopenia | AEFI Stage | Elemento de datos | GGLLaieVChK |
| 69 | AEFI - Toxic shock syndrome | AEFI Stage | Elemento de datos | Apq4JaueuWR |
| 70 | AEFI - Vomiting | AEFI Stage | Elemento de datos | cMEIyp0rMo1 |
| 71 | AEFI - Death | AEFI Stage | Elemento de datos | DOA6ZFMro84 |
| 72 | AEFI - Hospitalization | AEFI Stage | Elemento de datos | Il1lTfknLdd |
| 73 | AEFI - Life threatening | AEFI Stage | Elemento de datos | lATDYNmTLKD |
| 74 | AEFI - Persistent or significant disability | AEFI Stage | Elemento de datos | lsO8n8ZmLAB |
AEFI national level summary (Event Report)¶
-
note: the screenshot above does not represent the full linelist
-
Go to DHIS 2 Event Reports app
- Select Table style Line list
- Select Output style Enrollment
- In Data section, select program Adverse events folloing immunization (AEFI)
- Select applicable Stage. See the table below
- Use the table below and add the Data elements / Program Attributes in the suggested order.
- In Periods section, select Last 12 months
- In Organisation units section, select User org unit
- Click Favourites button and Save.
- Add Name - AEFI national level summary (this year)
- Click Favourites button and Save.
- Click Share. Restrict external and public access and share the event report with applicable user groups: AEFI access (can view) and AEFI admin (can edit and view)
- Go to AEFI Dashboard and add the event report to the dashboard.
| Field/column # | Variable name | Source Stage | Object type | UID |
|---|---|---|---|---|
| 1 | Número | |||
| 2 | DON (Date of Notification - date patient notified the event to the health system) | |||
| 3 | Incident date | |||
| 4 | Unidad Organizativa | |||
| 5 | AEFI Case ID | Program attribute | h5FuguPFF2j | |
| 6 | AEFI - Date when seen for approval at national level | National level stage | Elemento de datos | cWMUoQEuvtR |
| 7 | AEFI - Date of final classification | National level stage | Elemento de datos | wDijUvPYVne |
| 8 | AEFI - Valid Diagnosis | National level stage | Elemento de datos | IZoGGNUkNl0 |
| 9 | AEFI - Vaccine 1 name | AEFI Stage | Elemento de datos | uSVcZzSM3zg |
| 10 | AEFI - Vaccination 1 date | AEFI Stage | Elemento de datos | dOkuCjpD978 |
| 11 | AEFI - Vaccine 2 name | AEFI Stage | Elemento de datos | g9PjywVj2fs |
| 12 | AEFI - Vaccination 2 date | AEFI Stage | Elemento de datos | VrzEutEnzSJ |
| 13 | AEFI - Vaccine 3 name | AEFI Stage | Elemento de datos | OU5klvkk3SM |
| 14 | AEFI - Vaccination 3 date | AEFI Stage | Elemento de datos | f4WCAVwjHz0 |
| 15 | AEFI - Vaccine 4 name | AEFI Stage | Elemento de datos | menOXwIFZh5 |
| 16 | AEFI - Vaccination 4 date | AEFI Stage | Elemento de datos | H3TKHMFIN6V |
| 17 | AEFI - Final causality assessment classification | National level stage | Elemento de datos | DpgoIsq65SW |
| 18 | AEFI - Final causality assessment sub-classification | National level stage | Elemento de datos | D42M2tdJo7R |
Visualizations¶
Visualizations associated with the AEFI stage are detailed in the overview of the AEFI facility level line list. There are two key visualizations associated with causality assessment classification and sub-classification.