IDS - Integrated Disease Surveillance Installation Guide¶

This document includes an installation guide for the IDS aggregate package.

System default language: English

Available translations: French

Visão Geral¶

The metadata reference and metadata json files provide technical details on package version and content.

The metadata package consists of the following modules:

• Integrated Disease Surveillance
• Integrated Disease Surveillance (dashboard)

Instalação¶

A instalação do módulo consiste em várias etapas:

1. Preparing the metadata file with DHIS2 metadata
2. Importing the metadata file into DHIS2
3. Configuring the imported metadata
4. [Adaptando o programa após a importação] (#adaptando o programa)

Recomenda-se ler primeiro cada secção do guia de instalação antes de iniciar o processo de instalação e configuração no DHIS2. Identifique as secções aplicáveis, dependendo do tipo de sua importação:

1. import into a blank DHIS2 instance
2. import into a DHIS2 instance with existing metadata.

As etapas descritas neste documento devem ser testadas em uma instância de teste/teste DHIS2 e só então aplicadas a um ambiente de produção.

Requisitos¶

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

Metadata files¶

Embora nem sempre seja necessário, muitas vezes pode ser vantajoso fazer certas modificações no arquivo de metadados antes de importá-lo para o DHIS2.

Preparing the Metadata File¶

Dimensão padrão dos dados¶

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.

Para evitar conflitos ao importar os metadados, é aconselhável pesquisar e substituir todo o arquivo .json para todas as ocorrências desses objectos padrão, substituindo os UIDs do arquivo .json pelos UIDs da instância em que o arquivo será importado. A Tabela 1 mostra os UIDs que devem ser substituídos, bem como os endpoints da API para identificar os UIDs existentes

Identify the UIDs of the default dimesions in your instance using the listed API requests and replace the UIDs in the json file with the UIDs from the instance.

NOTA

Observe que esta operação de pesquisa e substituição deve ser feita com um editor de texto simples, não um processador de texto como o Microsoft Word.

Tipos de indicadores¶

Indicator type is another type of object that can create import conflict because certain names are used in different DHIS2 databases (.e.g "Percentage"). Since Indicator types are defined by their factor (including 1 for "numerator only" indicators), they are unambiguous and can be replaced through a search and replace of the UIDs. This method helps avoid potential import conflicts, and prevents the implementer from creating duplicate indicator types. The table below contains the UIDs which could be replaced, as well as the API endpoints to identify the existing UIDs:

Visualizations using root organisation unit UID¶

Visualizações, relatórios de eventos, tabelas de relatórios e mapas atribuídos a um nível de unidade organizacional específico ou grupo de unidades organizacionais têm uma referência à unidade organizacional raiz (nível 1). Tais objectos, se presentes no arquivo de metadados, contêm um espaço reservado <OU_ROOT_UID>. Use a função de pesquisa no editor de arquivos .json para possivelmente identificar esse espaço reservado e substituí-lo pelo UID da unidade organizacional de nível 1 na instância de destino.

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:

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

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.

A ordem de classificação pode ser ajustada no aplicativo Manutenção.

1. Vá para o Conjunto de Opções aplicável
2. Abra a secção "Opções"
3. Use as alternativas "CLASSIFICAR POR NOME", "CLASSIFICAR POR CÓDIGO/VALOR" ou "CLASSIFICAR MANUALMENTE".

The IDS package contains one option set and two options:

{
    "optionSets": [
        {
            "name": "YES/NO (numeric)",
            "id": "TdDqpX1kdd2",
            "code": "YES_NO_NUM",
            "valueType": "INTEGER_ZERO_OR_POSITIVE",
            "options": [
                {
                    "id": "VavIEUmBv8j"
                },
                {
                    "id": "Xu8ieCbS7jH"
                }
            ]
        }
    ],
    "options": [
        {
            "name": "Yes",
            "id": "VavIEUmBv8j",
            "code": "1",
            "sortOrder": 1,
            "optionSet": {
                "id": "TdDqpX1kdd2"
            }
        },
        {
            "name": "No",
            "id": "Xu8ieCbS7jH",
            "code": "0",
            "sortOrder": 2,
            "optionSet": {
                "id": "TdDqpX1kdd2"
            }
        }
    ]
}

This Yes/No option set is based on "INTEGER_ZERO_OR_POSITIVE" option values that are assigned to two data elements and evaluated in a predictor listed below:

Population data¶

The IDS package includes data elements, indicators and other metadata objects that are related to population data.

If the target instance already has metadata infrastructure, which is used for collecting Population data, please refer to the steps listed below:

1. Choose the strategy to align population metadata in the target instance and in the .json file.
2. Alternative 1: Replace the UIDs of the data elements and all their occurences in the json file with the UIDs from the target system

3. Alternative 2: Consider replacing the UIDs of these data elements in the target system with the UIDs from the json file. GEN data elements are part of DHIS2 core metadata library and are used in other metadata packages.

4. Indicators that use the population data will be aggregating data at the level/levels where the data is entered.

5. Additional mapping and configuration may be required after the package is imported. Refer to the data set configuration section

NOTE

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

Predictors¶

The package includes the following predictors:

Predictor metadata includes organisation unit levels used for aggregation of data values. The package metadata file contains placeholders that need to be replaced with the UIDs of the corresponding organisation unit levels in the target database.

The steps to prepare the predictors for import are described below:

1. Identify the organisationUnitLevel UID of the District level at which the data for the predictors will be aggregated. Use the following API endpoint to identify the required UID: ../api/organisationUnitLevels.json?fields=id,name
2. Find the following organisationUnitLevel placeholders in the json file: <OU_LEVEL_DISTRICT_UID>
3. Replace the placeholders with the UID of the identified facility level in the target instance.

Validation rules¶

All validation rules included in the package are listed in the metadata reference file.

The organisation unit groups for all validation rules are set to the district level. The district level value is located in the "organisationUnitLevels" property of each validation rule. It is set to 3 by default. Adjust these levels in the metadata file to match the district level in the target instance before importing the package.

Validation rule notifications¶

All validation notifications included in the package are listed in the metadata reference file.

Note that all validation rule notifications for this package are all set to be sent as a "single notification." This means that one notification is sent out for each organisation unit/period combination when a notification is triggered. This can also be configured as a "collective summary." The strategy for sending these notifications is located in the "sendStrategy" property of each validation notification. It is set to SINGLE_NOTICIATION by default. Adjust these values to COLLECTIVE_SUMMARY within the metadata file if you would like to change this strategy before importing the package.

NB: Note that you can also change this in maintenance for each validation rule notification at any time after they are imported as you may want to demonstrate or test both strategies to select one that is appropriate for your own setting.

Importando metadados¶

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

Manipulando conflitos de importação¶

NOTA

Se estiver importando o pacote para uma nova instância do DHIS2, não haverá conflitos de importação, pois não há metadados no banco de dados de destino. Após importar os metadados, vá para a secção “Configuração”.

Existem vários conflitos diferentes que podem ocorrer, embora o mais comum seja a existência de objectos de metadados no pacote de configuração com um nome, nome abreviado e/ou código que já existem no banco de dados de destino. Existem algumas soluções alternativas para esses problemas, com diferentes vantagens e desvantagens. Qual é mais apropriado dependerá, por exemplo, do tipo de objecto para o qual ocorre um conflito.

Alternativa 1¶

Renomeie o objecto existente em seu banco de dados DHIS2 para o qual há um conflito. A vantagem dessa abordagem é que não há necessidade de modificar o arquivo .json, pois as alterações são feitas por meio da interface do usuário do DHIS2. Isso provavelmente será menos propenso a erros. Isso também significa que o pacote de configuração é deixado como está, o que pode ser uma vantagem, por exemplo, quando as actualizações do pacote são lançadas. Os objectos do pacote original também são frequentemente referenciados em materiais de treinamento e documentação.

Alternativa 2¶

Renomeie o objecto para o qual há um conflito no arquivo .json. A vantagem dessa abordagem é que os metadados DHIS2 existentes são deixados como estão. Isso pode ser um fator quando há material de treinamento ou documentação como SOPs de dicionários de dados vinculados ao objeto em questão, e não envolve nenhum risco de confundir os usuários ao modificar os metadados com os quais estão familiarizados.

Observe que, para as alternativas 1 e 2, a modificação pode ser tão simples quanto adicionar um pequeno pré/pós-correção ao nome, para minimizar o risco de confusão.

Alternativa 3¶

Uma terceira e mais complicada abordagem é modificar o ficheiro .json para reutilizar os metadados existentes. Por exemplo, nos casos em que um conjunto de opções já existe para um determinado conceito (por exemplo, "sexo"), esse conjunto de opções pode ser removido do ficheiro .json e todas as referências ao seu UID substituídas pela opção correspondente já existente na base de dados. A grande vantagem disso (que não se limita aos casos em que há um conflito direto de importação) é evitar a criação de metadados duplicados na base de dados. Existem algumas considerações importantes a serem feitas ao executar esse tipo de modificação:

• Isto requer conhecimento especializado da estrutura detalhada dos metadados do DHIS2
• a abordagem não funciona para todos os tipos de objec tos. Em particular, certos tipos de objectos têm dependências que são complicadas de resolver dessa maneira, por exemplo, relacionadas a desagregações.
• futuras actualizações do pacote de configuração serão complicadas.

Configuração¶

Depois que todos os metadados forem importados com sucesso, é necessário executar algumas etapas antes do funcionamento do módulo

Partilha¶

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 program as well as who can register/enter data into the program. By default, sharing has been configured for the following:

• Painéis
• Visualizações, mapas, relatórios de eventos e tabelas de relatórios
• Conjuntos de dados
• Opções de categoria

Consulte a [documentação DHIS2] (#compartilhamento) para obter mais informações sobre compartilhamento.

Três grupos de usuários principais estão incluídos no pacote:

• IDS access (view metadata/view data)
• IDS admin (view and edit metadata/no access to data)
• IDS alerts (view metadata/capture and view data)

Os usuários são atribuídos ao grupo de usuários apropriado com base em sua função no sistema. O compartilhamento de outros objectos no pacote pode ser ajustado dependendo da configuração. Consulte a [Documentação DHIS2 sobre compartilhamento] (#compartilhamento) para obcter mais informações.

Funções do Utilizador¶

Os utilizadores precisarão de funções de utilizador para interagir com os vários aplicativos no DHIS2. As seguintes funções mínimas são recomendadas:

1. Aggregate data analysis : Can access dashboards, data visualizer, pivot tables, reports and maps.
2. Aggregate data capture : Can acccess the data entry app and add/modify data values,

Consulte a Documentação DHIS2 para obter mais informações sobre a configuração de funções de usuário.

Organisation unit assignment¶

The data sets must be assigned to organisation units within existing hierarchy in order to be accessible for data entry and data analysis personnel.

Creating jobs in the scheduler¶

You will have to use the scheduler app in order to take advantage of the predictor and validation notification components of the package. You will need at least 3 jobs in the following order:

1. Predictor
2. Analytics Table
3. Monitoramento

You will want each job to complete before you run the next one (ie. the predictors should all be created before analytics starts; the monitoring job should only start after analytics is complete). Each DHIS2 implementation will need to review their configuration to determine the time it takes to run each of these jobs and schedule them accordingly. It is recommended that you have these run late at night when there is not much activity within your DHIS2 instance, as these are generally resource heavy operations.

A couple tips for each job type:

Predictor¶

Predictor jobs consist of a relative start and end date. This means you can run your predictors for the most recent period to generate the latest data that you need. This should be useful if your previous data is not being changed, as the other predicted values will already be generated and stored (and thus this process will not necessarily need to occur once more for those already generated values that are still valid). This is a particularly resource heavy operation, and if your previous data is not routinely changing, generating data for the most recent period that you need data for is the recommended approach.

You are also able to select specific predictors or predictor groups to run during the job. The predictor group for this package is simply called IDS. If you select multiple groups it will run the predictors in the order the groups are selected. You can read more about this within the DHIS2 documentation.

This needs to be the first job that starts in your sequence, and should finish before the next job (analytics) starts.

Analytics table¶

The analytics table job takes all of the raw data that has been entered and applies the necessary aggregation to it based on your configuration. If you are using an integrated system with multiple programs inside your instance, then you may already have an analytics table job scheduled to run at routine intervals. If this is the case, you may need to modify the period in which it runs so it can run after the predictor job has been completed.

This needs to be second job in your sequence, and should finish before the next job (monitoring) starts.

Monitoramento¶

Similar to the predictor, the monitoring job also consists of a relative start and end date. If your data is not changing during previous periods, you can run the monitoring job only for the period you need to review.

You can specify validation rule groups for the monitoring job. Create one monitoring job that runs weekly, using the validation rule group IDS - Weekly

If you want to send out the validation notifications, ensure that the "Send notifications" item is selected.

Sending out notifications¶

By default, notifications will be sent out to via the DHIS2 messaging app.

In order to send out notifications via SMS or e-mail, you will need an SMS gateway and/or an e-mail configuration set up within your DHIS2 instance. The settings necessary for these will vary between implementations and it is best to consult the documentation links provided here for more information.

Metadado 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 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”

Mesmo quando os metadados foram importados com sucesso sem nenhum conflito de importação, pode haver duplicação nos metadados - elementos de dados, atributos de entidade rastreados ou conjuntos de opções que já existem. Como foi observado na secção acima, sobre a resolução de conflitos, uma questão importante a ser lembrada é que as decisões sobre a alteração dos metadados no DHIS2 também precisam levar em consideração outros documentos e recursos que, de maneiras diferentes, estão associados aos metadados existentes, e os metadados que foram importados pelo pacote de configuração. Resolver duplicação é, portanto, não apenas uma questão de "limpar o banco de dados", mas também garantir que isso seja feito sem, por exemplo, quebrar o potencial de integração com outros sistemas, a possibilidade de usar material de treinamento, interromper SOPs, etc. tudo isto depende muito do contexto.

Uma coisa importante a se ter em mente é que o DHIS2 tem ferramentas que podem ocultar algumas das complexidades de possíveis duplicações em metadados. Por exemplo, onde existem conjuntos de opções duplicados, eles podem ser ocultados para grupos de usuários por meio de compartilhamento.

Adapting the program¶

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

• Acrescentando variáveis ​​adicionais ao formulário.
• Adapting data element names according to national conventions.
• Adicionando traduções às variáveis ​​e/ou ao formulário de entrada de dados.
• Modifying indicators based on local case definitions
• Adding dashboards/dashboard items

However, it is strongly recommended to take great caution if you decide to change or remove any of the included form/metadata. There is a danger that modifications could break functionality, for example predictors or notifications.

Removing metadata¶

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.