TB 家庭调查安装指南{ #tb-hh-installation }¶

软件包版本 1.0.0

系统默认语言：系统默认语言：英语

安装¶

模块的安装包括以下几个步骤：

1. [准备]（#准备元数据文件）元数据文件。
2. 将元数据文件[导入]（＃importing-metadata）到DHIS2中。
3. Configuring 导入的元数据。
4. 导入后[Adapting]（＃adapting-the-tracker-program）程序

在开始 DHIS2 的安装和配置过程之前，建议首先阅读安装指南的各个部分。根据导入类型确定适用的章节：

1. 导入空白的 DHIS2 实例
2. 导入具有现有元数据的 DHIS2 实例（之前未导入其他版本的结核病例监测跟踪器）。
3. 更新现有/旧版结核病例监测跟踪器。

本文件中概述的步骤应在测试/暂存 DHIS2 实例中进行测试，然后才应用于生产环境。

要求¶

安装模块需要 DHIS2 管理员用户账户。

应格外注意确保服务器本身和 DHIS2 应用程序的安全，并应定义对所收集数据的访问权限。有关 DHIS2 系统安全的详细信息不在本文讨论范围之内，请参阅DHIS2 文档。

元数据文件{ #metadata-files }¶

元数据参考和元数据 json 文件提供了软件包版本和内容的技术细节。

在将元数据文件导入 DHIS2 之前，通常需要对其进行某些修改，但这并非总是必要的。

准备元数据文件¶

建议在使用和调整任何 DHIS2 元数据包之前，将 DHIS2 通用 HIS 元数据包导入目标实例。 DHIS2 支持的版本可在元数据包下载下载通用 HIS 元数据包。

默认数据维度¶

在 DHIS2 早期版本中，默认数据维度的 UID 是自动生成的。因此，虽然所有 DHIS2 实例都有默认类别选项、数据元素类别、类别组合和类别选项组合，但这些默认值的 UID 可能不同。DHIS2 的后期版本对默认维度的 UID 进行了硬编码，这些 UID 在配置包中使用。

为避免导入元数据时发生冲突，建议搜索并替换整个 .json 文件中所有出现的这些默认对象，将 .json 文件中的 UID 替换为导入该文件的实例中的 UID。表 1 显示了应替换的 UID，以及用于识别现有 UID 的 API 端点

使用列出的 API 请求识别实例中默认维度的 UID，并用实例中的 UID 替换 json 文件中的 UID。

注

请注意，必须使用纯文本编辑器，而不是 Microsoft Word 等文字处理程序来执行搜索和替换操作。

指标类型¶

指标类型是另一种可能造成导入冲突的对象类型，因为某些名称在不同的 DHIS2 数据库中 使用（如 "百分比"）。由于指标类型由其因子（包括 "仅分子 "指标的 1）定义，因此它们是明确的，可通过搜索和替换 UID 来替换。这种方法有助于避免潜在的导入冲突，并防止实施者创建重复的指标类型。下表包含可替换的 UID，以及用于识别现有 UID 的 API 端点：

追踪实体类型¶

与指标类型一样，您的 DHIS2 数据库中可能已有跟踪实体类型。应更改对跟踪实体类型的引用，以反映系统中的情况，从而避免产生重复。下表包含可替换的 UID，以及用于识别现有 UID 的 API 端点：

选项代码{ #option-codes }¶

根据 DHIS2 命名规则，元数据代码使用大写字母、下划线和空格。可能出现的一些例外情况在相应的软件包文档中有所说明。 当前软件包中元数据对象的所有代码都符合命名约定。目标数据库中使用的现有元数据对象的代码可能使用小写字母。在这种情况下，必须直接在数据库中更新这些值。

重要**

在导入过程中，现有的选项代码将被更新的大写代码覆盖。 为了更新数据库中现有数据的数据值，必须使用数据库命令更新数据库中存储的值。 在替换值之前，请确保映射现有的旧选项代码和新选项代码。先使用暂存实例，然后再在生产服务器上进行调整。

对于数据元素值，请使用

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

注

更新现有 DHIS2 实例中元数据元素的 UID 时，需要在数据库中运行 SQL 命令，并替换其 UID 在其他元数据对象（预测器、指标、验证规则表达式等）中的所有出现和引用。

选项的排序顺序{ #sort-order-of-options }¶

检查系统中选项的排序顺序 sortOrder 是否与元数据包中选项的排序顺序一致。这仅适用于 json 文件和目标实例包含相同 UID 的选项和选项集时。

导入后，确保选项集中选项的排序顺序从 1 开始，排序顺序值不应有间隙（如 1、2、3、5、6）。

排序顺序可在维护应用程序中调整。

1. 转到适用的选项集
2. 打开 "选项 "部分
3. 使用 "按名称排序"、"按代码/数值排序 "或 "手动排序"。

确保一个选项集中没有相同排序顺序的选项。可以使用以下 api 端点检查这一点：

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

为了固定包含大量选项的选项集的排序顺序，请参考此 SQL 脚本。

使用根组织单位 UID 进行可视化{ #visualizations-using-root-organisation-unit-uid }¶

分配给特定组织单位级别或组织单位组的可视化、事件报告、报告表和地图都有一个对根（第 1 级）组织单位的引用。此类对象（如果存在于元数据文件中）包含一个占位符 <OU_ROOT_UID>。使用 .json 文件编辑器中的搜索功能可以识别该占位符，并将其替换为目标实例中 1 级组织单位的 UID。

某些可视化和地图可能包含对组织单位级别的引用。由多个地图视图组成的地图可能会根据地图层的配置包含不同的组织单位级别引用。在导入元数据文件之前，请调整元数据 json 文件中的组织单位级别引用，以便与目标实例中的组织单位结构相匹配。

升级元数据包{ #upgrading-metadata-package }¶

在工作中的 DHIS2 实例中将现有软件包升级到较新版本是一项复杂的操作，必须慎之又慎。在升级生产服务器上的配置之前，必须先在开发和暂存实例中运行该过程。由于元数据对象可能已被删除、添加或更改，因此必须确保：

• 现有数据的格式可根据新配置进行映射和调整；
• 从实例中删除终止的元数据对象；
• 更新现有对象；
• 创建新对象；
• 审查将用户分配到相关用户组的情况。

导入元数据¶

使用 Import/Export DHIS2 应用程序导入元数据包。建议在尝试实际导入元数据之前使用 "模拟运行 "功能来发现问题。如果 "模拟运行 "报告了任何问题或冲突，请参阅下面的[导入冲突]（#处理-导入-冲突）部分。如果 "试运行"/"验证 "导入无误，请尝试导入元数据。如果导入成功且无任何错误，则可以继续配置 模块。在某些情况下，"模拟 "过程中不会显示导入冲突或问题，但在尝试实际导入时会显示。在这种情况下，导入摘要将列出需要解决的任何错误。

处理导入冲突¶

注

如果将软件包导入新的 DHIS2 实例，由于目标数据库中没有元数据，因此不会出现导入冲突。导入元数据后，进入"配置 "部分。

可能会发生多种冲突，但最常见的是配置包中的元数据对象的名称、简称和/或代码已经存在于目标数据库中。这些问题有几种不同的解决方案，各有利弊。例如，哪种方案更合适取决于发生冲突的对象类型。

备选方案1¶

重命名 DHIS2 数据库中存在冲突的现有对象。这种方法的优点是无需修改 .json 文件，而是通过 DHIS2 的用户界面进行更改。这可能更不容易出错。这也意味着配置包保持原样，例如在发布包更新时，这可能是一个优势。在培训材料和文档中也经常引用原始软件包对象。

备选方案2¶

重命名.json文件中存在冲突的对象。这种方法的优点是现有的DHIS2元数据保持不变。当存在培训材料或文档（例如链接到所讨论对象的数据字典的SOP）时，这可能是一个因素，并且不存在通过修改用户熟悉的元数据而使用户感到困惑的风险。

请注意，对于备选项1和2，修改可以简单到在名称中添加一个小的前缀/后缀，以最大程度地减少混乱的风险。

备选3¶

第三种也是更复杂的方法是修改.json文件以重新使用现有的元数据。例如，在某个概念的某个选项集已经存在的情况下（例如“性别”），可以从.json文件中删除该选项集，并且对其UID的所有引用都将替换为数据库中已经存在的相应选项集。这样做的最大优点（不限于直接导入冲突的情况）是避免在数据库中创建重复的元数据。执行这种类型的修改时，需要考虑一些关键因素：

• 它需要有关DHIS2详细元数据结构的专业知识
• 该方法不适用于所有类型的对象。特别地，某些类型的对象具有依赖关系，这种依赖关系以这种方式难以解决，例如与分解有关。
• 将来对配置包的更新将很复杂。

将肺结核家庭接触者调查软件包与现有的肺结核病例监测模块链接{ #linking-the-tb-household-contacts-investigation-package-to-an-existing-tb-case-surveillance-module }¶

本节将指导如何将结核病家庭接触者调查包添加到结核病 CS 追踪器的运行实例中。

对于现有实施，不建议直接升级实例中的元数据包。

结核病家庭接触调查包重复使用了结核病病例监测包中的几个元数据对象。这些对象包括跟踪实体类型、跟踪实体属性、数据元素、选项集、选项和用户组。在将实例中的基线元数据与软件包中的元数据对象合并之前，比较两个软件包的元数据 参考文件将有助于用户识别这些元素。

建议使用 2.1.0 版肺结核病例监测软件包与肺结核家庭接触者调查模块连接。下文介绍了如何配置关系类型，以支持通过结核病病例监视跟踪器中的关系窗口小部件登记家庭接触者。

``json { "relationshipTypes"：[ { "代码"："tb_cs_index_hh"、 "名称"："TB - 索引病例 → 住户联系人"、 "externalAccess": false、 "publicAccess"："rw------"、 "userGroupAccesses"：[], "userAccesses"：[], "访问"：{ "manage": true、 "外部化"： true "写入"：true "读取"：true "更新"：true "删除"：true "数据"：{ "write": true、 "read": true } }, "收藏夹[], "共享"：{ "owner"："Ia1Xtxa5eG8"、 "外部"： false、 "用户"：{}, "用户组"：{}, "public": "rw------" }, "fromConstraint"：{ "relationshipEntity"："tracked_entity_instance"、 "trackedEntityType"：{ "id"："MCPQUTHX1Ze" }, "程序"：{ "id"："Lt6P15ps7f6" }, "trackerDataView"：{ "attributes"：[ "sB1IHYu2xQT"、 "ENRjVGxVL6l"、 "Ewi7FUfcHAD" ], "dataElements"（数据元素）：[] } }, "到约束"：{ "relationshipEntity"："tracked_entity_instance"、 "trackedEntityType"：{ "id"："MCPQUTHX1Ze" }, "程序"：{ "id"："cQsXTtAJ3HW" }, "trackerDataView"：{ "attributes"：[ "Ewi7FUfcHAD"、 "sB1IHYu2xQT"、 "ENRjVGxVL6l" [ "ENRjVGxVL6l"]. ], "dataElements"（数据元素）：[] } }, "描述"："肺结核确诊病例的家庭联系人"、 "双向": true、 "fromToName"："家庭联系人"、 "toFromName"："索引病例"、 "referral": false、 "displayFromToName"："住户联系人"、 "displayToFromName"："索引案件"、 "displayName"："TB - 索引案例→住户联系人"、 "favorite": false、 "id"："l0wf8ZWv9nX"、 "attributeValues"：[] } ] } ``` 此配置可在跟踪实体实例之间创建双向关系，并允许用户在关系 widget 中查看以下数据：

1. 肺结核病例：

| 名称 | 对象 | UID | UID |-|-|-| | 家庭联系 | 关系 | | 家庭联系 | 给定名称 | 跟踪实体属性 | sB1IHYu2xQT | sB1IHYu2xQT | 家庭名称 | 跟踪实体属性 |ENRjVGxVL6l|ENRjVGxVL6l | National ID | Tracked Entity Attribute | Ewi7FUfcHAD | `Ewi7FUfcHAD

1. 住户请联系

| 名称 | 对象 | UID | UID |-|-|-| 索引情况 | 关系 | | | | | | | | | | | | | | | 给定名称 | 跟踪实体属性 | sB1IHYu2xQT | sB1IHYu2xQT | 家庭名称 | 跟踪实体属性 |ENRjVGxVL6l|ENRjVGxVL6l | National ID | Tracked Entity Attribute | Ewi7FUfcHAD | `Ewi7FUfcHAD

可以编辑关系 widget 中显示的属性列表。

关系 widget 中显示的跟踪实体属性必须分配给跟踪实体类型。必须激活 "在列表中显示 "选项。

要在关系 widget 中显示的跟踪实体属性必须分配给相应的方案。

必须为相关的 "跟踪实体属性 "激活 "在列表中显示而不显示程序 "选项。

组态¶

成功导入所有元数据后，需要执行一些步骤，模块才能正常运行。

分享中¶

首先，您必须使用 DHIS2 的*共享*功能来配置哪些用户（用户组）应查看与程序相关的元数据和数据，以及谁可以在程序中注册/输入数据。默认情况下，共享配置如下：

• 仪表板（可视化、地图、事件报告和报告表）
• 数据集
• 表格对象类型和关键字
• 计划和计划阶段

这些核心用户群都包含在软件包中：

• TB 管理员
• 结核病防治
• 结核病数据采集

默认情况下，将以下内容分配给这些用户组

需要根据用户在系统中的角色将其分配到相应的用户组。应根据需要设置软件包中其他对象的共享。有关配置共享的详细信息，请参阅 DHIS2 Documentation 。

用户角色¶

用户将需要用户角色才能参与DHIS2中的各种应用程序。建议以下最低角色：

1. 跟踪器数据分析：可以查看事件分析并访问仪表板，事件报告，事件可视化器，数据可视化器，数据透视表，报告和地图。
2. 跟踪器数据捕获：可以添加数据值，更新跟踪的实体，跨组织单位搜索跟踪的实体以及访问跟踪器捕获

有关配置用户角色的更多信息，请参见[DHIS2文档]（http://dhis2.org/documentation）。

组织单位¶

计划必须分配给组织单位层次结构中的适用组织单位。

重复的元数据¶

注

本节仅适用于导入已有元数据的 DHIS2 数据库。如果您使用的是新的 DHIS2 实例，请跳过本节，转到调整跟踪程序。 如果您正在使用任何依赖于当前元数据的第三方应用程序，请考虑到此次更新可能会破坏它们"。

即使成功导入了元数据而没有任何导入冲突，元数据中也可能存在重复项-数据元素，跟踪的实体属性或已存在的选项集。正如上面有关解决冲突的部分所述，要牢记的一个重要问题是，在DHIS2中更改元数据的决定还需要考虑与现有元数据有不同关联的其他文档和资源。 ，以及通过配置包导入的元数据。因此，解决重复项不仅是“清理数据库”的问题，而且还要确保做到这一点，例如，不破坏与其他系统的集成，使用培训材料的可能性，破坏SOP等。这将非常很大程度上取决于上下文。

配置跟踪器捕捉界面、小工具和顶栏{ #configuring-tracker-capture-interface-widgets-and-top-bar }¶

安装软件包后，必须配置 Tracker 采集仪表板。该配置包括数据输入表单、小部件和顶栏。

数据输入表¶

• 注册第一个（测试）案例后，访问跟踪器捕获表单中的**设置**菜单，选择**显示/隐藏小工具**
• 使用**表格数据录入**
• 确保选中**注册**、反馈、档案**和**关系**部件。点击**关闭。
• 单击 "将仪表板布局保存为默认设置"。
• 单击 "为所有用户锁定布局

顶部酒吧{ #top-bar }¶

顶部栏的激活和配置可让用户对显示在跟踪捕获仪表板顶部的关键案件数据有一个清晰的概览。

将基于个案的数据报告为综合数据集{ #reporting-case-based-data-into-aggregate-data-sets }¶

结核病家庭接触者调查跟踪器包括一个 "汇总数据交换 "配置，可汇总基于病例的数据并填充结核病 HMIS 软件包中的季度 "结核病家庭接触者 "数据集。

在汇总包中，**计划指标**与**数据元素**和**类别选项组合**相对应。

默认配置设置为内部数据交换，即跟踪器和聚合数据集位于同一实例中。可以在 json 组件中更改这一配置。使用数据交换的用户必须能访问跟踪器和聚合数据。更多信息请参阅数据交换文档

调整跟踪器程序¶

程序导入后，您可能需要对程序进行某些修改。本地改编的例子包括

• 向表单添加其他变量。
• 根据国家惯例修改数据元素/选项名称。
• 向变量和/或数据输入表单添加翻译。
• 根据当地案例定义修改计划指标。

但是，如果您决定更改或删除任何包含的表格/元数据，强烈建议格外小心。修改可能会破坏功能，例如程序规则和程序指示器。