结核病例监测跟踪器安装指南{ #tb-cs-installation }¶

软件包版本 3.0.0

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

安装¶

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

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

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

1. 导入空白的 DHIS2 实例
2. 将现有元数据（包括以前或其他版本的结核病例监测跟踪器）导入 DHIS2 实例。

注

请注意，此版本的结核病例监测跟踪器并非用于与现有的先前版本合并。它可以作为一个独立模块导入，并被配置为取代任何以前的版本。

本文件中概述的步骤应在测试/暂存 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 在其他元数据对象（预测器、指标、验证规则表达式等）中的所有出现和引用。

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

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

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

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

当前模块不能与结核病例监测跟踪器的现有配置合并。虽然许多跟踪实体属性、数据元素、选项集和选项的 UID 保持不变，但计划、计划阶段、计划阶段部分、计划规则和某些其他对象的 UID 发生了变化。为了支持结核病监测的新指南，治疗和结果计划阶段已合并为一个阶段。

导入元数据¶

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

处理导入冲突¶

注

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

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

备选方案1¶

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

备选方案2¶

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

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

备选3¶

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

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

组态¶

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

分享中¶

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

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

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

• TB 管理员
• 结核病防治
• 结核病实验室访问
• 结核病数据采集
• 结核病实验室数据采集

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

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

用户角色¶

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

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

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

组织单位¶

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

重复的元数据¶

注

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

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

计划通知{ #program-notifications }¶

TB CS Tracker 3.0.0 包含 3 个通知模板，可根据本地要求进行编辑。设置短信或电子邮件通知需要额外配置。

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

基于病例的结核病监测跟踪器捕获的数据可输入标准的汇总报告表（即月度、季度、年度或由国家决定）。该软件包包含预先配置的计划指标和汇总数据交换，可映射到最新的汇总 DHIS2 结核病 HMIS 软件包。

结核病例监测和实验室软件包中的**计划指标**与 DHIS2 结核病汇总软件包（通知、结果、实验室）中的**数据元素**和**类别选项组合**相对应。

配置自动汇总数据交换需要以下步骤：

1. 审查计划指标 确保汇总数据交换所需的计划指标配置正确，并引用正确的数据元素和类别选项组合

2. 审查汇总数据交换 确保汇总数据交换的配置正确，数据汇总的时间段与要求的时间段一致，并且在请求中引用了正确的计划指标。

3. 审查所需数据元素组 确保数据集中使用的数据元素被添加到相应的数据元素组中。记下数据元素组 uid。我们将以 D2spytmv9am 为例。

4. 为每个数据元素组配置预测因子。 在运行特定时段的汇总数据交换之前，预测器将用于重置汇总数据集中的数据值。预测器示例如下：

"code": "CODE",
"name": "Name",
"shortName": "Short Name",
"output": {
  "id": "[Any data element UID can be used here. It will only serve as a placeholder. No data will be posted to this data element]"
},
"generator": {
 "expression": "forEach ?de in :DEG:D2spytmv9am --> if((isNull(#{?de})),#{?de},0)",
 "description": "Description",
 "slidingWindow": false,
 "missingValueStrategy": "NEVER_SKIP",
},
"periodType": "[Data set period]",
"organisationUnitLevels": [
 {
   "id": "[Organisation unit level uid]"
 }
],
"organisationUnitDescendants": "SELECTED",
"sequentialSampleCount": 0,
"annualSampleCount": 0

1. 配置计划作业/作业队列，以运行汇总数据交换。 计划任务的顺序必须按以下方式配置：

   1. 在规定时间内运行 "预测 "任务。
   2. 运行 "分析表 "任务
   3. 运行 "交换汇总数据 "任务
   4. 运行 "分析表 "任务

调整跟踪器程序¶

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

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

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