TB Household Investigation Installation Guide¶

Verze balíčku 1.0.0

Výchozí jazyk systému: angličtina

Instalace¶

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

1. Příprava souboru metadat.
2. Import souboru metadat do DHIS2.
3. Configuring the imported metadata.
4. Adaptace 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 (No other versions of TB Case Surveillance tracker imported previously).
3. Update existing/older version of the TB Case Surveillance tracker.

Kroky popsané v tomto dokumentu by měly být otestovány v testovací instanci DHIS2 a teprve poté aplikovány na produkční prostředí.

Požadavky¶

In order to install the module, a DHIS2 administrator user account is required.

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¶

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.

Příprava souboru metadat¶

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

Výchozí dimenze dat¶

V dřívějších verzích DHIS2 byla UID výchozích datových dimenzí automaticky generována. I když tedy všechny instance DHIS2 mají výchozí volbu 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 tato UID se používají v konfiguračních balíčcích.

Aby se předešlo 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 UID souboru .json UID z instance, 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

Identifikujte UID výchozích dimenzí ve vaší instanci pomocí uvedených požadavků API a nahraďte UID v souboru json UID z instance.

POZNÁMKA

Pamatujte, že tato operace hledání a nahrazování musí být provedena pomocí editoru prostého textu, nikoli textového procesoru, jako je Microsoft Word.

Typy indikátorů¶

Typ indikátoru je dalším typem objektu, který může způsobit konflikt importu, protože určitá jména se používají v různých databázích DHIS2 (např. "Procento"). Vzhledem k tomu, že typy indikátorů jsou definovány svým faktorem (včetně 1 pro indikátory „pouze čitatel“), jsou jednoznačné a lze je nahradit vyhledáváním a nahrazováním UID. Tato metoda pomáhá vyhnout se potenciálním konfliktům při importu a zabraňuje implementátoru ve vytváření duplicitních typů indikátorů. Níže uvedená tabulka obsahuje UID, která lze nahradit, a také koncové body API pro identifikaci stávajících UID:

TrackedEntityType¶

Stejně jako typy indikátorů můžete mít ve své databázi DHIS2 již existující typy trasovaných entit. Odkazy na typ trasované entity by se měly změnit tak, aby odrážely to, co je ve vašem systému, abyste nevytvářeli duplikáty. Níže uvedená tabulka obsahuje UID, která lze nahradit, a také koncové body API pro identifikaci stávajících UID:

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.

Pro hodnoty datových prvků použijte:

```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>;
```

POZNÁMKA

Při aktualizaci UID prvku metadat ve stávající instanci DHIS2 budete muset spustit příkaz SQL v databázi a dodatečně nahradit všechny výskyty a odkazy jeho UID v jiných objektech metadat: prediktor, indikátor, výrazy ověřovacích pravidel atd. .

Sort order of options¶

Zkontrolujte, zda pořadí řazení sortOrder možností ve vašem systému odpovídá pořadí řazení možností obsažených v balíčku metadat. To platí pouze v případě, že soubor json a cílová instance obsahují volby a sady voleb se stejným UID.

After import, make sure that the sort order of options within an option set starts at 1. There should be no gaps (eg. 1,2,3,5,6) in the sort order values.

Pořadí řazení lze upravit v aplikaci Údržba.

1. Přejděte na příslušnou sadu možností
2. Otevřete sekci „Možnosti“.
3. Použijte alternativy "ŘADIT PODLE JMÉNA", "ŘADIT PODLE KÓDU/HODNOTY" nebo "ŘADIT RUČNĚ".

Make sure that no options within an option set have the same sort order. This can be checked using the following api endpoint:

../api/options.json?paging=false&fields=id,name,sortOrder&filter=optionSet.id:in:[<optionSet UID>]

In order to fix sort order in option sets containing large numbers of options, please refer to this SQL script.

Visualizations using Root Organisation Unit UID¶

Vizualizace, sestavy událostí, tabulky sestav a mapy, které jsou přiřazeny konkrétní úrovni organizační jednotky nebo skupině organizačních jednotek, mají odkaz na kořenovou organizační jednotku (úroveň 1). Takové objekty, pokud jsou v souboru metadat přítomny, obsahují zástupný symbol <OU_ROOT_UID>. Použijte funkci vyhledávání v editoru souborů .json k případné identifikaci tohoto zástupného symbolu a jeho nahrazení UID organizační jednotky úrovně 1 v cílové instanci.

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 process of upgrading an existing package to a newer version in a working DHIS2 instance is a complex operation that has to be taken with precaution. Such process has to be run in development and staging instances first, before upgrading the configuration on the production server. As metadata objects may have been removed, added or changed, it is important to ensure that:

• the format of existing data can be mapped and adjusted to the new configuration;
• the discontinued metadata objects are deleted from the instance;
• The existing objects are updated;
• the new objects are created;
• assignment of users to relevant user groups is reviewed.

Import metadat¶

K importu balíčků metadat použijte aplikaci Import/Export DHIS2. Před pokusem o skutečný import metadat je vhodné použít funkci „suchého běhu“ k identifikaci problémů. Pokud "suchý běh" nahlásí nějaké problémy nebo konflikty, podívejte se do sekce konflikty importu níže. Pokud import „suché spuštění“/„ověření“ funguje bez chyby, pokuste se importovat metadata. Pokud import proběhne bez chyb, můžete přistoupit ke konfiguraci modulu. V některých případech se konflikty nebo problémy při importu nezobrazí během „suchého běhu“, ale objeví se při pokusu o vlastní import. V tomto případě budou v souhrnu importu uvedeny všechny chyby, které je třeba vyřešit.

Řešení konfliktů importu¶

POZNÁMKA

