Hypertension Registry - Installation Guide¶
Instalace¶
Instalace modulu se skládá z několika kroků:
- Příprava souboru metadat s metadaty DHIS2.
- Import souboru metadat do DHIS2.
- Konfigurace importovaná metadata.
- Adaptace programu po importu
Před zahájením procesu instalace a konfigurace v DHIS2 se doporučuje nejprve si přečíst každou část. Byly identifikovány oddíly, které nelze použít, v závislosti na tom, zda importujete do nové instance DHIS2 nebo instance DHIS2 s již existujícími metadaty. Postup popsaný v tomto dokumentu by měl být testován v testovacím / fázovacím prostředí před opakováním nebo přenesením do produkční instance DHIS2.
Požadavky¶
K instalaci modulu je vyžadován uživatelský účet správce na DHIS2. Postup popsaný v tomto dokumentu by měl být testován v testovacím / fázovém prostředí před provedením na produkční instanci DHIS2.
Je třeba věnovat velkou pozornost tomu, aby byl samotný server a aplikace DHIS2 dobře zabezpečené, aby se omezil přístup ke shromažďovaným datům. Podrobnosti o zabezpečení systému DHIS2 jsou mimo rozsah tohoto dokumentu a odkazujeme na dokumentaci DHIS2.
Příprava souboru metadat¶
POZNÁMKA: Pokud instalujete balíček na novou instanci DHIS2, můžete přeskočit část „Příprava souboru metadat“ a okamžitě přejít do části „Import souboru metadat do DHIS2.“
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.
Výchozí dimenze dat¶
V dřívějších verzích DHIS2 byl automaticky vygenerován UID výchozí datové dimenze. Zatímco tedy všechny instance DHIS2 mají výchozí možnost kategorie, kategorii datových prvků, kombinaci kategorií a kombinaci možností kategorie, UID těchto výchozích hodnot se mohou lišit. Novější verze DHIS2 mají pevně zakódované UID pro výchozí dimenzi a tyto UID se používají v konfiguračních balíčcích.
Aby nedocházelo ke konfliktům při importu metadat, je vhodné vyhledat a nahradit celý soubor .json pro všechny výskyty těchto výchozích objektů a nahradit identifikátory UID souboru .json identifikátory UID databáze, do které bude soubor importován. Tabulka 1 ukazuje UID, která by měla být nahrazena, a také koncové body API pro identifikaci stávajících UID
| Objekt | UID | Koncový bod API |
|---|---|---|
| Kategorie | GLevLNI9wkl | ../api/categories.json?filter=name:eq:default |
| Možnost kategorie | xYerKDKCefk | ../api/categoryOptions.json?filter=name:eq:default |
| Kombinace kategorií | bjDvmb4bfuf | ../api/categoryCombos.json?filter=name:eq:default |
| Kombinace možností kategorie | HllvX50cXC0 | ../api/categoryOptionCombos.json?filter=name:eq:default |
Pokud například importujete konfigurační balíček do https://play.dhis2.org/demo, identifikátor UID výchozí kombinace možností kategorie lze identifikovat pomocí https://play.dhis2.org/demo/api/categoryOptionCombos.json?filter=name:eq:default jako bRowv6yZOF2.
Poté můžete vyhledat a nahradit všechny výskyty HllvX50cXC0 s bRowv6yZOF2 v souboru .json, protože to je ID výchozího v systému, do kterého importujete. Upozorňujeme, že tato operace hledání a nahrazení musí být provedena pomocí editoru prostého textu, nikoli pomocí textového editoru, jako je Microsoft Word.
Typy indikátorů¶
Typ indikátoru je další typ objektu, který může způsobit konflikt importu, protože se v různých databázích DHIS2 používají určité názvy (např. „Procento“). Vzhledem k tomu, že typy indikátorů jsou definovány jednoduše podle jejich faktoru a bez ohledu na to, zda se jedná o jednoduchá čísla bez jmenovatele, jsou jednoznačné a lze je nahradit pomocí vyhledávání a nahrazení UID. Tím se vyhnete možným konfliktům při importu a vyhnete se vytváření duplicitních typů indikátorů. Tabulka 2 ukazuje identifikátory UID, které lze nahradit, a také koncové body API pro identifikaci stávajících identifikátorů UID
| Objekt | UID | Koncový bod API |
|---|---|---|
| Pouze čitatel (číslo) | kHy61PbChXr | ../api/indicatorTypes.json?filter=number:eq:true&filter=factor:eq:1 |
| Procento | hmSnCXmLYwt | ../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:100 |
TrackedEntityType¶
Stejně jako typy indikátorů můžete mít ve své databázi DHIS2 již existující trasované typy entit. Odkazy na typ trasované entity by měly být změněny tak, aby odrážely to, co je ve vašem systému, abyste nevytvářeli duplikáty. Tabulka 3 ukazuje identifikátory UID, které lze nahradit, a také koncové body API pro identifikaci stávajících identifikátorů UID
| Objekt | UID | Koncový bod API |
|---|---|---|
| Osoba | MCPQUTHX1Ze | ../api/trackedEntityTypes.json?filter=name:eq:Person |
Visualizations using Root Organisation Unit¶
Visualizations, if included in a package, may contain a placeholder for a Root Organisation Unit. The placeholder label example is
Import metadat¶
Soubor metadat .json je importován prostřednictvím aplikace [Import/Export] (https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/maintaining-the-system/importexport-app.html) systému DHIS2. Před pokusem o skutečný import metadat je vhodné použít funkci „suchý běh“ k identifikaci problémů. Pokud „suchý běh“ hlásí nějaké problémy nebo konflikty, podívejte se do níže uvedené části konflikty importu. Pokud import „na sucho“/„ověření“ funguje bez chyby, zkuste importovat metadata. Pokud import proběhne bez chyb, můžete přejít ke konfiguraci modulu. V některých případech se konflikty importu nebo problémy nezobrazí během „suchého běhu“, ale zobrazí se při pokusu o skutečný import. V tomto případě bude v souhrnu importu uvedeny všechny chyby, které je třeba vyřešit.
Řešení konfliktů importu¶
POZNÁMKA: Pokud importujete do nové instance DHIS2, nebudete se muset starat o konflikty importu, protože v databázi, do které importujete, není nic, co by bylo v konfliktu. Při importu metadat postupujte podle pokynů, poté pokračujte do části „Další konfigurace“.
Může nastat řada různých konfliktů, i když nejběžnější je, že v konfiguračním balíčku jsou objekty metadat se jménem, zkratkou a / nebo kódem, který již v cílové databázi existuje. 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, pro který dojde ke konfliktu.
Alternativa 1¶
Přejmenujte existující objekt v databázi DHIS2, u kterého došlo ke konfliktu. Výhodou tohoto přístupu je, že není nutné upravovat soubor .json, protože změny se místo toho provádějí prostřednictvím uživatelského rozhraní DHIS2. Pravděpodobně to bude méně náchylné k chybám. To také znamená, že konfigurační balíček je ponechán tak, jak je, což může být výhodou, například když se použije školicí materiál a dokumentace založená na konfiguračním balíčku.
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.
Všimněte si, že pro alternativu 1 i 2 může být modifikace stejně jednoduchá jako přidání malého pre / post-fix k názvu, aby se minimalizovalo riziko záměny.
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:
- vyžaduje odborné znalosti podrobné struktury metadat DHIS2
- přístup nefunguje u všech typů objektů. Zejména určité typy objektů mají závislosti, které se tímto způsobem komplikovaně řeší, například v souvislosti s rozčleněními.
- budoucí aktualizace konfiguračního balíčku budou komplikované.
Known Import Issues¶
- Sort order for options do not match Symptoms: import fails with no errors. Please check the dhis.log in your server/instance. If you see the following error:
* ERROR 2021-07-15 10:05:58,018 java.lang.NullPointerException at org.hisp.dhis.dxf2.metadata.objectbundle.hooks.OptionSetObjectBundleHook.lambda$updateOption$0(OptionSetObjectBundleHook.java:71) at java.lang.Iterable.forEach(Iterable.java:75)
The issue is related to sortOrder of options in an optionSet included in the package not matching the sortOrder of same options in the instance/server. 2. Duplicate key value violates unique constraint Symptoms: import fails with no errors. Please check the dhis.log in your server/instance. If you see the following error:
* ERROR 2021-07-15 10:12:20,272 ERROR: duplicate key value violates unique constraint "uk_myox13mr8r27oxl7ts33ntpd5" Detail: Key (uid)=(YYtAbckt77l) already exists. (SqlExceptionHelper.java [taskScheduler-23]) * ERROR 2021-07-15 10:12:20,303 javax.persistence.PersistenceException: org.hibernate.exception.ConstraintViolationException: could not execute statement
Další 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í¶
Nejprve budete muset pomocí funkce Sdílení DHIS2 konfigurovat, kteří uživatelé (skupiny uživatelů) by měli vidět metadata a data spojená s programem a kdo může registrovat / zadávat data do programu. Ve výchozím nastavení bylo sdílení nakonfigurováno pro následující:
- Typ trasované entity
- Program
- Fáze programu
- Ovládací panely
Balíček obsahuje tři skupiny uživatelů:
- HTN access
- HTN admin
- HTN data capture
Ve výchozím nastavení je těmto skupinám uživatelů přiřazeno následující
| Objekt | Uživatelská skupina | ||
|---|---|---|---|
| Access | Admin | Data capture | |
| Typ trasované entity | Metadata : lze zobrazit Data: lze zobrazit | Metadata: lze upravovat a prohlížet Data: lze zobrazit | Metadata: lze zobrazit Data: lze zachytit a zobrazit |
| Program | Metadata : lze zobrazit Data: lze zobrazit | Metadata: lze upravovat a prohlížet Data: lze zobrazit | Metadata: lze zobrazit Data: lze zachytit a zobrazit |
| Fáze programu | Metadata : lze zobrazit Data: lze zobrazit | Metadata: lze upravovat a prohlížet Data: lze zobrazit | Metadata: lze zobrazit Data: lze zachytit a zobrazit |
| Ovládací panely | Metadata : lze zobrazit Data: lze zobrazit | Metadata: lze upravovat a prohlížet Data: lze zobrazit | Metadata : lze zobrazit Data: lze zobrazit |
Budete chtít přiřadit své uživatele k příslušné skupině uživatelů na základě jejich role v systému. V závislosti na vašem nastavení můžete chtít povolit sdílení pro jiné objekty v balíčku. Další informace o konfiguraci sdílení najdete v dokumentaci DHIS2.
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:
- Analýza dat trasovače: Může zobrazit analytiku událostí a přistupovat k ovládacím panelům, zprávám o událostech, vizualizátorům událostí, vizualizátorům dat, kontingenčním tabulkám, zprávám a mapám.
- Zachycování dat Trasovače: Může přidávat datové hodnoty, aktualizovat trasované entity, prohledávat trasované entity napříč organizačními jednotkami a přistupovat k zachycení trasovačů
Další informace o konfiguraci rolí uživatelů najdete v dokumentaci DHIS2.
Organizační jednotky¶
Program musíte přiřadit organizačním jednotkám v rámci vaší vlastní hierarchie, aby bylo možné program vidět v záznamu trasovače.
Duplikovaná metadata¶
POZNÁMKA: Tato část platí pouze v případě, že importujete do databáze DHIS2, ve které již existují metadata. Pokud pracujete s novou instancí DHIS2, přeskočte tuto část a přejděte na Přizpůsobení trasovacího programu.“
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.
Jedna důležitá věc, kterou je třeba mít na paměti, je, že DHIS2 má nástroje, které mohou skrýt některé složitosti potenciálních duplikací v metadatech. Například tam, kde existují duplicitní sady možností, mohou být skryty pro skupiny uživatelů prostřednictvím sdílení.
Přizpůsobení trasovacího programu¶
Po importu programu můžete provést určité úpravy programu. Mezi příklady místních úprav, které lze provést, patří:
- 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ů.
- Úprava indikátorů programu na základě místních definic 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.