TB Case Surveillance Tracker Installation Guide¶

Package Version 3.0.0

System default language: English

Instalação¶

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

1. Preparing the metadata file.
2. Importando o ficheiro de metadados no DHIS2.
3. Configuring the imported metadata.
4. Adaptando o programa depois de ser importado

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 including previous or other versions of TB Case Surveillance tracker.

NOTE

Note that it this version of the TB Case Surveillance tracker is not designed to be merged with an existing previous version. It can be imported as an independent module and is configured to replace any previous versions.

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

Metadata files¶

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

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

Preparando o ficheiro de metadados¶

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

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 dimensions 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:

Tipo de entidade rastreada¶

Assim como os tipos de indicadores, pode já ter tipos de entidade rastreados em seu banco de dados DHIS2. As referências ao tipo de entidade rastreada devem ser alteradas para refletir o que está em seu sistema para que não crie duplicatas. A tabela abaixo contém os UIDs que podem ser substituídos, bem como os endpoints da API para identificar os UIDs existentes:

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.

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.

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.

Upgrading metadata package¶

The current module cannot be merged with an existing configuration of the TB Case Surveillance tracker. While the UIDs of many tracked entity attributes, data elements, option sets and options have been kept the same, the UIDs of the program, program stages, program stage sections, program rules and certain other objects have changed. The treatment and the outcome program stages have been merged into one for the purpose of supporting the new guidelines for TB surveillance.

Importando metadados¶

Use o aplicativo Import/Export DHIS2 para importar pacotes de metadados. É aconselhável usar o recurso "dry run" para identificar problemas antes de tentar fazer uma importação real dos metadados. Se o "dry run" relatar problemas ou conflitos, consulte a secção conflitos de importação abaixo. Se a importação "dry run"/"validate" funcionar sem erros, tente importar os metadados. Se a importação for bem-sucedida sem erros, pode continuar configurando o módulo. Em alguns casos, conflitos ou problemas de importação não são mostrados durante o "dry run", mas aparecem quando a importação real é tentada. Nesse caso, o resumo de importação listará todos os erros que precisam ser resolvidos.

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
• Programs and program stages

These core user groups are included in the package:

• Administrador de TB
• Acesso TB
• TB lab access
• Captura de dados TB
• TB lab data capture

Por padrão o seguinte é atribuído a esses grupos de utilizadores.

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.

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. Análise de dados do rastreador: pode ver análises de eventos e aceder a painéis, relatórios de eventos, visualizador de eventos, visualizador de dados, tabelas dinâmicas, relatórios e mapas.
2. Captura de dados rastreados : Pode adicionar valores de dados, actualizar entidades rastreadas, pesquisar entidades rastreadas nas unidades organizacionais e acessar Track capture

Consulte a Documentação DHIS2 para obter mais informações sobre como configurar funções de utilizador

Unidades organizacionais¶

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

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

Program notifications¶

TB CS Tracker 3.0.0 includes 3 notification templates that can be edited based on local requirements. Additional configuration for setting up SMS or email notifications is required.

Reporting case-based data into aggregate data sets¶

The TB case-based surveillance tracker captures data that can be fed into standard, aggregate reporting forms (i.e. monthly, quarterly, yearly or as determined by the country). This package contains preconfigured program indicators and aggregate data exchanges that are mapped to the newest Aggregate DHIS2 TB HMIS package.

The program indicators in the TB Case Surveillance and Laboratory package are mapped with data elements and category option combinations in the DHIS2 TB aggregate package (Notifications, Outcomes, Laboratory).

Configuration of automated aggregate data exchanges requires the following steps:

1. Review program indicators Make sure that the program indicators required for the aggregate data exchange are configured properly and reference correct data elements and category option combinations

2. Review aggregate data exchanges Make sure the aggregate data exchanges are configured properly, the period for data aggregation matches the required period, and correct program indicators are referenced in the request.

3. Review required data element groups Make sure the data elements used in the data set are added to a corresponding data element group. Take a note of the data element group uid. We will use D2spytmv9am as an example.

4. Configure predictors for each data element group. Predictors will be used to reset data values in the aggregate data sets before running an aggregate data exchange for a specific period. An example of a predictor can be found below:

"code": "CODE",
"name": "Name",
"shortName": "Short Name",
"output": {
  "id": "[Any data element UID can be used here. It will only serve as a placeholder. No data will be posted to this data element]"
},
"generator": {
 "expression": "forEach ?de in :DEG:D2spytmv9am --> if((isNull(#{?de})),#{?de},0)",
 "description": "Description",
 "slidingWindow": false,
 "missingValueStrategy": "NEVER_SKIP",
},
"periodType": "[Data set period]",
"organisationUnitLevels": [
 {
   "id": "[Organisation unit level uid]"
 }
],
"organisationUnitDescendants": "SELECTED",
"sequentialSampleCount": 0,
"annualSampleCount": 0

1. Configure scheduled jobs/job queues to run aggregate data exchanges. The order of scheduled jobs has to be configured as listed below:

   1. Run "Predictor" job/s for the required period.
   2. Run "Analytics table" job/s
   3. Run "Exchange aggregate data" job/s
   4. Run "Analytics table" job/s

Adaptando o programa rastreador¶

Depois que o programa for importado, convém fazer certas modificações no programa. Exemplos de adaptações locais que * poderiam * ser feitas incluem:

• Acrescentando variáveis ​​adicionais ao formulário.
• Adaptar os nomes de elemento de dados/opções de acordo com convenções nacionais.
• Adicionando traduções às variáveis ​​e/ou ao formulário de entrada de dados.
• Modifying program indicators based on local case definitions.

Contudo, é recomendável ter cuidado ao alterar ou remover qualquer um dos formulários/metadados incluídos. Existe o perigo de que as modificações possam interromper a funcionalidade, por exemplo, regras e indicadores do programa.