IDS - Integrated Disease Surveillance Installation Guide¶

This document includes an installation guide for the IDS aggregate package.

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

Available translations: French

Přehled¶

The metadata reference and metadata json files provide technical details on package version and content.

The metadata package consists of the following modules:

• Integrated Disease Surveillance
• Integrated Disease Surveillance (dashboard)

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. Přizpůsobení 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. importovat do prázdné instance DHIS2
2. importovat do instance DHIS2 s existujícími metadaty.

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¶

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.

Preparing the Metadata File¶

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:

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.

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:

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

Sort order for 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.

Po importu se ujistěte, že pořadí řazení možností v sadě možností začíná na 1. V hodnotách pořadí řazení by neměly být žádné mezery (např. 1,2,3,5,6).

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

The IDS package contains one option set and two options:

{
    "optionSets": [
        {
            "name": "YES/NO (numeric)",
            "id": "TdDqpX1kdd2",
            "code": "YES_NO_NUM",
            "valueType": "INTEGER_ZERO_OR_POSITIVE",
            "options": [
                {
                    "id": "VavIEUmBv8j"
                },
                {
                    "id": "Xu8ieCbS7jH"
                }
            ]
        }
    ],
    "options": [
        {
            "name": "Yes",
            "id": "VavIEUmBv8j",
            "code": "1",
            "sortOrder": 1,
            "optionSet": {
                "id": "TdDqpX1kdd2"
            }
        },
        {
            "name": "No",
            "id": "Xu8ieCbS7jH",
            "code": "0",
            "sortOrder": 2,
            "optionSet": {
                "id": "TdDqpX1kdd2"
            }
        }
    ]
}

This Yes/No option set is based on "INTEGER_ZERO_OR_POSITIVE" option values that are assigned to two data elements and evaluated in a predictor listed below:

Population data¶

The IDS package includes data elements, indicators and other metadata objects that are related to population data.

If the target instance already has metadata infrastructure, which is used for collecting Population data, please refer to the steps listed below:

1. Zvolte strategii pro zarovnání metadat populace v cílové instanci a v souboru .json.
2. Alternativa 1: Nahraďte UID datových prvků a všechny jejich výskyty v souboru json UID z cílového systému

3. Alternativa 2: Zvažte nahrazení UID těchto datových prvků v cílovém systému UID ze souboru json. Datové prvky GEN jsou součástí základní knihovny metadat DHIS2 a používají se v jiných balíčcích metadat.

4. Indicators that use the population data will be aggregating data at the level/levels where the data is entered.

5. Po importu balíčku může být vyžadováno další mapování a konfigurace. Viz sekce konfigurace datové sady

NOTE

When updating the UID of a metadata element in the existing DHIS2 instamce, you will need to run an SQL command in the database and additionally replace all occurances and references of its UID in other metadata objects: predictors, indicators, validation rule expressions, etc.

Predictors¶

Balíček obsahuje následující prediktory:

Metadata prediktoru zahrnují úrovně organizačních jednotek používané pro agregaci hodnot dat. Soubor metadat balíčku obsahuje zástupné symboly, které je třeba nahradit UID odpovídajících úrovní organizačních jednotek v cílové databázi.

Kroky k přípravě prediktorů pro import jsou popsány níže:

1. Identifikujte UID úrovně organizační jednotky na úrovni okresu, na které budou data pro prediktory agregována. K identifikaci požadovaného UID použijte následující koncový bod API: ../api/organisationUnitLevels.json?fields=id,name
2. Find the following organisationUnitLevel placeholders in the json file: <OU_LEVEL_DISTRICT_UID>
3. Nahraďte zástupné symboly UID identifikované úrovně zařízení v cílové instanci.

Validation rules¶

All validation rules included in the package are listed in the metadata reference file.

The organisation unit groups for all validation rules are set to the district level. The district level value is located in the "organisationUnitLevels" property of each validation rule. It is set to 3 by default. Adjust these levels in the metadata file to match the district level in the target instance before importing the package.

Validation rule notifications¶

All validation notifications included in the package are listed in the metadata reference file.

