艾滋病毒预防跟踪器安装指南{ #hiv-prev-installation }¶
软件包版本 1.0.0
系统默认语言：系统默认语言：英语
安装¶
模块的安装包括以下几个步骤：
- [准备]（#准备元数据文件）元数据文件。
- 将元数据文件[导入]（＃importing-metadata）到DHIS2中。
- Configuring 导入的元数据。
- 导入后[Adapting]（＃adapting-the-tracker-program）程序
在开始 DHIS2 的安装和配置过程之前，建议首先阅读安装指南的各个部分。根据导入类型确定适用的章节：
- 导入空白的 DHIS2 实例
- 导入具有现有元数据的 DHIS2 实例（之前未导入其他版本的 HIV 预防追踪器）。
- 更新现有/旧版本的艾滋病毒预防跟踪器。
本文件中概述的步骤应在测试/暂存 DHIS2 实例中进行测试，然后才应用于生产环境。
要求¶
为了安装该模块，需要DHIS2上的管理员用户帐户。在DHIS2的生产实例上执行此文档中概述的过程之前，应在测试/分阶段环境中进行测试。
应格外小心，以确保服务器本身和DHIS2应用程序受到良好保护，以限制对所收集数据的访问。保护DHIS2系统的详细信息不在本文档的范围之内，我们参考[DHIS2文档]（http://dhis2.org/documentation）。
准备元数据文件¶
注意： 如果在 DHIS2 的新实例上安装软件包，可跳过 "准备元数据文件 "部分，直接转到[将元数据文件导入 DHIS2]部分（#importing-metadata）。
尽管并非总是必要，但在将元数据文件导入DHIS2之前对其进行某些修改通常可能是有利的。
默认数据维度（如适用）{ #default-data-dimension-if-applicable }¶
在早期版本的DHIS2中，默认数据维的UID是自动生成的。因此，尽管所有DHIS2实例都具有默认类别选项，数据元素类别，类别组合和类别选项组合，但这些默认的UID可以不同。 DHIS2的更高版本具有用于默认维度的硬编码UID，并且这些UID在配置包中使用。
为避免在导入元数据时发生冲突，建议搜索并替换整个.json文件以查找所有这些默认对象，并将.json文件的UID替换为将导入文件的数据库的UID。表1显示了应替换的UID以及用于标识现有UID的API端点。
| 目的 | 用户标识 | 应用程序接口端点 |
|---|---|---|
| 类别 | GLevLNI9wkl | .../api/categories.json?filter=name:eq:default。 |
| 类别选项 | xYerKDKCefk | .../api/categoryOptions.json?filter=name:eq:default。 |
| 不 | bjDvmb4bfuf | .../api/categoryCombos.json?filter=name:eq:default。 |
| 类别选项组合 | HllvX50cXC0 | .../api/categoryOptionCombos.json?filter=name:eq:default`。 |
例如，如果将配置包导入https://play.dhis2.org/demo ，默认类别选项组合的 UID 可通过https://play.dhis2.org/demo/api/categoryOptionCombos.json?filter=name:eq:default 识别为 bRowv6yZOF2。
然后，您可以在 .json 文件中用 bRowv6yZOF2 搜索并替换所有出现过的 HllvX50cXC0，因为这是您导入系统中的默认 ID。注意，此搜索和替换操作必须使用纯文本编辑器_，而不是 Microsoft Word 等文字处理器。
指标类型¶
指标类型是另一种可能造成导入冲突的对象类型，因为在不同的 DHIS2 数据库中使用某些 名称（如 "百分比"）。由于指标类型仅由其因子和是否是无分母的简单数字来定义，因此它们是明确的，可通过 搜索和替换 UID 来替换。这避免了潜在的导入冲突，也避免了创建重复的指标类型。下表显示了可以替换的 UID，以及用于识别现有 UID 的 API 端点
| 目的 | 用户标识 | 应用程序接口端点 |
|---|---|---|
| 百分比 | hmSnCXmLYwt | .../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:100`。 |
| 比率（系数=1） | k4RGC3sMTzO | .../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:1`。 |
| 每 10 000 人 | FWTvArgP0jt | .../api/indicatorTypes.json?filter=number:eq:false&filter=factor:eq:10000`。 |
| 仅分母（数字） | kHy61PbChXr | .api/indicatorTypes.json?filter=number:eq:true`。 |
追踪实体类型¶
像指示器类型一样，您的DHIS2数据库中可能已经存在跟踪的实体类型。对跟踪实体类型的引用应该更改以反映系统中的内容，因此您不会创建重复项。表3显示了可以替换的UID以及用于标识现有UID的API端点
| 目的 | 用户标识 | 应用程序接口端点 |
|---|---|---|
| 个人 | MCPQUTHX1Ze | .../api/trackedEntityTypes.json?filter=name:eq:Person`。 |
使用根组织单位 UID 进行可视化{ #visualizations-using-root-organisation-unit-uid }¶
分配给特定组织单位级别或组织单位组的可视化、事件报告、报告表和地图都有一个对根（第 1 级）组织单位的引用。此类对象（如果存在于元数据文件中）包含一个占位符 <OU_ROOT_UID>。使用 .json 文件编辑器中的搜索功能可以识别该占位符，并将其替换为目标实例中 1 级组织单位的 UID。
某些可视化和地图可能包含对组织单位级别的引用。由多个地图视图组成的地图可能会根据地图层的配置包含不同的组织单位级别引用。在导入元数据文件之前，请调整元数据 json 文件中的组织单位层级引用，以便与目标实例中的组织单位结构相匹配。
升级元数据包{ #upgrading-metadata-package }¶
在工作中的 DHIS2 实例中将现有软件包升级到较新版本是一项复杂的操作，必须慎之又慎。在升级生产服务器上的配置之前，必须先在暂存实例中运行该过程。由于元数据对象可能已被删除、添加或更改，因此必须确保：
- 现有数据的格式可根据新配置进行映射和调整；
- 从实例中删除终止的元数据对象；
- 更新现有对象；
- 创建新对象；
- 审查将用户分配到相关用户组的情况。
导入元数据¶
.json元数据文件是通过DHIS2的[Import / Export]（https://docs.dhis2.org/master/en/user/html/import_export.html）应用程序导入的。建议在尝试实际导入元数据之前使用“空运行”功能来识别问题。如果“空运行”报告了任何问题或冲突，请参见下面的[导入冲突]（＃handling-import-conflicts）部分。
如果 "模拟"/"验证 "导入无误，请尝试导入元数据。如果导入成功且无任何错误，则可以继续 配置 模块。在某些情况下，"模拟运行 "时不会显示导入冲突或问题，但在尝试实际导入时会显示。在这种情况下，导入摘要将列出需要解决的错误。
处理导入冲突¶
注意：如果您要导入一个新的 DHIS2 实例，则不必担心导入冲突，因为您导入的数据库中没有与之冲突的内容。请按照说明导入元数据，然后进入"配置 "部分。
可能会发生许多不同的冲突，尽管最常见的是配置包中有目标数据库中已经存在名称，简称和/或代码的元数据对象。对于这些问题，有两种替代解决方案，具有不同的优缺点。哪一个更合适将取决于例如发生冲突的对象的类型。
备选方案1¶
重命名DHIS2数据库中存在冲突的现有对象。这种方法的优点是无需修改.json文件，因为更改是通过DHIS2的用户界面完成的。这很可能不太容易出错。这也意味着配置包将保留原样，例如在使用基于配置包的培训材料和文档时，这可能是一个优势。
备选方案2¶
重命名.json文件中存在冲突的对象。这种方法的优点是现有的DHIS2元数据保持不变。当存在培训材料或文档（例如链接到所讨论对象的数据字典的SOP）时，这可能是一个因素，并且不存在通过修改用户熟悉的元数据而使用户感到困惑的风险。
请注意，对于备选项1和2，修改可以简单到在名称中添加一个小的前缀/后缀，以最大程度地减少混乱的风险。
备选3¶
第三种也是更复杂的方法是修改.json文件以重新使用现有的元数据。例如，在某个概念的某个选项集已经存在的情况下（例如“性别”），可以从.json文件中删除该选项集，并且对其UID的所有引用都将替换为数据库中已经存在的相应选项集。这样做的最大优点（不限于直接导入冲突的情况）是避免在数据库中创建重复的元数据。执行这种类型的修改时，需要考虑一些关键因素：
- 它需要有关DHIS2详细元数据结构的专业知识
- 该方法不适用于所有类型的对象。特别地，某些类型的对象具有依赖关系，这种依赖关系以这种方式难以解决，例如与分解有关。
- 将来对配置包的更新将很复杂。
组态¶
成功导入所有元数据后，需要执行一些步骤，模块才能正常运行。
分享中¶
首先，您必须使用 DHIS2 的_共享_功能来配置哪些用户（用户组）应查看与程序相关的元数据和数据，以及谁可以在程序中注册/输入数据。默认情况下，共享功能配置如下：
- 追踪实体类型
- 程序
- 计划阶段
- 仪表板
元数据包通常包含多个用户组：
- HIV PREV - 获取
- 艾滋病毒 PREV - 管理
- HIV PREV - 数据采集
默认情况下，会为这些用户组分配以下内容
| 目的 | 用户组 | 用户组 | 用户组 |
|---|---|---|---|
| HIV PREV - 获取 | 艾滋病毒 PREV - 管理 | HIV PREV - 数据采集 | |
| 追踪实体类型 | 元数据：可查看 数据：可查看 | 元数据：可编辑和查看 数据：可查看 | 元数据：可查看 数据：可采集和查看 |
| 程序 | 元数据：可查看 数据：可查看 | 元数据：可编辑和查看 数据：可查看 | 元数据：可查看 数据：可采集和查看 |
| 计划阶段 | 元数据：可查看 数据：可查看 | 元数据：可编辑和查看 数据：可查看 | 元数据：可查看 数据：可采集和查看 |
| 仪表板 | 元数据：可查看 数据：可查看 | 元数据：可编辑和查看 数据：可查看 | 元数据：可查看 数据：可查看 |
您将需要根据用户在系统中的角色将其分配给适当的用户组。您可能需要根据设置来启用包中其他对象的共享。有关配置共享的更多信息，请参考[DHIS2文档]（https://docs.dhis2.org/master/zh/dhis2_user_manual_zh/about-sharing-of-objects.html）。
用户角色¶
用户将需要用户角色才能参与DHIS2中的各种应用程序。建议以下最低角色：
- 跟踪器数据分析：可以查看事件分析并访问仪表板，事件报告，事件可视化器，数据可视化器，数据透视表，报告和地图。
- 跟踪器数据捕获：可以添加数据值，更新跟踪的实体，跨组织单位搜索跟踪的实体以及访问跟踪器捕获
有关配置用户角色的更多信息，请参见[DHIS2文档]（http://dhis2.org/documentation）。
组织单位¶
您必须将程序分配给自己的层次结构中的组织单位，以便能够在跟踪器捕获中查看程序。
重复的元数据¶
注
本节仅适用于导入已有元数据的 DHIS2 数据库。如果您使用的是新的 DHIS2 实例，请跳过本节，转到调整跟踪程序。 如果您正在使用任何依赖于当前元数据的第三方应用程序，请考虑到此次更新可能会破坏它们"。
即使成功导入了元数据而没有任何导入冲突，元数据中也可能存在重复项-数据元素，跟踪的实体属性或已存在的选项集。正如上面有关解决冲突的部分所述，要牢记的一个重要问题是，在DHIS2中更改元数据的决定还需要考虑与现有元数据有不同关联的其他文档和资源。 ，以及通过配置包导入的元数据。因此，解决重复项不仅是“清理数据库”的问题，而且还要确保做到这一点，例如，不破坏与其他系统的集成，使用培训材料的可能性，破坏SOP等。这将非常很大程度上取决于上下文。
[CONFIG] 元数据{ #config-metadata }¶
导入后需要配置以下元数据。
| 元数据类型 | 名称 |
|---|---|
| 选项集 | [CONFIG]_HIV - PrEP 终止的原因 |
| 选项集 | [CONFIG]_HIV - PrEP 不良反应 |
**请注意，这可能会对计划指标和计划规则产生影响。
调整跟踪器程序¶
程序导入后，您可能需要对程序进行某些修改。本地改编的例子包括
- 向表单添加其他变量。
- 根据国家惯例修改数据元素/选项名称。
- 向变量和/或数据输入表单添加翻译。
- 根据当地案例定义修改计划指标。
但是，如果您决定更改或删除任何包含的表格/元数据，强烈建议格外小心。修改可能会破坏功能，例如程序规则和程序指示器。