Education Toolkit Installation Guide¶

Přehled¶

Soubory json metadat balíčku obsahují komponentu „balíček“, která poskytuje technické podrobnosti o verzi a obsahu balíčku. Níže jsou uvedeny soubory dostupné v aktuální verzi balíčku.

Instalace¶

Instalace modulu se skládá z několika kroků:

1. Preparing the metadata file with DHIS2 metadata

2. Importing the metadata file into DHIS2

3. Configuring the imported metadata

4. Úprava programu po importu

Před zahájením procesu instalace a konfigurace v DHIS2 se doporučuje nejprve přečíst každou část instalační příručky. Identifikujte příslušné sekce v závislosti na typu vašeho importu:

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.

Požadavky¶

Pro instalaci modulu je vyžadován uživatelský účet správce na DHIS2.

Velkou péči je třeba věnovat tomu, aby byl server samotný i aplikace DHIS2 dobře zabezpečeny, měla by být definována přístupová práva ke shromážděným datům. Podrobnosti o zabezpečení systému DHIS2 jsou mimo rozsah tohoto dokumentu a odkazujeme na dokumentaci DHIS2.

Metadata files¶

I když to není vždy nutné, může být často výhodné provést určité úpravy souboru metadat před jeho importem do DHIS2.

Příprava souboru metadat¶

Před importem souboru metadat je nutné provést některé změny. Rozsah práce se může balíček od balíčku lišit.

Výchozí dimenze dat¶

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

Objekt	UID	API Endpoint
Kategorie	GLevLNI9wkl	../api/categories.json?filter=name:eq:default
Možnost kategorie	xYerKDKCefk	../api/categoryOptions.json?filter=name:eq:default
Category Combination	bjDvmb4bfuf	../api/categoryCombos.json?filter=name:eq:default
Kombinace možností kategorie	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.

Import metadat¶

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.

Řešení konfliktů importu¶

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.

Může dojít k řadě různých konfliktů, i když nejběžnějším je, že v konfiguračním balíčku jsou objekty metadat s názvem, zkratkou a/nebo kódem, které již v cílové databázi existují. Existuje několik alternativních řešení těchto problémů s různými výhodami a nevýhodami. Který z nich je vhodnější, bude záviset například na typu objektu, u kterého ke konfliktu dojde.

Alternativa 1¶

Přejmenujte existující objekt v databázi DHIS2, u kterého existuje konflikt. Výhodou tohoto přístupu je, že není potřeba upravovat soubor .json, protože změny se místo toho provádějí prostřednictvím uživatelského rozhraní DHIS2. To bude pravděpodobně méně náchylné k chybám. To také znamená, že konfigurační balíček zůstane tak, jak je, což může být výhodou například při vydání aktualizací balíčku. Na původní objekty balíčku se také často odkazuje ve školicích materiálech a dokumentaci.

Alternativa 2¶

Přejmenujte objekt, u kterého došlo ke konfliktu v souboru .json. Výhodou tohoto přístupu je, že stávající metadata DHIS2 jsou ponechána tak, jak jsou. To může být faktor, když existuje školicí materiál nebo dokumentace, jako jsou SOP datových slovníků propojených s daným objektem, a to nezahrnuje žádné riziko záměny uživatelů úpravou metadat, se kterými jsou obeznámeni.

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¶

Třetím a komplikovanějším přístupem je úprava souboru .json pro opětovné použití existujících metadat. Například v případech, kdy pro určitý koncept již existuje sada možností (např. „Pohlaví“), by tato sada možností mohla být odstraněna ze souboru .json a všechny odkazy na jeho UID nahrazeny odpovídající sadou možností již v databázi. Velkou výhodou tohoto (která se neomezuje na případy přímého konfliktu importu) je vyhnout se vytváření duplicitních metadat v databázi. Při provádění tohoto typu modifikace je třeba provést několik klíčových úvah:

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

Konfigurace¶

Po úspěšném importu všech metadat existuje několik kroků, které je třeba provést, než bude modul funkční.

Sdílení¶

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:

• Ovládací panely
• Vizualizace, mapy, zprávy o událostech a tabulky zpráv
• Datové sady
• Možnosti kategorie

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

Balíčky obsahují tři základní skupiny uživatelů:

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

Uživatelské role¶

Uživatelé budou potřebovat uživatelské role, aby mohli pracovat s různými aplikacemi v rámci DHIS2. Doporučují se následující minimální role:

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¶

Sady dat musí být přiřazeny organizačním jednotkám v rámci existující hierarchie, aby byly přístupné prostřednictvím aplikace pro zachycení.

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.

Duplikovaná metadata¶

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”

I když byla metadata úspěšně importována bez jakýchkoli konfliktů při importu, v metadatech mohou existovat duplikáty - datové prvky, trasované atributy entit nebo sady voleb, které již existují. Jak bylo uvedeno v části výše o řešení konfliktů, je třeba mít na paměti důležitý problém, že rozhodnutí o provádění změn metadat v DHIS2 musí také zohledňovat další dokumenty a zdroje, které jsou různými způsoby spojeny s existujícími metadaty a metadata, která byla importována prostřednictvím konfiguračního balíčku. Vyřešení duplikátů tedy není jen otázkou „vyčištění databáze“, ale také zajištěním toho, aby se tak dělo například bez narušení potenciálu integrace s jinými systémy, možnosti použít školicí materiál, rozbití SOP atd. To bude velmi záviset na kontextu.

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:

• Přidání dalších proměnných do formuláře.

• Přizpůsobení názvů datových prvků / možností podle národních konvencí.

• Přidávání překladů do proměnných nebo do formuláře pro zadávání údajů.

• Modifikace ukazatelů na základě definic místních případů

Důrazně se však doporučuje věnovat velkou pozornost, pokud se rozhodnete změnit nebo odebrat některý ze zahrnutých formulářů / metadat. Existuje nebezpečí, že by úpravy mohly narušit funkčnost, například pravidla programu a indikátory programu.

Removing metadata¶

Aby byla vaše instance čistá a předešlo se chybám, doporučuje se z instance odstranit nepotřebná metadata. Odstranění nepotřebných metadat vyžaduje pokročilé znalosti DHIS2 a různých závislostí.