Note that all validation rule notifications for this package are all set to be sent as a "single notification." This means that one notification is sent out for each organisation unit/period combination when a notification is triggered. This can also be configured as a "collective summary." The strategy for sending these notifications is located in the "sendStrategy" property of each validation notification. It is set to SINGLE_NOTICIATION by default. Adjust these values to COLLECTIVE_SUMMARY within the metadata file if you would like to change this strategy before importing the package.

NB: Note that you can also change this in maintenance for each validation rule notification at any time after they are imported as you may want to demonstrate or test both strategies to select one that is appropriate for your own setting.

Import metadat¶

Use the 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¶

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

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

Další informace o sdílení naleznete v dokumentaci DHIS2.

Balíček obsahuje tři základní skupiny uživatelů:

• IDS access (view metadata/view data)
• IDS admin (view and edit metadata/no access to data)
• IDS alerts (view metadata/capture and view data)

Uživatelé jsou 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 může být upraveno v závislosti na nastavení. Další informace naleznete v dokumentaci DHIS2 o sdílení.

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. Aggregate data analysis : Can access dashboards, data visualizer, pivot tables, reports and maps.
2. Aggregate data capture : Can acccess the data entry app and add/modify data values,

Další informace o konfiguraci rolí uživatelů najdete v dokumentaci DHIS2.

Organisation unit assignment¶

The data sets must be assigned to organisation units within existing hierarchy in order to be accessible for data entry and data analysis personnel.

Creating jobs in the scheduler¶

You will have to use the scheduler app in order to take advantage of the predictor and validation notification components of the package. You will need at least 3 jobs in the following order:

1. Prediktor
2. Analytics Table
3. Monitoring

You will want each job to complete before you run the next one (ie. the predictors should all be created before analytics starts; the monitoring job should only start after analytics is complete). Each DHIS2 implementation will need to review their configuration to determine the time it takes to run each of these jobs and schedule them accordingly. It is recommended that you have these run late at night when there is not much activity within your DHIS2 instance, as these are generally resource heavy operations.

A couple tips for each job type:

Predictor¶

Predictor jobs consist of a relative start and end date. This means you can run your predictors for the most recent period to generate the latest data that you need. This should be useful if your previous data is not being changed, as the other predicted values will already be generated and stored (and thus this process will not necessarily need to occur once more for those already generated values that are still valid). This is a particularly resource heavy operation, and if your previous data is not routinely changing, generating data for the most recent period that you need data for is the recommended approach.

You are also able to select specific predictors or predictor groups to run during the job. The predictor group for this package is simply called IDS. If you select multiple groups it will run the predictors in the order the groups are selected. You can read more about this within the DHIS2 documentation.

This needs to be the first job that starts in your sequence, and should finish before the next job (analytics) starts.

Analytics table¶

The analytics table job takes all of the raw data that has been entered and applies the necessary aggregation to it based on your configuration. If you are using an integrated system with multiple programs inside your instance, then you may already have an analytics table job scheduled to run at routine intervals. If this is the case, you may need to modify the period in which it runs so it can run after the predictor job has been completed.

This needs to be second job in your sequence, and should finish before the next job (monitoring) starts.

Monitoring¶

Similar to the predictor, the monitoring job also consists of a relative start and end date. If your data is not changing during previous periods, you can run the monitoring job only for the period you need to review.

You can specify validation rule groups for the monitoring job. Create one monitoring job that runs weekly, using the validation rule group IDS - Weekly

If you want to send out the validation notifications, ensure that the "Send notifications" item is selected.

Sending out notifications¶

By default, notifications will be sent out to via the DHIS2 messaging app.

In order to send out notifications via SMS or e-mail, you will need an SMS gateway and/or an e-mail configuration set up within your DHIS2 instance. The settings necessary for these will vary between implementations and it is best to consult the documentation links provided here for more information.

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

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ů pomocí sharing.

Adapting the program¶

Once the program 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.
• Adapting data element names according to national conventions.
• 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ů
• Adding dashboards/dashboard items

However, it is strongly recommended to take great caution if you decide to change or remove any of the included form/metadata. There is a danger that modifications could break functionality, for example predictors or notifications.

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