WHO Anti-Tuberculosis Drugs Resistance Survey (DRS) - Tracker Installation Guide¶

Package Version 1.0.1

System default language: English

Available translations: French, Spanish, Portuguese

Visão Geral¶

Os arquivos json de metadados do pacote contêm um componente "pacote" que fornece detalhes técnicos sobre a versão e o conteúdo do pacote. Os arquivos disponíveis na versão actual do pacote estão listados abaixo.

DHIS2.35¶

"package": {
    "DHIS2Build": "35d663a",
    "DHIS2Version": "2.35.11",
    "code": "TBDR00",
    "description": "Anti-Tuberculosis Drug Resistance Survey (DRS)",
    "lastUpdated": "20220124T083253",
    "locale": "en",
    "name": "TB_DRS_TKR_1.0.1_DHIS2.35.11-en",
    "type": "TKR",
    "version": "1.0.1"
}

DHIS2.36¶

"package": {
    "DHIS2Build": "5d136cb",
    "DHIS2Version": "2.36.6",
    "code": "TBDR00",
    "description": "Anti-Tuberculosis Drug Resistance Survey (DRS)",
    "lastUpdated": "20220124T073407",
    "locale": "en",
    "name": "TB_DRS_TKR_1.0.1_DHIS2.36.6-en",
    "type": "TKR",
    "version": "1.0.1"
}

When importing this package into a new/blank instance, please refer to the DHIS2 installation guide.

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. [Configurando] (# configuração-adicional) os metadados importados.
4. Adaptando o programa depois de ser importado

Recomenda-se ler primeiro cada secção antes de iniciar o processo de instalação e configuração no DHIS2. As secções que não são aplicáveis ​​foram identificadas, dependendo se estiver a importar para uma nova instância do DHIS2 ou uma instancia DHIS2 com metadados já presentes. O procedimento descrito neste documento deve ser testado em um ambiente de teste / preparado antes de ser repetido ou transferido para uma instância de produção do DHIS2.

Requisitos¶

Para instalar o módulo, precisa-se de uma conta de usuário administrador no DHIS2. O procedimento descrito neste documento deve ser testado em um ambiente de teste / preparo antes de ser executado em uma instância de produção do DHIS2.

Great care should be taken to ensure that the server itself and the DHIS2 application is well secured, to restrict access to the data being collected. Details on securing a DHIS2 system is outside the scope of this document, and we refer to the DHIS2 documentation.

Preparando o ficheiro de metadados¶

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 Importing a metadata file into DHIS2

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.

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:

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:

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

Dashboards and visualizations¶

The dashboards and visualizations in each dashboard cannot be hidden/unhidden by constants. Therefore the unapplicable dashboards/visualizations have to be manually removed during package installation based on the selection of tests/drugs.

Visualizations in the metadata file may contain a placeholder . This placeholder in the metadata.json file has to be replaced by the Root Organisation unit UID from the target instance before the package can be imported.

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. The table below provides an overview of such items included in the package. 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.

Exemplo:

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 adicional¶

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

• Tipo de entidade rastreada
• Programa
• Estagios de Programa
• Painéis

There are four user groups that come with the package:

• DRS - admin
• DRS - access
• DRS - data capture

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

You will want to assign your users to the appropriate user group based on their role within the system. You may want to enable sharing for other objects in the package depending on your set up. Refer to the DHIS2 Documentation for more information on configuring sharing.

User roles¶

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 a configuração de funções de usuário.

Organisation units¶

O programa e os conjuntos de dados devem ser atribuídos a unidades de organização dentro da hierarquia existente para serem acessíveis por meio de aplicativos de captura/captura do rastreador.

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.

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.

Constantes¶

WHO Anti-Tuberculosis Drugs Resistance Survey (DRS) Tracker package includes a set of tests and a list of drugs that can be modified by the implementing country according to national context (e.g. which drugs and tests are used/available in country). The use of constants and corresponding program rules enables a system admin in an implementing country to easily ‘turn on’ or ‘turn off’ types of drugs and tests depending on availability. When the complete package is installed into a DHIS2 instance, all data elements for all tests and drugs included in this package are included in the system. All constant values are initially set to 1 (enabling the related data elements for data entry) and can be set to 0 by an implementer or system admin according to country context if not needed (disabling the related data elements for data entry). If a test or drug later becomes available, the admin can simply re-enable the data elements by changing the constant from a value of 0 to a value of 1.

Cluster Sampling / Exhaustive Sampling of all Health Facilities¶

Configure whether the country is using Cluster Sampling or Exhaustive Sampling of all Health Facilities

Number of DRS Samples sent to NRL¶

Configure the number of samples are sent to NRL processing

Initial Screening Tests¶

Configure which initial screening tests are used for bacteriological confirmation of TB: Sputum Smear Microscopy, Xpert MTB/RIF or both.

SRL Sample Processing¶

Configure whether the country has an option of sending samples to SRL (supranational lab).

Tests at NRL¶

List of Available Drugs¶

Please note, that the constants help to hide certain sections and data element from the data entry without the need to delete them from the system/metadata.json file. However, the elements are still assigned to the program and will be included when exporting all data into eg. csv files.

Configuring tracker capture interface, widgets and top bar¶

You must configure tracker capture dashboard after the package has been installed. This configuration includes data entry forms, widgets and top bar.

Formulários de entrada de dados¶

• After registering the first (test) case, access the Settings menu in the tracker capture form and select Show/Hide Widgets
• Switch from Timeline Data Entry to Tabular Data Entry
• Make sure that Enrollment, Feedback and Profile widgets are selected. Click Close.
• Adjust the widgets on the screen.

Top Bar¶

• Access the Settings menu and select Top bar settings
• Select Activate top bar
• Select required information fields and assign their Sort order

• Clique em ** Salvar **
• Return to the Settings menu. Click Saved dashboard layout as default. Lock layout for all users.

Adaptando o programa rastreador¶

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:

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