Pokud importujete balíček do nové instance DHIS2, nezaznamenáte konflikty importu, protože v cílové databázi nejsou žádná metadata. Po importu metadat přejděte k části „Konfigurace“.

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.

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

Linking the TB Household Contacts Investigation package to an existing TB Case Surveillance module¶

This section provides guidance on adding the TB Household Contacts Investigation packag to the functioning instance with the TB CS tracker.

For existing implementations, direct upgrade of metadata packages in the instance is not recommended.

TB Household Contacts Investigation package reuses several metadata objects from the TB Case Surveillance package. These include tracked entity type, tracked entity attributes, data elements, option sets, options and user groups. Comparing metadata reference files for both packages will help the user identify these elements before merging baseline metadata in the instance with the metadata objects in the package.

It is recommended to use version 2.1.0 of the TB Case Surveillance package when linking it with the TB Household Contacts Investigation module. The configuration of the relationship type to support enrollment of the household contacts through the relationship widget in the TB Case Surveillance tracker is described below.

{
    "relationshipTypes": [
        {
            "code": "TB_CS_INDEX_HH",
            "name": "TB - Index case --> Household contact",
            "externalAccess": false,
            "publicAccess": "rw------",
            "userGroupAccesses": [],
            "userAccesses": [],
            "access": {
                "manage": true,
                "externalize": true,
                "write": true,
                "read": true,
                "update": true,
                "delete": true,
                "data": {
                    "write": true,
                    "read": true
                }
            },
            "favorites": [],
            "sharing": {
                "owner": "Ia1Xtxa5eG8",
                "external": false,
                "users": {},
                "userGroups": {},
                "public": "rw------"
            },
            "fromConstraint": {
                "relationshipEntity": "TRACKED_ENTITY_INSTANCE",
                "trackedEntityType": {
                    "id": "MCPQUTHX1Ze"
                },
                "program": {
                    "id": "Lt6P15ps7f6"
                },
                "trackerDataView": {
                    "attributes": [
                        "sB1IHYu2xQT",
                        "ENRjVGxVL6l",
                        "Ewi7FUfcHAD"
                    ],
                    "dataElements": []
                }
            },
            "toConstraint": {
                "relationshipEntity": "TRACKED_ENTITY_INSTANCE",
                "trackedEntityType": {
                    "id": "MCPQUTHX1Ze"
                },
                "program": {
                    "id": "cQsXTtAJ3HW"
                },
                "trackerDataView": {
                    "attributes": [
                        "Ewi7FUfcHAD",
                        "sB1IHYu2xQT",
                        "ENRjVGxVL6l"
                    ],
                    "dataElements": []
                }
            },
            "description": "Household contacts of confirmed TB cases",
            "bidirectional": true,
            "fromToName": "Household contact",
            "toFromName": "Index case",
            "referral": false,
            "displayFromToName": "Household contact",
            "displayToFromName": "Index case",
            "displayName": "TB - Index case --> Household contact",
            "favorite": false,
            "id": "l0wf8ZWv9nX",
            "attributeValues": []
        }
    ]
}

1. For the TB Case:

1. For the Household contact:

It is possible to edit the list of displayed attributes in the relationship widget.

Tracked Entity Attributes that are displayed in the relationship widget have to be assigned to the Tracked Entity Type. 'Display in list' option has to be activated for them.

Tracked Entity Attributes to be displayed in the relationship widget have to be assigned to the corresponding programmes.

'Display in list without program' option has to be activated for the relevant Tracked Entity Attributes.

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:

• Dashboards (Visualizations, maps, event reports and report tables)
• Datové sady
• Možnosti kategorie
• Programy a fáze programu

Tyto základní skupiny uživatelů jsou součástí balíčku:

• TB admin
• TB přístup
• Sběr dat TB

Ve výchozím nastavení je těmto skupinám uživatelů přiřazeno následující

Uživatelé musí být přiřazeni do příslušné skupiny uživatelů na základě jejich role v systému. Sdílení pro další objekty v balíčku by mělo být nastaveno v závislosti na požadavcích. Další informace o konfiguraci sdílení naleznete 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:

1. 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.
2. 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 uživatelských rolí naleznete v Dokumentaci DHIS2.

Organizační jednotky¶

Program musí být přiřazen k příslušným organizačním jednotkám v rámci hierarchie organizačních jednotek.

Duplikovaná metadata¶

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”

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.

Konfigurace rozhraní pro snímání trasovače, widgetů a horní lišty¶

Tracker capture dashboard must be configured after the package has been installed. This configuration includes data entry forms, widgets and top bar.

Formuláře pro zadávání údajů¶

• Po registraci prvního (testovacího) případu přejděte do nabídky Nastavení ve formuláři pro zachycení trasovače a vyberte Zobrazit / Skrýt widgety
• Use Tabular Data Entry
• Make sure that Enrollment, Feedback, Profile and Relationships widgets are selected. Click Close.
• Click "Saved dashboard layout as default"
• Click "Lock layout for all users"

Horní lišta¶

Top bar activation and configuration allows the user to have a clear overview of key case data displayed at the top of the tracker capture dashboard.

Reporting case-based data into aggregate data sets¶

The TB Household Contacts Investigation tracker includes an Aggregate Data Exchange configuration that can aggregate case-based data and populate the quarterly "TB Household Contacts" data sets included in the TB HMIS package.

The program indicators are mapped with data elements and category option combinations in the aggregate package.

The default configuration is set to internal data exchange, i.e. when the tracker and the aggregate data sets are located in the same instance. It is possible to change this configuration in the json component. The user working with data exchange has to have access to both tracker and aggregate data. More information can be found in the Data Exchange documentation

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é by se mohly 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.