Education Toolkit Installation Guide¶

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.

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. Adapting the program after import

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.

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¶

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.

Preparando o ficheiro de metadados¶

It is required to apply some changes to the metadata file before it can be imported. The scope of work may vary from package to package.

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.

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

Objecto	UID	API Endpoint
Category	GLevLNI9wkl	../api/categories.json?filter=name:eq:default
Category option	xYerKDKCefk	../api/categoryOptions.json?filter=name:eq:default
Category Combination	bjDvmb4bfuf	../api/categoryCombos.json?filter=name:eq:default
Category option combination	HllvX50cXC0	../api/categoryOptionCombos.json?filter=name:eq:default

Visualizations using Root Organisation Unit UID¶

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.

Importando metadados¶

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.

Manipulando conflitos de importação¶

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.

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.

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¶

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:

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

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

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

Three core user groups are included in the packages:

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

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

Organisation unit assignment¶

The data sets must be assigned to organisation units within existing hierarchy in order to be accessible via capture app.

Indicator mapping¶

When implementing the dashboard package only, the indicator numerators and denominators have to be configured using the metadata objects in the existing instance. Configuration information is available in the documentation and the description of numerators and denominators in the metadata file.

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

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.

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:

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

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.