source.revision.date: 2026-04-01

Warranty: THIS DOCUMENT IS PROVIDED BY THE AUTHORS ‘’AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS MANUAL AND PRODUCTS MENTIONED HEREIN, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License: Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the source of this documentation, and is available here online: http://www.gnu.org/licenses/fdl.html

toc.title

总览

Web API 是一个组件,它使外部系统成为可能访问和操作存储在 DHIS2 实例中的数据。更多的准确地说,它为广泛的为第三方等应用项目公开数据和服务方法软件客户端、门户网站和内部 DHIS2 模块。

介绍

Web API 遵循 REST 架构风格背后的许多原则。以下是一些重要原则:

基本构建块称为*资源*。资源可以是任何暴露在 Web 上的东西,从文档到业务流程 - 客户端可能想要与之交互的任何内容。资源的信息方面可以通过资源*表示*进行检索或交换。表示是资源在任何特定时间的状态视图。例如,DHIS2 中的*可视化* 资源代表了汇总数据的*可视化*,可用于一组特定的参数。该资源可以以各种表示格式获取,包括 JSON 和 CSV。所有资源都可以通过 URI(也称为
URL)唯一标识。所有资源都有一个默认表示。您可以称为 URL）。所有资源都有一个默认表示法。您可以查询参数来表明您对特定表示的兴趣。因此,要检索 CSV 格式的提供*Accept* HTTP 标头、文件扩展名或*format*格式或在请求 URL 中添加 .csv 或 ?format=csv。与 API 的交互需要正确使用 HTTP 方法或动词。这意味着对于资源,您必须在想要检索它时发出 GET
请求,在想要创建它时发出 POST 请求, 在想要更新它时发出 PUT 请求,在想要删除它时发出 DELETE 请求。请求，当您要检索它时，POST 请求创建一个，要更新时*PUT*，要删除时*DELETE*。基本身份验证

个人访问令牌 (PAT)

OAuth 2

验证并获取当前已认证用户的信息。
GET /api/me
获取当前已通过身份验证用户的授权列表。

GET /api/me/authorization

检查当前已通过身份验证的用户是否拥有指定权限。

GET /api/me/authorization/{authority}

例如,检查用户是否拥有 F_CONSTANT_ADD 权限。

GET /api/me/authorization/F_CONSTANT_ADD

响应将以 JSON 格式显示为true或 false。

基本认证 { #webapi_basic_authentication }

DHIS2 Web API 支持*基本身份验证*。基本身份验证是一种客户端通过 HTTP 将登录凭据发送到 Web 服务器的技术。从技术上讲,用户名后附有冒号和密码,经过 Base64 编码,前缀 Basic 并作为值提供给 Authorization HTTP 标头。更正式的格式是:

Authorization: Basic base64encode(username:password)

大多数网络开发环境都支持基本

身份验证,例如 Apache HttpClient 和 Spring RestTemplate。一个重要的注意事项是此身份验证方案不提供安全性, 因为用户名和密码是以纯文本形式发送的,可以很容易地被攻击者截获。仅当服务器使用 SSL/TLS (HTTPS) 加密与客户端的通信时才应使用。请将此视为与 Web API 进行安全交互的硬性要求。

两因素验证 { #webapi_2fa }

DHIS2 支持两因素身份验证。这可以为每个用户启用。启用后,用户将被要求在登录时输入 2FA 代码。您可以在此处阅读更多关于 2FA 的信息。

个人访问令牌{ #webapi_pat_authentication }

个人访问令牌 (PAT) 是使用 API 时对 DHIS2 进行身份验证的密码替代方法。

个人访问令牌(PAT)是使用 API 时对 DHIS2 进行身份验证的另一种方式。

PAT 可作为 HTTP 基本身份验证的一种更安全的替代方式。在创建新应用或脚本等时,PAT 应该是您的首选。

HTTP 基本身份验证被认为是不安全的,原因包括

它会以明文发送用户名和密码。在未来的 DHIS2 版本中,基本身份验证可能会被弃用或改为选择启用,这意味着需要在配置中明确启用基本身份验证。重要的安全问题! { #important-security-concerns }

您的 PAT 将自动继承用户拥有的所有权限和授权。因此,根据您打算使用令牌的方式,限制授予令牌的访问权限极为重要。请参阅 配置您的令牌 部分。

如果您只想让令牌访问服务器的某一特定部分,建议您创建一个新的专用用户,并只分配您希望它访问的角色/权限。如果您只想让令牌访问服务器的一个狭窄且特定的部分,建议您创建一个新的专用用户,并只分配您希望它访问的角色/权限。

创建令牌

要创建新的 PAT,您有两个选择:

A. 在账户个人资料页面的用户界面上创建令牌。

B. 通过 API 创建令牌。

A. 在账户页面上创建令牌 { #a-creating-a-token-on-the-account-page } * 使用用户名和密码登录,进入个人资料页面 (点击右上角,从下拉菜单中选择 "编辑个人资料")。在用户配置文件页面,从左侧菜单中选择 "个人访问令牌"。现在您应该在 "管理个人访问令牌" 页面上看到文本:"您没有任何有效的个人访问令牌"。点击 "生成新令牌" 创建新令牌。弹出 "生成新令牌" 窗口,为您提供两种选择: * 1. 服务器/脚本上下文 { #1-serverscript-context }

"该类型用于不会被浏览器访问的集成和脚本"。

如果您计划在应用、脚本或类似文件中使用令牌,则应选择此类型。

2. 浏览器上下文

"这种类型适用于将通过 Web 浏览器访问的应用,如公共门户网站"。

如果您需要在网页上链接到 DHIS2,或嵌入 iframe, 这可能就是您需要的令牌类型。

配置令牌

选择需要的令牌类型后,可以为令牌配置不同的访问限制。所谓限制,是指如何限制和缩小令牌的使用范围。如果计划在公共环境中使用令牌,这一点至关重要, 例如,在其他网站的公共仪表板上嵌入 iframe。由于令牌总是拥有与用户相同的访问权限/授权,因此如果您打算在公共环境中使用令牌,或者在任何您无法 100% 控制的环境中使用它,就需要特别小心。

注意:如果其他人获取了您的令牌,他们可以执行您的用户可以执行的任何操作。无法区分使用令牌执行的操作和用户执行的其他操作。

重要:如果您打算在非安全和/或公共环境中使用 PAT 令牌,强烈建议您创建一个单独的专用用户,该用户只能拥有您希望令牌拥有的角色/权限,

例如,在您无法 100% 控制的 PC 或服务器上,或 "嵌入" 到另一台服务器的网页中。

限制类型 { #constraint-types }

到期时间

允许的 IP 地址

允许的 HTTP 方法

允许的 HTTP 引用来源
有效期 { #expiry-time }
到期时间用于设置令牌的有效期,默认为 30 天。过期后,令牌将直接返回 401(未授权)响应。您可以设置任何到期时间,但我们强烈建议您根据自己的使用情况设置一个合理的过期时间。
IP 地址 { #ip-addresses }

这是一个以逗号分隔的 IP 地址列表,用于限制令牌请求的来源。

重要:IP 地址验证依赖于 X-Forwarded-For 标头,该标头可能被伪造。为了安全起见,请确保负载平衡器或反向代理会覆盖该标头。

HTTP 方法

以逗号分隔的 HTTP 方法列表,您希望令牌能够使用这些方法。如果您只需要令牌来查看数据,而不是修改或删除数据,那么只选择 GET HTTP 方法是合理的。

HTTP 引用来源 { #http-referrers }

HTTP 引用来源是添加到请求中的一个标头,当您点击链接时,它会显示您点击链接时所在的网站/页面。

点击此处了解有关 HTTP 引用来源头的更多信息: https://en.wikipedia.org/wiki/HTTP_referer

这可用于限制使用嵌入到其他网站页面上的 "公共" 令牌。确保引用来源标头与网站主机名相匹配,有助于避免令牌被滥用, 例如,如果有人在公共论坛上发布令牌。

重要:这不是一项安全功能。`Referer` 标头很容易被欺骗。

此设置旨在阻止未经授权的第三方开发人员连接到公共访问实例。

保存令牌 { #saving-a-token }

完成令牌配置后,点击弹出窗口右下方的 "生成新令牌" 按钮保存。这样,令牌将被保存,并在服务器上生成一个秘密令牌密钥。新的密钥将显示在 PAT 令牌列表底部,背景为绿色和文本 "新创建的令牌"。秘密令牌密钥的外观与此类似:

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

重要:生成的秘密令牌密钥只会显示一次,因此请务必

现在就复制令牌密钥,并将其保存在安全的地方,以便以后使用。秘密令牌密钥将在服务器上安全散列,只有该秘密令牌密钥的散列才会保存到数据库中。这样做的目的是在有人未经授权访问数据库时,最大限度地减少安全影响。这与处理密码的方式类似。

使用应用项目接口{ #creating-a-token-with-the-api } 创建令牌示例说明如何使用 API 创建新的个人访问令牌:

POST /api/apiToken
Content-Type: application/json
Authorization: Basic admin

{}

注意:记住请求体中的空 JSON 主体 (`{}`)!

这将返回一个包含类似令牌的响应:

{
  "httpStatus": "已创建",
  "httpStatusCode": 201,
  "status": "正常",
  "response": {
     "responseType": "ApiTokenCreationResponse",
     "key": "d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092",
     "uid": "jJYrtIVP7qU",
     "klass": "org.hisp.dhis.security.apikey.ApiToken",
     "errorReports": []
  }
}

注意:令牌密钥只会在此响应中显示一次。您需要将其复制并保存在安全的地方,以便以后使用!

令牌本身由三部分组成:

前缀: (d2pat_) 表示这是什么类型的令牌。

随机字节 Base64 编码: (5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ)

CRC32 校验和:(1151814092) 校验和部分以 0 填充,因此长度始终为 10 个字符。 1. 使用 API { #configure-token-with-the-api } 配置令牌 2. 要更改令牌上的任何限制条件,可发出以下 HTTP API 请求。 3. 注意:创建令牌后,只能修改约束条件。

```bash

PUT /api/apiToken/jJYrtIVP7qU Content-Type: application/json Authorization: Basic admin

```json
{
  "version": 1,
  "type": "PERSONAL_ACCESS_TOKEN",
  "expires": 163465349603200,
  "attributes": [
      {
        "type": "IpAllowedList",
        "allowedIps": ["192.168.0.1"]
      },
      {
        "type": "MethodAllowedList",
        "allowedMethods": ["GET"]
      }
  ]
}

使用个人访问令牌 { #using-a-personal-access-token }

要使用新创建的令牌发出请求,请使用相应的授权标头。授权标头格式如下:

Authorization: ApiToken [YOUR_SECRET_API_TOKEN_KEY]

例如:

GET /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

删除个人访问令牌{ #deleting-a-personal-access-token }

您可以在创建 PAT 的个人资料页面的用户界面中删除 PAT、或像这样通过应用项目接口删除:

DELETE /api/apiToken/jJYrtIVP7qU
Content-Type: 应用项目/json
授权:ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2

DHIS2支持* OAuth2 身份验证协议。OAuth2是开放的授权标准,允许第三方客户端代表DHIS2用户进行连接,并为对Web API的后续请求获取*bearer token。DHIS2不支持细粒度 OAuth2角色,而是根据用户角色提供应用访问权限,基于 DHIS2用户的身份。

您要允许其使用OAuth 2身份验证的每个客户端都必须在DHIS2中注册。要添加新的OAuth2客户端,请转到应用>设置> OAuth2客户端。在用户界面中,单击*添加新*,然后输入所需的客户端名称和授权类型。

创建客户端

可以通过Web API添加OAuth2客户端。例如,我们可以发送这样的有效载荷:

{
  "name": "OAuth2 Demo Client",
  "cid": "demo",
  "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
  "grantTypes": [
    "password",
    "refresh_token",
    "authorization_code"
  ],
  "redirectUris": [
    "http://www.example.org"
  ]
}

可用以下命令发送有效负载:

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

该客户端将作为下一个授权类型示例的基础。

授权类型:密码 { #webapi_oauth2_password }

所有授权类型中最简单的是*password*授权类型。这种授权类型类似于基本身份验证,因为它要求客户端收集用户的用户名和密码。作为示例,我们可以使用我们的演示服务器:

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

这将给您类似的响应:

{
  "expires_in": 43175,
  "scope": "ALL",
  "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
  "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
  "token_type": "bearer"
}

现在,我们将专注于access_token,这就是我们将用作身份验证(承载)令牌的内容。例如,我们将获取使用我们的令牌访问所有数据元素:

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

授权类型:refresh_token { #webapi_refresh_token }

通常,访问令牌的有效性有限。您可以查看上一个示例中响应的expires_in属性, 了解令牌何时到期。要获得新的access_token,您可以再次访问服务器并使用refresh_token, 这允许您获得更新的令牌而无需要求再次使用用户凭据。

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

响应与获得令牌开始时的响应完全相同。

授权类型:authorization_code { #webapi_authorization_code }

如果您不想在外部存储用户凭据,建议使用授权码授权类型。它允许DHIS2直接从用户收集用户名/密码,而不是由客户端收集,然后代表用户进行身份验证。请注意这种方法使用了客户端有效载荷中的redirectUris部分。

第 1 步:使用 Web 浏览器访问以下 URL。如果您有多个重定向 URI,可能需要添加 &redirect_uri=http://www.example.org 到 URL:

```bash

SERVER="https://play.dhis2.org/dev" $SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

第 2 步:在用户成功登录并接受您的
客户端访问后,它将重定向回您的重定向 URI,如下所示:

    http://www.example.org/?code=XYZ

第 3 步:这一步类似于我们在密码授权类型中所做的,
使用获得的代码,我们现在将请求访问令牌:

```bash
SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

错误和信息消息 { #webapi_error_info_messages }

Web API 使用统一的格式返回所有错误/警告和信息性消息:

{
  "httpStatus": "Forbidden",
  "message": "You don't have the proper permissions to read objects of this type.",
  "httpStatusCode": 403,
  "status": "ERROR"
}

在这里,我们可以看到用户试图访问一个

无法访问的资源。它使用了 HTTP 状态代码 403、HTTP 状态信息 forbidden 和描述性消息。

WebMessage 属性

名称

描述

httpStatus

此响应的 HTTP 状态信息,更多信息请参见 RFC 2616(第 10 节)。	httpStatusCode
此响应的 HTTP 状态代码,更多信息请参见 RFC 2616(第 10 节)。	status
DHIS2状态,可能的值为OK、WARNING 或 ERROR,其中`OK`表示一切顺利,`ERROR`表示操作未完成,`WARNING`表示操作部分成功,如果消息包含`response`属性,请在那里查找更多信息。	message
用户友好型消息,说明操作是否成功。	devMessage
技术性更强、对开发人员更友好的消息(目前尚未使用)。	response
`WebMessage`格式未来扩展的扩展点。	日期和期间格式 { #webapi_date_period_format }
在整个 Web API 中,我们会引用日期和期间。日期格式
如下:	```
年-月-日
```

例如,如果要表达 2014 年 3 月 20 日,必须使用

2014-03-20。

下表描述了期间格式(也可通过 API 端点/api/periodTypes获取)

期间格式

期间类型

格式

示例

描述	日	yyyyMMdd	2004 年 3 月 15 日
周	yyyyWn	20040315	2004W10
2004 年第 10 周	周三开始的周	yyyyWedWn	2015WedW5
第 5 周,周三开始	周四开始的周	yyyyThuWn	2015ThuW6
第 6 周,周四开始	周六开始的周	yyyySatWn	2015SatW7
第 7 周,周六开始	周日开始的周	yyyySunWn	2015SunW8
第 8 周,周日开始	双周	yyyyBiWn	2015BiW1
2015 年第 1-2 周	月份	yyyyMM	2004 年 3 月
双月	yyyyMMB	200403	200401B
2004 年 1-2 月	季度	yyyyQn	2004Q1
2004 年 1-3 月	六个月	yyyySn	2004S1
2004 年 1 月至 6 月	4月开始的六个月	yyyyAprilSn	2004AprilS1
2004 年 4 月至 9 月	年份	yyyy	2004 年
4月开始的财政年度	yyyyApril	2004	2004
2004April	2004 年 4 月至 2005 年 3 月	7月开始的财政年度	yyyyJuly
2004July	2004 年 7 月至 2005 年 6 月	10月开始的财政年度	yyyyOct
2004Oct	2004 年 10 月至 2005 年 9 月	相对时期 { #webapi_date_relative_period_values }	在应用项目接口的某些部分,如分析资源,您可以
除固定时间段(如上定义)外,还可以使用相对时间段。
相对时间段是相对于当前日期而言的,可用于创建动态报告等。
创建动态报告。可用的相对周期值如下表所示
如下表所示。

名称

关键词

今天	今天
昨天	昨天
最近 3 天	LAST_3_DAYS
最近 7 天	LAST_7_DAYS
最近 14 天	LAST_14_DAYS
最近 30 天	LAST_30_DAYS
最近 60 天	LAST_60_DAYS
最近 90 天	LAST_90_DAYS
最近 180 天	LAST_180_DAYS
本月	THIS_MONTH
本双月	THIS_BIMONTH
上双月	LAST_BIMONTH
本季度	THIS_QUARTER
上一季度	LAST_QUARTER
本六个月	THIS_SIX_MONTHS
上六个月	LAST_SIX_MONTHS
今年的周	WEEKS_THIS_YEAR
今年的月	MONTHS_THIS_YEAR
今年的双月	BIMONTHS_THIS_YEAR
今年的季度	QUARTERS_THIS_YEAR
今年	THIS_YEAR
去年的月	MONTHS_LAST_YEAR
去年的季度	QUARTERS_LAST_YEAR
去年	LAST_YEAR
最近 5 年	LAST_5_YEARS
最近 10 年	LAST_10_YEARS
最近 12 个月	LAST_12_MONTHS
最近 6 个月	LAST_6_MONTHS
最近 3 个月	LAST_3_MONTHS
最近 6 个双月	LAST_6_BIMONTHS
最近 4 个季度	LAST_4_QUARTERS
最近 2 个六个月	LAST_2_SIX_MONTHS
本财政年度	THIS_FINANCIAL_YEAR
上一财政年度	LAST_FINANCIAL_YEAR
最近 5 个财政年度	LAST_5_FINANCIAL_YEARS
最近 10 个财政年度	LAST_10_FINANCIAL_YEARS
本周	THIS_WEEK
上周	LAST_WEEK
本双周	THIS_BIWEEK
上双周	LAST_BIWEEK
最近 4 周	LAST_4_WEEKS
最近 4 个双周	LAST_4_BIWEEKS
最近 12 周	LAST_12_WEEKS
最近 52 周	LAST_52_WEEKS
自定义日期时段 { #webapi_date_custom_date_periods }	分析 `query` 资源支持额外的参数来表达时段。

可以通过以下方式检索这些相对周期的 ISO 表示法向 /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD} 提出 GET 请求。

该终端支持以下参数： - startDate"（开始日期）：代表计算相对周期的起始日期。格式为yyyyy-MM-dd`。如果没有提供，默认为今天。 - financialYearStart"（财务年度开始）：应为 FINANCIAL_YEAR_APRIL、FINANCIAL_YEAR_JULY、FINANCIAL_YEAR_OCTOBER 中的一个。如果未提供，则默认为 FINANCIAL_YEAR_OCTOBER。

例如，要获取从 2021-08-15 日开始的相对周期 "LAST_3_MONTHS "的 ISO 表示值，可以发出以下请求的 ISO 表示，可以发出以下请求： GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

在这种情况下的回答是

``json { [ "202105", "202106", "202107" ] }

### 这些参数会替代默认的 `pe` 维度:

用于 `/analytics/events/query` 的 `eventDate`

用于 `/analytics/enrollments/query` 的 `enrollmentDate`

- 允许在一个或多个日期字段上添加条件并将它们合并。
- 自定义日期时段的使用 { #usage-of-custom-date-periods }

在支持自定义日期时段的资源中,有一些额外的查询参数,这些参数将被组合起来,以表达时间维度上的条件。

#### 自定义日期周期

事件查询资源

| 注册查询资源 | `eventDate`  | [x] |
|--------------------|------------------------|---------------------------|
| [ ]        | `lastUpdated`                    | [x]                       |
| [x]   | [x]                    | `lastUpdated`                       |
| [ ]    | `/api/analytics/events/query/...?..&eventDate=2021&...`                    | [x]                       |
| [x]     | `lastUpdated`                    | `lastUpdated`                       |
| [x]      | `lastUpdated`                    | `lastUpdated`                       |

可以在同一查询中合并多个时间字段:

`/api/analytics/events/query/...?..&eventDate=2021&incidentDate=202102&...`

所有这些条件都可以与 `pe` 维度相结合:

`/api/analytics/events/query/...?..&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&...`

支持的格式见上文 "日期和期间格式"。还提供了一种额外的格式来表达一系列日期:`yyyyMMdd_yyyyMMdd` 和 `yyyy-MM-dd_yyyy-MM-dd`。

在下面的示例中,端点将返回计划在 20210101 和 20210104 之间发生的事件:

`/api/analytics/events/query/...?..&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&scheduledDate=20210101_20210104&...`

当局 { #authorities }

所有可用的系统授权都可以通过以下端点列出其标识符和名称:

##     GET /api/authorities

返回格式如下:

```json
{
  "systemAuthorities": [
    {
      "id": "ALL",
      "name": "ALL"
    },
    {
      "id": "F_ACCEPT_DATA_LOWER_LEVELS",
      "name": "Accept data at lower levels"
    }
  ]
}

元数据 { #webapi_metadata }

标识符方案 { #webapi_identifier_schemes }

本节将解释标识符方案的概念。

在导入过程中,标识符方案用于将元数据对象映射到其他元数据对象, 并将元数据作为导出的一部分。请注意, 并非所有方案都适用于所有 API 调用,也并非所有方案都能同时用于输入和输出。在后续章节中会解释各种 API 端点支持的方案。

下面列出了可用的全套标识符方案对象类型,

使用在查询中使用的属性名称:

idScheme

dataElementIdScheme

描述
DateTime
programIdScheme
programStageIdScheme
Can either be VALIDATE which will report errors in the payload without making changes to the database or COMMIT (default) which will validate the payload and make changes to the database.
IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is UID.
通用 idScheme 适用于所有类型的对象, 但可以被特定的对象类型方案覆盖。
所有参数的默认方案是 UID(稳定的 DHIS2 标识符)。支持的标识符方案如下表所示:

表:标识符方案值

方案

描述

ID, UID	Parameter name
CODE	与 DHIS2 编码匹配,主要用于与外部系统交换数据。
NAME	在 DHIS2 名称上匹配,请注意这使用的是可用的 object.name,而不是翻译后的名称。还请注意,名称并不总是唯一的,在这种情况下,不能使用它们。
ATTRIBUTE:ID	根据元数据属性进行匹配,需要将此属性分配给要匹配的类型,同时将唯一属性设置为 true。它的主要用途是与外部系统交换数据,与 CODE 相比,它有一些优势,因为可以添加多个属性,所以可以用于与多个系统同步。
请注意,标识符方案不是一个独立的功能,需要与数据值导入、元数据导入和
GeoJson 导入等资源结合使用。	例如,指定 CODE 作为通用 id 方案并覆盖
使用 UID 作为组织单位 ID 方案,您可以使用这些查询
参数:

?idScheme=CODE&orgUnitIdScheme=UID

再举一个例子,为组织单位 id 指定一个属性方案,数据元素 id 方案的代码并使用默认 UID id 作为所有其他对象的方案,您可以使用这些参数:

?orgUnitIdScheme=ATTRIBUTE:j38fk2dKFsG&dataElementIdScheme=CODE

浏览Web API { #webapi_browsing_the_web_api }

浏览 Web API 的入口点是 /api。这个资源提供所有可用资源的链接。四种资源表示格式始终适用于所有资源:HTML、XML、JSON 和 JSONP。某些资源将具有其他可用格式,例如 MS Excel、PDF、CSV 和 PNG。要从 Web 浏览器探索 API,请导航到 /api 入口点并按照链接访问您想要的资源,例如/api/dataElements。对于所有返回元素列表的资源, 某些查询参数可用于修改响应:

表:查询参数

参数

选项值

默认值	描述	paging	Parameter name
true	表示是否返回分页的元素列表。	Tracked Entity UIDS	数字
定义要返回的页码。	order	1	数字
定义每页返回的元素数量。	order	50	property:asc/iasc/desc/idesc
iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。	如何使用这些参数获取完整列表的示例
XML 响应格式的数据元素组:		/api/dataElementGroups.xml?links=false&paging=false

您可以在 name 属性上查询元素,而不是返回使用 query 查询参数的完整元素列表。在这个例子中我们查询名称中带有“贫血”一词的所有数据元素:

/api/dataElements?query=贫血

您可以像这样获取特定页码和页面大小的对象:

/api/dataElements.json?page=2&pageSize=20

您可以像这样完全禁用分页:

/api/indicatorGroups.json?paging=false

要基于特定属性对结果进行排序:

/api/indicators.json?order=shortName:desc

首先根据创建的日期时间属性排序(降序),然后根据名称属性排序(升序):

/api/indicators.json?order=created:desc,name:asc

您可以通过以下方式在所有对象类型中根据对象的 ID 查找对象 identifiableObjects 资源:

/ api / identifiableObjects / <id>

翻译 { #webapi_translation }

DHIS2 支持数据库内容的翻译,如数据元素、指标和计划、指标和项目。网络应用项目接口中的所有元数据对象都有属性,这些属性包括 displayName, displayShortName, displayDescription 和 displayFormName(用于数据元素和跟踪实体属性)。

表格翻译选项

参数

价值观

默认值	译	Parameter name
启用翻译。请注意,默认情况下这是关闭的(在其他端点,默认情况下是打开的)。	表示是否返回分页的元素列表。	使用的本地语言
从用户本地语言更改为自定义本地语言。	翻译API { #webapi_translation_api }	对象的翻译呈现为对象本身的一部分
在* translation *数组中。请注意,
JSON / XML有效负载的翻译数组通常为您预先过滤,这意味着它们不能直接用于导入/导出翻译(因为那样会
通常会覆盖当前用户以外的语言环境)。

在用户语言环境中过滤了转换数组的数据元素示例:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute French",
  "translations": [
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    }
  ]
}

转换关闭的数据元素示例:

{
  "id": "FTRrcoaog83",
  "displayName": "Accute Flaccid Paralysis (Deaths < 5 yrs)",
  "translations": [
    {
      "property": "FORM_NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "Accute Flaccid Paral"
    },
    {
      "property": "SHORT_NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Accute French"
    },
    {
      "property": "NAME",
      "locale": "en_FK",
      "value": "aa"
    },
    {
      "property": "DESCRIPTION",
      "locale": "en_FK",
      "value": "aa"
    }
  ]
}

请注意,即使您得到未过滤的结果,并且正在使用适当的类型端点,即我们不允许的 /api/dataElements 更新,因为这样做很容易犯错误并覆盖其他可用的语言环境。

要阅读和更新翻译,您可以使用特殊翻译每个对象资源的端点。可以通过*GET*或访问在适当的/ api / <object-type> / <object-id> / translations端点上* PUT *。

例如,对于标识符为 FTRrcoaog83 的数据元素,您可以使用 /api/dataElements/FTRrcoaog83/translations来获取和更新翻译。翻译。可用的字段有:property (可选 NAME、SHORT_NAME、FORM_NAME、DESCRIPTION)、locale(支持任何有效的 locale"(支持任何有效的 locale ID)和已翻译的属性 value。

法语语言环境的NAME属性示例:

{
  "property": "NAME",
  "locale": "fr",
  "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
}

然后将此有效负载添加到翻译数组中,并发回到适当的端点:

{
  "translations": [
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Paralysie Flasque Aiguë (Décès <5 ans)"
    }
  ]
}

对于ID为* FTRrcoaog83 的数据元素,您可以 PUT *此代码为 / api / dataElements / FTRrcoaog83 / translations。确保发送全部特定对象的翻译,而不仅仅是单个语言环境的翻译 (否则,您可能会覆盖其他区域的现有语言环境语言环境)。

如果数据值已成功保存或更新,则状态代码将为204 No Content,如果存在验证错误(例如,同一语言环境有多个SHORT_NAME),则状态代码将为404 Not Found。

Web API版本 { #webapi_api_versions }

网络 API /api可与 DHIS2 版本号一起使用,例如

/api/42/dataElements

支持版本 28-43。调用带有或不带版本的端点不会改变 API 的行为。无论使用哪种方法,行为都是一样的。我们的目标是不再支持带版本的 API 调用,因此请使用不带版本号的 API 调用。
支持使用版本是由于传统的设计,并没有按照最初的设想发展。

元数据对象过滤器 { #webapi_metadata_object_filter }

要过滤元数据,可以对返回的元数据列表应用多种过滤操作。过滤器的格式很简单,遵循以下模式: property:operator:value,其中 property 是要过滤的元数据属性, operator 是要执行的比较运算符,value 是要匹配的值。

请参阅 "模式"部分,了解哪些属性可用。

除列出的属性外,筛选器还可应用于自定义属性值,方法是使用属性的 ID 作为属性名。

还支持递归过滤,即对关联对象或对象集合进行过滤。

表:可用操作符

操作符

类型

所需值	描述	eq	Parameter name
true	不等于	Tracked Entity UIDS	字符串、布尔值、整数、浮点、枚举、集合(检查大小)、日期
true	不等于	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串、布尔值、整数、浮点、枚举、集合(检查大小)、日期
true	不等于	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串、布尔值、整数、浮点、集合(检查大小)、日期
true	小于	Tracked Entity UIDS	字符串、布尔值、整数、浮点、集合(检查大小)、日期
true	小于	Tracked Entity UIDS	字符串、布尔值、整数、浮点、集合(检查大小)、日期
true	小于	Tracked Entity UIDS	字符串、布尔值、整数、浮点、集合(检查大小)、日期
true	小于	Tracked Entity UIDS	所有
false	*	subjectTemplate	所有
false	*	subjectTemplate	集合
false	集合为空	subjectTemplate	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串
true	不区分大小写的字符串结尾匹配	Tracked Entity UIDS	字符串、布尔值、整数、浮点、日期
描述	查找匹配 1 个或多个值的对象	Tracked Entity UIDS	字符串、布尔值、整数、浮点、日期
true	查找匹配 1 个或多个值的对象	Tracked Entity UIDS	获取ID属性为ID1或ID2的数据元素:

/api/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

获取名称属性为 MyDataElement 的数据元素,忽略大小写:

/api/dataElements?filter=name:ieq:mydataelement

获取具有 ID1 数据集的所有数据元素:

/api/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

获取所有使用聚合运算符 sum 和值类型为 int 的数据元素:

/api/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

您可以在集合内进行筛选,例如,要获取属于 ANC 数据元素组的数据元素, 可以使用相关数据元素组的 id 属性进行查询:

/api/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

要获取元数据属性中具有特定属性值的数据元素, 可使用相同的集合查询语法指定属性 ID 和属性值的过滤器:

/api/dataElements.json?filter=attributeValues.attribute.id:eq:n2xYlNbsfko&filter=attributeValues.value:eq:AFP

获取已设置选项集的数据元素:

/api/dataElements?filter=optionSet:!null

由于默认情况下所有运算符都是 AND,因此您无法直接找到匹配多个 id 的数据元素,为此您可以使用 in 操作符:

/api/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

逻辑运算符 { #webapi_metadata_logical_operator }

如前一节所述,过滤器应用的默认逻辑运算符是 AND,这意味着所有对象过滤器必须都匹配。但是,在某些情况下,您希望匹配其中之一几个过滤器(可能是 id 和 code 字段),在这些情况下,它是可以将根逻辑运算符从 AND 切换为 OR 使用 rootJunction 参数。

示例:正常过滤,其中 id 和 code 必须匹配才能具有

结果返回

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

示例:过滤逻辑运算符已切换为 OR 的位置现在只有一个过滤器必须匹配才能产生结果回

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR

可识别的令牌过滤器 { #identifiable-token-filter }

除了上述基于特定属性的过滤之外, 我们还通过* token 基于 AND 过滤了一组属性:ID,代码和名称(如果可用,还包括shortName)。这些属性通常称为*可识别。这个想法是为了过滤ID,名称,代码或简称中包含某些内容的元数据。

示例:过滤所有包含 2^nd 的数据元素

如下: id,name,code,shortName

/api/dataElements.json?filter=identifiable:token:2nd

也可以指定多个过滤值。

示例:获取在任何 identifiable 属性中找到 ANC visit 的所有数据元素。系统返回所有数据元素,其中在可识别属性中的任何地方都可以找到令牌(ANC 和访问)。

/api/dataElements.json?filter=identifiable:token:ANC访问

也可以将可识别过滤器与基于属性的过滤器结合起来,并期望应用 rootJunction。

/api/dataElements.json?filter=identifiable:token:ANC visit&filter = displayName:ilike:tt1

/api/dataElements.json?filter=identifiable:token:ANC访问
  &filter = displayName:ilike:tt1&rootJunction = OR

元数据字段过滤器 { #webapi_metadata_field_filter }

在许多情况下,元数据的默认视图可能过于冗长。冗长。客户可能只需要每个对象中的几个字段,并希望从响应中删除不必要的字段。从响应中删除不必要的字段。要了解每个对象有哪些字段请参阅 "模式"部分。除了列出的属性外,还可以通过使用属性属性 ID 作为属性名称。

include/exclude 的格式允许无限递归。要过滤可以在"根"级只使用字段的名称,

例如,?fields=id,name 只显示每个对象的id和name字段。对于集合或复杂对象,可以使用以下格式 ?fields=id,name,dataSets[id,name],这将返回根对象的name和id字段。并且包括该对象的所有数据集的 id and name
可以使用感叹号操作符进行否定操作,我们有一组字段选择预设。支持 XML 和 JSON 格式。

示例:在指标资源上获取id和name:

/ api / indicators?fields = id,名称

示例:从数据元素中获取 id 和 name,并从相关数据集中获取 id 和 name:

/ api / dataElements?fields = id,name,dataSets [id,name]

示例:获取用户定义属性的 id、name 和值 ID 为 DnrLSdo4hMl 的组织单位的用户定义属性值:

/api/organisationUnits?fields=id,name,DnrLSdo4hMl

然后,该属性将作为每个匹配对象的属性 DnrLSdo4hMl 包含在响应中。属性。可以使用 rename 转换器进行重命名,如下一节所示。

要从输出中排除字段,可以使用感叹号!。操作符。这是在查询中的任何地方都允许的,而根本不会包括该属性,因为它可能已经插入了某些预设。

一些预设(选定的字段组)可用并且可以应用使用: 运算符。

表格属性操作符

操作员

描述

所需值	Parameter name
<object>[<field-name>, ...]	包含一个集合中的字段(将应用于该集合中的每个对象),或只包含一个对象上的字段。
!<field-name>,<object>[!<field-name>	请勿包含此字段名称,它也适用于对象/集合内部。在使用预设包含字段时非常有用。
,<object>[]	包括某个对象上的所有字段,如果应用于某个集合,则会包括该集合中所有对象上的所有字段。
:<preset>	别名,用于选择多个字段。目前有三种预设,请参阅下表了解说明。
表格字段预设	预设

描述

一应俱全	Parameter name
*	所有的别名
可识别	包括 id、名称、代码、创建、最后更新和最后更新由字段
可命名	包括 id、名称、简称、代码、描述、创建和最后更新字段
持续	返回对象的所有持久化属性,不考虑对象是否是关系的所有者。
所有者	返回对象上的所有持久化属性,其中该对象是所有属性的所有者,此有效负载可用于通过 API 进行更新。
示例:包括数据集中除组织单位以外的所有字段:	/ api / dataSets?fields =:all,!organizationUnits

示例:仅包含ID,名称和数据集中的组织单位集合,但不包含组织单位中的ID:

/ api / dataSets / BfMAe6Itzgt?fields = id,name,organisationUnits [:all,!id]

示例:包括所有指标的可命名属性:

/api/indicators.json?fields=:nameable

字段转换器 { #webapi_field_transformers }

字段转换器可用于转换属性。语法说明如下:

/api/dataElements/ID?fields=id_{rename(i),name}rename(n)

这会将 id 属性重命名为 i,将 name 属性重命名为 n。

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

/api/dataElementGroups.json?fields=id,displayName,dataElements~isNotEmpty~rename(haveDataElements)

下表列出了支持的转换器操作符。

表:可用转换器

名称

参数

类型	size	Parameter name
isEmpty		字符串或集合是否为空
isNotEmpty		字符串或集合是否不为空
rename		参数 1:名称
重命名属性名称	paging	参数 1:页码,参数 2:页面大小
true	pluck	可选参数 1:字段名
将对象数组转换为对象选定字段的数组。默认情况下,使用集合返回的第一个字段(通常是 ID)。	keyBy	可选参数 1:字段名
将对象数组转换为以字段名(默认 id)为键的对象。这对 JavaScript 中的快速查找非常有用。	keyBy	变压器使用示例如下。

获取集合的大小:

/api/dataElements?fields=dataSets~size

测试集合是否为空:

/api/dataElements?fields=dataSets~isEmpty

测试集合是否为空:

/api/dataElements?fields=dataSets~isNotEmpty

重命名属性

/api/dataElements/ID?fields=id~rename(i),name~rename(n)

对集合进行分页:

/api/dataElementGroups?fields=id,displayName,dataElements~paging(1;20)

获取包含组织单位 ID 的数组:

/api/categoryOptions.json?fields=id,organisationUnits~pluck

获取包含组织单位名称的数组:

/api/categoryOptions.json?fields=id,organisationUnits~pluck[name]。

通过d字段键入 dataElements 数组:

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy[id,name,valueType]。

通过valueType字段键入 dataElements 数组,因为多次点击这将生成(数据元素的)数组:

/api/dataElementGroups.json?fields=id,name,dataElements~keyBy(valueType)[id,name,valueType]。

元数据创建,读取,更新,删除,验证 { #webapi_metadata_crud }

DHIS2 中的所有元数据实体都有自己的 API 端点,支持 CRUD 操作(创建、读取、更新和删除)。端点 URL 遵循以下格式:

/ api /

entityName 使用驼峰命名法。例如,端点对于_数据元素_是:

/ api / dataElements

** 注意: ** 更新对象时,所有现有属性值都将被覆盖,即使新值为空。如果要对对象进行部分更新,请使用 JSON Patch API。

创建/更新参数 { #webapi_metadata_create_update }

以下请求查询参数可用于所有元数据端点。

表:可用的查询过滤器

参数

类型

需要	Potential duplicate status	检索和删除项目通知模板	Attribute identifiers	Parameter name
假	项目阶段	subjectTemplate	表示是否返回分页的元素列表。	枚举
Sets import strategy, `CREATE_AND_UPDATE` will try and match on identifier, if it doesn't exist, it will create the object.	创建_并_更新\|创建\|更新\|删除	subjectTemplate	创建和更新对象 { #webapi_creating_updating_objects }	要创建新对象,您需要知道端点、类型
格式,并确保您拥有所需的权限。作为
例如,我们将创建和更新一个常量。为了弄清楚
格式,我们可以使用新的 schema 端点来获取格式
描述。因此,我们将从获取该信息开始:

http:// /api/schemas/constant.json

从输出中,您可以看到创建所需的权限是F_CONSTANT_ADD,重要的属性是:name 和价值。由此,我们可以创建一个 JSON 负载并将其保存为文件称为constant.json:

{
  "name": "PI",
  "value": "3.14159265359"
}

与XML有效内容相同的内容:

<constant name="PI" xmlns="http://dhis2.org/schema/dxf/2.0">
  <value>3.14159265359</value>
</constant>

我们现在准备通过发送 POST 请求来创建新的*常量* 使用curl 的带有JSON 有效负载的constants端点:

curl -d @constant.json "http://server/api/constants" -X POST
  -H "Content-Type: application/json" -u user:password

将常量发布到演示中的具体示例服务器:

curl -d @constant.json "https://play.dhis2.org/api/constants" -X POST
  -H "Content-Type: application/json" -u admin:district

如果一切顺利,您应该看到类似以下的输出:

{
  "status": "SUCCESS",
  "importCount": {
    "imported": 1,
    "updated": 0,
    "ignored": 0,
    "deleted": 0
  },
  "type": "Constant"
}

更新过程将完全相同,您进行更改到 JSON/XML 负载,找出常量的 ID,然后向端点发送包含 ID 的 PUT 请求:

curl -X PUT -d @pi.json -H "Content-Type: application/json"
  -u user:password "http://server/api/constants/ID"

删除物件 { #webapi_deleting_objects }

删除对象非常简单,您需要知道 ID 和你要删除的类型的端点,让我们继续我们的上一节中的示例并使用*常量*。让我们假设 id 是 abc123,那么你需要做的就是发送 DELETE 对端点的请求 + id:

```bash

curl -X DELETE -u user:password "http://server/api/constants/ID"

成功删除应返回HTTP状态204(无内容)。

在集合中添加和删除对象 { #webapi_adding_removing_objects_collections } 

集合资源允许您修改集合
对象。

### 添加或删除单个对象 { #webapi_collections_adding_removing_single_objects } 

为了在对象集合中添加或删除对象,您
可以使用以下
    图案:

####     / api / {collection-object} / {collection-object-id} / {collection-name} / {object-id}

应该使用POST方法添加,使用DELETE方法删除
一个东西。当对象之间存在多对多关系时,
您必须首先确定哪个对象拥有该关系。如果不是
清除这是哪个对象,尝试两种方式调用以查看哪个有效。

模式的组成部分是:

集合对象:拥有您的集合的对象类型

想修改。

  - 集合对象 id:拥有该对象的对象的标识符
    要修改的集合。

  - 集合名称:您要修改的集合的名称。
    object id:要添加或删除的对象的标识符

  - 从集合。

  - 例如,为了删除标识符为 IDB 的数据元素
从具有标识符 IDA 的数据元素组中,您可以执行 DELETE
要求:
        删除/ api / dataElementGroups / IDA / dataElements / IDB

将带有标识符 IDB 的类别选项添加到带有
标识符 IDA 你可以做一个 POST
要求:

    POST / api / categories / IDA / categoryOptions / IDB

添加或删除多个对象 { #webapi_collections_adding_removing_multiple_objects } 

您可以在一个请求中从集合中添加或删除多个对象
具有这样的有效载荷:

#### ```json
{
  "identifiableObjects": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ]
}

使用此有效负载,您可以添加,替换或删除项目:

添加项目:

POST / api / categories / IDA / categoryOptions

更换物品:

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ],
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"
    }
  ]
}

删除项目:

删除/ api / categories / IDA / categoryOptions

在单个请求中添加和删除对象 { #webapi_collections_adding_removing_objects_single_request }

您可以在单个 POST 中从集合中添加和删除对象请求到以下 URL:

POST / api / categories / IDA / categoryOptions

有效负载格式为:

{
  "additions": [{
      "id": "IDA"
    }, {
      "id": "IDB"
    }, {
      "id": "IDC"
    }
  ],
  "deletions": [{
      "id": "IDD"
    }, {
      "id": "IDE"
    }, {
      "id": "IDF"
    }
  ]
}

验证有效载荷 { #webapi_validating_payloads }

DHIS 2 支持元数据有效载荷的系统范围验证,这意味着将检查 API 端点上的创建和更新操作允许进行更改之前的有效负载。找出哪些验证为特定端点准备好了,看看/api/schemas 端点,即要找出数据元素具有哪些约束,您会去/api/schemas/dataElement。

您还可以手动验证您的有效负载,方法是将其发送到适当的

架构端点。如果您想从创建中验证常量之前的部分,您可以这样发送:

POST / api / schemas / constant

一个简单的(非验证)示例为:

curl -X POST -d "{\"name\": \"some name\"}" -H "Content-Type: application/json"
  -u admin:district "https://play.dhis2.org/dev/api/schemas/dataElement"

这样就能得到结果:

[
   {
      "message" : "Required property missing.",
      "property" : "type"
   },
   {
      "property" : "aggregationOperator",
      "message" : "Required property missing."
   },
   {
      "property" : "domainType",
      "message" : "Required property missing."
   },
   {
      "property" : "shortName",
      "message" : "Required property missing."
   }
]

部分更新 { #webapi_partial_updates }

对于处理元数据的 API 端点,我们支持使用 JSON 补丁标准进行部分更新 (PATCH)。有效负载基本上概述了您想要应用于现有元数据对象的一组操作。有关 JSON 补丁的详细信息和示例,请参阅 jsonpatch.com。支持三个运算符:添加、删除和替换。

下面是几个与 DHIS2 相关的示例。请注意,对有效载荷的任何更新都应视为 HTTP PUT 操作,即任何突变都必须产生有效的 PUT 元数据有效载荷。

JSON 补丁的默认 importReportMode(导入报告模式)是 ERRORS_NOT_OWNER,这意味着在更新任何不属于该特定对象的属性时(例如,试图将指标组直接添加到指标中),会出现错误。

根据 JSON 补丁规范,发送补丁时必须始终使用 mimetype application/json-patch+json。

例子 { #examples }

更新数据元素的名称和值类型{ #update-name-and-value-type-of-data-element }

```

/api/dataElements.csv?fields=id,displayName,dataElementGroups

##### ```json
[
  {"op": "add", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/valueType", "value": "INTEGER"}
]

从 orgUnit 组中删除特定 orgUnit{ #remove-a-specific-orgunit-from-an-orgunit-group }

PATCH /api/dataElementGroups/{id}

```json

[ {"op": "add", "path": "/dataElements/-", "value": {"id": "data-element-id"}} ]

更改数据元素的域和值类型{ #change-domain-and-value-type-of-a-data-element }

PATCH /api/dataElementGroups/{id}

##### ```json
[
  {"op": "remove", "path": "/dataElements"}
]

更改数据元素的域和值类型{ #change-domain-and-value-type-of-a-data-element }

PATCH /api/dataElements/{id}

```json

[ {"op": "add", "path": "/domainType", "value": "TRACKER"}, {"op": "add", "path": "/valueType", "value": "INTEGER"} ]

从 orgUnit 组中删除特定 orgUnit{ #remove-a-specific-orgunit-from-an-orgunit-group }

PATCH /api/organisationUnitGroups/{id}

##### ```json
[
  {"op": "remove", "path": "/organisationUnits/1"}
]

受阻将 dataElementGroup 添加到 dataElement{ #blocked-add-dataelementgroup-to-dataelement }

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

```json

[ {"op": "add", "path": "/dataElementGroups/-", "value": {"id": "data-element-group-id"}} ]

按 id 删除收藏项{ #remove-collection-item-by-id }

PATCH /api/dataElements/{id}?importReportMode=ERRORS_NOT_OWNER

#### ```json
[
    {"op": "add", "path": "/dataElementGroups/0", "value": {"name": "new-name"}}
]

按 id 删除收藏项{ #remove-collection-item-by-id }

补丁 /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

```json

[ {"op": "remove-by-id", "path": "/organisationUnits", "id": "u6CvKyF0Db5"} ]

回应

如果`path`属性无效或不存在,则修补服务将返回如下错误。

#### ```
补丁 /api/dataSets/{id}?importReportMode=ERRORS_NOT_OWNER

[
    {"op": "remove-by-id", "path": "/test", "id": "u6CvKyF0Db5"}
]

回应

{
    "httpStatus": "Bad Request",
    "httpStatusCode": 400,
    "status": "ERROR",
    "message": "Invalid path /test"
}

元数据 CSV 导出{ #webapi_metadata_csv_export } CSV字段过滤与CSV(请注意,在/api/metadata端点上使用CSV不受支持)几乎相同,但字段转换尚不支持。

对于支持CSV的端点(如`/api/dataElements` `/api/organisationUnits`等我们的元数据端点),您可以使用`Accept`头部和值`text/csv`,或者您可以使用扩展名`.csv`。请注意,不支持复杂对象,我们仅支持id-object集合(因此将返回一个UID列表)。

名称

选项

类型	用户设置 { #webapi_user_settings }	Parameter name
默认过滤器是`id,displayName`	skipHeader	假/真
标题(包含列名)是否应包括在内	下载	默认值: `.`
立柱分离器	数组分隔符	默认值:`;`
如果其中一个字段是一个 ID 对象集合,该分隔符将分隔所有 UID	例子 { #examples }	获取包括组关联在内的所有数据元素{ #get-all-data-elements-including-their-group-associations }

```

/api/dataElements.csv?fields=id,displayName,dataElementGroups

#### 获取所有组织单位,包括几何(将被忽略){ #get-all-org-units-including-geometry-which-will-get-ignored }

/api/organisationUnits.csv?fields=id,displayName,organisationUnitGroups,geometry

#### 元数据导出 { #webapi_metadata_export } 

本节介绍了可在以下位置获得的元数据 API
`/api/元数据`。支持 XML 和 JSON 资源表示。

##     / api /元数据

最常用的参数在下面的“导出参数”中描述
桌子。您还可以使用以下方法将其应用于所有可用类型
`type:fields=<filter>` 和 `type:filter=<filter>`。你也可以
通过设置 `type=true|false` 启用/禁用某些类型的导出。

表:导出参数

名称

选项

| 类型 | 用户设置 { #webapi_user_settings }  | Parameter name |
|---|---|---|
| 默认过滤器是`id,displayName` | 过滤 | 与元数据对象过滤器相同 |
| 数据值 | 订单 | 与元数据顺序相同 |
| iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。 | 译 | 假/真 |
| 启用翻译。请注意,默认情况下这是关闭的(在其他端点,默认情况下是打开的)。 | 下载 | <locale\> |
| 从用户本地语言更改为自定义本地语言。 | 默认 | 包括/排除 |
| 是否应在有效载荷中包含自动生成的类别对象。如果您要在两个非同步实例之间移动元数据,可能需要将其设置为 EXCLUDE,以方便处理这些生成的对象。 | 跳过共享 | 假/真 |
| 跳过共享属性,更新时不合并共享,创建新对象时不添加用户组访问权限。 | 下载 | NON_NULL, ALWAYS, NON_EMPTY |
| *NON_NULL* 包括非空属性,*ALLWAYS* 包括所有属性,*NON_EMPTY* 包括非空属性(不包括长度为 0 的字符串或空集合)。 | 下载 | 假/真 |
| 启用此功能将添加 HTTP 标头 Content-Disposition,指定数据应作为附件处理,并由网络浏览器提供下载。 | 下载 | 导出所有元数据。小心,因为响应可能非常大,具体取决于
关于您的元数据配置: |

###     / api /元数据

导出由lastUpdated降序排列的所有元数据:

表:导出参数

导出仅包括指标和指标组的元数据:

    / api / metadata?indicators = true&indicatorGroups = true

导出所有数据元素的id和displayName,按displayName排序:

    / api / metadata?dataElements:fields = id,name&dataElements:order = displayName:desc

导出名称以“ ANC”开头的数据元素和指示符:

    / api / metadata?filter = name:^ like:ANC&dataElements = true&indicators = true

具有依赖项的元数据导出 { #webapi_dataset_program_export_dependencies } 

当您想交换数据集、项目、类别组合、仪表盘、选项集或数据元素组的元数据时、
仪表板、选项集或数据元素组的元数据时
时,有六个专用端点可供使用:

### ```
/api/dataSets/{id}/metadata.json

/api/programs/{id}/metadata.json

/api/categoryCombos/{id}/metadata.json

/api/dashboards/{id}/metadata.json

/api/optionSets/{id}/metadata.json

/api/dataElementGroups/{id}/metadata.json

然后可以使用/ api / metadata导入这些导出。

这些端点还支持以下参数:

表:导出参数

名称

选项

类型	用户设置 { #webapi_user_settings }	Parameter name
跳过共享属性,更新时不合并共享,创建新对象时不添加用户组访问权限。	下载	NON_NULL, ALWAYS, NON_EMPTY
启用此功能将添加 HTTP 标头 Content-Disposition,指定数据应作为附件处理,并由网络浏览器提供下载。	下载	导出所有元数据。小心,因为响应可能非常大,具体取决于
关于您的元数据配置:

/ api /元数据

导入器允许您导入元数据有效负载,其中可能包括许多不同的实体和每个实体的任意数量的对象。元数据导出元数据导出API生成的可以直接导入。

表:导出参数

表:导入参数

名称

选项(第一项为默认值)

类型	导入模式	Parameter name
设置整体导入模式,决定是否仅 `VALIDATE` 或也 `COMMIT` 元数据,这与我们旧的 dryRun 标志具有相似的功能。	标识符	uid、代码、自动
设置用于引用匹配的标识符方案。`AUTO`表示先尝试`UID`,再尝试 `CODE`。	导入报告模式	错误、全部、调试
设置 `ImportReport` 模式,控制导入完成后报告的内容。`ERRORS`只包含有错误的对象的 ObjectReport 报告。`FULL`返回所有已导入对象的 ObjectReport ,而 `DEBUG`则返回相同对象名称(如果有)。	预热模式	参考、全部、无
设置预热器模式,用于指示是否应该对 `ALL` 进行预热(就像以前使用 preheatCache=true 一样)或对对象进行更智能的扫描以查看要预热的内容(现在是默认设置),将其设置为不推荐使用`无`。	导入策略	CREATE_AND_UPDATE, CREATE, UPDATE, DELETE
Sets import strategy, `CREATE_AND_UPDATE` will try and match on identifier, if it doesn't exist, it will create the object.	原子模式	全部,无
设置原子模式,在旧的导入器中,我们总是进行best effort导入,这意味着即使某些引用不存在,我们仍然会导入(即数据元素组导入时缺少数据元素)。新进口商的默认设置是不允许这样做,并且类似地拒绝任何验证错误。设置 `NONE` 模式模拟了旧的行为.	冲洗模式	自动,目标
设置刷新模式,控制何时刷新内部缓存。强烈建议将其保留为`AUTO`(这是默认设置)。仅将 `OBJECT` 用于调试目的,您会看到休眠异常并想查明堆栈发生的确切位置(休眠只会在刷新时抛出,因此很难知道哪个对象有问题)。	跳过共享	假,真
跳过共享属性,更新时不合并共享,创建新对象时不添加用户组访问权限。	跳过验证	假,真
跳过导入的验证。`不推荐`。	跳过验证	假,真
异步导入时,会立即返回一个 Location 标头,指向 importReport 的位置。有效载荷还包含一个已创建任务的 json 对象。	跳过验证	无、当前、选定
允许你覆盖正在导入的每个对象的用户属性,选项包括 NONE(不做任何操作)、CURRENT(使用导入用户)、SELECTED(使用 overrideUser=X 选择特定用户)。	覆盖用户	用户 ID
如果 userOverrideMode 为 SELECTED,则使用此参数选择要覆盖的用户。	> NOTE When updating objects, all property values will be overwritten even if the new values are `null`. Please use JSON Patch API in case you want do partial update to an object.	要导入的元数据负载的示例如下所示。注意如何
每个实体类型都有自己的属性和一个对象数组:

{
  "dataElements": [
    {
      "name": "EPI - IPV 3 doses given",
      "shortName": "EPI - IPV 3 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    },
    {
      "name": "EPI - IPV 4 doses given",
      "shortName": "EPI - IPV 4 doses given",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "valueType": "INTEGER_ZERO_OR_POSITIVE"
    }
  ],
  "indicators": [
    {
      "name": "EPI - ADS stock used",
      "shortName": "ADS stock used",
      "numerator": "#{LTb8XeeqeqI}+#{Fs28ZQJET6V}-#{A3mHIZd2tPg}",
      "numeratorDescription": "ADS 0.05 ml used",
      "denominator": "1",
      "denominatorDescription": "1",
      "annualized": false,
      "indicatorType": {
        "id": "kHy61PbChXr"
      }
    }
  ]
}

将此有效负载发布到元数据端点时,响应将包含有关导入过程中使用的参数的信息和每个摘要实体类型,包括创建、更新、删除和忽略:

{
  "importParams": {
    "userOverrideMode": "NONE",
    "importMode": "COMMIT",
    "identifier": "UID",
    "preheatMode": "REFERENCE",
    "importStrategy": "CREATE_AND_UPDATE",
    "atomicMode": "ALL",
    "flushMode": "AUTO",
    "skipSharing": false,
    "skipTranslation": false,
    "skipValidation": false,
    "metadataSyncImport": false,
    "firstRowIsHeader": true,
    "username": "UNICEF_admin"
  },
  "status": "OK",
  "typeReports": [
    {
      "klass": "org.hisp.dhis.dataelement.DataElement",
      "stats": {
        "created": 2,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 2
      }
    },
    {
      "klass": "org.hisp.dhis.indicator.Indicator",
      "stats": {
        "created": 1,
        "updated": 0,
        "deleted": 0,
        "ignored": 0,
        "total": 1
      }
    }
  ],
  "stats": {
    "created": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0,
    "total": 3
  }
}

GeoJSON 导入 { #geojson-import }

GeoJSON 导入用于将几何数据附加到组织单位。

对于批量导入,需要一个带有特征集合的 GeoJSON 文件。

该集合中的每个地物都需要指向其应链接到的组织单位的引用。的引用。

默认情况下,文件中的几何图形存储为组织单位的几何图形属性。要存储额外的几何图形,可以创建GEOJSON类型的属性。当使用属性时,文件中的所有几何图形都存储为相同的属性,该属性提供了一个附加参数attributeId。

GeoJSON 批量数据导入{ #webapi_geojson_bulk_import }

表:导入参数

名称

类型

| 类型 | Potential duplicate status | 仪表板资源将提供仪表板列表。请记住仪表板对象是共享的,因此列表将受当前已验证的用户。您可以检索有关一个的更多信息特定的仪表板,请点击其链接,类似于: | Parameter name | |-------------------|--------------------------------|---|-----------------------------------------------------------------------------------------------------------------------------------| | true | Field Presets { #field-presets } | Tracker import { #webapi_tracker_import } | String | | 未定义 | JSON格式 | dryRun | enum:[id、code、name] | | id | GeoJSON 文件中使用的标识符所指向的组织单位属性 | attributeId | String | | 未定义 | JSON格式 | dryRun | boolean | | false | Field Presets { #field-presets } | flushMode | boolean | | false | Field Presets { #field-presets } | flushMode | POST /api/organisationUnits/geometry |

The post body is the GeoJSON file. Content type should be application/json or application/geo+json. The file may be .zip or .gzip compressed.

For example, a default file where id is used to refer to an organisation unit id has this structure:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "O6uvpzGd5pu",
      "geometry": { ... }
    },
    ...
  ]
}

一个使用特征属性来引用组织单位代码的文件将采用这种结构:

{ 
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "code": "OU1_CODE" },
      "geometry": { ... }
    },
    ...
  ]
}

几何体中的 坐标可以是成对的,也可以是三维的。如果存在第三个维度,则会在导入时去除。

几何图形也可以是空,以有效清除或删除特定组织单位的几何图形。删除。下一节将介绍一种特殊的批量删除 API。将在下一节中介绍。同步运行时,会直接返回导入报告。 HTTP 状态代码总是 OK,消息有效载荷中的 status表示是否所有记录都已成功导入。表示是否成功导入了所有行。报告中包含的导入计数统计信息可提供更多信息:

imported(导入的):成功更新了几何图形的组织单位数量,该组织单位在更新属性之前没有几何图形

updated: number of organisation units that were successfully updated with a geometry that did have value for the updated property already

ignored: number of organisation units that failed to update
deleted: number of organisation units that where successfully update with a empty geometry
When the import is run asynchronous the request returns immediately with status OK and job configuration response that contains a relative reference to the task endpoint that allows to track the status of the asynchronous import. For example:
/api/system/tasks/GEOJSON_IMPORT/{job-id}

同步执行时直接返回的摘要见

/api/system/taskSummaries/GEOJSON_IMPORT/{job-id}

一旦导入完成。

GeoJSON 批量数据删除{ #webapi_geojson_bulk_deletion }

要清除或取消设置所有组织单位的几何数据,请使用:

DELETE /api/organisationUnits/geometry

要清除或取消设置所有组织单位的特定 GEOJSON 属性的几何体数据,请使用所有组织单位使用:

DELETE /api/organisationUnits/geometry?attributeId={attr-id}

Clearing is always synchronous and returns a similar report as the bulk import. It does not support any other parameters. No dry-run can be performed. Bulk clearing requires the F_PERFORM_MAINTENANCE authority.

GeoJSON 单一数据导入{ #webapi_geojson_single_import }

单次导入可以更新单个组织单元的几何图形。

POST /api/organisationUnits/{id}/geometry

例如,帖子正文只包含 GeoJSON geometry 值:

{
  "type": "Polygon",
  "coordinates": [...]
}

单次导入只支持 attributeId 和 dryRun 参数。 GeoJSON 单一数据删除{ #webapi_geojson_single_deletion } 要清除单个组织单位的 geometry GeoJSON 数据,请使用

DELETE /api/organisationUnits/{id}/geometry

同样,要清除单个组织的 GEOJSON 属性值单位使用:

DELETE /api/organisationUnits/{id}/geometry?attributeId={attr-id}

Clearing is always synchronous returns a similar report as single import. The dry-run parameter is supported as well. The performing user requires authority to modify the target organisation unit.

架构图 { #webapi_schema }

可用于内省所有可用 DXF 2 对象的资源可以在/api/schemas 上找到。对于特定资源,您可以拥有查看/api/schemas/<type>。

要获取XML中所有可用的模式:

GET /api/schemas.xml

要获取JSON中所有可用的模式,请执行以下操作:

GET /api/schemas.json

要获取特定类的JSON模式:

GET /api/schemas/dataElement.json

图示 { #webapi_icons }

DHIS2 包含一系列图标,可用于为元数据提供可视化语境。元数据的上下文。有两种不同的图标:

默认图标:预装在应用项目中,无法修改或删除。

自定义图标:可任意创建、更新和删除。 - 它们都可以通过图标资源访问。 - GET /api/icons

此端点返回有关可用默认图标和自定义图标的信息列表。默认情况下,关键字、描述、关键字和 href 将包含在响应中。但可以使用字段参数来改变这种行为。

{
  key: "mosquito_outline",
  description: "Mosquito outline",
  keywords: [
    "malaria",
    "mosquito",
    "dengue"
  ],
  "created": "2024-02-12T09:50:11.794",
  "lastUpdated": "2024-02-12T09:50:11.794",
  href: "<dhis server>/api/icons/mosquito_outline/icon.svg"
}

也可以通过关键字过滤直接获取特定图标,在下面的例子中,关键字是 mosquito_outline。

GET /api/icons/mosquito_outline

自定义图标操作{ #webapi_icons_custom }

可通过某些请求参数获取自定义图标列表

GET /api/icons?type=CUSTOM

请求参数

类型

允许值	Potential duplicate status	`order`	Parameter name
jobType	`search`	`keys`	`Text`
应检索的自定义图标键列表	`createdStartDate`		`Text`
应检索自定义图标的关键字列表	`createdStartDate`		`Text`
在图标键和关键字中搜索给定文本,并检索键或关键字中包含该文本的所有图标。	`createdStartDate`		`Date`
创建日期的起点	`createdEndDate`		`Date`
创建日期的终点	`createdEndDate`		`Date`
最后更新日期的起点	`createdEndDate`		`Date`
最后更新日期的终点	`createdEndDate`		请求参数

类型

允许值	Potential duplicate status	`order`	Parameter name
comma separated list of fields or presets to include	要返回的页码。如果缺少,默认为 1	`paging`	`Integer`
默认	要返回的页码。如果缺少,默认为 1	`paging`	`Boolean`
`true`\|`false`	表示是否应忽略分页并返回所有行。默认为 `true`,即默认情况下所有请求都分页,除非 `paging=false`.	用于订购{ #request-parameters-for-ordering } 的请求参数	请求参数

类型

允许值	Potential duplicate status	`order`	Parameter name
extent of fields selected by `*` field selector	`createdStartDate`	用于过滤响应的请求参数{ #request-parameter-to-filter-responses }	The endpoints accept a `fields` parameter which controls which fields will be returned in the
JSON response. `fields` parameter accepts a comma separated list of field names. If nothing is specified, default fields will be used and those are

`key,keywords,description,fileResourceUid,createdByUserUid,href`

可通过提供图标密钥下载自定义图标资源:

GET /api/icons/{key}/icon

自定义图标可以创建、修改和删除。要创建自定义图标,请使用下面的资源。

POST /api/icons

它需要一个包含图标关键字、描述、关键字列表和文件资源 uid 的有效载荷来链接数据。

{
    "key": "iconKey",
    "description": "description",
    "keywords": ["keyword 1","keyword 2"],
    "fileResourceUid": "ARsqBjfB2cf"
}

只能使用以下资源更新自定义图标。

PUT /api/icons

通过以下有效载荷,图标的描述和关键字将被更新。

{
    "key": "iconKey",
    "description": "new description",
    "keywords": ["new keyword 1", "new keyword 2"] 
}

请注意,也可以只更新其中一个。也就是说,如果我们想更新描述,同时保留关键字,只需提供图标键和描述 json 字段即可。反之亦然,更新关键字的同时保留原始描述。

只能使用以下资源删除自定义图标。

DELETE /api/icons/{icon_key}

渲染类型 { #webapi_render_type }

某些元数据类型具有名为 renderType 的属性。渲染类型属性是 device 和 renderingType 之间的映射。应用可以使用此信息作为有关如何呈现对象的提示在特定设备上。例如,移动设备可能想要渲染与台式计算机不同的数据元素。

当前有两种不同的renderingTypes可用:

值类型渲染

项目阶段部分渲染

还提供2种设备类型:
移动

桌面

下表列出了可用的元数据和呈现类型。值类型呈现具有基于元数据的附加约束配置,这将显示在第二个表中。
表格元数据和渲染类型概览

元数据类型

可用的渲染类型

项目阶段部分	* 列表(默认) * 序列 * 矩阵
跟踪实体属性	* DEFAULT * DROPDOWN * VERTICAL_RADIOBUTTONS * HORIZONTAL_RADIOBUTTONS * VERTICAL_CHECKBOXES * HORIZONTAL_CHECKBOXES * SHARED_HEADER_RADIOBUTTONS * ICONS_AS_BUTTONS * SPINNER * ICON * TOGGLE * VALUE * SLIDER * LINEAR_SCALE * AUTOCOMPLETE * QR_CODE * BAR_CODE * GS1_DATAMATRIX
描述	表:根据值类型允许的渲染类型

值类型

对象是一个选项集吗?

false \| true	TRUE_ONLY	不
单个变更建议可通过以下方式查看	Program notification template	不
JSON object for `ADD` proposal, JSON array for `UPDATE` proposal, nothing for `REMOVE` proposal	Program notification template
Note that synthetic fields `displayName` and `displayShortName` are always
returning the translated value independent of the `translate` parameter.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	不
验证基于此 regex `^[0-9+#\.\s\/ext-]{6,50}$`.最大长度为 50。例如+4733987937, (+47) 3398 7937, (47) 3398 7937.123	Program notification template	不
创建提案的日期时间	不	不
一般电子邮件格式 abc@email.com	Program notification template
`true` or `false`	Program notification template
数字	Program notification template
没有	Program notification template
没有	Program notification template
数值长度 = 1 并且是字母	Program notification template

值类型渲染也有一些额外的属性,可以设置,通常在渲染某些特定类型时需要:

表:renderType 对象属性

财产

描述

指标组	Parameter name	Potential duplicate status
枚举(参见元数据和渲染类型表中的列表)	分钟	仅用于值类型渲染。表示该字段可以具有的最小值。
整数	最大	Enrollments
最小-最大数据元素 { #webapi_min_max_data_elements }	步骤	Enrollments
整数	小数点	Enrollments
整数	renderingType 可以在创建或更新第一个表中列出的元数据时设置。项目阶段部分的渲染类型的示例负载如下所示:	Enrollments

对于数据元素和跟踪的实体属性:

{
  "renderingType": {
    "type": "SLIDER",
    "min": 0,
    "max": 1000,
    "step": 50,
    "decimalPoints": 0
  }
}

对象样式 { #webapi_object_style }

大多数元数据都有一个属性名称“样式”。可以使用此属性由客户以某种方式表示对象。属性目前支持的样式如下:

表格样式属性

财产

描述

指标组	Parameter name	Potential duplicate status
字符串 (#000000)	图标	图标,由图标名称表示。
串	目前,没有官方列表或对图标库的支持,所以
这目前由客户提供。下面的列表显示
所有支持样式的对象:	具有以下要求:

数据元素类别选项

描述
指示符
<indicator-id>
对于组织单位维度,您可以指定组织
Validation rule
IndicatorGroup
项目阶段
项目阶段部分
关系(跟踪器)
跟踪实体属性
追踪实体类型
在创建或更新任何这些对象时,您可以包括以下有效负载更改样式:

```json { "style": { "color": "#ffffff", "icon": "my-beautiful-icon" } }

类别选项{ #category-option } 

合并类别选项{ #category_option_merge }

## 类别{ #category } 

### 合并类别{ #category_merge }

类别合并端点允许您将多个类别（源）合并为一个目标类别。

> **注**
>
> 类别只能在以下情况下合并
> 
> 1. 它们具有相同的类别选项<br> 
> 源类别和目标类别不共享类别组合<br> 
> 3. 源类别之间不共享类别组合<br> 
>
> 这些限制确保只有重复的类别才能被合并，并有助于保持系统的完整性。

#### 请求{ #request } 

执行类别合并所需的主要权限是 `F_CATEGORY_MERGE`。

####     /api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

通过 POST 请求合并类别：

POST /api/categories/merge

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

| The manual merge is suitable when there are resolvable conflicts or when not all the data needs to
be moved during the merge. For example, if an attribute has different values in both tracked
entities , the user can specify whether to keep the original value or move over the duplicate's
value. Since the manual merge involves the user explicitly requesting to move data, there are some
additional checks:         | 检索和删除项目通知模板 | ```json
{
  "object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userAccesses": [],
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}
```                                                                            |
|---------------|----------|----------------------------------------------------------------------------------|
| 要合并的类别选项(源类别选项)的标识符数组       | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```      | 要合并的类别（源类别）的标识符数组          |
| 将来源合并为指标(目标指标)的标识符        | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```      | 将来源合并为类别（目标类别）的标识符       |
| 是否在操作后删除源类别选项。默认为假。 | Program notification template       | 是否在操作后删除源类别。默认为假。   |

合并操作将把源类别合并到目标类别中。可以指定一个或多个源类别。只能指定一个目标。

合并操作会将所有源类别元数据关联转移到目标类别。
以下元数据将被更新：

| 采取的行动          | 指标组              | 类别选项组合                                                                                                                                                                              |
|-------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 删除来源    | 类别            | 类别选项组合                                                                                                                                                                            |
| 删除来源     | 类别            | 成员                                                                                                                                                                |
| 删除来源,添加目标 | 周期(pe)             | 选项组合                                                                                                                                                                |
| Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)).              | catDimensionConstraints | - 用户有一个或多个源和目标 -> 删除所有源约束<br/> - 用户有一个或多个源，无目标 -> 将一个源更新为目标，删除其他源约束 |


#### 删除源

错误代码

描述

| json(应用项目/ json) | Parameter name                                                                          |
|------------|--------------------------------------------------------------------------------------|
| E1531      | 必须指定至少一个来源类别                                       |
| E1532      | 必须指定目标类别                                                    |
| E1533      | 目标类别不能是源类别                                          |
| 回复{ #response }       | 源/目标类别不存在： `{uid}`                                       |
| E1535      | 源类别选项与目标类别选项不匹配                           |
| E1536      | 源类别和目标类别不能共享一个类别组合                            |
| E1537      | 源类别不能共享类别组合                                       |


#### 成功响应示例如下
##### ```json
{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "response": {
        "mergeReport": {
            "mergeErrors": [],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [
                "vQ0dGV9EDrw"
            ],
            "message": "IndicatorType merge complete"
        }
    }
}

错误响应示例如下

``json { "httpStatus"："OK"、 "httpStatusCode"：200, "status"："确定"、 "响应"：{ "mergeReport"：{ "mergeErrors"：[], "mergeType"："类别"、 "sourcesDeleted"：[ "FbLZS3ueWbQ"、"dPSWsKeAZNw" ], "消息"："类别合并完成" } } }

##### ```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

数据库约束样本错误响应:

`json { "httpStatus"："冲突"、 "httpStatusCode"：409, "status"："WARNING"、 "消息"："发生了一个或多个错误，请查看合并报告中的全部详情。"、 "响应"：{ "mergeReport"：{ "mergeErrors"：[ { "message"："必须指定至少一个源类别"、 "errorCode"："E1530", "args"：[] }, { "message"："目标类别不存在：abcdefg1221`"、 "errorCode"："E1533", "args"：[ "目标"、 "abcdefg1221" ] } ], "合并类型"："类别"、 "sourcesDeleted"：[], "消息"："类别合并有错误" } } }

## 通过类别选项合并端点,可以将多个类别选项(源)合并为一个目标类别选项。

### 授权{ #authorisation } 

执行类别选项合并所需的主要权限是 `F_CATEGORY_OPTION_MERGE`。  
其他所需的权限涉及类别选项的一般共享和访问,即 `F_CATEGORY_OPTION_PUBLIC_ADD` 和 `F_CATEGORY_OPTION_DELETE`。

#### 请求{ #request } 

通过 POST 请求合并类别选项:

####     /api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

JSON 格式的有效载荷如下所示:

```json
{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "deleteSources": true
}

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

元数据

财产

采取的行动	指标组	类别选项组合
The status code will be `204 No Content` if the data value was successfully saved or updated, or `409 Conflict` if there was a validation error (e.g. more than one `SHORT_NAME` for the same `locale`).	类别选项组	成员
删除来源,添加目标	类别选项组合	成员
删除来源,添加目标	类别选项组	成员
删除来源,添加目标	组织单位	成员
DataElementCategory	类别选项组	成员

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定目标类别选项
E1532	目标类别选项不能是源类别选项
E1533	源/目标类别选项不存在: `{uid}`
回复{ #response }	成功{ #success }

成功响应示例如下

```json

{ "httpStatus": "OK", "httpStatusCode": 200, "status": "OK", "response": { "mergeReport": { "mergeErrors": [], "mergeType": "IndicatorType", "sourcesDeleted": [ "vQ0dGV9EDrw" ], "message": "IndicatorType merge complete" } } }

错误响应示例如下

错误响应示例如下

##### ```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

数据库约束样本错误响应:

进口验证{ #category_option_combo_import_validation }

`CategoryOptionCombo`s are unique in that they are auto-generated by the system, most of the time (imports are allowed with specific expectations, mentioned below). They are generated based on their category model:

`CategoryOption`

Category (has category options) - CategoryCombo (has categories) - 将为 Category``CategoryOption 的每个组合创建一个 CategoryOptionCombo。 - 生成的 CategoryOptionCombo 示例{ #gen_category_option_combo_example }

有 1 个 CategoryCombo [CC1]

CC1 有 2 个类别 CC1=[C1, C2]

Each Category has 2 CategoryOptions C1=[CO1, CO2], C2=[CO3, CO4]
从该类别模型生成的 CategoryOptionCombos 将产生 4 个 CategoryOptionCombos:
CO1=[CO1, CO3]
CO2=[CO1, CO4]
CO3=[CO2, CO3]
CO4=[CO2, CO4]
在尝试导入 CategoryOptionCombos 时,理解这一点非常重要。导入 CategoryOptionCombos 时会执行验证,以确保提供的 CategoryOptionCombos 集与预期生成的 CategoryOptionCombos 集一致。这是为了确保不会有无效的状态/关系进入系统,从而防止出现各种问题(孤儿数据、数据库中未在 API 中公开的隐藏关系等)。
Note

This validation is performed using the UIDs of the CategoryOptionCombos. No other idScheme is supported.

合并类别选项组合{ #category_option_combo_merge }

类别选项组合合并端点允许你将一些类别选项(源)合并到一个目标类别选项中。这可用于清理系统,例如删除重复内容。

> 注

只能合并重复的类别选项组合。有关这方面的更多信息,请参阅下面的验证部分。

授权{ #authorisation } 执行类别选项组合合并所需的主要权限是 F_CATEGORY_OPTION_COMBO_MERGE。

请求{ #request }

通过 POST 请求合并类别选项组合:

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

JSON 格式的有效载荷如下所示:

{
  "sources": [
    "FbLZS3ueWbQ",
    "dPSWsKeAZNw"
  ],
  "target": "rEq3Hkd3XXH",
  "dataMergeStrategy": "DISCARD"
}

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

注

在合并过程中,所有源类别选项组合都会被删除。这是因为在处理完所有源引用后,会留下空的类别选项组合。系统认为这些选项组合无效。

更新以下元数据

元数据

财产

采取的行动	指标组	类别选项组合
删除来源	类别组合	类别选项组合
删除来源	数据元素操作数	类别选项组合
设定为目标	数据值审计	表情
设定为目标	表达	表情
以目标取代源	指示符	选项组合
对于组织单位维度,您可以指定组织	指示符	选项组合
对于组织单位维度,您可以指定组织	最小最大数据元素	选项组合
设定为目标	预测变量	表情
选项	SMSCode	表情
设定为目标	类别标识	表情

采取的行动	指标组	类别选项组合
根据合并策略(DISCARD / LAST_UPDATED)进行操作。DISCARD 将删除所有源数据值。LAST_UPDATED 将使用最后更新的数据值(如果存在多个数据值)。	数据值审计	属性选项组合
根据合并策略(DISCARD / LAST_UPDATED)进行操作。DISCARD 将删除所有源数据值。LAST_UPDATED 将使用最后更新的数据值(如果存在多个数据值)。	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合
合并策略(DISCARD 或 LAST_UPDATED)	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合
DISCARD 或离开,取决于是否删除信息源	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合
合并策略(DISCARD 或 LAST_UPDATED)	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合
DISCARD 或离开,取决于是否删除信息源	数据值审计	属性选项组合
DISCARD 或离开,取决于是否删除信息源	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合
合并策略(DISCARD 或 LAST_UPDATED)	> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	属性选项组合

适用以下限制和错误代码。其中一个主要验证点是关于重复的 CategoryOptionCombos。一个重复的 CategoryOptionCombo 就是一个满足条件的 CategoryOptionCombo:

删除源

具有相同的类别选项 - 有不同的 UID - 表:限制条件和错误代码 - 错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定目标 CategoryOptionCombo
E1532	目标 CategoryOptionCombo 不能是源 CategoryOptionCombo
E1533	源/目标 CategoryOptionCombo 不存在: `{uid}`
回复{ #response }	必须指定 dataMergeStrategy 字段。值为 `DISCARD` 或 `LAST_UPDATED` 时
数据库约束{ #database-constraints }	类别选项组合必须重复(相同的类别组合、相同的类别选项、不同的 UID)才能合并
数据库约束{ #database-constraints }	有一些独特的制约因素可能会妨碍成功合并。这些限制由 DHIS2 设置,以维持一个逻辑域模型。
以下是撰写本文时已知的数据库唯一键约束列表。例如
只能有 1 个具有相同组织单位、数据元素和类别选项组合的最大最小数据元素。

表:数据库表唯一键约束

表格

唯一键约束

最小数据元素	orgunit, dataelement, categoryoptioncombo
计划阶段	项目阶段、数据元素

成功响应示例如下

```json

错误响应示例如下

错误响应示例如下

##### ```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

数据库约束样本错误响应:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

数据元素 { #data-elements }

本节介绍指标和指标表达式。

类别组合{ #category-combo }

合并类别组合{ #category_combo_merge }

类别组合合并端点允许您将多个类别组合（源）合并为一个目标类别组合。

注

类别组合只有在以下情况下才能合并：

源类别组合和目标类别组合具有相同的类别
属于所涉类别组合的所有类别选项组合都是有效的（选项数量正确，选项成员有效）
所涉及的类别组合中不存在重复的类别选项组合

这些约束条件确保只有等同的类别组合才能被合并，并有助于维护系统的完整性。

警告

类别组合合并会产生重复的类别选项组合。在类别组合合并后，应立即合并这些组合，以保持系统的完整性。可以使用数据完整性检查 "category_option_combos_have_duplicates "发现重复。

请求{ #request }

执行类别组合合并所需的主要权限是 F_CATEGORY_COMBO_MERGE。

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

通过 POST 请求合并类别组合：

POST /api/categoryCombos/merge

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

合并操作将把源类别组合合并到目标类别组合中。可以指定一个或多个源类别组合。只能指定一个目标。

合并操作会将所有源类别组合元数据关联转移到目标类别组合。以下元数据将被更新：

采取的行动	指标组	类别选项组合
The status code will be `204 No Content` if the data value was successfully saved or updated, or `409 Conflict` if there was a validation error (e.g. more than one `SHORT_NAME` for the same `locale`).	类别组合	类别选项组合
删除来源,添加目标	类别组合	表情
Property name	类别组合	表情
设定为目标	类别组合	表情
DataElementGroup	类别组合	表情
IndicatorGroup	类别组合	表情
IndicatorGroup	注册类别组合	表情
以目标取代源	类别组合	表情
以目标取代源	属性类别组合	表情
数据审批工作流程	类别组合	表情

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定至少一个源 CategoryCombo
E1532	必须指定目标类别组合
E1533	目标分类组合不能是源分类组合
回复{ #response }	源/目标 CategoryCombo 不存在： `{uid}`
E1545	源和目标类别组合必须具有相同的类别：源 `{uid}` 具有 `{categories}`
E1546	CategoryOptionCombo 的 CategoryOptions 数量不正确。本应是 `{n}`，但发现 `{m}` 的 COC: `{uid}`。
E1547	CategoryOptionCombo 具有对 CategoryCombo 类别无效的 CategoryOptions：`{uid}`
E1548	为 CategoryCombo `{uid}` 找到重复的 CategoryOptionCombo `{uid}`。请在尝试合并前修复此问题。

成功响应示例如下

```json

错误响应示例如下

``json
{
    "httpStatus"："OK"、
    "httpStatusCode"：200,
    "status"："确定"、
    "响应"：{
        "mergeReport"：{
            "mergeErrors"：[],
            "mergeType"："CategoryCombo"、
            "sourcesDeleted"：[
                "FbLZS3ueWbQ"、"dPSWsKeAZNw"
            ],
            "消息"："类别组合合并完成。合并后会出现重复的 CategoryOptionCombos。应立即合并，以保持系统完整性。可以使用数据完整性检查 "category_option_combos_have_duplicates "发现重复。
        }
    }
}

```json

{ "httpStatus": "Conflict", "httpStatusCode": 409, "status": "WARNING", "message": "One or more errors occurred, please see full details in merge report.", "response": { "mergeReport": { "mergeErrors": [ { "message": "At least one source DataElement must be specified", "errorCode": "E1530", "args": [] }, { "message": "Target DataElement does not exist: abcdefg1221", "errorCode": "E1533", "args": [ "Target", "abcdefg1221" ] } ], "mergeType": "DataElement", "sourcesDeleted": [], "message": "DataElement merge has errors" } } }

数据库约束样本错误响应:

``json
{
    "httpStatus"："冲突"、
    "httpStatusCode"：409,
    "status"："WARNING"、
    "消息"："发生了一个或多个错误，请查看合并报告中的全部详情。"、
    "响应"：{
        "mergeReport"：{
            "mergeErrors"：[
                {
                    "message"："必须指定至少一个源 CategoryCombo"、
                    "errorCode"："E1530",
                    "args"：[]
                },
                {
                    "message"："目标 CategoryCombo 不存在：`abcdefg1221`"、
                    "errorCode"："E1533",
                    "args"：[
                        "目标"、
                        "abcdefg1221"
                    ]
                }
            ],
            "合并类型"："CategoryCombo"、
            "sourcesDeleted"：[],
            "信息"："类别组合合并有错误
        }
    }
}

> 注意事项

合并 DataElements 时应格外小心。特别注意应特别注意合并涉及数据元素引用的数据值。合并。在执行合并之前,应充分了解合并的潜在副作用。合并。数据元素的合并具有深远的影响。以下信息数据元素合并的内容。数据元素合并涉及系统的所有主要部分(元数据、数据、跟踪器、分析和审计)。

如果源 DataElements 与大量数据/审计记录链接,系统性能可能会受到影响。

数据元素合并端点允许您将多个数据元素(源)合并为一个目标数据元素。

授权{ #authorisation }

执行数据元素合并所需的主要权限是 F_DATA_ELEMENT_MERGE。
所需的其他权限涉及数据元素的一般共享和访问,即 F_DATAELEMENT_PUBLIC_ADD 和 F_DATAELEMENT_DELETE。

请求{ #request }

通过 POST 请求合并数据元素:

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

JSON 格式的有效载荷如下所示:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true,
  "dataMergeStrategy": "DISCARD"
}

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

元数据

物业

采取的行动	指标组	类别选项组合
设定为目标	最小最大数据元素	数据元素
设定为目标	项目阶段数据元素	数据元素
删除来源,添加目标	最小最大数据元素	数据元素
项目	项目规则变量	数据元素
Points to note { #points-to-note }	最小最大数据元素	数据元素
fromToName, toFromName	最小最大数据元素	数据元素
设定为目标	最小最大数据元素	数据元素
设定为目标	最小最大数据元素	数据元素
设定为目标	最小最大数据元素	数据元素
设定为目标	最小最大数据元素	数据元素
选项	数据集元素	数据元素
设定为目标	最小最大数据元素	数据元素
设定为目标	最小最大数据元素	数据元素
删除来源,添加目标	数据元素组	成员
删除源指标,增加目标指标	数据元素组	成员
删除来源,添加目标	组织单位	成员
合并策略(DISCARD 或 LAST_UPDATED)	数据值	成员
对于组织单位维度,您可以指定组织	指示符	选项组合
对于组织单位维度,您可以指定组织	最小最大数据元素	选项组合
选项	预测变量	选项组合
选项	数据条目表格	选项组合
以目标取代源	计划指示器	选项组合
以目标取代源	指示符	选项组合
以目标取代源	数据值	选项组合
根据合并策略(DISCARD / LAST_UPDATED)进行操作。DISCARD 将删除所有源数据值。LAST_UPDATED 将使用最后更新的数据值(如果存在多个数据值)。	最小最大数据元素

采取的行动	指标组	类别选项组合
合并策略(DISCARD 或 LAST_UPDATED)	数据值	数据元素
根据合并策略(DISCARD / LAST_UPDATED)进行操作。DISCARD 将删除所有源数据值。LAST_UPDATED 将使用最后更新的数据值(如果存在多个数据值)。	最小最大数据元素	如果要删除信息源,则删除,否则不做任何操作。
数据值审计		适用以下限制条件和错误代码。
DISCARD 或离开,取决于是否删除信息源		适用以下限制条件和错误代码。

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定目标数据元素
E1532	目标数据元素不能是源指示符
E1533	源/目标数据元素不存在: `{uid}`
回复{ #response }	All source ValueTypes must match target ValueType: `ValueType`. Other ValueTypes found: `ValueType`
E1551	所有源 DataElementDomain 必须与目标 DataElementDomain 匹配:`DataElementDomain`。找到的其他 DataElementDomain:`DataElementDomain`。
E1534	必须指定 dataMergeStrategy 字段。值为 `DISCARD` 或 `LAST_UPDATED` 时
数据库约束{ #database-constraints }	类别选项组合必须重复(相同的类别组合、相同的类别选项、不同的 UID)才能合并

表:数据库表唯一键约束

表格

唯一键约束

最小数据元素	orgunit, dataelement, categoryoptioncombo
计划阶段	项目阶段、数据元素
数据元素	数据集、数据元素
回复{ #response }	成功{ #success }

成功响应示例如下

```json

错误响应示例如下

错误响应示例如下

##### ```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source DataElement must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target DataElement does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

数据库约束样本错误响应:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "All source ValueTypes must match target ValueType: `TEXT`. Other ValueTypes found: `NUMBER`",
                    "errorCode": "E1550",
                    "args": []
                }
            ],
            "mergeType": "DataElement",
            "sourcesDeleted": [],
            "message": "DataElement merge has errors"
        }
    }
}

数据库约束样本错误响应:

{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "ERROR: duplicate key value violates unique constraint \"minmaxdataelement_unique_key\"\n  Detail: Key (sourceid, dataelementid, categoryoptioncomboid)=(193236, 1148617, 167661) already exists."
}

数据元素 { #data-elements }

本节介绍指标和指标表达式。

综合指标

要检索指标,您可以向指标发出 GET 请求像这样的资源:

/ api /指标

指标表示可以计算和呈现的表达式因此。指标表达式分为分子和分母。分子和分母是数学的可以包含对数据元素、其他指标、常量和组织单位组。变量将替换为数据使用时的值,例如在报告中。允许的变量表达式在下表中描述。

表:指标变量

变量

目的

#{<programstage-id>.<dataelement-id>}	UID \	Parameter name
指集合数据元素和类别选项组合的组合。类别和属性选项组合 id 都是可选的,可以使用通配符"*"来表示任何值。	Syntax	类别选项组
指一个综合数据元素和一个类别选项组,包含多个类别选项组合。	#{<data-element-id>}	汇总数据元素
指所有类别选项组合中的聚合数据元素的总值。	D{<program-id>.<data-element-id>}	项目数据元素
引用项目中跟踪器数据元素的值。	IN_GROUP-<indicatorgroup-id>	指所有类别选项组合中的聚合数据元素的总值。
指项目中被跟踪实体属性的值。	I{<program-indicator-id>}	计划指标
指项目指示器的值。	<dataelement-id>	引用项目中跟踪器数据元素的值。
指报告率指标。指标可以是REPORTING_RATE,REPORTING_RATE_ON_TIME,ACTUAL_REPORTS,ACTUAL_REPORTS_ON_TIME,EXPECTED_REPORTS。	C{<constant-id>}	指项目中被跟踪实体属性的值。
指恒定值。	N{<indicator-id>}	指示符
指现有指标。	对于组织单位维度,您可以指定组织	组织单位组
指组织单位组内组织单位的数量。	Category combination	项目

值

| 响应示例: | json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } | Parameter name | |---|---|---| | 数据元素组中的所有汇总数据元素 | 数据元素组中的所有汇总数据元素 | deGroup:data-element-group-id | | 数据元素组中的所有汇总数据元素 | 类别-选项-组合-id | 类别-选项-组合-id | | 类别选项组合 | 类别选项组合 | co:category-option-id | | 类别选项组合 | 类别-选项-组合-id | coGroup:category-option-group-id | | 类别选项组合 | 类别-选项-组合-id | coGroup:co-group-id1&co-group-id2... | | 类别选项组合 | 语法看起来像这: | #{.} + C{} + OUG{} |

一个相应的例子看起来像这:

请注意,对于数据元素变量,类别选项组合标识符可以省略。该变量将代表总数对于数据元素,例如在所有类别选项组合中。例子:

数据元素操作数可以包括任何类别选项组合和属性选项组合,并使用通配符表示任何价值:

#{P3jJH5Tu5VC.S34ULMcHMca} + #{P3jJH5Tu5VC.*.j8vBiBqGf6O} + #{P3jJH5Tu5VC.S34ULMcHMca.*}

使用数据元素组的示例

#{deGroup:oDkJh5Ddh7d}+ #{deGroup:GBHN1a1Jddh.j8vBiBqGf6O}

使用类别选项、数据元素组和类别选项组的示例:

#{P3jJH5Tu5VC.co:FbLZS3ueWbQ}+ #{deGroup:GBHN1a1Jddh.coGroup:OK2Nr4wdfrZ.j8vBiBqGf6O}

使用多个类别选项组的示例:

#{P3jJH5Tu5VC.coGroup:OK2Nr4wdfrZ&j3C417uW6J7&ddAo6zmIHOk}

使用项目数据元素和项目属性的示例:

(D {eBAyeGv0exc.vV9UWAZohSf} * A {IpHINAT79UW.cejWyOfXge6})/ D {eBAyeGv0exc.GieVkTxp4HH}

结合计划指标和综合指标的示例:

I {EMOt6Fwhs1n} * 1000 /#{WUg3MYWQ7pt}

以报告率为例:

R {BfMAe6Itzgt.REPORTING_RATE} *#{P3jJH5Tu5VC.S34ULMcHMca}

另一个使用实际数据集报告和预期报告的报告率示例:

R {BfMAe6Itzgt.ACTUAL_REPORTS} / R {BfMAe6Itzgt.EXPECTED_REPORTS}

使用现有指标的示例

N {Rigf2d2Zbjp} *#{P3jJH5Tu5VC.S34ULMcHMca}

表达式可以是任何类型的有效数学表达式,作为例子:

(2 *#{P3jJH5Tu5VC.S34ULMcHMca})/(#{FQ2o8UBlcrS.S34ULMcHMca}-200)* 25

计划指标 { #webapi_program_indicators }

要检索项目指标,您可以向项目发出 GET 请求像这样的指标资源:

/ api / programIndicators

项目指示器可以包含在项目中收集的信息。指标有一个表达式,可以包含对数据的引用元素、属性、常量和项目变量。变量下表中描述了允许在表达式中使用。

表:计划指标变量

变量

描述

#{<programstage-id>.<dataelement-id>}	Parameter name
A{<attribute-id>}	指跟踪的实体属性。
V{<variable-id>}	指项目变量。
C{<constant-id>}	指一个常数。
指恒定值。	#{.} + #{} + V{} + C{}

一个相应的例子看起来像这:

#{A03MvHHogjR.a3kGcGDCuk6} + A{OvY4VVhSDeJ} + V{incident_date} + C{bCqvfPR02Im}

表达方式 { #webapi_expressions }

表达式是数学公式,可以包含对数据元素、常量和组织单元组。验证和获取表达式的文本描述,您可以发出 GET 请求到表达式资源:

/ api / expressions / description?expression =

响应遵循标准的 JSON Web 消息格式。状态属性表示验证的结果,如果成功和“错误”如果失败。 message 属性将为“有效” 如果成功并提供原因的文字描述如果不是,则验证失败。 *描述*提供了文字说明表达式的描述。

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Valid",
  "description": "Acute Flaccid Paralysis"
}

合并指标{ #webapi_indicator_merge }

通过指标合并端点,可以将多个指标(源)合并为一个目标指标。

授权{ #authorisation }

执行指标合并需要使用权限 F_INDICATOR_MERGE。

请求{ #request }

通过 POST 请求合并指标:

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

JSON 格式的有效载荷如下所示:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

元数据

物业

采取的行动	指标组	类别选项组合
删除源指标,增加目标指标	组织单位	基础设施指标(指标组)
DataElementGroup	组态	基础设施指标(指标组)
任何有来源的链接数据项都将与目标数据项链接	部门	指标
删除源指标,增加目标指标	组态	基础设施指标(指标组)
The reference is present and not null in the payload.	指示符	基础设施指标(指标组)
对于组织单位维度,您可以指定组织	数据条目表格	htmlCode
以目标取代源	计划指示器	htmlCode
将任何源引用替换为目标引用作为排序维度	验证{ #validation }	适用以下限制条件和错误代码。

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定目标指标
E1532	目标指标不能是源指标
E1533	源/目标指标不存在: `{uid}`
回复{ #response }	成功{ #success }

成功响应示例如下

```json

错误响应示例如下

```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source Indicator must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target Indicator does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "Indicator",
            "sourcesDeleted": [],
            "message": "Indicator merge has errors"
        }
    }
}

数据库约束样本错误响应:

合并指标类型 { #webapi_indicator_type_merge}

通过指标类型合并端点,可以将多个指标类型合并为一个目标指标类型。

授权{ #authorisation }

执行指示符类型合并需要使用权限 F_INDICATOR_TYPE_MERGE。

请求{ #request }

通过 POST 请求合并指标类型:

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

JSON 格式的有效载荷如下所示:

{
  "sources": [
    "jNb63DIHuwU",
    "WAjjFMDJKcx"
  ],
  "target": "V9rfpjwHbYg",
  "deleteSources": true
}

下表描述了 JSON 属性。

表格合并有效载荷字段

领域

需要

验证{ #validation }

适用以下限制条件和错误代码。

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
E1531	必须指定目标指标类型
E1532	目标指标类型不能是源指标类型
E1533	源/目标指标类型不存在: `{uid}`
回复{ #response }	成功{ #success }

成功响应示例如下

```json

错误响应示例如下

```json
{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "WARNING",
    "message": "One or more errors occurred, please see full details in merge report.",
    "response": {
        "mergeReport": {
            "mergeErrors": [
                {
                    "message": "At least one source IndicatorType must be specified",
                    "errorCode": "E1530",
                    "args": []
                },
                {
                    "message": "Target IndicatorType does not exist: `abcdefg1221`",
                    "errorCode": "E1533",
                    "args": [
                        "Target",
                        "abcdefg1221"
                    ]
                }
            ],
            "mergeType": "IndicatorType",
            "sourcesDeleted": [],
            "message": "IndicatorType merge has errors"
        }
    }
}

数据库约束样本错误响应:

organisationUnits 资源遵循标准约定,如 DHIS2 中的其他元数据资源。该资源支持一些附加查询参数。

获取组织单位列表

要获取组织单位的列表,可以使用以下资源。

/ api / 33 / organisationUnits

表:组织单位查询参数

查询参数

选项

eventCreatedPeriod	用户设置 { #webapi_user_settings }	Parameter name
真	假	仅 userDataView
假	假	数据视图组织单位只与当前用户相关。
userDataViewFallback	假	真
仅与当前用户相关联的数据视图组织单位,可退回到数据采集组织单位。	不区分大小写的字符串结尾匹配	字符串
查询名称、代码和 ID 属性。	查询参数	整数
层次结构中指定级别的组织单位。	查询参数	整数
在给定的最大级别或更高级别上的组织单位。	假	假
真	假	withinUserSearchHierarchy
假	不区分大小写的字符串结尾匹配	将搜索和检索限制在当前用户搜索范围内的组织单位。注意:"in withinUserHierarchy"(如果为 true)优先级更高。
会员收藏	串	对于显示集合内成员的计数,指的是与组织单位相关联的集合名称。

成员对象

用户标识

用于显示集合中成员的计数,指集合对象成员的标识符。

获取带有子层次结构的组织单位{ #webapi_organisation_units_with_sub_hierarchy }

eventCreatedPeriod	用户设置 { #webapi_user_settings }	Parameter name
查询参数	假	描述
包括儿童	假	真
包括指定组织单位的直属子单位,即子层次结构中下一级的直属单位。	假	假
查询名称、代码和 ID 属性。	查询参数	包括祖先

假

真

包括指定组织单位的所有家长。

夷为平地

整数

包括子层次结构中指定级别的指定组织单位的子机构。这是相对于组织单位而言的,从 1 开始为紧接组织单位之下的层级。

按类别获取组织单位选项

专门用于检索类别选项与组织单位之间关联的端点。该端点是检索项目组织单位关联的首选方式。

/api/33/categoryOptions/orgUnits?categoryOptions={categoryOptionIdA} 、{categoryOptionIdB}

夷为平地

{
  "<categoryOptionIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<categoryOptionIdC>": []
}

所有组织单位都能访问的类别选项会以组织单位的空数组([])返回。

按项目获取组织单位{ #webapi_organisation_units_by_programs }

专用端点,用于检索项目与组织单位之间的关联。该端点是检索项目与组织单位关联的首选方式。

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

答复的格式如下

{
  "<programIdA>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdB>": [
    "<orgUnitUid>",
    "<orgUnitUid>"
  ],
  "<programIdC>": []
}

下表描述了 JSON 属性。

分体式组织单位{ #webapi_organisation_unit_split }

领域

请求{ #request }

主要目标

不

要将与源相关的汇总数据、事件和跟踪实体转移到的组织单位的标识符。如果未指定,将使用第一个目标。

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
该操作将把源组织单位的所有数据记录转移到指定为主要目标的组织单位,如果没有指定,则转移到第一个指定的目标组织单位。这包括汇总数据值、数据批准记录、事件、跟踪实体等。	验证{ #validation }
适用以下限制条件和错误代码。	表:限制条件和错误代码
错误代码	描述
E1510	必须指定来源网络单位
E1511	必须指定至少两个目标组织单位
E1512	源组织单位不能是目标组织单位

E1513

必须指定主要目标

请求{ #request }

主要目标必须是目标组织单位

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

目标组织单位不存在

合并组织单位 { #webapi_organisation_unit_merge}

下表描述了 JSON 属性。

授权{ #authorisation }

领域

需要

数据审批合并策略

不

Strategy for merging data approval records. Options: LAST_UPDATED (default), DISCARD.

删除源

错误代码

描述

json(应用项目/ json)	Parameter name
指定的数据值合并策略定义了如何处理数据值。对于`LAST_UPDATED`策略,所有源组织单位的数据值都将转移到目标组织单位,并且在相同参数存在数据值的情况下,将使用最后更新或创建的数据值。这样做是为了避免数据重复。对于`DISCARD`策略,数据值不会转移到目标组织单位,而是简单地删除。指定的数据审批合并策略定义了数据审批记录的处理方式,并遵循与数据值相同的逻辑。	验证{ #validation }
适用以下限制条件和错误代码。	表:限制条件和错误代码
错误代码	描述
E1500	必须指定至少两个来源组织单位

E1501

必须指定目标组织单位

E1502

目标组织单位不能是源组织单位

E1503

源机构单位不存在

数据集 { #webapi_data_sets }

dataSets 资源遵循标准约定作为其他

DHIS2 中的元数据资源。此资源支持一些额外的查询参数。

/ api / 33 / dataSets

要检索数据集的版本,您可以发出GET请求:

GET /api/33/dataSets/<uid>/version

要提高(增加一个)数据集的版本,您可以发出 POST 要求:

POST / api / 33 / dataSets / <uid> / version

数据集通知模板{ #webapi_dataset_notifications }

*数据集通知模板*资源遵循标准 DHIS2 中其他元数据资源的约定。

GET /api/33/dataSetNotficationTemplates

要检索数据集通知模板,您可以发出GET请求:

GET /api/33/dataSetNotficationTemplates/<uid>

要添加数据集通知模板,您可以发出POST请求: - POST / api / 33 / dataSetNotficationTemplates - 要删除数据集通知模板,您可以发出DELETE请求:

删除/ api / 33 / dataSetNotficationTemplates /

JSON有效负载示例如下:

{
  "name": "dataSetNotificationTemplate1",
  "dataSetNotificationTrigger": "DATA_SET_COMPLETION",
  "relativeScheduledDays": 0,
  "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
  "dataSets": [{
    "id": "eZDhcZi6FLP"
  }],
  "deliveryChannels": ["SMS","EMAIL"],
  "subjectTemplate": "V{data_set_name}",
  "messageTemplate": "V{data_set_name}V{registration_period}",
  "sendStrategy": "SINGLE_NOTIFICATION"
}

notificationRecipient can be one of:

USER_GROUP for internal messages

`ORGANISATION_UNIT_CONTACT` for external messages

填充的组织单位级别 { #webapi_filled_organisation_unit_levels }

fillOrganisationUnitLevels 资源提供了一个有序的列表组织单元级别,其中生成的级别被注入到列表以填充不存在持久级别的位置。

GET /api/33/filledOrganisationUnitLevels

要设置组织单位级别,您可以发出一个 POST 请求,其中包含一个

内容类型为 application/json 的 POST 请求:

{
  "organisationUnitLevels": [{
    "name": "National",
    "level": 1,
    "offlineLevels": 3
  }, {
    "name": "District",
    "level": 2
  }, {
    "name": "Chiefdom",
    "level": 3
  }, {
    "name": "Facility",
    "level": 4
  }]
}

预测变量 { #webapi_predictors }

预测器允许您根据表达式生成数据值。这可以用于例如生成目标、阈值、或估计值。

要检索预测器,您可以向预测器发出 GET 请求像这样的资源:

/ api / predictors

创建预测变量

您可以使用对预测器的 POST 请求创建预测器资源:

POST / api / predictors

#{<programstage-id>.<dataelement-id>}	UID \	Parameter name
预测表达式 { #webapi_predictor_expressions }	D{<program-id>.<data-element-id>}	项目数据元素
变量	Syntax	描述
#{}	IN_GROUP-<indicatorgroup-id>	指所有类别选项组合中的聚合数据元素的总值。
#{.	I{<program-indicator-id>}	计划指标
D{.}	<dataelement-id>	引用项目中跟踪器数据元素的值。
A{.}	C{<constant-id>}	指项目中被跟踪实体属性的值。
I{}	N{<indicator-id>}	指示符
R{.}	Category combination	项目
C{}	不变	指恒定值。

OUG{}

组织单位组

指组织单位组内组织单位的数量。

[天]

天数

当前期间的天数。

生成预测值 { #webapi_generating_predicted_values }

要运行所有预测器(生成预测值),您可以进行 POST 请求运行资源:

POST / api / predictors / run

要运行单个预测器,您可以向运行发出 POST 请求预测器的资源:

POST / api / predictors / AG10KUJCrRk / run

计划{ #webapi_programs }

要检索项目,可以像这样向项目资源发出 GET 请求:

/api/programs

项目类别映射{ #webapi_program_category_mappings }

从 2.42 版开始,项目可选择定义一个或多个类别映射。这些映射可用于为该计划的计划指标添加分类。该计划的计划指标可以选择在其类别组合和/或属性组合中使用哪种映射。类别组合和/或属性组合中的类别。

这样就可以按类别和类别选项查看计划指标数据例如在数据展示台中。它还允许聚合数据交换从计划指标中生成包含类别选项组合和/或属性选项组合的值。生成包含类别选项组合和/或属性选项组合的值。 - 这些类别映射可由维护(预览)应用项目生成生成,也可以使用 Web API 添加。如果使用 Web API,本节将介绍类别映射的格式。 - 新项目没有类别映射。在网络应用项目接口中,这看起来像 - ```json "categoryMappings": []

要在项目中添加类别映射,可编辑项目定义的这一部分,然后将结果导入 DHIS2。
定义,然后将结果导入 DHIS2。
以下是编辑字段的示例:
```json
"categoryMappings": [
  {
    "id": "goor7Li4See",
    "categoryId": "cX5k9anHEHd",
    "mappingName": "standard Gender mapping",
    "optionMappings": [
      {
        "optionId": "apsOixVZlf1",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Female'"
      },
      {
        "optionId": "jRbMi0aBjYn",
        "filter": "#{Zj7UnCAulEk.oZg33kd9taw} == 'Male'"
      }
    ]
  },
  {
    "id": "ESesheeva1i",
    "categoryId": "VPqYge5RB93",
    "mappingName": "standard Outcome mapping",
    "optionMappings": [
      {
        "optionId": "e3oqm527jBS",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Managed at PHU'"
      },
      {
        "optionId": "rSdQZYDmHJm",
        "filter": "#{Zj7UnCAulEk.sAg4Niej9bo} == 'Referred'"
      }
    ]
  },
  {
    "id": "laiHaid9eit",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at event",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{event_date})>=5"
      }
    ]
  },
  {
    "id": "SeNg0bohFah",
    "categoryId": "fkAkrdC7eJF",
    "mappingName": "Referrals Age at analyitcs period start",
    "optionMappings": [
      {
        "optionId": "K4gwuiVvW3z",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})<5"
      },
      {
        "optionId": "oaFqxkefkPs",
        "filter": "d2:yearsBetween(#{wYTF0YCHMWr.AZLp9Shoab9},V{analytics_period_start})>=5"
      }
    ]
  }
]

在此示例中,该计划定义了四个类别映射,可用于的项目指标:

displayColumnOrder	dataFilters
Two mappings for the `Referrals Age` category. A program indicator can choose which mapping	取决于是否要在事件日期显示年龄
或分析期开始时的年龄。	The `categoryMappings` fields are:
名称	描述
本我	唯一标识映射的 11 个字符的 UID。第一个字符必须是大写或小写字母,然后是 10 个字符,每个字符都是大写或小写字母或数字。应选择唯一的 ID。项目指示符选择映射时会使用该 UID。
类别标识	要映射的类别的 UID。在本例中,它们是性别、结果和转介年龄的 UID。
数据值	您为映射指定的名称。如果您为一个类别定义了多个映射,则该名称必须在该项目中该类别的映射中是唯一的。

选项映射

这些指定了类别内每个类别选项的过滤器。

optionId

该过滤器适用的类别选项的 UID。

过滤

用于该类别选项的筛选器。过滤器的语法必须与项目中项目指示符的过滤器表达式相同。提示: 可以使用维护应用项目生成并验证该过滤器:将其构建为节目中新的或现有节目指示符的过滤器表达式,确保其有效,然后复制并粘贴到元数据中。(你不必保存带有该过滤器的计划指标)。

项目指示符可在其 `categoryMappingIds` 字段中选择要使用的项目映射。

新的项目指示符没有类别映射 id。在 Web API 中,这看起来像

"categoryMappingIds": [],

You can replace this with the category mappings that you want the program indicator to use. For example, if the program indicator has selected a category combination that combines Gender and Outcome, this field could be edited to contain the mapping ids for these categories such as defined in the above categoryMappings example:

```json

"categoryMappingIds": [ "goor7Li4See", "ESesheeva1i" ],

计划规则 { #webapi_program_rules } 

本节是关于发送和读取项目规则,并解释
项目规则数据模型。项目规则赋予功能
在 DHIS2 项目中配置动态行为。

| displayColumnOrder | dataFilters | 表:项目规则操作 |
|---|---|---|
| `{ "periodFrom": -15, "periodTo": 15}` | 下表给出了项目规则的详细概述
模型。 | 表:项目规则操作 |
| displayColumnOrder | 描述 | 表:项目规则操作 |
| dataFilters | 执行项目规则的项目。 | 表:项目规则操作 |
| See an example payload below. | 项目规则显示给 dhis2 配置器的名称。项目最终用户看不到。 | 强制性 |
| 描述 | 项目规则的描述,配置器可用于描述规则。项目的最终用户看不到。| 表:项目规则操作 |
| 项目阶段 | 如果为项目规则设置了项目阶段(programStage),则该规则只能在指定的项目阶段内进行评估。 | 强制性 |

#### 健康)状况

为使项目规则触发其子操作,需要求值为 true 的表达式。表达式使用运算符、函数调用、硬编码值、常量和项目规则变量编写。`d2:hasValue('hemoglobin') && #{hemoglobin} <= 7 `.

强制性

| displayColumnOrder | dataFilters | 表:项目规则操作 |
|---|---|---|
| 计划规则操作模型详细信息 { #program-rule-action-model-details }  | 下表给出了对 programRuleAction 的详细概述
模型。 | 表:项目规则操作 |
| 名称 | 描述| 表:项目规则操作 |
| 项目规则 | 该操作的父项目规则。 | 强制性 |
| 项目规则--动作类型 | The type of action that is to be performed.<br>  * `DISPLAYTEXT` - Displays a text in a given widget.<br> * `DISPLAYKEYVALUEPAIR` - Displays a key and value pair(like a program indicator) in a given widget.<br> * `HIDEFIELD` - Hide a specified dataElement or trackedEntityAttribute.<br>    -         *content* - if defined, the text in *content* will be displayed to the end user in the instance where a value is previously entered into a field that is now about to be hidden (and therefore blanked). If *content* is not defined, a standard message will be shown to the user in this instance.<br>   -         *dataElement* - if defined, the HIDEFIELD action will hide this dataElement when the rule is effective.<br>   -         *trackedEntityDataValue* - if defined, the HIDEFIELD action will hide this trackedEntityDataValue when the rule is effective.<br>  * `HIDESECTION` - Hide a specified section.<br>    -         *programStageSection* - must be defined. This is the programStageSection that will be hidden in case the parent rule is effective.<br>  * `ASSIGN` - Assign a value to either a dataElement or trackedEntityAttribute or a ProgramRuleVariable. Intended to help the user calculate something or fill in an obvious value somewhere.<br>    -         *content* - if defined, the value in *data* is assigned to this variable. If content id defined, and thus a variable is assigned for use in other rules, it is important to also assign a *programRule.priority* to make sure the rule with an ASSIGN action runs before the rule that will in turn evaluate the assigned variable.<br>   -         *data* - must be defined, data forms an expression that is evaluated and assigned to either a variable(#{myVariable}), a dataElement, or both.<br>   -         *dataElement* - if defined, the value in *data* is assigned to this data element.<br>  Either the content or dataElement must be defined for the ASSIGN action to be effective.<br> * `SHOWWARNING` - Show a warning to the user, not blocking the user from completing the event or registration.<br>    -         *content* - if defined, content is a static part that is displayed at the end of the error message.<br>   -         *data* - if defined, data forms an expression that is evaluated and added to the end of the warning message.<br>   -         *dataElement* - if defined, the warning message is displayed next to this data element.<br>   -         *trackedEntityAttribute* - if defined, the warning message is displayed next to this tracked entity attribute.<br>  Either dataElement or trackedEntityAttribute must be specified.<br> * `SHOWERROR` - Show an error to the user, blocking the user from completing the event or registration.<br>    -         *content* - if defined, content is a static part that is displayed in the start of the error message.<br>   -         *data* - if defined, data forms an expression that is evaluated and added to the end of the error message.<br>   -         *dataElement* - if defined, the error message is linked to this data element.<br>   -         *trackedEntityAttribute* - if defined, the error message is linked to this tracked entity attribute.<br>  Either dataElement or trackedEntityAttribute must be specified.<br> * `WARNINGONCOMPLETE` - Show a warning to the user on the "Complete form" dialog, but allowing the user to complete the event.<br>    -         *content* - if defined, content is a static part that is displayed at the end of the error message.<br>   -         *data* - if defined, data forms an expression that is evaluated and added to the end of the warning message.<br>   -         *dataElement* - if defined, the warning message prefixed with the name/formName of the data element.<br>  * `ERRORONCOMPLETE` - Show an error to the user on in a modal window when the user tries to complete the event. The user is prevented from completing the event.<br>    -         *content* - if defined, content is a static part that is displayed in the start of the error message.<br>   -         *data* - if defined, data forms an expression that is evaluated and added to the end of the error message.<br>   -         *dataElement* - if defined, the error message is linked to this data element.<br>  * `CREATEEVENT` - Create an event within the same enrollment.<br>    -         *content*<br>   -         *data* - if defined, contains data values to assign the created event. The format is <uid\>:<data value\>. Where several values is specified, these are separated with comma.<br> AcMrnleqHqc:100,AqK1IHqCkEE:'Polyhydramnios'<br>   -         *programStage* - must be defined, and designates the program stage that the rule shall create an event of.<br>  * `SETMANDATORYFIELD` - Set a field to be mandatory.<br>    -         *dataElement* - if defined, this data element will be set to be mandatory in the data entry form.<br>   -         *trackedEntityAttribute* - if defined, this tracked entity attribute will be set to mandatory in the registration form or profile.<br>  * `SENDMESSAGE` - To send message at completion of event/enrollment or at data value update.<br>    -         *messageTemplate* - if defined, this template will be delivered either as SMS or EMAIL depending upon DeliveryChannel value in message template.<br>  * `SCHEDULEMESSAGE` - To schedule message at completion of event/enrollment or at data value update.<br>    -         *messageTemplate* - if defined, this template will be delivered either as SMS or EMAIL depending upon DeliveryChannel value in message template.<br>   -         *Date to send message* - Expression which is going to be used for evaluation of scheduled date. This expression should result in Date, any other resultant will be discarded and notification will not get scheduled. <br>  * `HIDEPROGRAMSTAGE` - Prevent adding new events to stage. <br>  * `HIDEOPTION` - Hide option (from an optionSet). <br>  * `HIDEOPTIONGROUP` - Hide option group (hide the options that belong to that option group). <br>  * `SHOWOPTIONGROUP` - Show option group (show the options that belong to that option group). | 强制性 |
| 地点 | 用于动作类型 DISPLAYKEYVALUEPAIR 和 DISPLAYTEXT,以指定在哪个部件中显示文本或按键对。必须用于 DISPLAYKEYVALUEPAIR 和 DISPLAYTEXT。 | 强制性 |
| 最小最大数据元素 | 用于不同操作中的用户信息。有关在每种操作类型中如何使用的详细说明,请参阅操作类型概述。SHOWWARNING、SHOWERROR、WARNINGONCOMPLETE、ERRORONCOMPLETE、DISPLAYTEXT 和 DISPLAYKEYVALUEPAIR 必须使用。HIDEFIELD 和 ASSIGN 可选。 | 强制性 |
| 数据 | 用于不同操作中的表达式。有关各操作类型中如何使用该表达式的详细说明,请参阅操作类型概述。ASSIGN 必须使用。SHOWWARNING、SHOWERROR、WARNINGONCOMPLETE、ERRORONCOMPLETE、DISPLAYTEXT、CREATEEVENT 和 DISPLAYKEYVALUEPAIR 可选。 | 强制性 |
| 数据元素 | 用于将规则操作链接到数据元素。有关在每种操作类型中如何使用的详细说明,请参阅操作类型概述。SHOWWARNING、SHOWERROR、WARNINGONCOMPLETE、ERRORONCOMPLETE、ASSIGN 和 HIDEFIELD 的可选项。 | 强制性 |
| 跟踪属性 | 用于将规则操作链接到跟踪实体属性(trackedEntityAttributes)。有关在每种操作类型中如何使用的详细说明,请参阅操作类型概述。SHOWWARNING、SHOWERROR 和 HIDEFIELD 的可选项。 | 强制性 |
| See an example payload below. | 用于将规则操作链接到选项。有关在每种操作类型中如何使用的详细说明,请参阅操作类型概述。HIDEOPTION 的可选项 | 强制性 |
| 选项组 | 用于将规则操作链接到选项组。有关在每种操作类型中如何使用的详细说明,请参阅操作类型概述。SHOWOPTIONGROUP 和 HIDEOPTIONGROUP 必须使用。 | 强制性 |

##### 项目阶段
仅用于 CREATEEVENT 规则操作。必须用于 CREATEEEVENT。

参见说明

| displayColumnOrder | 仅用于 HIDESECTION 规则操作。必须用于 HIDESECTION |
|---|---|
|参见说明| 项目规则行动验证{ #programruleaction-validation }  |
|2.37 中为 ProgramRuleAction 模型添加了一些验证。主要目的是防止用户创建错误的项目规则,以保持数据库的一致性。这些验证取决于项目规则动作类型。每种操作类型都有各自的验证。 | 项目规则行动验证{ #programruleaction-validation }  |
|名称| 验证检查 ID 是否存在 |
|短信| 通知模板 ID |
|日程消息| 选项 id |
|隐藏| ProgramStage 段落 ID |
|隐藏计划阶段| 数据元素或跟踪实体属性 id |
|希德菲尔德| 数据元素或跟踪实体属性 id |
|隐藏选项| 选项 id |
|隐藏选项组| 选项组 ID |
|显示选项组| 选项组 ID |
|设置必填字段| 选项 id |
|淋浴器||
|始终有效| 选项 id |
|始终有效| 选项 id |
|数据元素或跟踪实体属性 id| 选项 id |

分配

数据元素或跟踪实体属性 id


完成警告

#### 数据元素或跟踪实体属性 id

erroroncomplete

数据元素或跟踪实体属性 id

| displayColumnOrder                     | dataFilters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 表:项目规则操作      |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| displayColumnOrder                     | 下表详细概述了
项目规则变量模型。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | 表:项目规则操作      |
| 名称               | 描述 | 表:项目规则操作      |
| 名称                | programRuleVariable 的名称 - 该名称用于表达式中。#{myVariable} \> 5                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | 表:项目规则操作      |
| 最小最大数据元素              | Defines how this variable is populated with data from the enrollment and events.<br> *DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE - This source type works the same way as DATAELEMENT_NEWEST_EVENT_PROGRAM, except that it only evaluates values from one program stage. This source type can be useful in program rules where the same data element is used in several program stages, and a rule needs to evaluate the newest data value from within one specific stage. In order to know what event is the newest, the report date (event date) is used. If you have many events with the same report date, the system choose the one with the latest `createdAt` property of the event. <br>*DATAELEMENT_NEWEST_EVENT_PROGRAM - This source type is used when a program rule variable needs to reflect the newest known value of a data element, regardless of what event the user currently has open.<br>**NB** Future dates are "newer" than current or past dates.<br>In order to know what event is the newest, the report date (event date) is used. If you have many events with the same report date, the system choose the one with the latest `createdAt` property of the event.<br>*DATAELEMENT_CURRENT_EVENT - Program rule variables with this source type will contain the data value from the same event that the user currently has open. This is the most commonly used source type, especially for skip logic (hide actions) and warning/error rules.<br>*DATAELEMENT_PREVIOUS_EVENT - Program rule variables with this source type will contain the value from a specified data element from a previous event. Only older events is evaluated, not including the event that the user currently has open. This source type is commonly used when a data element only should be collected once during an enrollment, and should be hidden in subsequent events. Another use case is making rules for validating input where there is an expected progression from one event to the next - a rule can evaluate whether the previous value is higher/lower and give a warning if an unexpected value is entered.<br>*CALCULATED_VALUE - Program rule variable with this source type is not connected directly to any form data - but will be populated as a result of some other program rules **ASSIGN** action. This variable will be used for making preliminary calculations, having a **ASSIGN** program rule action and assigning a value, this value can be used by other program rules - potentially making the expressions simpler and more maintainable. These variables will not be persisted and will stay in memory only during the execution of the set of program rules. Any program rule that assigns a data value to a preliminary calculated value would normally also have a **priority** assigned - to make sure that the preliminary caculation is done before the rule that consumes the calculated value.<br>*TEI_ATTRIBUTE - Populates the program rule variable with a specified tracked entity attribute for the current enrollment. Use this is the source type to create program rules that evaluate data values entered during registration. This source type is also useful when you create program rules that compare data in events to data entered during registration. This source type is only used for tracker programs (programs with registration).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | 强制性 |
| 数据 | valueType 参数定义此 ProgramRuleVariable 可包含的值的类型。其值取决于 sourceType 参数。如果源是 DataElement 或 TrackedEntityAttribute<br> ,那么 valueType 将从源的 valueType 派生。当 sourceType 为 CALCULATED_VALUE 时,valueType 应由用户提供,否则<br> 将默认为 ValueType.TEXT                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 强制性 |
| 数据元素    | 用于将项目规则变量链接到数据元素。必须用于所有以 DATAELEMENT_ 开头的源类型。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                 |
| See an example payload below.             | 跟踪属性                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 强制性 |

### 参见说明

- useCodeFor- 选项集

如果选中,变量将使用任何链接选项集的代码(而不是名称)。默认值为未选中,即输入选项名称。

项目阶段

用于指定从哪个特定项目阶段获取 programRuleVariable 值。DATAELEMENT_NEWEST_EVENT_PROGRAM_STAGE 必须使用。

    / api / programRules

创建项目规则 { #webapi_creating_program_rules } 

    / api / programRules

要检索programRules的列表,您可以执行GET请求,如下所示:

    / api / programRules

要检索单个programRule,您可以执行GET请求,如下所示:

    / api / programRules

要保存/添加单个programRule,您可以执行POST请求,如下所示:

    / api / programRules / <program_rule_uid>

## 要更新单个programRule,您可以执行如下PUT请求:

    / api / programRules / <program_rule_uid>

要删除单个programRule,您可以执行以下DELETE请求:

| 默认值 | Validation rule | Parameter name |
|---|---|---|
| E7228 | To retrieve information about a form (which corresponds to a data set
and its sections) you can interact with the `form` resource. The form
response is accessible as XML and JSON and will provide information
about each section (group) in the form as well as each field in the
sections, including labels and identifiers. By supplying period and
organisation unit identifiers the form response will be populated with
data values. | 表格表单查询参数 |
| Filter on whether the current user can manage the returned users through the managed user group relationships. | 串 | 描述 |
| 聚乙烯 | 假 | 填入表格数据值的时间段。 |

欧

用户标识

用于填充表单数据值的组织单位。

元数据

假

真

是否包含表格各部分每个数据元素的元数据。

要检索数据集的表单,您可以执行GET请求,如下所示:

    / api / dataSets / <dataset-id> /form.json

检索具有标识符“BfMAe6Itzgt”的数据集的表单
XML:

##     / api / dataSets / BfMAe6Itzgt / form

要检索包含JSON中的元数据的表单,请执行以下操作:



    /api/dataSets/BfMAe6Itzgt/form.json?metaData=true

| 检索填充了特定时期数据值的表单,并
XML 中的组织单位: | Parameter name |
|---|---|
| displayColumnOrder | ```bash
curl -d @form.html "localhost/api/dataSets/BfMAe6Itzgt/form"
  -H "Content-Type:text/html" -u admin:district -X PUT
``` |
| 文件资料 { #webapi_documents }  | 对文件的引用可以与文档资源一起存储。 |
| 表格文件字段 | 字段名称 |

描述

名称

文件唯一名称

外部

标识文件位置的标志。外部文件为 TRUE,内部文件为 FALSE

网址

文件的位置。外部文件的 URL。内部文件的文件资源 ID(请参阅 [文件资源](developer-manual.md#webapi_file_resources))。

对文档端点的GET请求将返回所有文档:

    / api / documents

## 对文档端点的POST请求将创建一个新文档:

```bash
curl -X POST -d @document.json -H "Content-type: application/json"
  "http://dhis.domain/api/documents"

{
  "name": "dhis home",
  "external": true,
  "url": "https://www.dhis2.org"
}

带有附加文档 ID 的 GET 请求将返回信息关于文件。对同一端点的 PUT 请求将更新文档的字段:

/ api / documents / <documentId>

将 /data 附加到 GET 请求将返回实际文件内容文件的:

/ api / documents / <documentId> / data

CSV元数据导入 { #webapi_csv_metadata_import }	DHIS2支持以CSV格式导入元数据,例如数据元素,组织单位和验证规则。根据列顺序/列索引来标识各种元数据对象的属性(有关详细信息,请参见下文)。您可以省略不需要的对象属性/列,但是由于列顺序很重要,因此必须包括一个空列。换句话说,如果您要指定在列顺序中排在后面的属性/列,但不指定在列顺序中排在较早的位置的某些列,则可以为它们添加空白/空白列。
startDate 和 endDate 参数允许获取链接的数据
到这些日期之间的任何时间段。这避免了定义所有
期间明确在
要求:	要上传CSV格式的元数据,您可以向元数据端点发出POST请求:
POST / api / metadata?classKey = CLASS-KEY	支持以下对象类型。 `classKey` 查询参数是强制性的,可以在下表中的每个对象类型旁边找到。
表格对象类型和关键字	对象类型
类键	资料元素
E7229	Use fornat `HH:mm`
DATA_ELEMENT_GROUP	类别选项
CATEGORY_OPTION	类别选项组
CATEGORY_OPTION_GROUP	组织单位
ORGANISATION_UNIT	组织单位组

ORGANISATION_UNIT_GROUP

验证规则

VALIDATION_RULE

选项集

OPTION_SET

翻译

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		索引
2	串	Program notification template	串	OptionSetUid
3	zscore	Program notification template		是的
4	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	Program notification template	指标{ #webapi_csv_indicators }	稳定的标识符。正好 11 个字母数字字符,以字母开头。如果未指定,将由系统生成。
5	Parameter name	Program notification template		不
6	简称	Program notification template		名称
7	如果未指定,将返回姓名的前 50 个字符。最多 50 个字符。唯一。	Program notification template	不	自由文本描述。
8	false \| true	Program notification template	最大 230 字符。	域名类型
9	不	Program notification template	数据元素的域类型,可以是聚合或跟踪。最多 16 个字符。	值类型
10	不	Program notification template	串	聚集类型
11	不	Program notification template		聚合类型,表示如何按不同维度聚合数据。最多 16 个字符。
12	类别组合	Program notification template	假	类别组合的 UID。如果未指定,将默认为默认类别组合。
13	网址	Program notification template	串	零具有重要意义
14	不	Program notification template	串	表示该数据元素是否存储零值。

选项集

不

用户标识

要用于数据的选项集的 UID。

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		表格:组织单位 CSV 格式
2	串	Program notification template	串	需要
3	zscore	Program notification template		是的
4	姓名。最多 230 个字符。唯一。	Program notification template	串	用户标识
5	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	Program notification template	指标{ #webapi_csv_indicators }	稳定代码。最多 50 个字符。
6	Parameter name	Program notification template		不
7	上级组织单位的 UID。	Program notification template	不	50 名字的第一个字符
8	如果未指定,将返回姓名的前 50 个字符。最多 50 个字符。唯一。	Program notification template		不
9	async	Program notification template		不
10	1970-01-01	Program notification template	关闭日期	不
11	组织单位的关闭日期,格式为 YYYY-MM-DD,如果当前开放,则跳过。	Program notification template		不
12	Text.	Program notification template		不
13	NONE \| MULTI_POLYGON \| POLYGON \| POINT \| SYMBOL	Program notification template		坐标
14	不	Program notification template		网址
15	```
/ api / userLookup
```	Program notification template		联系人
16	不	Program notification template		地址

不

组织单位地址。最多 255 个字符。

电子邮件

不

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		表格:组织单位 CSV 格式
2	串	Program notification template	串	需要
3	zscore	Program notification template		是的
4	Parameter name	Program notification template		不
5	用户标识	Program notification template		码
6	不	Program notification template	描述	不
7	自由文本描述。	Program notification template	不	自由文本教学。
8	所需值	Program notification template	中	高
9	Retrieve the `id` property of the returned file resource.	Program notification template	规则类型(忽略)	不
10	验证	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		操作员
11	不	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		左侧表达
12	期间类型	Program notification template	月刊	日刊
13	周刊	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		操作员
14	年刊	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		左侧表达
15	是的	Program notification template	月刊	是的

自由文本。

左侧缺失值策略

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	右侧表达	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		基于数据元素和选项组合 UID 的数学公式。
2	右侧表达描述	Program notification template	串	右侧缺失值策略
3	不	Program notification template		是的
4	never_skip	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		选项集 { #webapi_csv_option_sets }
5	表:选项集 CSV 格式	Program notification template	串	需要
6	描述	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		是的

是的

姓名。最多 230 个字符。唯一。每个选项都应重复。

选项设置 UID

不

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	Parameter name
1	选项名称	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		基于数据元素和选项组合 UID 的数学公式。
2	选项 UID	Program notification template	右侧缺失值策略
3	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	Program notification template	是的
4	稳定代码。最多 50 个字符。	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
`\|\|`csv
optionsetname,optionsetuid,optionsetcode,optionname,optionuid,optioncode
“颜色”,“颜色”,“蓝色”,“蓝色”
“颜色”,“颜色”,“绿色”,“绿色”
“颜色”,“颜色”,“黄色”,“黄色”
“性别”,“男”,“男”
“性别”,“女性”,“女性”
“性别”,“未知”,“未知”
“结果”,“高”,“高”
“结果”,“中”,“中”
“结果”,“低”,“低”
“ Impact”,“ cJ82jd8sd32”,“ IMPACT”,“ Great”,“ GREAT”
“影响”,“ cJ82jd8sd32”,“影响”,“中等”,“中等”
“影响”,“ cJ82jd8sd32”,“影响”,“不良”,“不良”
```
5	柱	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		索引
6	柱	Program notification template	值(默认为第一位)
7	描述	Program notification template	是的

姓名。最多 230 个字符。唯一。每个选项都应重复。

OptionGroupUid

不

稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。每个选项都应重复。

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	Parameter name
1	简称。最多 50 个字符。唯一。每个选项都应重复。	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		基于数据元素和选项组合 UID 的数学公式。
2	稳定的标识符。最多 11 个字符。每个选项都应重复。	Program notification template	右侧缺失值策略
3	稳定的标识符。最多 11 个字符。	Program notification template	是的
4	稳定代码。最多 50 个字符。	Program notification template	```csv
optionGroupName,optionGroupUid,optionGroupCode,optionGroupShortName,optionSetUid,optionUid,optionCode
optionGroupA,groupA,xmRubJIhmaK,OptionA
optionGroupA,groupgroup,xmRubJIhmaK,OptionB
optionGroupB 、、 groupB,QYDAByFgTr1,OptionC
```
5	选项组集 { #option-group-set }	Program notification template	索引
6	柱	Program notification template	值(默认为第一位)

描述

选项组设置名称是的

姓名。最多 230 个字符。唯一。每个选项都应重复。

OptionGroupSetUid

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		索引
2	串	Program notification template	串	OptionSetUid
3	zscore	Program notification template		是的
4	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	指标{ #webapi_csv_indicators }	稳定的标识符。正好 11 个字母数字字符,以字母开头。如果未指定,将由系统生成。
5	最小最大数据元素	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		用户标识
6	值(默认为第一位)	Program notification template		名称
5	指示符	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		用户标识
6	不	Program notification template		名称
6	码	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		索引
6	简称	Program notification template		50 名字的第一个字符
6	如果未指定,将返回姓名的前 50 个字符。最多 50 个字符。唯一。	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		串	指标表达。

分母描述

不

最大 230 字符。

分子

是的
指标表达。
分子描述
不

最大 230 字符。

年化

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板
1	串	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	串	指标类型的 UID。
2	串	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	串	除了导入对象,您还可以选择只导入对象
对象和组之间的组成员关系。目前,该
支持以下组和对象对

组织单位组-组织单位

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		表格:组织单位 CSV 格式
2	串	Program notification template	串	是的
3	zscore	Program notification template		是的
4	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	Program notification template		要添加到集合中的对象的 UID
5	类别选项组{ #category-option-group }	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		柱

需要

值(默认为第一位)

是的	Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	姓名。最多 230 个字符。唯一。	Parameter name
1	类型	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```		表格:组织单位 CSV 格式
2	串	Program notification template	串	是的
3	zscore	Program notification template		是的
4	稳定的标识符。最多 11 个字符。如果未指定,将由系统生成。	Program notification template		要添加到集合中的对象的 UID

表格数据元素组、类别选项、组织单位组 CSV 格式

索引

柱

需要

值(默认为第一位)

描述

名称

是的

姓名。最多 230 个字符。唯一。

用户标识

不

用户标识

稳定标识符。最多 11 个字符。如果未指定,将由系统生成。

码

不

稳定代码。最多 50 个字符。

简称

不

简称。最多 50 个字符。

类别选项的示例如下所示:

名称,uid,代码,简称
“男”,“男”
“女性”,“女性”

删除的对象 { #webapi_deleted_objects }

GET /api/deletedObjects.json?klass=DataElement

/ api / deletedObjects

每当删除元数据类型的对象时,都会保留日志 uid、代码、类型和删除时间。这个 API 是在/api/deletedObjects 字段过滤和对象过滤中可用与其他元数据资源类似。

获取类型为数据元素的已删除对象:

GET /api/deletedObjects.json?klass=DataElement

获取在 2015 年删除的指标类型的已删除对象和向前:

GET /api/deletedObjects.json?klass=Indicator&deletedAt=2015-01-01

收藏夹 { #webapi_favorites }

某些类型的元数据对象可以标记为收藏夹

当前登录的用户。这目前适用于仪表板。

/ api / dashboards / <uid> /收藏

要使仪表板成为收藏夹,您可以发出 POST 请求(无内容 type required) 到这样的 URL:

/ api /仪表板/ iMnYyBfSxmM /收藏

要将仪表板删除为收藏夹,您可以发出 DELETE 请求使用与上面相同的 URL。

收藏夹状态将显示为布尔值 收藏夹 字段元数据响应中的对象(例如仪表板)。订阅内容 { #webapi_subscription } 已登录的用户可以订阅某些类型的对象。目前可订阅的对象类型包括 EventChart、EventReport.Map、Visualization 和 EventVisualization、地图、可视化和事件可视化类型的对象。

注

事件图表(EventChart)和事件报告(EventReport)对象已被弃用。请使用 EventVisualization 代替。

要获取对象的订阅者(返回用户 ID 数组),您可以发出 GET 请求:

/ api / <object-type> / <object-id> /订阅者

请参见以下示例:

/api/visualizations/DkPKc1EUmC2/subscribers

检查当前用户是否订阅了一个对象(返回一个 boolean) 您可以执行 GET 调用:

/ api / <object-type> / <object-id> /已订阅

请参见以下示例:

/api/visualizations/DkPKc1EUmC2/subscribed

要订阅/取消订阅对象,请执行 POST/DELETE 请求(不需要内容类型):

/ api / / / subscriber

文件资源 { #webapi_file_resources } 文件资源*是用于表示和存储二进制内容的对象。 *FileResource 对象本身包含文件元数据(名称、内容类型、大小等)以及允许检索来自数据库外部文件存储的内容。 FileResource 对象与其他数据库一样存储在数据库中,但内容(文件)是存储在别处并可使用包含的引用检索 (存储密钥)。 / api / fileResources 文件资源的内容不能直接访问,但可以从其他对象(如数据值)引用来存储二进制几乎无限大小的内容。创建不需要相应数据值的文件资源、向端点 /api/fileResources 发送多部分上传:

bash curl "https://server/api/fileResources" -X POST -F "file=@/path/to/file/name-of-file.png"   - 文件资源的` uid `可以在创建时提供,例如:
    ```bash
curl "https://server/api/fileResources?uid=0123456789x" -X POST
  -F "file=@/path/to/file/name-of-file.png"
 创建文件资源和引用文件的数据值、 在 DHIS 2.36 或更高版本中,POST 到 `/api/dataValues/file` 端点:

bash curl "https://server/api/dataValues/file?de=xPTAT98T2Jd &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -X POST -F "file=@/path/to/file/name-of-file.png"

    For the `api/fileResources` endpoint, the only form parameter required is
*file*, which is the file to upload. For the `api/dataValues/file`
endpoint, the parameters required are the same as for a post to
`api/dataValues`, with the addition of *file*.
    文件名和内容类型也应包含在请求中,但
如果没有提供,将用默认值代替。

  - 成功创建文件资源后,返回的数据将包含
一个 `response` 字段,它又包含这样的 `fileResource`:
    ```json
{
  "httpStatus": "Accepted",
  "httpStatusCode": 202,
  "status": "OK",
  "response": {
    "responseType": "FileResource",
    "fileResource": {
      "name": "name-of-file.png",
      "created": "2015-10-16T16:34:20.654+0000",
      "lastUpdated": "2015-10-16T16:34:20.667+0000",
      "externalAccess": false,
      "publicAccess": "--------",
      "user": { ... },
      "displayName": "name-of-file.png",
      "contentType": "image/png",
      "contentLength": 512571,
      "contentMd5": "4e1fc1c3f999e5aa3228d531e4adde58",
      "storageStatus": "PENDING",
      "id": "xm4JwRwke0i"
    }
  }
}

注意响应是202 Accepted,表示返回的

资源已提交后台处理(持续到在这种情况下是外部文件存储)。另外,请注意 storageStatus 字段指示内容是否已存储。在这点,到外部存储的持久化还没有完成(它是可能会上传到某个地方的基于云的商店) PENDING 状态。

即使内容尚未完全存储,文件资源现在可以使用,例如作为数据值中的引用内容(参见使用文件数据值)。如果我们需要检查更新的 storageStatus 或以其他方式检索文件,可以查询fileResources端点。

curl "https://server/api/fileResources/xm4JwRwke0i" -H "Accept: application/json"

| 此请求将返回 FileResource 对象,如上面例子的反应。 | 此请求将返回 FileResource 对象,如上面例子的反应。 | | ------------------------------------- | ---- | | 文件资源*必须*从另一个对象引用(分配) | 以便长期坚持。一个文件资源是 | | 创建但未被其他对象(例如数据值)引用 | 被认为处于*分期*。此中的任何文件资源 | | 状态并且超过*两个小时*将被标记为删除 | 并将最终从系统中清除。 | | 文件资源初始创建返回的ID不是 | 可从任何其他位置检索,除非文件资源具有 | | 已被引用(其中 ID 将被存储为引用), | 所以丢失它需要重复 POST 请求和一个新的 | | 要创建的对象。 孤立*文件资源将被清理 | 自动起来。 | | 文件资源对象是*不可变的,意味着修改不是 | 允许并需要创建一个全新的资源。 | | 文件资源阻止列表 { #file-resource-blocklist } | |

出于安全原因,某些类型的文件被阻止上传。

以下内容类型被阻止。	以下内容类型被阻止。	以下内容类型被阻止。
文字/ HTML	应用项目/ x-ms-dos-可执行	文字/ css
application / vnd.microsoft.portable-executable	文字/ javascript	application / vnd.apple.installer + xml
字体/ otf	application / vnd.mozilla.xul + xml	应用项目/ x-shockwave-flash
应用项目/ x-httpd-php	application / vnd.debian.binary-package	应用项目/ x-sh
应用/ x-rpm	应用项目/ x-csh	应用项目/ Java归档
以下文件扩展名被阻止。	文件扩展名	文件扩展名
文件扩展名	网页

黛比

htm 转数

名称

类型	检索和删除项目通知模板	Parameter name
js	subjectTemplate	SH

微信

可执行项目

/api/metadata/version/create:这个端点将创建元数据

OTF

响应:

蝙蝠

瑞士法郎

/api/metadata/version/create:这个端点将创建元数据

元数据版本控制 { #webapi_metadata_versioning }

响应:

/api/metadata/version:这个端点将返回当前的元数据

调用它的系统的版本。表格查询参数

名称

类型	检索和删除项目通知模板	Parameter name
假	subjectTemplate	获取元数据版本示例 { #webapi_metadata_versioning_examples }

示例:获取此系统的当前元数据版本

请求:

/api/metadata/version/create:这个端点将创建元数据

响应:

**示例:**获取名称为“ Version_2”的版本的详细信息

请求:

/api/metadata/version/create:这个端点将创建元数据

响应:

/api/metadata/version/history:这个端点将返回所有

调用它的系统的元数据版本。表格查询参数

名称

类型	检索和删除项目通知模板	Parameter name
枚举(参见元数据和渲染类型表中的列表)	Tracked Entity UIDS	获取所有元数据版本的列表 { #webapi_get_list_of_metadata_versions }

**示例:**获取此系统中所有版本的列表

请求: ``` / api /元数据/版本/历史记录

    响应:

  - ```json
{
  "metadataversions": [{
    "name": "Version_1",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:54:41.139+0000",
    "id": "SjnhUp6r4hG",
    "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798"
  }, {
    "name": "Version_2",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T05:59:33.238+0000",
    "id": "SaNyhusVxBG",
    "hashCode": "8050fb1a604e29d5566675c86d02d10b"
  }, {
    "name": "Version_3",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
  }]
}

**示例:**获取此系统在“ Version_2”之后创建的所有版本的列表请求:

/ api / metadata / version / history?baseline = Version_2

响应:

{
  "metadataversions": [{
    "name": "Version_3",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:23.680+0000",
    "id": "FVkGzSjAAYg",
    "hashCode": "70b779ea448b0da23d8ae0bd59af6333"
  }, {
    "name": "Version_4",
    "type": "BEST_EFFORT",
    "created": "2016-06-30T06:01:28.684+0000",
    "id": "Ayz2AEMB6ry",
    "hashCode": "848bf6edbaf4faeb7d1a1169445357b0"
  }]
 }

/api/metadata/version/create:这个端点将创建元数据

version 参数中指定的版本类型。

响应:

名称

需要描述类型
真正描述用户可以选择需要创建的元数据类型。元数据版本类型决定了进口商应该如何对待给定的版本。导入元数据时将使用此类型。有两种类型的元数据。

BEST_EFFORT:这种类型表明丢失的引用可以

类型	检索和删除项目通知模板	Parameter name
js	Tracked Entity UIDS	> 注意
>
> 建议有一个 ATOMIC 类型的版本,以确保所有
> 系统(中央和本地)具有相同的元数据。任何遗漏
> 引用在验证阶段本身被捕获。请参阅
> 进口商详细信息的完整解释。

创建元数据版本

示例: 创建类型为 BEST_EFFORT 的元数据版本

/api/metadata/version/create:这个端点将创建元数据

curl -X POST -u admin:district "https://play.dhis2.org/dev/api/metadata/version/create?type=BEST_EFFORT"

响应:

{
  "name": "Version_1",
  "created": "2016-06-30T05:54:41.139+0000",
  "lastUpdated": "2016-06-30T05:54:41.333+0000",
  "externalAccess": false,
  "publicAccess": "--------",
  "user": {
    "name": "John Traore",
    "created": "2013-04-18T17:15:08.407+0000",
    "lastUpdated": "2016-04-06T00:06:06.571+0000",
    "externalAccess": false,
    "displayName": "John Traore",
    "id": "xE7jOejl9FI"
  },
  "displayName": "Version_1",
  "type": "BEST_EFFORT",
  "hashCode": "fd1398ff7ec9fcfd5b59d523c8680798",
  "id": "SjnhUp6r4hG"
}

`/api/metadata/version/{versionName}/data`:这个端点将下载

特定于作为路径传递的版本名称的实际元数据

范围。 /api/metadata/version/{versionName}/data.gz:这个端点将下载特定于作为路径传递的版本名称的实际元数据压缩格式(gzipped)的参数。

选项值

类型	检索和删除项目通知模板	Parameter name
js	Tracked Entity UIDS	格式为 "Version_<id>"的路径参数,以便 API 下载特定版本

下载版本元数据 { #webapi_download_version_metadata } **示例:**获取“版本5”的实际元数据请求: ``bash curl -u admin:district "https://play.dhis2.org/dev/api/metadata/version/Version_5/data"

    响应:

  - ```json
{
  "date": "2016-06-30T06:10:23.120+0000",
  "dataElements": [
    {
      "code": "ANC 5th Visit",
      "created": "2016-06-30T06:10:09.870+0000",
      "lastUpdated": "2016-06-30T06:10:09.870+0000",
      "name": "ANC 5th Visit",
      "id": "sCuZKDsix7Y",
      "shortName": "ANC 5th Visit ",
      "aggregationType": "SUM",
      "domainType": "AGGREGATE",
      "zeroIsSignificant": false,
      "valueType": "NUMBER",
      "categoryCombo": {
        "id": "p0KPaWEg3cf"
      },
      "user": {
        "id": "xE7jOejl9FI"
      }
    }
  ]
}

元数据同步{ #webapi_metadata_synchronization } 本节介绍了可用的元数据同步 API 2.24 开始/api/metadata/sync`:此端点执行元数据同步通过下载和在查询参数中传递的版本名称从远程服务器导入指定的版本,如定义设置应用项目。

表格查询参数名称需要描述版本名称真正

versionName 查询参数的形式为 "Version_<id>" 。api 会从远程服务器下载该版本,并将其导入本地系统。

使用此 API 时应格外小心。请注意,有

/api/metadata/version/create:这个端点将创建元数据

利用“数据管理”中的元数据同步任务

应用项目。详见用户手册第 22 章 22.17 节

关于元数据同步任务。

此同步 API 也可用于同步元数据

从元数据同步调度项目失败的版本。由于

它依赖于给定的元数据版本号,应该注意

为调用 this 的顺序而采用。例如。如果这个api是

用于从中央实例同步一些更高版本,然后

同步可能会失败,因为元数据依赖项不存在于

本地实例。

假设本地实例在 Version_12 并且如果使用这个端点

从中央同步Version_15(类型BEST_EFFORT)

例如,调度项目将从以下位置开始同步元数据

Most notably the sequence has only a single item. Information on top level object and the object in the sequence both originate from the job configuration.

`Version_12` 和 `Version_15` 之间的版本。你需要手动

仅使用这些端点同步丢失的版本。

同步元数据版本 { #webapi_metadata_synchronization_version }

**示例:**将Version_6从中央系统同步到该系统

请求:

```bash

curl -u admin:district "https://play.dhis2.org/dev/api/metadata/sync?versionName=Version_6"

元数据存储库 { #webapi_metadata_repository } 

DHIS2 提供了一个包含元数据包的元数据存储库
各种内容。元数据包是符合 DHIS2 的 JSON 文档
它描述了一组元数据对象。

### 要检索可用元数据包的索引,您可以发出
对 *metadataRepo* 资源的 GET 请求:

    GET /api/synchronization/metadataRepo

元数据包条目包含有关包的信息和
相关包的 URL。索引可能如下所示:

```json
{
  "packages": [
    {
      "id": "sierre-leone-demo",
      "name": "Sierra Leone demo",
      "description": "Sierra Leone demo database",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/sierra-leone-demo/metadata.json"
    },
    {
      "id": "trainingland-org-units",
      "name": "Trainingland organisation units",
      "description": "Trainingland organisation units with four levels",
      "version": "0.1",
      "href": "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
    }
  ]
}

客户端可以通过 URL 安装元数据包带有元数据包的内容类型 text/plain 的 POST 请求 URL 作为 metadataPull 资源的有效负载:
POST / api / synchronization / metadataPull
curl命令示例如下所示:

curl "localhost:8080/api/synchronization/metadataPull" -X POST
  -d "https://dhis2.org/metadata-repo/221/trainingland-org-units/metadata.json"
  -H "Content-Type:text/plain" -u admin:district

注

提供的 URL 将根据 dhis.conf 文件中的配置属性 metadata.sync.remote_servers_allowed 进行检查。如果基本 URL 不在允许的配置服务器之列,则不允许执行操作。请看下面的失败示例。
配置集为 metadata.sync.remote_servers_allowed=https://server1.org/,https://server2.org/ 的一些示例 - 提供 https://server1.org/path/to/resource -> 这将被接受 - 提供 https://server2.org/resource/path -> 这将被接受 - 提供 https://oldserver.org/resource/path -> 这将被拒绝 JSON 格式的故障响应示例。

 {
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Provided URL is not in the remote servers allowed list",
  "errorCode": "E1004"
}

参考用户创建的{ #reference-to-created-by-user } Each object created in DHIS2 will have a property named user which is linked to User who created the object.

From version 2.36 we have changed the name of this property to createdBy to avoid confusion.

不过,为了保持向后兼容性,传统的 user 属性仍包含在有效载荷中,并像以前一样正常工作。

{
  "createdBy": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"
  },
  "user": {
      "displayName": "John Kamara",
      "name": "John Kamara",
      "id": "N3PZBUlN8vq",
      "username": "district"
  }
}

元数据提案工作流程{ #webapi_metadata_proposal_workflow }

元数据提议工作流程端点可实现提议和接受元数据更改的工作流程。

/api/metadata/proposals

提议更改元数据{ #webapi_metadata_proposal_propose }

一个提案总是针对一个元数据对象,使用

POST /api/metadata/proposals

根据有效载荷的不同,该提案可以

添加一个新的元数据对象。

按 ID 更新现有元数据对象引用。

删除 ID 引用的现有元数据对象。

要提议添加新的元数据对象,请发送类似下面的 JSON 有效载荷:

```json

{ "type": "ADD", "target": "ORGANISATION_UNIT", "change": {"name":"My Unit", "shortName":"MyOU", "openingDate": "2020-01-01"} }

`change` 属性包含相同的 JSON 对象,可直接发布到相应的端点以创建对象。

要提议更新现有元数据对象,请发送一个 JSON 有效载荷,如下例所示:

```json
{
  "type": "UPDATE",
  "target": "ORGANISATION_UNIT",
  "targetId": "<id>",
  "change": [
    {"op": "replace", "path": "/name", "value": "New name"}
  ]
}

The targetId refers to the object by its ID which should be updated. The change property here contains a JSON patch payload. This is the same patch payload that could be posted to the corresponding endpoint to directly apply the update. 要提议删除现有对象,请发送一个有效载荷,如上一个示例:

```json

{ "type": "REMOVE", "target": "ORGANISATION_UNIT", "targetId": "" }

The `targetId` refers to the object  by its ID which should be removed. A free text `comment` can be added to any type of comment.

Only `target` type `ORGANISATION_UNIT` is supported currently.

接受元数据更改建议{ #webapi_metadata_proposal_accept }

### 要接受一个开放的提案,请在提案资源上使用`POST`
    POST /api/metadata/proposals/<uid>

成功后,提案的状态变为`接受`状态。一旦被接受,提案就不能再被拒绝。

Should a proposal fail to apply it changes to status `NEEDS_UPDATE`. The `reason` field contains a summary of the failures when this information is 
available.

反对元数据变更提案{ #webapi_metadata_proposal_oppose }

如果提案不太正确并且需要调整,可以通过发送提案资源的`PATCH`来反对提案

    PATCH /api/metadata/proposals/<uid>

可选地,可以在其中添加纯文本正文,以给出提案遭到反对的`原因`。

反对的提案必须处于`PROPOSED`状态,并将更改为`NEEDS_UPDATE`状态。

| The manual merge is suitable when there are resolvable conflicts or when not all the data needs to
be moved during the merge. For example, if an attribute has different values in both tracked
entities , the user can specify whether to keep the original value or move over the duplicate's
value. Since the manual merge involves the user explicitly requesting to move data, there are some
additional checks:       | Parameter name |
| ----------- | -------------------------------------------------------------- |
| Two mappings for the `Referrals Age` category. A program indicator can choose which mapping          | 这种调整既可以不带正文,也可以使用 JSON 正文,其中包含一个对象,该对象包含更新后的 `change` 和 `targetId` 内容。 
调整: |
| 枚举(参见元数据和渲染类型表中的列表)        | The JSON type of the `change` value depends on the proposal `type` analogous to when a proposal is initially made. |
| 用户友好型消息,说明操作是否成功。      | 要拒绝打开的提案,请在提案资源上使用`DELETE` |
| 将来源合并为指标(目标指标)的标识符      | 这最终将提案的状态更改为`拒绝`。不能对此提案进行进一步的更改。它作为事件的文档保存。 |
| 元数据变更建议清单{ #webapi_metadata_proposal_list }    | 所有提案均可列入清单: |
|     GET /api/metadata/proposals/   | 可以使用`filter`参数过滤结果列表。
例如,要只列出已接受的提案,请使用 |
|     GET /api/metadata/proposals?filter=status:eq:ACCEPTED     | 同样,只显示公开提案的使用情况: |
|     GET /api/metadata/proposals?filter=status:eq:PROPOSED | 过滤器也可应用于除 `change` 以外的任何字段。支持的过滤器操作符是 Gist Metadata API 中描述的操作符。这也包括 Gist API 中描述的属性转换器。 |
| 可用字段列表如下   | 领域 |
| 描述     | 本我 |
| 提案的唯一标识符      | 类型 | 
| `ADD` a new object, `UPDATE` an existing object, `REMOVE` an existing object      | 地位 |

### `PROPOSED` (open proposal), `ACCEPTED` (successful), `NEEDS_UPDATE` (accepting caused error or opposed), `REJECTED`
目标

type of metadata object to add/update/remove; currently only `ORGANISATION_UNIT`

targetId

更新或删除对象的 UID,未为`添加`定义

## 创建人
| Potential duplicate status | 创建
|---| --- |
| 创建提案的日期时间 | 时间
| 接受或拒绝建议的用户 | 时间
| 提案转为接受或拒绝的决定性状态的日期时间 | 评论
| 为初步建议提供可选的纯文本注释  | 理由
| 可选的纯文本,在提案被反对或接受提案失败时出现的错误时给出 | 改变
| JSON object for `ADD` proposal, JSON array for `UPDATE` proposal, nothing for `REMOVE` proposal | `order`
| 单个变更建议可通过以下方式查看  |     GET /api/metadata/proposals/<uid>
| 参数 `fields` 可用来缩小显示对象所包含字段的范围。例如 |     GET /api/metadata/proposals/<uid>?fields=id,type,status,change
| 元数据 属性值 类型和验证{ #metadata-attribute-value-type-and-validations }  | 类型
| 验证 | 文本
| 没有 | LONG_TEXT
| 没有 | 信
| 数值长度 = 1 并且是字母 | PHONE_NUMBER
| 验证基于此 regex `^[0-9+\(\)#\.\s\/ext-]{6,50}$`.最大长度为 50。  <br /> 例如+4733987937, (+47) 3398 7937, (47) 3398 7937.123 | 电子邮件
| 一般电子邮件格式 abc@email.com | BOOLEAN
| `true` or `false` | TRUE_ONLY
| 数字 | 日期
| Use format `yyyy-MM-dd` | 日期
| 使用格式`yyyy-MM-dd HH:mm:ssZ` 或`yyyy-MM-dd'T'HH:mm:ss`。 | 时间
| Use fornat `HH:mm` | 数字
| 数值必须是数字,最大长度 = 250 | 时间
| 数值为数字,包含 0 和 1 之间的值 | 百分比
| Text. | 整数
| 值为整数 | INTEGER_NEGATIVE
| 值为正整数 | INTEGER_NEGATIVE
| 值为负整数 |INTEGER_ZERO_OR_POSITIVE
| 数值为正整数或零整数 | 时间

## Value is a username of an existing `User`

### COORDINATE

没有

### ORGANISATION_UNIT

#### Value is a valid UID of an existing `OrganisationUnit`

REFERENCE

没有

AGE

Value is date of birth. Use format as in DATE type.

网址

Value is a valid URL

#### FILE_RESOURCE

Value is a valid UID of existing `FileResource`

| UID \           | 指标组  | GEOJSON                                     |
|------------------|-----------|------------------------------------------|
| IndicatorGroup          | displayColumnOrder      | 没有            |
| 以目标取代源 | displayColumnOrder      |     POST /api/programs/{uid}/copy |
| 以目标取代源 | Get translations |     POST /api/programs/{uid}/copy |

Example with a `Program` with a `UID` of `Program123a`

    POST /api/programs/Program123a/copy

Successful response will include the new `Program` `UID` and will look like this:

```json
{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Program created: 'Program456b'"
}

指标组	Copy options { #copy-options }
displayColumnOrder	230
Get translations	50

Property

Info

项目名称

请求{ #request }

GET /api/authorities

名称

Database constraint - needs to be unique
ProgramIndicator

shortName

Database constraint - needs to be unique

In this example when a custom prefix is supplied, an original Program with a name of My Simple Program would be copied to a new Program with the name my prefix My Simple Program
If no copy options are sent in the API call then the default Copy of prefix will be used for the above properties.
To send a custom prefix just add a HTTP request param prefix like so:
POST /api/programs/{uid}/copy?prefix=my prefix

Note

The database does have limits for the number of characters allowed for properties. At the time of writing these limits are noted in the table below. Bear these in mind.

Property

character limit

名称

shortName

If a property has exceeded its character limit, then an error will be returned like so:

{
    "httpStatus": "Conflict",
    "httpStatusCode": 409,
    "status": "ERROR",
    "message": "ERROR: value too long for type character varying(230)",
    "errorCode": "E1004"
}

Two mappings for the Referrals Age category. A program indicator can choose which mapping

```json { "httpStatus": "Not Found", "httpStatusCode": 404, "status": "ERROR", "message": "Program with id {uid} could not be found.", "errorCode": "E1005" }

Authorisation { #authorisation } 

##### Authorities { #authorities } 

A `User` will need the following authorities to be able to copy a `Program`:

#### F_PROGRAM_PUBLIC_ADD

F_PROGRAM_INDICATOR_PUBLIC_ADD

| UID \                         | A `Program` needs one of the following states for it to be able to be copied:  |
|--------------------------------|--------------|
| IndicatorGroup                        |              |
| A specific `User` to have sharing `read` & `write` access                 | IndicatorGroup      |
| 以目标取代源               | IndicatorGroup      |
| Points to note { #points-to-note }             | IndicatorGroup      |
| Indicator group set                   | IndicatorGroup      |
| A deep copy in this context means that a completely new instance of a `Program` or `Program` property has been created with its own unique identifiers. These include amongst others:            | Indicator group set |
| uid   | Indicator group set |
| Shallow copy { #shallow-copy }                      |              |

A shallow copy in this context means that an existing `Program` property will be reused by the newly-created `Program` or `Program` property.

| UID \                        | 指标组          |
|-------------------------------|-------------------|
| 以目标取代源              | Property of            |
| A deep copy in this context means that a completely new instance of a `Program` or `Program` property has been created with its own unique identifiers. These include amongst others:           | ProgramSection |
| Shallow copy { #shallow-copy }                     | 用于项目阶段引用的 IdScheme。默认为 `idScheme` 参数。            |


# 项目
项目规则变量

项目

项目阶段

* 项目
  ProgramStageSection
* 项目阶段
  ProgramStageSectionDataElement
* 项目阶段
  注册

## > **Note**
>
> The following properties have been set as empty as an initial approach. This approach should keep things simple to start off with.  
目的

Property

ProgramIndicator

groups

ProgramStageSection

programIndicators

* 注册
  events
* Metadata Gist API { #gist_api } 
* <!--DHIS2-SECTION-ID:gist_api-->
  The Metadata Gist API is a RESTful read-only JSON API to fetch and browse 
metadata. Items in this API contain the gist of the same item in the Metadata API.
* 应用项目接口是专门为避免以下情况而设计的:
* Large response payloads because of the inclusion of partial nested object 
  graphs.
* Resource intensive in memory processing of requests 
  (e.g. in memory filtering or object graph traversal).
  _n + 1_ database queries as a result of object graph traversal while rendering
* the response.
* 与元数据应用项目接口{ #gist_vs_metadata_api } 的比较 
  <!--DHIS2-SECTION-ID:gist_vs_metadata_api-->
* 标准元数据应用项目接口是一个灵活而强大的应用项目接口,可为任何 
用例。
但这样做的缺点是,并非所有功能和组合都能在扩展的同时 
同时保持良好的性能。
特别是带有项目的列表,其中每个项目本身都有一个属性,而这个属性是一个复杂对象的大集合。 
的大量复杂对象的集合,这已被证明是个问题,因为它们会很快
引用整个对象图的很大一部分。
  添加`/gist`应用项目接口是为了提供一个元数据应用项目接口,其中良好的扩展性是我们的 
的首要任务。这样做的弊端是对
技术上合理的功能,这意味着并非标准元数据 API 的所有功能都适用于 Gist API。 
标准元数据 API 的所有功能都适用于 Gist API。
* The Gist API uses a divide and conquer strategy to avoid responses with large
partial object graphs. Instead of including nested objects or lists it provides
a `/gist` endpoint URI where this object or list can be viewed in isolation.
* **The `/gist` API refers to nested data using URIs rather than including it.**
This means if a client is interested in this nested information more requests
are required but each of them is kept reasonable small and will scale
well in context of huge number of potential items.
* Known Differences:

items only includes fields of referenced identifiable objects if these do not

* have an endpoint on their own
  it never includes identifiable collections of objects directly
  items by default do not include all available fields, but a subset that depends 
* on context and parameters
* lists cannot be used without pager (therefore there is no `pager` parameter)
* fields with collections are not paged using the `pager`-transformer but through
* a paged API endpoint for the particular collection property
* items in a list, a collection property size or boolean transformer result 
* always considers object sharing (the set of considered items is always the set
  visible to the user)

Gist offers `member(<id>)` and `not-member(<id>)` collection field transformers


## Gist offers `canRead` and `canWrite` access check filter instead of filtering
on the `access` property

Gist offers using attribute UIDs as field and filter property names to allow

* listing or filtering based on custom attribute values
* Gist offers filter grouping
* Gist offers renaming the enrty list in a paged response using `pageListName`

Gist offers to pluck multiple simple properties


## Known Limitations:
by default only persisted are included; a handful of special 

non-persistent fields (synthetic fields) can be added explicitly; other 

non-persistent fields might be possible to extract using `from` transformation


## filters can only be applied to persisted fields
orders can only be applied to persisted fields

token filters are not available


### order is always case-sensitive
`pluck` transformer limited to text properties (or simple properties for multi-pluck)

| 默认值      | 用户设置 { #webapi_user_settings }                | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于:                            | Parameter name          |
| -------------- | --------------------- |------------------------------------| ---------------------|
| <!--DHIS2-SECTION-ID:gist_endpoints--> | `order`     | flushMode                            | <code>/api/&lt;object-type&gt;/&lt;object-id&gt;<b>/gist</b></code>: view single object by ID (implicit `auto=L`) |
| <code>/api/&lt;object-type&gt;/&lt;object-id&gt;/&lt;field-name&gt;<b>/gist</b></code>: paged list of all known and visible items in the collection of owner object's field (implicit `auto=M`; in case this is a simple field just the field value)         | These endpoints correspond to the endpoints of the standard metadata API without 
the `/gist` suffix and share the majority of parameters and their options with 
that API. | Browsing Data { #gist_browse }                 | <!--DHIS2-SECTION-ID:gist_browse--> |
| The API supports CSV and JSON response for `GET /api/tracker/events`.       | To manually browse data it can be handy to use the `absoluteUrls=true` parameter.
Linkage between parts of the gist can now be followed directly in browsers that
render JSON responses. | Parameters { #gist_parameters }                                 | <!--DHIS2-SECTION-ID:gist_parameters--> |
| All endpoints of the `/gist` API accept the same set of parameters.
Parameters and their options that do not make sense in the endpoint context are 
ignored.       | 总览 { #overview }  |                                    | Parameters in alphabetical order: |
| Parameter     | `order`     | flushMode                            | 描述 |
| `absoluteUrls`      | `order`     | flushMode                            | `true` use relative paths in links, `false` use absolute URLs in links |
| `auto`       |                       | `XS`, `S`, `M`, `L`, `XL` | (context dependent) |
| extent of fields selected by `*` field selector        | `fields` | (depends on endpoint)                             | `*` |
| comma separated list of fields or presets to include         | `filter`                   | 1                                  | `<field>:<operator>` or `<field>:<operator>:<value>` |
| 默认     | `headless`                | 50                                 | `true` or `false` |
| `false` | `true` skip wrapping result in a pager (ignores `total`), `false` use a pager wrapper object around the result list | `inverse` | `true` or `false` | 
| `false` | `true` return items **not** in the list, `false` return items in the list         | `locale`                              | (user account configured language) |
| translation language override        | `order`     | flushMode                            | `:asc` |
| comma separated list of query order fields (can be used more than once)    | `order`     | Tracker import { #webapi_tracker_import }                             | page number |



### `pageSize`
1-1000

number of items on a page

`pageListName`

`<text>`

(object type plural)

overrides the property name of the result entry list

`rootJunction`

`与`或`或`


### `AND`
logical combination of `filter`s, `AND`= all must match, `OR`= at least one must match

* `total`/`totalPages`
* `true` or `false`
* `false`

`true` add total number of matches to the pager, `false` skip counting total number of matches

`translate`

* `true` or `false`
* `true`
* `true` translate all translatable properties, `false` skip translation of translatable properties (no effect on synthetic display names)
* The `absoluteUrls` Parameter { #gist_parameters_absoluteUrls } 
* <!--DHIS2-SECTION-ID:gist_parameters_absoluteUrls-->

By default, URIs in `apiEndpoints`, `href` and the `pager` `prev` and `next` 
members are relative, starting with `/<object-type>/` path.


### 可以使用 `absoluteUrls` 参数将 URI 更改为绝对 URL。
For example, `/api/users/rWLrZL8rP3K/gist?fields=id,href` returns:

```json
{
  "id": "rWLrZL8rP3K",
  "href": "/users/rWLrZL8rP3K/gist"
}

whereas /api/users/rWLrZL8rP3K/gist?fields=id,href&absoluteUrls=true returns:

{
  "id": "rWLrZL8rP3K",
  "href": "http://localhost:8080/api/users/rWLrZL8rP3K/gist?absoluteUrls=true"
}

As the example shows the absoluteUrls parameter is also forwarded or carried over to the included URLs so allowing to browse the responses by following the provided URLs.

The auto Parameter { #the-auto-parameter }

Each endpoint implicitly sets a default for the extent of fields matched by the * / :all fields selector:

/api/<object-type>/gist: implies auto=S

/api/<object-type>/<object-id>/gist: implies auto=L

/api/<object-type>/<object-id>/<field-name>/gist: implies auto=M

The auto parameter is used to manually override the default to make list items include more or less fields. This setting again acts as a default which can be further overridden on a per field basis using an explicit transformation.

Possible options for auto are ("t-shirt sizes"):

XS: includes only IDs and textual properties

S: excludes complex (object) properties, collection are only linked (not counted)

M: complex included as reference URL, references and collections as count and reference URL

L: like M but references and collections included as IDs (OBS! unbound in size)

XL: like L but references and collections included as ID objects: { "id": <id> } For example, /api/users/gist would list items with fields id, surname, firstName, phoneNumber, email, lastUpdated whereas /api/users/gist?auto=XS only lists id, surname, firstName, phoneNumber, email. Using /api/users/gist?auto=L would also include organisationUnits, dataViewOrganisationUnits, teiSearchOrganisationUnits and userGroups each with the list of IDs of the members in the lists/sets.

The fields Parameter { #gist_parameters_fields }

Specifies the list of fields to include for each list item.

Fields are included in the result JSON objects for an item in the provided order. A preset in the list of fields is expanded to the fields it contains at the position in the fields list it appears. Fields within the preset are ordered from simple to complex.

If no fields parameter is provided fields=* is assumed. Note that the fields of the * preset also depend on the auto parameter

To remove a field use either !<name> or -<name> in the list of fields. For example to remove the userGroups from a user, use:

/api/users/gist?fields=*,!userGroups

The same principle can also be used to specify the transformer to use for a field. For example, to include the IDs of the user's user groups use:

/api/users/gist?fields=*,userGroups::ids

The fields parameter does allow listing fields of nested objects. For example to add userCredentials with id and name of a user use:

/api/users/gist?fields=*,userCredentials[id,username]

This creates items of the form:

```json { ... "userCredentials": { "id": "Z9oOHPi3FHB", "username": "guest" } }

When including nested fields of collections the nested field must be a text
property. 

* 例如,通过以下方式包含用户的`userGroups`的所有`名称`:
*     /api/users/gist?fields=*,userGroups[name]
* This lists the `userGroups` as:

```json
{
  "userGroups": {
    "name": [
      "_PROGRAM_Inpatient program",
      "_PROGRAM_TB program",
      "_DATASET_Superuser",
      "_PROGRAM_Superuser",
      "_DATASET_Data entry clerk",
      "_DATASET_M and E Officer"
    ]
  }
}

The above is functional identical to:	Parameter name
GET /api/dataStore/?fields=name&order=name	```json
{
"pager": {
"page": 1,
"pageSize": 50
},
"users": [
"Kamara",
"Wakiki",
"Nana",
"Malai",
...
]
}
```
GET /api/dataStore/?fields=name&order=name:desc	```json
"Wakiki"
```
In summary, order can be one of the following:	The `filter` Parameter { #gist_parameters_filter }
`desc:`: alphanumeric descending order	要过滤返回的项目列表,请添加一个或多个`过滤器`参数。

Multiple filters can either be specified as comma-separated list of a single filter parameter or as multiple filter parameters each with a single filter.

There are two types of filters:	Parameter name
To filter entries within the query API context add one or more `filter` parameters
while also using the `fields` parameter.	A field can be:
a persisted field of the listed item type	a persisted field of a directly referenced object (1:1 relation)
a UID of an attribute	Available unary operators are:
set operators: `<path>:<operator>:[<value>,<value>,...]`	描述
`null`	field is null (undefined)
`null`	field is not null (defined)
`empty`	field is a empty collection or string
`!ilike`	field is a non-empty collection or string
`$like`	Binary Operator

描述

eq

field equals value

ieq

There are two types of filters:	Parameter name
field is not equal value	`lt`
字段_小于_值	`le`, `lte`
field is less than or equal to value	`gt`
field is greater than value	`ge`, `gte`
field is greater than or equal to value	`in`
field is a collection and value is an item contained in the collection	`!in`

field is a collection and value is an item not contained in the collection

If the <value> of an in or !in filter is a list it is given in the form [value1,value2,...], for example: userGroups:in:[fbfJHSPpUQD,cYeuwXTCPkU].

Any >, >=, < <=, == or != comparison applied to a collection field with a numeric value will compare the size of the collection to the value, for example: userGroups:gt:0.

Any >, >=, < <=, == or != comparison applied to a text field with a integer number value will compare the text length to the value, for example: name:eq:4 (name has length 4).

Available binary pattern matching operators are:

Binary Operator

描述

like, ilike

There are two types of filters:	Parameter name
field does not contain `<value>` or field does not match pattern `<value>` (when wildcards `*` or `?` in value)	`$like`, `$ilike`, `startsWith`
field starts with `<value>`	`!$like`, `!$ilike`, `!startsWith`
field does not start with `<value>`	`like$`, `ilike$`, `endsWith`
field ends with `<value>`	`!like$`, `!ilike$`, `!endsWith`
field does not end with `<value>`	The `like` and `!like` operators can be used by either providing a search term
in which case a match is any value where the term occurs anywhere, or they can
be used by providing the search pattern using `` as any number of characters*
and `?` as any single character.

All pattern matching operators named like are case-sensitive. All others are case-insensitive.

Note that filters on attribute values use text based comparison which means all text filters are supported.

For example, to only list organisations on second level use

/api/organisationUnits/gist?filter=level:eq:2

Similarly, when listing the children of a particular organisation unit the collection can be filtered. To only list those children that are connected to a program one would use:

/api/organizationUnits/rZxk3S0qN63/children/gist?filter=项目:gt:0

Binary operators for access (sharing) based filtering:

Binary Operator

描述

canRead

Has user <value> metadata read permission to the object

canWrite
Has user <value> metadata write permission to the object

canDataRead

Has user <value> data read permission to the object

canDataWrite

Has user <value> data write permission to the object

canAccess

Has user <value0> permission <value1> to the object

When the user ID <value> is omitted the check is performed for the currently logged-in user. Similarly, if <value0> is ommitted for canAccess filter the check is performed for the currently logged-in user.

When applied to a simple value property, here code, the filter restricts the response to those data elements (owner object) the user can read/write:

/api/dataElements/gist?filter=code:canWrite:OYLGMiazHtW

When applied to a reference property, here `categoryCombo`, the filter restricts the response

to those data elements having a category combo that the user can read/write: /api/dataElements/gist?filter=categoryCombo:canWrite:OYLGMiazHtW

When applied to a reference collection property, here dataElementGroups, the filter restricts the response to those data elements where a data element group exists in the collection property and which the user can read/write:

/api/dataElements/gist?filter=dataElementGroups:canWrite:OYLGMiazHtW

The canAccess expects two arguments, 1^st is user ID, 2^nd the access pattern, for example to check metadata read and write access the pattern is rw%:

/api/dataElements/gist?filter=code:canAccess:[OYLGMiazHtW,rw%]

In addition, filter can be grouped to allow combining selected filters with

logical OR when the general filter combinator is logical AND, or vice-versa with logical AND when the general combinator is logical OR. For groups the filter pattern is extended as following:

unary: <group>:<field>:<operator>

binary: <group>:<field>:<operator>:<value>

The group is an arbitrary number between 0 and 9 (when omitted 0 is assumed).

The behaviour is best explained with a small example for an imaginary object type with an age and name property.

?filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar

The above filter has two groups 1 and 2, and the 2 group has 2 members. This is equivalent to the SQL (note the and and or as well as the grouping braces):

e.age = 50 and (e.name = 'foo' or e.name = 'bar')

现在,如果将相同的过滤器与rootJunction=OR结合使用

?filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar&rootJunction=OR

the effect would be equivalent to the following SQL instead:

e.age = 50 or (e.name = 'foo' and e.name = 'bar')

The headless Parameter { #gist_parameters_headless }

Endpoints returning a list by default wrap the items with an envelope containing the pager and the list, which is named according to the type of object listed.

For example /api/organisationUnits/gist returns:

{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "nextPage": "/organisationUnits/gist?page=2"
  },
  "organisationUnits": [
    ...
  ]
}

With headless=true the response to /api/organisationUnits/gist?headless=true is just the [...] list part in above example.

The inverse Parameter { #the-inverse-parameter }

The inverse can be used in context of a collection field gist of the form /api/<object-type>/<object-id>/<field-name>/gist to not list all items that are contained in the member collection but all items that are not contained in the member collection.

For example, while

/api/organisationUnits/rZxk3S0qN63/children/gist

将列出作为rZxk3S0qN63子级的所有组织单位

/api/organisationUnits/rZxk3S0qN63/children/gist?inverse=true

would list all organisation units that are not children of rZxk3S0qN63. This would e.g. be used to compose a list of all units that can be made a child of a particular unit.

Filters and orders do apply normally, meaning they filter or order the items

not contained in the member collection. The locale Parameter { #gist_parameters_locale }

The locale parameter is usually used for testing purposes to ad-hoc switch translation language of display names.

If not specified the translation language is the one configured in the users account settings.

Examples:

/api/organisationUnits/gist?locale=en
/api/organisationUnits/gist?locale=en_GB

The `order` Parameter

To sort the list of items one or more order expressions can be given.

An order expression is either just a field name of a persisted field, or a field

name followed by :asc (ascending order - the default) or :desc (descending order). For example, to sort organisation units alphabetically by name use:

/api/organisationUnits/gist?order=name

Reverse alphabetical order would use:
/api/organisationUnits/gist?order=name:desc

To sort organisation units first by level, then by name use:

/api/organisationUnits/gist?order=level,name

This would start with root(s) at level 1. To start with the leaf units use:

/api/organisationUnits/gist?order=level:desc,name

If no order is specified the result list will have a stable order based on internal data organisation.

The page Parameter { #gist_parameters_page }

指在分页列表中查看的页面,以1开头的第一页。

如果不存在page参数,则等于page=1。

The page is always in relation to the pageSize. If a page is given beyond the number of existing matches an empty item list is returned.

The `pageSize` Parameter

指的是页面上的项目数。最多 1000 个项目。

如果没有pageSize参数,则等于pageSize=50。

The rootJunction Parameter { #gist_parameters_rootJunction }

The rootJunction parameter can be used to explicitly set the logic junction used between filters. Possible are:

AND: all filters have to match an entry for it to be included in the results

OR: any of the filters matches an entry for it to be included in the results

默认为与。

The `pageListName` Parameter

The array property in a paged response that contains the matching entry list is named after the object type contained in the list. For /api/organisationUnits/gist it would be named organisationUnits.

This default naming can be customized using the pageListName parameter. For example, /api/organisationUnits/gist?pageListName=matches returns a response root object with the format:

{
  "pager": {},
  "matches": []
}

(details of the pager and matches are omitted here)

The `total` or `totalPages` Parameter

By default, a gist query will not count the total number of matches should those exceed the pageSize limit. Instead, we opt-in to the additional costs the total count implicates.

When not counting the total matches (total=false) the response pager will assume that there is a next page in case pageSize items were found. This could however turn out to be false when browsing to the page. Also, the total field stating the number of total matches is not included in the pager.

For example, /api/organisationUnits/gist returns a pager:

```json

{ "pager": { "page": 1, "pageSize": 50, "nextPage": "/organisationUnits/gist?page=2" } }

* When counting the total matches (`total=true`) the response `pager` will 
contain the `total` field with the actual number of total matches at the cost
of an additional database operation.
* The response to `/api/organisationUnits/gist?total=true` now returns this `pager`:
* ```json
{
  "pager": {
    "page": 1,
    "pageSize": 50,
    "total": 1332,
    "nextPage": "/organisationUnits/gist?total=true&page=2",
    "pageCount": 27
  }
}

* The translate Parameter { #gist_parameters_translate } *

像`name`或`shortName`这样的字段可以被翻译(国际化)。

By default, any translatable field that has a translation is returned translated given that the user requesting the gist has an interface language configured.

要返回普通的非翻译字段,请使用 translate=false。

| For example, /api/organisationUnits/gist returns items like this: | json { "name": "A translated name", ... } | Parameter name | |----------------------|------------------------|-------------------------------------------------------------------------------------------------------| | json { "name" "Plain field name", ... } | Note that synthetic fields displayName and displayShortName are always returning the translated value independent of the translate parameter. | Fields { #gist_fields } | | | The fields included by default (without fields parameter) correspond to fields=*. This means the list of fields shown depends on object type, endpoint context as well as the auto parameter. | Note that the /gist API always excludes certain fields that usually are of no interest to clients, like for example the translations or sharing fields. These can be added explicitly. | | When not explicitly provided by name in the fields parameters the list of fields is computed from a preset. A preset can be used in the list of fields like a field name. It expands to zero, one or many fields depending on the object type, used endpoint and selector. | Field Presets { #field-presets } | * / :all: default fields depend on the context and auto parameter | | :identifiable: all persisted fields of the IdentifiableObject interface | Field Presets { #field-presets } | :nameable: all persisted fields of the NameableObject interface | | :persisted: literally all persisted fields | isEmpty | A transformer or transformation can be applied to a field by appending any of the indicators ::, ~ or @ followed by the transformer expression. | | Available transformer expressions are: | Transformer | JSON Result Type | | 描述 | Field Presets { #field-presets } | -- | | renames the field in the response to <name> | Field Presets { #field-presets } | number | | number of items in the collection field | isEmpty | boolean | | emptiness of a collection field | isNotEmpty | boolean |

non-emptiness of a collection field

ids

string or [string]

ID of an object or IDs of collection items

id-objects

[{ "id": <id> }]

IDs of collection items as object

member(<id>)

boolean

具有<id>的成员用于集合字段

`not-member(<id>)`

boolean

集合字段中没有具有<id>的成员

pluck(<field>,...)

string or [string]

order is always case-sensitive

from(<field>,...)

Synthetic Fields

The /gist API is tightly coupled to properties that exist the database. This means properties that aren't stored in the database usually aren't available. The exception to this are the "synthetic" properties which are dynamically computed on the basis of one or more database stored properties.

Synthetic properties are available for all endpoints where the persisted properties needed to compute the synthetic property exist.

Except for the apiEndpoints property which is automatically added when needed all other synthetic properties are not included by default and have to be requested explicitly in the list of fields.

总览

Synthetic fields in alphabetical order:

领域

描述

apiEndpoints

contains links to browse nested complex objects or collections

`href`

link to the list item itself (single item view)

displayName

已翻译的名称(始终已翻译)

displayShortName

translated shortName (always translated)

access

summary on ability of current user to read/write/modify the entry

The href Field { #gist_syntheticFields_href }

Each item in a /gist response can link to itself. This link is given in the href property.

access

/api/<object-type>/gist?fields=*,href

The `displayName` and `displayShortName` Field

By definition the displayName is the translated name and the displayShortName is the translated shortName.

To add displayName or displayShortName add it to the list use (for example):

/api/<object-type>/gist?fields=*,displayName
/api/<object-type>/gist?fields=*,displayShortName

Note that by default all translatable properties like name and shortName would also be translated. When translate=false is used to disable this displayName and displayShortName stay translated.

The `apiEndpoints` Field

This property provides the links to further browse complex objects or list of items that are included in the /gist response in form of a transformed simple value like an item count.

The apiEndpoints object will have a member of the same name for every member in the item that was transformed to a simple value.

For example,

/api/users/gist?fields=id,userGroups::size,organisationUnits::size

returns items in the form:

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "/users/rWLrZL8rP3K/organisationUnits/gist",
    "userGroups": "/users/rWLrZL8rP3K/userGroups/gist"
  }
}

The list of userGroups and organisationUnits are included as their size. Each has a corresponding member in apiEndpoints with the path to browse the list.

The paths can be changed to URLs by using the absoluteUrls parameter.

/api/users/gist?fields=id,userGroups::size,organisationUnits::size&absoluteUrls=true

returns items in the form:

{
  "id": "rWLrZL8rP3K",
  "userGroups": 0,
  "organisationUnits": 1,
  "apiEndpoints": {
    "organisationUnits": "http://{host}/api/users/rWLrZL8rP3K/organisationUnits/gist?absoluteUrls=true",
    "userGroups": "http://{host}/api/users/rWLrZL8rP3K/userGroups/gist?absoluteUrls=true"
  }
}

The access Field { #the-access-field }

The access summary is based on the sharing and the current user. This means it is only applicable for objects that have a sharing property.

For example, when listing data elements with access field

/api/dataElements/gist?fields=*,access

返回的数据元素项包含一个访问成员,如下所示:

"access": {
  "manage": false,
  "externalize": false,
  "write": false,
  "read": true,
  "update": false,
  "delete": false
}

Attributes as Fields { #gist_attributeFields }

DHIS2 allows creating and adding custom attributes to metadata objects. Their values are contained in the attributeValues property of a metadata object in form of a map with the attribute UID as the map's key.

To directly list one or more specific attribute values from this map as if they were usual fields of the metadata object the attribute UID can be used as if it was a name of a usual field.

For example, to include the value of the attribute with UID Y1LUDU8sWBR as the property unit-of-measure in the list use:

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)

This results in list items of the form:

{
  "id": "qrur9Dvnyt5",
  "name": "Age in years",
  "unit-of-measure": "years"
}

By default, the values are fetched as JSON and extracted from the map of attribute values. This means the listing will contain the proper JSON type for the type of attribute value. This comes at the overhead of fetching all attribute values. To single out the value within the database the PLUCK transformation can be used.

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)~pluck

The result will look the same but now the value is extracted as text in the database turning any JSON value to a string in the property output.

例子 { #gist_examples }

A few examples starting from simple listings moving on to very specific use cases.

It is preferable to always supply an explicit list of `fields` so this section

will do so.

List organisation units with id and name:

/api/organisationUnits/gist?fields=id,name

List organisation units with id and name and total count:

/api/organisationUnits/gist?fields=id,name&total=true

List users with id and username:

/api/users/gist?fields=id,userCredentials.username

List users with id, username and last login date:

/api/users/gist?fields=id,userCredentials[username,lastLogin]

List only organisation units on second level with id, name and level:

/api/organisationUnits/gist?fields=id,name,level&filter=level:eq:2

List only organisation units that have more than 1 child with id, name and number of children:

/api/organisationUnits/gist?fields=id,name,children::size&filter=children:gt:1

List only organisation units that are not yet a children of another unit zFDYIgyGmXG:

/api/organisationUnits/zFDYIgyGmXG/children/gist?fields=id,name&inverse=true

List users and flag whether they are a member of a specific user group NTC8GjJ7p8P and name that field is-member in the response:

/api/users/gist?fields=id,userCredentials.username,userGroups::member(NTC8GjJ7p8P)~rename(is-member)

List links to all users in pages of 10 items:

/api/users/gist?fields=href&absoluteUrls&pageSize=10

数据 { #data }

“ dataelement”,“ period”,“ orgunit”,“ catoptcombo”,“ attroptcombo”,“ value”,“ strby”,“ lstupd”,“ cmt”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 1”,“用户名”,“ 2015-04-01”,“ comment1”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 2”,“用户名”,“ 2015-04-01”,“ comment2”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 3”,“用户名”,“ 2015-04-01”,“ comment3”

本节关于发送和读取数据值。

/api/dataValueSets

发送数据值 { #webapi_sending_data_values }

To send data values you can make a POST request to the following resource.

POST /api/dataValueSets

A common use-case for system integration is the need to send a set of data values from a third-party system into DHIS. In this example, we will use the DHIS2 demo on http://play.dhis2.org/demo as basis. We assume that we have collected case-based data using a simple software client running on mobile phones for the Mortality <5 years data set in the community of Ngelehun CHC (in Badjia chiefdom, Bo district) for the month of January 2014. We have now aggregated our data into a statistical report and want to send that data to the DHIS2 instance. The base URL to the demo API is http://play.dhis2.org/demo/api. The following links are relative to the base URL.

最适合我们发送数据的资源 values 是 /api/dataValueSets 资源。一个数据值集代表一个一组具有关系的数据值,通常来自从相同的数据输入表单中捕获。格式看起来像这:

```xml

JSON支持以下格式:

```json
{
  "dataSet": "dataSetID",
  "completeDate": "date",
  "period": "period",
  "orgUnit": "orgUnitID",
  "attributeOptionCombo": "aocID",
  "dataValues": [
    {
      "dataElement": "dataElementID", 
      "categoryOptionCombo": "cocID", 
      "value": "1", 
      "comment": "comment1"
    },
    {
      "dataElement": "dataElementID", 
      "categoryOptionCombo": "cocID", 
      "value": "2", 
      "comment": "comment2"
    },
    {
      "dataElement": "dataElementID", 
      "categoryOptionCombo": "cocID", 
      "value": "3", 
      "comment": "comment3"
    }
  ]
}

CSV支持以下格式:

“ dataelement”,“ period”,“ orgunit”,“ catoptcombo”,“ attroptcombo”,“ value”,“ strby”,“ lstupd”,“ cmt”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 1”,“用户名”,“ 2015-04-01”,“ comment1”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 2”,“用户名”,“ 2015-04-01”,“ comment2”
“ dataElementID”,“ period”,“ orgUnitID”,“ cocID”,“ aocID”,“ 3”,“用户名”,“ 2015-04-01”,“ comment3”

Note

Please refer to the date and period section above for time formats.

Note

Any imported data value which is seen as unchanged will be ignored and the import summary will reflect this. An unchanged data value is classed as one which has the same value for all 3 of these properties: - value - comment - followUp

从这个例子中,我们可以看出我们需要识别周期, 数据集、组织单位(设施)和数据元素报告。

To obtain the identifier for the data set we make a request to the /api/dataSets resource. From there we find and follow the link to the Mortality < 5 years data set which leads us to /api/dataSets/pBOMPrpg1QX. The resource representation for the Mortality < 5 years data set conveniently advertises links to the data elements which are members of it. From here we can follow these links and obtain the identifiers of the data elements. For brevity we will only report on three data elements: Measles with id f7n9E0hX8qk, Dysentery with id Ix2HsbDMLea and Cholera with id eY5ehpbEsB7.

剩下的就是掌握组织的标识符单元。 dataSet 表示方便地提供了到组织的链接报告它的单位,所以我们搜索 Ngelehun CHC 并按照链接到 /api/organisationUnits/DiszpKrYNg8 中的 HTML 表示,其中告诉我们这个组织单位的标识符是DiszpKrYNg8。

发送数据值 { #webapi_sending_data_values }

<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
  completeDate="2014-02-03" period="201401" orgUnit="DiszpKrYNg8">
  <dataValue dataElement="f7n9E0hX8qk" value="12"/>
  <dataValue dataElement="Ix2HsbDMLea" value="14"/>
  <dataValue dataElement="eY5ehpbEsB7" value="16"/>
</dataValueSet>

JSON格式:

{
  "dataSet": "pBOMPrpg1QX",
  "completeDate": "2014-02-03",
  "period": "201401",
  "orgUnit": "DiszpKrYNg8",
  "dataValues": [
    {
      "dataElement": "f7n9E0hX8qk", 
      "value": "1"
    },
    {
      "dataElement": "Ix2HsbDMLea", 
      "value": "2"
    },
    {
      "dataElement": "eY5ehpbEsB7", 
      "value": "3"
    }
  ]
}

To perform functional testing we will use the curl tool which provides an easy way of transferring data using HTTP. First, we save the data value set XML content in a file called datavalueset.xml. From the directory where this file resides we invoke the following from the command line:

curl -d @datavalueset.xml "https://play.dhis2.org/demo/api/dataValueSets"
  -H "Content-Type:application/xml" -u admin:district

要发送 JSON 内容,您必须设置 content-type 标头

因此:

curl -d @datavalueset.json "https://play.dhis2.org/demo/api/dataValueSets"
  -H "Content-Type:application/json" -u admin:district

选项(第一项为默认值)

默认值	发送大量数据值 { #webapi_sending_bulks_data_values }	Parameter name
DateTime	CSV格式:	JSON格式:
programStageIdScheme	CSV格式:	```csv
“ dataelement”,“ period”,“ orgunit”,“ categoryoptioncombo”,“ attributeoptioncombo”,“ value”
“ f7n9E0hX8qk”,“ 201401”,“ DiszpKrYNg8”,“ bRowv6yZOF2”,“ bRowv6yZOF2”,“ 1”
“ Ix2HsbDMLea”,“ 201401”,“ DiszpKrYNg8”,“ bRowv6yZOF2”,“ bRowv6yZOF2”,“ 2”
“ eY5ehpbEsB7”,“ 201401”,“ DiszpKrYNg8”,“ bRowv6yZOF2”,“ bRowv6yZOF2”,“ 3”
```
End date for the time span of the values to export	orgUnitIdScheme	请注意,使用 CSV 格式时,您必须使用二进制数据选项
保留 CSV 文件中的换行符:
programIdScheme	CSV格式:	```xml


false

```
outlining how to resolve identified issues	orgUnitIdScheme	The import process can be customized using a set of import parameters.
Table: Import parameters	orgUnitIdScheme	Values (default first)
`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	orgUnitIdScheme	uid \| name \| code \| attribute:ID
描述	orgUnitIdScheme	uid \| name \| code \| attribute:ID
假	假	uid \| name \| code\| attribute:ID
总览	假	source.target.request.categoryOptionComboIdScheme
Sets import strategy, `CREATE_AND_UPDATE` will try and match on identifier, if it doesn't exist, it will create the object.	dataSetIdScheme	id \| name \| code \| attribute:ID
Property of the data set to use to map the complete registrations.	假	uid \| name \| code\| attribute:ID
Property of the category object to use to map the data values (ADX only).	假	source.target.request.orgUnitIdScheme
异步导入时,会立即返回一个 Location 标头,指向 importReport 的位置。有效载荷还包含一个已创建任务的 json 对象。	假	id \| name \| code \| attribute:ID
Property of any of the above objects if they are not specified, to use to map the data values.	假	false \| true
描述	storedByDataValue	false \| true

Whether to save changes on the server or just return the import summary.

importStrategy

CREATE | UPDATE | CREATE_AND_UPDATE | DELETE

Save objects of all, new or update import status on the server.

skipExistingCheck

false | true

Skip checks for existing data values. Improves performance. Only use for empty databases or when the data values to import do not exist already.

skipAudit

false \| true	Skip audit, meaning audit values will not be generated. Improves performance at the cost of ability to audit changes. Requires authority "F_SKIP_DATA_IMPORT_AUDIT".	async
JSON object for `ADD` proposal, JSON array for `UPDATE` proposal, nothing for `REMOVE` proposal	Indicates whether the import should be done asynchronous or synchronous. The former is suitable for very large imports as it ensures that the request does not time out, although it has a significant performance overhead. The latter is faster but requires the connection to persist until the process is finished.	force

false | true

Indicates whether the import should be forced. Data import could be rejected for various reasons of data set locking for example due to approval, data input period, expiry days, etc. In order to override such locks and force data input one can use data import with force=true. However, one needs to be a *superuser* for this parameter to work.

dataSet

uid

Provide the data set ID for CSV import where the ID cannot be provided in the file itself 所有参数都是可选的,可以作为查询参数提供请求 URL 是这样的:
/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=name &dryRun=true&importStrategy=CREATE 它们也可以作为数据值集上的 XML 属性提供元素如下。 XML 属性将覆盖查询字符串参数。

```xml

    请注意,`preheatCache` 参数会对
表现。对于小的导入文件,将其设置为 false 会很快。
对于包含大量不同数据的大型导入文件
元素和组织单位,将其设置为 true 将是
幅度更快。

数据值要求 { #webapi_data_values_import_requirement } 

  - storedByDataValue

  - 是的

  - displayColumnOrder

  - 要求

评论

#### BOOLEAN

true &#124; True &#124; TRUE &#124; false &#124; False &#124; FALSE &#124; 1 &#124; 0 &#124; t &#124; f &#124;

Used when the value is a boolean, true or false value. The import service does not care if the input begins with an uppercase or lowercase letter, or if it's all uppercase.

标识符方案 { #webapi_data_values_identifier_schemes } 

Regarding the id schemes, by default the identifiers used in the XML
messages use the DHIS2 stable object identifiers referred to as `UID`.
In certain interoperability situations we might experience that an external
system decides the identifiers of the objects. In that case we can use
the `code` property of the organisation units and other objects to set
fixed identifiers. When importing data values we hence need to reference
the code property instead of the identifier property of these metadata
objects. Identifier schemes can be specified in the XML message as well
as in the request as query parameters. To specify it in the XML payload
you can do this:

```xml
<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0"
  dataElementIdScheme="CODE" orgUnitIdScheme="UID" idScheme="CODE">
</dataValueSet>

上面的参数表解释了如何指定 id 方案

作为查询参数。以下规则适用于优先级:

XML 或 JSON 负载中定义的 ID 方案优先于

id 方案定义为 URL 查询参数。


Specific id schemes such as dataElementIdScheme or	检索和删除项目通知模板	Parameter name
描述	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	uid
码	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	属性(后跟属性的UID)
属性选项是特殊的,指的是元数据属性
已被标记为独特。使用此选项时,`attribute` 必须
紧随其后的是属性的标识符,例如
“属性:DnrLSdo4hMl”。	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	uid
/api/dataValueSets?async=true	Program notification template	```json
{
"httpStatus": "OK",
"httpStatusCode": 200,
"status": "OK",
"message": "Initiated dataValueImport",
"response": {
"name": "dataValueImport",
"id": "YR1UxOUXmzT",
"created": "2018-08-20T14:17:28.429",
"jobType": "DATAVALUE_IMPORT",
"relativeNotifierEndpoint": "/api/system/tasks/DATAVALUE_IMPORT/YR1UxOUXmzT"
}
}
```
请阅读有关异步任务状态的部分了解更多信息
信息。	Program notification template	以下部分描述了 DHIS2 中使用的 CSV 格式。首先
行被假定为标题行,在导入期间将被忽略。
```json
{
"object": {
"publicAccess": "rw------",
"externalAccess": false,
"user": {},
"userAccesses": [],
"userGroupAccesses": [
{
"id": "hj0nnsVsPLU",
"access": "rw------"
},
{
"id": "qMjBflJMOfB",
"access": "r-------"
}
]
}
}
```	Program notification template	需要
描述	Program notification template	是的
Refers to ID by default, can also be name and code based on selected id scheme	Program notification template	是的
async	Program notification template	是的
Refers to ID by default, can also be name and code based on selected id scheme	Program notification template	不

Refers to ID

Attribute option combo

不

Refers to ID (from version 2.16)

值

不

您还可以请求CSV格式的数据,如下所示:

eventCreatedPeriod	检索和删除项目通知模板	Parameter name
eventDate	Program notification template	Date in ISO format
`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`	Program notification template	Free text comment
描述	Program notification template	true or false
programStageIdScheme	Program notification template	生成数据值集模板 { #webapi_data_values_template }
DateTime	Program notification template	描述了可用于进一步调整输出的参数
以下:

Table: Data values query parameters

查询参数

需要

描述

Whether to save changes on the server or just return the import summary.

默认值	Parameter name
描述	不
Organisation unit to use, supports multiple orgUnits, both id and code can be used.	comment
最小最大数据元素	Should comments be include, default: Yes.
eventDate	不
dueDate	数据元素标识方案
lastUpdatedDate	Data-element scheme to use, supports id \| code.
`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`	To read data values you can make a GET request to the following resource.
Table: Data value set query parameters	Data values can be retrieved in XML, JSON, CSV, and ADX format. Since we want to read data we will use the GET HTTP verb. We will also specify that we are
interested in the XML resource representation by including an `Accept` HTTP header with our request. The following query parameters are
available.
读取完整的数据集注册 { #webapi_reading_complete_data_sets }	Parameter
> 注
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo	dataSet
串	dataElementGroup
不	dataElement
Data element identifier. Can be repeated any number of times.	period
不	开始日期
DateTime	结束日期
programStageIdScheme	orgUnit
programIdScheme	children
End date for the time span of the values to export	orgUnitGroup
outlining how to resolve identified issues	attributeOptionCombo
Table: Import parameters	includeDeleted
`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`	lastUpdated
描述	lastUpdatedDuration
Include only data values which are updated within the given duration. The format is <value><time-unit>, where the supported time units are "d" (days), "h" (hours), "m" (minutes) and "s" (seconds).	limit
The max number of results in the response.	数据元素标识方案
Property of the data element object to use for data values in response.	orgUnitIdScheme
Property of the org unit object to use for data values in response.	categoryOptionComboIdScheme
The name of the headers to be returned as part of the response. One or more headers name separated by comma	attributeOptionComboIdScheme
Property of the attribute option combo objects to use for data values in response.	dataSetIdScheme
Property of the data set object to use in the response.	categoryIdScheme

Property of the category object to use in the response (ADX only). - categoryOptionIdScheme - Property of the category option object to use in the response (ADX only). - 方案

Property of any of the above objects if they are not specified, to use in the response. If not specified, the default idScheme for ADX is code, and for all other formats is uid.

E7126
临界点
组织单位分析资源使您可以指定一系列查询参数:
Identifier property used for the provided dataSet parameter values; id or code

inputDataElementGroupIdScheme

Identifier property used for the provided dataElementGroup parameter values; id or code

inputDataElementIdScheme

Identifier property used for the provided dataElement parameter values; id or code

inputIdScheme

General identifier property used for all object types, specific identifier schemes will override the general scheme; id or code

The following parameters from the list above are required:

Whether to compress the response payload; none, gzip or zip

attachment

File name to use for the response, a non-blank value indicates rendering the response as an attachment.

The following parameters from the list above are required:

either dataSet or dataElementGroup (for ADX this must be dataSet)

either period, both startDate and endDate, lastUpdated, or lastUpdatedDuration

either orgUnit or orgUnitGroup

支持以下响应格式:

xml(应用项目/ xml)

The following parameters from the list above are required:

csv(应用项目/ csv)

adx(应用项目/ adx + xml)

假设我们已经根据上一节称为 发送数据值 我们现在可以放在一起我们对单个数据值集的请求并使用 cURL 请求它:

curl "https://play.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8"
  -H "Accept:application/xml" -u admin:district

我们还可以使用开始和结束日期查询参数来请求一个大量的数据值。 IE。您还可以请求数据值多个数据集和组织单位以及一个时间跨度以便导出更大的数据块。请注意,期间查询参数采用优先于开始和结束日期参数。一个例子看起来像这:

```bash curl "https://play.dhis2.org/demo/api/dataValueSets?dataSet=pBOMPrpg1QX&dataSet=BfMAe6Itzgt &startDate=2013-01-01&endDate=2013-01-31&orgUnit=YuQRtpLP10I&orgUnit=vWbkYPRmKyS&children=true" -H "Accept:application/xml" -u admin:district

  - 检索已创建或更新的数据值
过去 10 天,您可以提出这样的请求:
        / api / dataValueSets?dataSet = pBOMPrpg1QX&orgUnit = DiszpKrYNg8&lastUpdatedDuration = 10d

  - A robust measure of the spread of data values, calculated as the median of the absolute deviations from the median.

  - ```xml
<?xml version='1.0' encoding='UTF-8'?>
<dataValueSet xmlns="http://dhis2.org/schema/dxf/2.0" dataSet="pBOMPrpg1QX"
  completeDate="2014-01-02" period="201401" orgUnit="DiszpKrYNg8">
<dataValue dataElement="eY5ehpbEsB7" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10003"/>
<dataValue dataElement="Ix2HsbDMLea" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10002"/>
<dataValue dataElement="f7n9E0hX8qk" period="201401" orgUnit="DiszpKrYNg8"
  categoryOptionCombo="bRowv6yZOF2" value="10001"/>
</dataValueSet>

您可以使用JSON格式请求数据,如下所示:

/api/dataValueSets.json?dataSet=pBOMPrpg1QX&period=201401&orgUnit=DiszpKrYNg8

响应将如下所示:

{
  "dataSet": "pBOMPrpg1QX",
  "completeDate": "2014-02-03",
  "period": "201401",
  "orgUnit": "DiszpKrYNg8",
  "dataValues": [
    {
      "dataElement": "eY5ehpbEsB7", 
      "categoryOptionCombo": "bRowv6yZOF2", 
      "period": "201401",
      "orgUnit": "DiszpKrYNg8", 
      "value": "10003"
    }, 
    {
      "dataElement": "Ix2HsbDMLea", 
      "categoryOptionCombo": "bRowv6yZOF2", 
      "period": "201401",
      "orgUnit": "DiszpKrYNg8", 
      "value": "10002"
    }, 
    {
      "dataElement": "f7n9E0hX8qk", 
      "categoryOptionCombo": "bRowv6yZOF2", 
      "period": "201401",
      "orgUnit": "DiszpKrYNg8", 
      "value": "10001"
    }
  ]
}

请注意,数据值是软删除的,即删除的值具有 deleted 属性设置为 true 而不是被永久删除。这在集成多个系统以进行通信时很有用删除。您可以在响应中包含已删除的值,如下所示:

/api/dataValueSets.json?dataSet=pBOMPrpg1QX&period=201401
  &orgUnit=DiszpKrYNg8&includeDeleted=true

您还可以请求CSV格式的数据,如下所示:

eventCreatedPeriod	检索和删除项目通知模板	Parameter name
Any delete operation will require the authority Perform maintenance tasks.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	/ api / 33 / system / flags
E7228	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	必须是至少一个期间或开始日期和结束日期
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	/ api / 33 / system / taskSummaries / {task-category-id}
描述	Program notification template	发送,读取和删除单个数据值 { #webapi_sending_individual_data_values }
```bash
GET /api/33/completeDataSetRegistrations?dataSet=pBOMPrpg1QX
&startDate=2014-01-01&endDate=2014-01-31&orgUnit=YuQRtpLP10I
&orgUnit=vWbkYPRmKyS&children=true
```	POST /api/dataValues	此资源支持以下查询参数:
本节说明如何取消注册数据的完整性
放。要取消完成数据集,您将与
completeDataSetRegistrations 资源:	查询参数	需要
Table: Query parameters	Program notification template	是的
日期时间	Program notification template	是的
描述	Program notification template	是的
Table: Program Stage Query Criteria	Program notification template	不

Category option combo identifier, default will be used if omitted

No (must be combined with cp)

Attribute category combo identifier

No (must be combined with cc)

Attribute category option identifiers, separated with ; for multiple values

ds

不

Data set, to check if POST or DELETE is allowed for period and organisation unit. If specified, the data element must be assigned to this data set. If not specified, a data set containing the data element will be chosen to check if the operation is allowed.

价值

不

comment

不

Data comment

跟进

不

Follow up on data value, will toggle the current boolean value 如果给定的任何标识符无效,如果数据值或评论无效或如果数据被锁定,响应将包含 409 Conflict 状态代码和描述性文本消息。如果操作导致保存或更新的值,200 OK 将被返回。请求的示例如下所示:

```bash curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s&value=12" -X POST -u admin:district

  此资源还允许使用特殊语法将值关联到
一个属性选项组合。这可以通过发送
属性类别组合的标识符,连同标识符
值代表的属性类别选项
组合。类别组合由 `cc` 参数指定,而
类别选项被指定为分号分隔的字符串,带有`cp`
范围。有必要确保类别选项都是部分
的类别组合。一个示例如下所示:

1.  ```bash
curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu&ou=DiszpKrYNg8
  &pe=201308&cc=dzjKKQq0cSO&cp=wbrDrL2aYEc;btOyqprQ9e8&value=26"
  -X POST -u admin:district

您可以使用 GET 方法通过请求检索数据值。这 value、comment 和 followUp 参数在这方面不适用:

```bash curl "https://play.dhis2.org/demo/api/dataValues?de=s46m5MS0hxu &pe=201301&ou=DiszpKrYNg8&co=Prlt0C1RF0s" -u admin:district

3.  您可以使用 *DELETE* 方法通过请求删除数据值。
    Sending individual data values as payload { #webapi_sending_individual_data_values_as_payload } 

You can send individual data values as a JSON payload using the following resource using `Content-Type: application/json`.

POST /api/dataValues

The resource will create a new data value or update a data value if it already exists. The JSON payload format is defined below.

## ```json
{
  "dataElement": "fbfJHSPpUQD",
  "categoryOptionCombo": "PT59n8BQbqM",
  "period": "202201",
  "orgUnit": "DiszpKrYNg8",
  "value": "10",
  "comment": "OK"
}

The endpoint supports specifying attribute option combos in a nested structure.

{
  "dataElement": "BOSZApCrBni",
  "categoryOptionCombo": "TkDhg29x18A",
  "attribute": {
    "combo": "O4VaNks6tta",
    "options": [
      "C6nZpLKjEJr", "i4Nbp8S2G6A"
    ]
  },
  "dataSet": "lyLU2wR22tC",
  "period": "202201",
  "orgUnit": "DiszpKrYNg8",
  "value": "15",
  "comment": "Good"
}

如果数据值已成功保存或更新,则状态代码将为201 Created,如果存在验证错误,则状态代码将为409 Conflict。

处理文件数据值

处理具有 file 类型数据元素的数据值时与上述方法存在一些偏差。这些数据值的特殊之处在于值的内容是一个 UID 引用到 FileResource 对象而不是自包含常量。这些数据值的行为就像其他存储文本的数据值一样内容,但应以不同方式处理以产生有意义的输入和输出。

There are two methods of storing file resource data values.

Upload the file to the /api/dataValues/file endpoint as

described in the file resource section. This works on versions 2.36 and later.

If you are writing code that needs to be compatible

with versions of DHIS2 before 2.36, then the process is:

如所述将文件上传到 /api/fileResources 端点

在文件资源部分。

| Retrieve the id property of the returned file resource. | Store the retrieved identifier using the value property of the data value using any | 上面描述的方法。 | 数据值和文件资源之间只有一对一的关系允许。这是在内部强制执行的,以便保存文件资源 ID 在多个数据值中是不允许的,并且会返回错误。删除数据值将删除引用的文件资源。直接删除的文件资源是不可能的。 | |---|---|---|---| | 数据值现在可以作为除返回数据以外的任何其他值进行检索将是文件资源的 UID。为了检索实际内容(意味着存储在映射的文件资源中的文件到数据值)必须向 /api/dataValues/files 发出 GET 请求镜像查询参数,因为它们将用于数据值本身。 /api/dataValues/files 端点仅支持 GET 请求。 | 值得注意的是,由于底层存储机制工作异步文件内容可能不会立即准备好从/api/dataValues/files 端点下载。这是特别真实的对于可能需要耗时上传的大文件外部文件存储的背景(取决于系统配置)。从文件资源元数据中检索 /api/fileResources/ <id> 端点允许检查 storageStatus 在尝试下载内容之前。 | Oct 04 2017-Oct 10-2017 | From version 2.20 we have included support for an international standard for aggregate data exchange called ADX. ADX is developed and maintained by the Quality Research and Public Health committee of the IHE (Integrating the HealthCare Enterprise). The wiki page detailing QRPH activity can be found at wiki.ihe.net. ADX is still under active development and has now been published for trial implementation. Note that what is implemented currently in DHIS2 is the functionality to read and write ADX formatted data, i.e. what is described as Content Consumer and Content Producer actors in the ADX profile. | | ADX 数据消息的结构与您可能的结构非常相似从前面描述的 DXF 2 数据中已经熟悉了。有一个几个重要的区别。我们将描述这些差异参考一个小例子: | Unlike dxf2, ADX requires that the datavalues are grouped according to orgUnit, period and dataSet. The example above shows a data report for the "(TB/HIV) VCCT" dataset from the online demo database. This example is using codes as identifiers instead of dhis2 uids. Codes are the preferred form of identifier when using ADX. | The ADX root element { #the-adx-root-element } | The ADX root element has only one mandatory attribute, which is the exported timestamp. In common with other ADX elements, the schema is extensible in that it does not restrict additional application specific attributes. | | The ADX group element { #the-adx-group-element } | Unlike dxf2, ADX requires that the datavalues are grouped according to orgUnit, period and dataSet. The example above shows a data report for the "(TB/HIV) VCCT" dataset from the online demo database. This example is using codes as identifiers instead of dhis2 uids. Codes are the preferred form of identifier when using ADX. | The orgUnit, period and dataSet attributes are mandatory in ADX. The group element may contain additional attributes. In our DHIS2 implementation any additional attributes are simply passed through to the underlying importer. This means that all attributes which currently have meaning in dxf2 (such as completeDate in the example above) can continue to be used in ADX and they will be processed in the same way. | A significant difference between ADX and dxf2 is in the way that periods are encoded. ADX makes strict use of ISO8601 and encodes the reporting period as (date|datetime)/(duration). So the period in the example above is a period of 1 month (P1M) starting on 2015-06-01. So it is the data for June 2015. The notation is a bit more verbose, but it is very flexible and allows us to support all existing period types in DHIS2 | | ADX期间定义 { #adx-period-definitions } | Unlike dxf2, ADX requires that the datavalues are grouped according to orgUnit, period and dataSet. The example above shows a data report for the "(TB/HIV) VCCT" dataset from the online demo database. This example is using codes as identifiers instead of dhis2 uids. Codes are the preferred form of identifier when using ADX. | Table: ADX Periods | 期间类型 | | Duration notation | Unlike dxf2, ADX requires that the datavalues are grouped according to orgUnit, period and dataSet. The example above shows a data report for the "(TB/HIV) VCCT" dataset from the online demo database. This example is using codes as identifiers instead of dhis2 uids. Codes are the preferred form of identifier when using ADX. | Duration(s) | 日常 | | P1D | Unlike dxf2, ADX requires that the datavalues are grouped according to orgUnit, period and dataSet. The example above shows a data report for the "(TB/HIV) VCCT" dataset from the online demo database. This example is using codes as identifiers instead of dhis2 uids. Codes are the preferred form of identifier when using ADX. | Oct 01 2017 | Weekly | | P7D | 2017-10-02/P7D | Oct 02 2017-Oct 08-2017 | Weekly Wednesday | | P7D | 2017-10-04/P7D | Oct 04 2017-Oct 10-2017 | Weekly Thursday | | P7D | 2017-10-05/P7D | Oct 05 2017-Oct 011-2017 | Weekly Saturday | | P7D | 2017-10-07/P7D | Oct 07 2017-Oct 13-2017 | Weekly Sunday | | P7D | 2017-10-01/P1M | Oct 01 2017-Oct 07-2017 | Bi-weekly | | P14D | 2017-10-01/P1M | Oct 02 2017-Oct 15 2017 | Monthly | | P1M | 2017-10-01/P1M | Oct 01 2017-Oct 31 2017 | 双月刊 | | P2M | 2017-01-01/P6M
2017-07-01/P6M | Nov 01 2017-Dec 31 2017 | Quarterly | | P3M | 2017-01-01/P6M
2017-07-01/P6M | Sep 01 2017-Dec 31 2017 | Six-monthly | | P6M | 2017-01-01/P6M
2017-07-01/P6M | Jan 01 2017-Jun 30 2017
Jul 01 2017-Dec 31 2017 | Six-monthly April | | P6M | 2017-01-01/P6M
2017-07-01/P6M | Apr 01 2017-Sep 30 2017
Oct 01 2017-Mar 31 2018 | Six-monthly November | | P6M | 2017-01-01/P6M
2017-07-01/P6M | Nov 01 2017-Apr 30 2018
May 01 2018-Oct 31 2018 | Yearly |

P1Y

2017-01-01/P1Y

Jan 01 2017-Dec 31 2017

Financial April

P1Y

2017-04-01/P1Y April 1 2017-Mar 31 2018
Financial July P1Y 2017-07-01/P1Y July 1 2017-June 30 2018

Financial October

P1Y

2017-10-01/P1Y

Oct 01 2017-Sep 30 2018

Financial November

P1Y

2017-11-01/P1Y

Nov 01 2017-Oct 31 2018

ADX Data values { #adx-data-values }

The dataValue element in ADX is very similar to its equivalent in DXF. The mandatory attributes are dataElement and value. The orgUnit and period attributes don't appear in the dataValue as they are required at the group level.

The most significant difference is the way that disaggregation is

represented. DXF uses the categoryOptionCombo to indicate the disaggregation of data. In ADX the disaggregations (e.g. AGE_GROUP and SEX) are expressed explicitly as attributes. If you use code as the id scheme for category, not that you must assign a code to all the categories used for dataElements in the dataSet, and further, that code must be of a form which is suitable for use as an XML attribute. The exact constraint on an XML attribute name is described in the W3C XML standard - in practice, this means no spaces, no non-alphanumeric characters other than '_' and it may not start with a letter. The example above shows examples of 'good' category codes ('GENDER' and 'HIV_AGE'). The same restrictions apply if you use name or attribute as id schemes.

In ADX, only category identifiers are used as XML attributes; identifiers for other metadata types do not have to be usalbe as XML attributes. Note that this syntax is not enforced by DHIS2 when you are assigning names, codes, or DHIS2 attributes, but you will get an informative error message if you try to import ADX data and the category identifiers are either not assigned or not suitable.

使用分解数据的显式维度的主要好处是

那

生成数据的系统不必与

DHIS2 中的 categoryOptionCombo。

生产者和消费者可以将他们的代码与第三方进行匹配

权威来源,例如 vterminology 服务。请注意,在

上面的性别和年龄组代码示例使用的是代码列表

来自世卫组织全球卫生观察站。

Note that this feature may be extremely useful, for example when producing disaggregated data from an EMR system, but there may be cases where a categoryOptionCombo mapping is easier or more desirable. The DHIS2 implementation of ADX will check for the existence of a categoryOptionCombo attribute and, if it exists, it will use that in preference to exploded dimension attributes. Similarly, an attributeOptionCombo attribute on the group element will be processed in the legacy way. Otherwise, the attributeOptionCombo can be treated as exploded categories just as on the dataValue.

In the simple example above, each of the dataElements in the dataSet have the same dimensionality (categorycombo) so the data is neatly rectangular. This need not be the case. dataSets may contain dataElements with different categoryCombos, resulting in a ragged-right ADX data message (i.e. values for different dataElements may have different numbers of categories.)

Importing ADX data { #importing-adx-data }

DHIS2 exposes an endpoint for POST ADX data at /api/dataValueSets using application/xml+adx as content type. So, for example, the following curl command can be used to POST the example data above to the DHIS2 demo server:

curl -u admin:district -X POST -H "Content-Type: application/adx+xml"
  -d @data.xml "https://play.dhis2.org/demo/api/dataValueSets?dataElementIdScheme=code&orgUnitIdScheme=code"

Note the query parameters are the same as are used with DXF data. The ADX endpoint should interpret all the existing DXF parameters with the same semantics as DXF.

Exporting ADX data { #exporting-adx-data }

DHIS2 exposes an endpoint to GET ADX data sets at /api/dataValueSets using application/xml+adx as the accepted content type. So, for example, the following curl command can be used to retrieve the ADX data:

```bash

curl -u admin:district -H "Accept: application/adx+xml" "https://play.dhis2.org/demo/api/dataValueSets?dataValueSets?orgUnit=M_CLINIC&dataSet=MALARIA&period=201501"

## Note the query parameters are the same as are used with DXF data. An
important difference is that the identifiers for dataSet and orgUnit may
be either uids or codes.

后续行动 { #webapi_follow_up } 

本节介绍了后续的标记数据。

数据值跟踪 { #data-value-follow-up } 

数据值跟踪端点允许标记数据值以进行跟踪。

PUT / api / 36 / dataValues /跟进

The payload in `JSON` format looks like this:

```json
{
  "dataElement": "s46m5MS0hxu",
  "period": "202005",
  "orgUnit": "DiszpKrYNg8",
  "categoryOptionCombo": "psbwp3CQEhs",
  "attributeOptionCombo": "HllvX50cXC0",
  "followup": true
}

The categoryOptionCombo and attributeOptionCombo fields are optional. A minimal JSON payload looks like this:

| json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } | Parameter name | |---|---| | 如果操作成功,响应状态代码将为200 OK,如果请求出错,则响应状态代码为409 Conflict。 | /api/analytics/events/query/IpHINAT79UW?stage=A03MvHHogjR&startDate=2016-03-01 &endDate=2016-12-31&dimension=ou:O6uvpzGd5pu&dimension=UXz7xuGCEhU:GT:2000 | | PUT /api/dataValues/followups | /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5 | | json { "values": [ { "dataElement": "s46m5MS0hxu", "period": "202005", "orgUnit": "DiszpKrYNg8", "categoryOptionCombo": "psbwp3CQEhs", "attributeOptionCombo": "HllvX50cXC0", "followup": true } ] } | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | Bulk update equally confirms with a 200 OK on success or returns a 409 Conflict in case of input errors. | 您可以使用以下方法过滤多个特定年龄的“年龄”数据元素像这样的 IN 运算符: | | 验证方式 { #webapi_validation } | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | GET /api/33/validation/dataSet/QX4ZTUbOt3a.json?pe=201501&ou=DiszpKrYNg8 | Filter by AGE is not null | | 第一个路径变量是引用数据集的标识符证实。支持 XML 和 JSON 资源表示。这响应包含违反验证规则。这将延长在即将到来的版本中有更多的验证类型。 | 要检索与特定数据集相关的验证规则, 意思是所有数据元素都是一部分的带有公式的验证规则的特定数据集,您可以向 validationRules 资源如下: | | GET /api/validationRules?dataSet= | 验证规则有左边和右边,也就是根据运营商比较有效性。有效的运算符值见下表。 |

Table: Operators

值

描述

equal_to

Less than

less_than_or_equal_to

Less than or equal to
compulsory_pair If either side is present, the other must also be
exclusive_pair If either side is present, the other must not be
左边和右边的表达式是数学表达式其中可以包含对数据元素和类别选项的引用以下格式的组合: $ {。 }

左侧和右侧表达式有一个 missing 值战略。这是指系统应该如何处理数据值缺少数据元素/类别选项组合引用在公式中是否应该检查验证规则为有效性或跳过。有效的缺失值策略见于下表。

Table: Missing value strategies

值

描述

SKIP_IF_ANY_VALUE_MISSING

Skip validation rule if any data value is missing

SKIP_IF_ALL_VALUES_MISSING

Skip validation rule if all data values are missing
NEVER_SKIP
Never skip validation rule irrespective of missing data values

Validation results { #webapi_validation_results }

验证结果是在执行期间发现的违规的持久结果验证分析。如果您在开始时选择“持久结果”或安排验证分析,发现的任何违规将存储在数据库。当结果存储在数据库中时,它将被使用对于 3 件事:

根据存储的结果生成分析。

未生成通知的持久结果将这样做,

一次。

跟踪结果是否产生了

通知。

跳过运行时已经检查过的规则

验证分析。

这意味着如果你不坚持你的结果,你将无法为验证结果生成分析,如果选中,结果将每次找到并运行验证时生成通知分析可能会更慢。

Query validation results { #query-validation-results }

持久化的验证结果可以在下面查看端点:

GET /api/33/validationResults

您还可以使用验证结果 ID 检查单个结果在这个端点:

GET /api/33/validationResults/<id>

验证结果也可以通过以下属性过滤:

组织单位:ou = <UID>

验证规则:vr = <UID>

期间:pe = <ISO-expression>
上面的每个过滤器属性可以多次出现,例如:
GET /api/36/validationResults?ou=jNb63DIHuwU&ou=RzgSFJ9E46G
同一过滤器的多个值与OR组合,结果必须匹配给定值之一。
如果使用了一个以上的过滤器属性,则将它们与AND组合在一起,结果必须与每个属性的值之一匹配。

对于时段过滤器,匹配结果必须与任何指定的时段重叠。

此外,验证结果还可以按其创建日期进行过滤:

GET /api/36/validationResults?createdDate=<date>

该过滤器可以与其他任何过滤器结合使用。

Trigger validation result notifications { #trigger-validation-result-notifications }

Validation results are sent out to the appropriate users once every day, but can also be manually triggered to run on demand using the following API endpoint:

POST / api / 33 / validation / sendNotifications

使用此端点仅发送未发送的结果。

Delete validation results { #delete-validation-results }

验证结果可以通过ID手动删除,

删除/ api / 36 / validationResults / <id>

或使用过滤器
删除/ api / 36 / validationResults?
Supported filter parameters include:
无效数值： 该算法可检测无法转换为数值的数据值。这种情况通常发生在输入的数据值位数过多时。

ou = <UID>以匹配组织单位的所有验证结果;提供多个参数时,多个单元组合或

`vr = <UID>`以匹配验证规则的所有验证结果;提供多个参数时,多个规则组合或

Start date for the timespan

| eventCreatedPeriod | Parameter name | Accept: application/json | Attribute identifiers | | --------------- | ------------------------------------------------------------ | --------- | ----------------------------------------- | | Table: Query parameters | DELETE /api/36/validationResults?ou=NqwvaQC1ni4&pe=2020Q1 | Follow-up data analysis | 要基于最小/最大值来识别数据离群值: | | Any delete operation will require the authority Perform maintenance tasks. | 支持的查询参数等于基于 std dev 的异常值上面描述的分析*资源。 | Follow-up data analysis | 组合维度。相反,响应将包含项目 | | dueDate | At least one data set or data element, start date and end date or period, and at least one organisation unit must be defined. | json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } | Parameter | | lastUpdatedDate | 请求查询参数 { #request-query-parameters } | json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } | Parameter | | Filter on whether the current user can manage the returned users through the managed user group relationships. | 强制的 | json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } | GET / api / 36 / outlierDetection?ds = BfMAe6Itzgt&ds = QX4ZTUbOt3a &ou = O6uvpzGd5pu&ou = fdc6uOvgoji&startDate = 2020-01-01&endDate = 2020-12-31 &algorithm = MIN_MAX | | Date used as basis for relative periods. | 不 [] | Program notification template | z_score、min_max、mod_z_score、invalid_numeric`。 | | Organisation unit, organisation unit level or groups (can be combined) | 不 [] | Program notification template | 开始日期 | | 间隔的开始日期,以检查异常值。 | 是的 | Program notification template | Parameter | | 检查异常值的时间间隔的结束日期。 | 是的 | Program notification template | Parameter | | End date for interval to check for outliers | 是的| Program notification template | 算法 | | Sort the records on the value column | 不 [] | Program notification template | 临界点 |

Threshold for outlier values. Z_SCORE and MOD_Z_SCORE algorithm only.

不

数值,大于零。默认值:3.0。

dataStartDate

Start date for interval for mean and std dev calculation. Z_SCORE and MOD_Z_SCORE algorithm only.

不

日期(yyyy-MM-dd)。

dataEndDate

End date for interval for mean and std dev calculation. Z_SCORE and MOD_Z_SCORE algorithm only.

不

日期(yyyy-MM-dd)。

订购

Field to order by. Z_SCORE and MOD_Z_SCOREalgorithm only.

不

MEAN_ABS_DEV,Z_SCORE

maxResults

输出的最大限制。

不

Integer, greater than zero and less than system setting `keyDataQualityMaxLimit` Default: 500.	[*] You must specify either data sets with the `ds` parameter, which will include all data elements in the data sets, or specify data elements with the `de` parameter.
数据存储 { #data-store }	The `startDate` and `endDate` parameters are mandatory and refer to the time interval for which you want to detect outliers. The `dataStartDate` and `dataEndDate` parameters are optional and refer to the time interval for the data to use when calculating the mean and std dev, which are used to eventually calculate the z-score.
使用特定项目和组织单位查询所有事件:	使用默认的z分数算法获取异常值:

GET / api / 36 / outlierDetection?ds = BfMAe6Itzgt&ds = QX4ZTUbOt3a
  &ou = O6uvpzGd5pu&ou = fdc6uOvgoji&startDate = 2020-01-01&endDate = 2020-12-31

属性选项组合标识符。

aocName

属性选项组合名称。

价值

数据值。

json(应用项目/ json)	Validation report
https://www.statisticshowto.com/probability-and-statistics/z-score/	标准偏差。
modifiedzscore	对于z得分,与均值的绝对偏差。对于最小-最大,与最小或最大边界的绝对偏差。
https://www.statisticshowto.com/modified-z-scores/	Z分数。仅Z分数算法。
medianabsdeviation	默认响应使用单个 `count` 列进行标准化。通过使用 `columns` 查询参数指定至少一个组织单位组集,可以在表格布局中呈现响应。
https://math.stackexchange.com/questions/2232309/median-absolute-deviation-mad-formula	上限。
lowerbound	数据值是否标记为后续。
Maximum	响应将与此类似。 `元数据`部分包含请求和响应的元数据。 `outlierValues` 部分包含异常值。
The maximum is the largest value in a dataset. It represents the highest observed value among all the data values.	约束与验证 { #constraints-and-validation }
All error messages are delivered with http status code 409.	错误代码

信息

E2200

必须至少指定一个数据元素

E2201

必须指定开始日期和结束日期

E2202

persist

E2203

| eventCreatedPeriod | Parameter name | Validation rule | 检索和删除项目通知模板 | 仪表板资源将提供仪表板列表。请记住仪表板对象是共享的,因此列表将受当前已验证的用户。您可以检索有关一个的更多信息特定的仪表板,请点击其链接,类似于: | |---|---|---|---| | E2206 | Indicator type | Response format | subjectTemplate | E2208 | | Filter on whether the current user can manage the returned users through the managed user group relationships. | 类别 | Response format |Tracked Entity UIDS | | | dueDate | 要运行验证规则并检索违规: | ds | subjectTemplate | 昨天 | | lastUpdatedDate | 描述 | ds | subjectTemplate | 昨天 | | vrg | Validation rule group | 假 | subjectTemplate | subjectTemplate | | 欧 | 组织单位 | 假 | subjectTemplate | subjectTemplate | | Sort the records on the value column | Date (yyyy-MM-dd) | 假| subjectTemplate | 500 |

结束日期

End date for the time span

Date (yyyy-MM-dd)

假

Today

persist

Whether to persist violations in the system

eventCreatedPeriod	Parameter name	Validation rule
Filter on whether the current user can manage the returned users through the managed user group relationships.	类别	Response format
dueDate	假	query
lastUpdatedDate	Integer, greater than zero. Maximum as specified by system setting `keyDataQualityMaxLimit`	query
Table: Query parameters	```json
{
"startDate":"2024-01-01",
"endDate":"2025-04-10",
"ou":"ImspTQPwCqd",
"notification":false,
"persist":false,
"vrg":"UP1lctvalPn",
"maxResults": 500
}

Sample output:

[{
    "validationRuleId": "kgh54Xb9LSE",
    "validationRuleDescription": "Malaria outbreak",
    "organisationUnitId": "DiszpKrYNg8",
    "organisationUnitDisplayName": "Ngelehun CHC",
    "organisationUnitPath": "/ImspTQPwCqd/O6uvpzGd5pu/YuQRtpLP10I/DiszpKrYNg8",
    "organisationUnitAncestorNames": "Sierra Leone / Bo / Badjia / ",
    "periodId": "201901",
    "periodDisplayName": "January 2019",
    "attributeOptionComboId": "HllvX50cXC0",
    "attributeOptionComboDisplayName": "default",
    "importance": "MEDIUM",
    "leftSideValue": 10.0,
    "operator": ">",
    "rightSideValue": 14.0
}, {
    "validationRuleId": "ZoG4yXZi3c3",
    "validationRuleDescription": "ANC 2 cannot be higher than ANC 1",
    "organisationUnitId": "DiszpKrYNg8",
    "organisationUnitDisplayName": "Ngelehun CHC",
    "organisationUnitPath": "/ImspTQPwCqd/O6uvpzGd5pu/YuQRtpLP10I/DiszpKrYNg8",
    "organisationUnitAncestorNames": "Sierra Leone / Bo / Badjia / ",
    "periodId": "201901",
    "periodDisplayName": "January 2019",
    "attributeOptionComboId": "HllvX50cXC0",
    "attributeOptionComboDisplayName": "default",
    "importance": "MEDIUM",
    "leftSideValue": 22.0,
    "operator": "<=",
    "rightSideValue": 19.0
}]
``` | Response format |
| 根据平均值的标准偏差识别数据异常值
价值: |     GET /api/dataAnalysis/stdDevOutlier | 支持以下查询参数: |

### Table: Standard deviation outlier analysis query parameters

查询参数

描述

选项

### 欧

组织单位

ID

开始日期

Start date for the timespan

| 默认值  | Parameter name                                                  | ```
Accept: application/json
``` | Attribute identifiers                   |
| ---------- | ------------------------------------------------------------ | --------- | ----------------------------------------- |
| Filter on whether the current user can manage the returned users through the managed user group relationships.         | 强制的          | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```       | ```
GET / api / 36 / outlierDetection?ds = BfMAe6Itzgt&ds = QX4ZTUbOt3a
  &ou = O6uvpzGd5pu&ou = fdc6uOvgoji&startDate = 2020-01-01&endDate = 2020-12-31
  &algorithm = MIN_MAX
```             |
| Table: Query parameters         | ```
DELETE /api/36/validationResults?ou=NqwvaQC1ni4&pe=2020Q1
```                   | Follow-up data analysis    | 要基于最小/最大值来识别数据离群值:                      |
| Any delete operation will require the authority _Perform maintenance tasks_.         | 支持的查询参数等于基于 *std dev 的异常值
上面描述的分析*资源。               | Follow-up data analysis    | 组合维度。相反,响应将包含项目                  |
| dueDate  | At least one data set or data element, start date and end date or period, and at least one organisation unit must be defined.               | Follow-up data analysis    | Parameter                        |
| lastUpdatedDate    | 请求查询参数 { #request-query-parameters }                  | Follow-up data analysis    | Parameter                        |
| E7228         | 是的                                               | Follow-up data analysis    | ds                        |
| 数据集,可以多次指定。     | 不 [*]                                                  | Follow-up data analysis    | 德                        |
| 数据元素,可以多次指定。        | 不 [*]     | Program notification template        | 开始日期         |
| Sort the records on the value column | 不 [*]                                    | Program notification template        | 结束日期  |

检查异常值的时间间隔的结束日期。

不 [*]

日期(yyyy-MM-dd)。


## 聚乙烯

ISO period ID.

### 不 [*]
Period ISO ID.

peType

ISO period.

不 [*]

Period ISO string.

可可

| Category option combos, can be specified multiple times. | Parameter name                                                                                                                   |
| -------- |-------------------------------------------------------------------------------------------------------------------------------|
| Category option combo identifier.     | maxResults                                                                                  |
| 输出的最大限制。  | 不 |
| Integer, greater than zero. Default: 50.   | [*]  You must specify either data sets with the `ds` parameter, which will include all data elements in the data sets, _or_ specify data elements with the `de` parameter.
     Equally, either `startDate` and `endDate` _or_ `period` must be specified.                               |
| The `startDate` and `endDate` parameters refer to the time interval for which you want to detect outliers.
If a period `pe` is provided instead the interval start and end is that of the period. | 如果未提供选项组合`coc`,则考虑所有数值类型的数据元素。                                           |

数据的完整性 { #webapi_data_integrity } 

数据管理模块的数据完整性功能通过网络应用项目接口提供。
可通过网络 API 使用。本节介绍如何运行
数据完整性流程和检索结果。具体
详细信息请参阅用户手册。

Listing the available data integrity checks { #webapi_data_integrity_list }

A description of the available checks is returned by a request to:

    GET /api/dataIntegrity

[ { "name": "data_elements_without_groups", "displayName": "Data elements lacking groups", "section": "Data Elements", "severity": "WARNING", "description": "Lists all data elements that have no data element groups", "issuesIdType": "dataElements", "isSlow": false } ]

The `name` member of the returned check elements is the identifier used for the
`checks` parameter to declare the set of checks to run.

> **Note**
> 
> Each check will indicate whether it may require significant time and resources to complete with the `isSlow` field. 
> Users should be cautious about running these
> checks on production systems as they could lead to decreased performance. 
> These checks can be run individually, but will 
> not be run unless specifically requested.

Checks are grouped semantically by the `section` member and categorised in 
one of four `severity` levels:

Severity

描述

### INFO

Indicates that this is for information only.

- WARNING
- A warning indicates that this may be a problem, but not necessarily an error. It is however recommended to triage these issues.

SEVERE

An error that should be fixed but which may not necessarily lead to the system not functioning.

CRITICAL

An error that must be fixed and which may lead to end-user error or system crashes.

The available checks can be filtered using the `checks` parameter.

    GET /api/dataIntegrity?checks=<pattern1>,<pattern2>

One or more exact names or patterns using `*` as a wildcard can be provided.

Additional results can be filtered using a `section` parameter.

    GET /api/dataIntegrity?section=Categories

The `section` filter will return all exact matches which have the specified section. 

Furthermore, to filter (select) only checks marked as `isSlow` use `slow=true`,
    GET /api/dataIntegrity?slow=true

或仅过滤(选择)不通过数据库查询执行的检查 
(项目化检查)使用 `programmatic=true`:

    GET /api/dataIntegrity?programmatic=true

The `slow`, `programmatic` and `section` filters can be combined in which case
all conditions must be met.

Running data integrity summaries { #webapi_data_integrity_run_summary }

Since version 2.38, data integrity checks have two levels of specificity: 

a `summary` level that provides an overview of the number of issues

a `details` level that provides a list of issues pointing to individual data integrity violations.

To trigger a summary analysis for a set of checks run:

###     POST /api/dataIntegrity/summary?checks=<name1>,<name2>

这将触发一个异步运行检查的作业。单个检查结果
将在检查完成后立即返回应用项目缓存。

Alternatively the list of checks can also be given as BODY of the POST request.
This can be useful if the list becomes to long to be used in the URL.
 - To fetch the data integrity summary of the triggered check(s) use:
 -     GET /api/dataIntegrity/summary?checks=<name1>,<name2>
 - When the `checks` parameter is omitted, all checks are fetched from the server cache.

The response is a "map" of check results, one for each check that has completed already.
This information is cached for one hour or until the check is rerun.

To wait for the summary to be available in the cache a `timeout` in milliseconds can be added:

    GET /api/dataIntegrity/summary?checks=<name1>,<name2>&timeout=500

### An example of a summary response could look like: 

```json
{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "startTime": "2023-01-11T06:12:56.436",
    "finishedTime": "2023-01-11T06:12:57.021",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "count": 12,
    "percentage": 2.3
  },
  "<name2>": {
    "name": "<name2>",
    "displayName": "<displayName2>",
    "startTime": "2023-01-11T06:12:57.345",
    "finishedTime": "2023-01-11T06:12:58.007",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "count": 4,
    "percentage": 5.1
  }
}

Each summary response will contain the name, section, severity, description and optionally an introduction and recommendation.
Each summary contains the number of issues found in the count field. When possible, an optional percentage field will provide the percentage of objects with data integrity issues when compared to all objects of the same type. The startTime field indicates when the check was initiated. Using the finishedTime the duration which was required to execute the check can be calculated.

Should a check analysis fail due to programming error or unforeseen data inconsistencies both the summary and the details will have an error field describing the error that occurred. The count of any checks which failed will be set to -1. No percentage will be returned in such cases.

{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "finishedTime": "2022-02-15 14:55",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "error": "what has happened",
    "issues": []
  }
}

Note

Each metadata check is run asynchronously on the server. Results will be returned as soon as each check completes. The safest way to ensure that you have retrieved the latest set of results which has been requested is to compare the timestamp of when the request was made with the finishedTime in the response.

To get a list of the names of checks that are currently being performed by the server use:

GET /api/dataIntegrity/summary/running

To get a list of the names of checks for which results are available already use:

GET /api/dataIntegrity/summary/completed

Retrieving completed checks as Prometheus metrics {#webapi_data_integrity_metrics}

Metadata integrity checks which are present in the cache, can be retrieved in the Prometheus metrics format by making a request to : GET /api/dataIntegrity/metrics

The response should return a plain text format in the Prometheus plain text exposition format. Several metrics are available for each data integrity check.

Count: A count of the number of issues identified by the metadata check.

Percentage: When available, provides a percentage of the objects which have been identified by the check relative to a baseline. For instance, if check "Organisation units with trailing spaces" has a percent of 2.13, the percentage is calculated by dividing the number of organisation units with trailing spaces by the total number of organisation units. Note that this percentage may not be available for all metadata integrity checks.

Duration: Number of milliseconds that the check took to execute the last time it was run.

An example of the output of this endpoint is provided below:

# HELP dhis_data_integrity_check_count Data integrity check counts { #help-dhis_data_integrity_check_count-data-integrity-check-counts } 
# TYPE dhis_data_integrity_check_count gauge { #type-dhis_data_integrity_check_count-gauge } 
dhis_data_integrity_check_count{check="orgunits_invalid_geometry"} 1
dhis_data_integrity_check_count{check="user_groups_scarce"} 0
dhis_data_integrity_check_count{check="indicator_no_analysis"} 13
# HELP dhis_data_integrity_check_percentage Data integrity check percentages { #help-dhis_data_integrity_check_percentage-data-integrity-check-percentages } 
# TYPE dhis_data_integrity_check_percentage gauge { #type-dhis_data_integrity_check_percentage-gauge } 
dhis_data_integrity_check_percentage{check="orgunits_invalid_geometry"} 0.13054830287206268
dhis_data_integrity_check_percentage{check="user_groups_scarce"} 0.0
dhis_data_integrity_check_percentage{check="indicator_no_analysis"} 16.0
# HELP dhis_data_integrity_check_duration Data integrity check durations { #help-dhis_data_integrity_check_duration-data-integrity-check-durations } 
# TYPE dhis_data_integrity_check_duration gauge { #type-dhis_data_integrity_check_duration-gauge } 
dhis_data_integrity_check_duration{check="orgunits_invalid_geometry"} 11
dhis_data_integrity_check_duration{check="user_groups_scarce"} 1
dhis_data_integrity_check_duration{check="indicator_no_analysis"} 0

Data integrity checks which are not currently in the cache will not be returned by this endpoint. A request would need to be made to the /summary endpoint to trigger the checks to be run or alternatively through a scheduled job.

Running data integrity details { #webapi_data_integrity_run_details } - To run a selection of details checks first trigger them using a POST request: POST /api/dataIntegrity/details?checks=, - Similar to the summary the list of checks can also be given as the POST body. - Then fetch the results from the cache using:

GET /api/dataIntegrity/details?checks=,&timeout=500

When the checks parameter is not provided, all checks which have not been marked as isSlow will be scheduled to be run on the server.

peType

The /details response returns a map similar to the summary, but does not contain a count or percentage. Instead, a list of issues is returned.

{
  "<name1>": {
    "name": "<name1>",
    "displayName": "<displayName1>",
    "startTime": "2023-01-11T06:12:56.436",
    "finishedTime": "2023-01-11T06:12:57.021",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "issuesIdType": "<object-type-plural>",
    "isSlow": false,
    "issues": [{
      "id": "<id-or-other-identifier>",
      "name": "<name-of-the-id-obj>",
      "comment": "optional plain text description or hint of the issue",
      "refs": ["<id1>", "<id2>"]
    }]
  },
  "<name2>": {
    "name": "<name2>",
    "displayName": "<displayName2>",
    "startTime": "2023-01-11T06:12:57.345",
    "finishedTime": "2023-01-11T06:12:58.007",
    "section": "...",
    "severity": "WARNING",
    "description": "...",
    "issuesIdType": "<object-type-plural>",
    "isSlow": false,
    "issues": []
  }
}

Each issue will always have id and name members. Often the issuesIdType is available to indicate the type of objects the id refers to. If the issuesIdType is not available, the id often is not available either and the name is used for an aggregate key of an issue that has no object equivalent.

The comment and refs fields are optional for each issue. A comment may provide more context or insight into why this particular issue is regarded to be a data integrity problem. The refs list may also give the identifiers of other objects that contributed to the violation. The finishedTime field shows when the particular check finished processing on the server. The cache will store the result of each completed check for one hour.

Tip

A set of checks can also be specified using wild-cards. To include all checks with element in the name use checks=*element*. Like full names such patterns can be used in a comma-separated list and be mixed with full names as well. Duplicates will be eliminated. Also a check can be given by its code. A code consists of the first letters of each word in the name as upper case letter. For example, orgunits_invalid_geometry has the code OIG.

Similar to the summary a set of names of the currently performed and the already completed details checks can be obtained using:

GET /api/dataIntegrity/details/running
GET /api/dataIntegrity/details/completed

Custom Data Integrity Checks

Users of DHIS2 can now create and supply their own Data Integrity Checks. This can be useful if users want to avail of this functionality and extend upon the supplied set of core data integrity checks.

Tip

Users are also encouraged to share their custom checks with others by opening a pull request in the dhis2-core repository containing their .yaml file(s). Please select platform-backend as reviewer to put the PR on our radar early on. The team will take care of checking and linking the check correctly, so it becomes part of the provided suite of checks with the next release.

An example of a custom check could be for determining if certain users are members of specific user groups. This type of check would be very specific to an implementation, and not generally applicable across all installs. These types of metadata checks can be used to extend the default checks which are included with DHIS2.

Custom checks can be implemented by satisfying the following requirements, each of which we will go into detail:

类型	zscore
Having a directory named `custom-data-integrity-checks` in your `DHIS2_HOME` directory	Supplying your valid custom data integrity check yaml files
Custom Data Integrity Check List File	DHIS2 will only try to load data integrity files when they are needed. e.g. when making a call to view all
data integrity checks:
GET /api/dataIntegrity	DHIS2 will look for a file named `custom-data-integrity-checks.yaml` in your `DHIS2_HOME` directory when loading
data integrity files. If you are not using custom checks and the file is not present, a warning log like this will
be present:

08:29:57.729  WARN o.h.d.d.DataIntegrityYamlReader: Failed to load data integrity check from YAML. Error message `{DHIS2_HOME}/custom-data-integrity-checks.yaml (No such file or directory)

If you are implementing custom data integrity checks then this file must be present. To see what the core data integrity checks file looks like as an example, check out this file.

The custom-data-integrity-checks.yaml file should list all of your custom data integrity checks. As an example, it could look something like this:

checks:
  - categories/my_custom_check.yaml
  - users/my_user_group_check.yaml
  - base_check.yaml

Check names in this file can be preceded with a directory name for logical grouping. From the 3 example checks listed

above, the directory structure should look like this:

├── DHIS2_HOME
│   ├── dhis.conf
│   ├── custom-data-integrity-checks.yaml
│   ├── custom-data-integrity-checks
│   │   ├── categories
│   │   │   ├── my_custom_check.yaml
│   │   ├── users
│   │   │   ├── my_user_group_check.yaml
│   │   ├── base_check.yaml

Name and Code constraints

Each data integrity check name and code must be unique. If there are any clashes then the violating custom check will not be loaded.

Note

System data integrity checks are always loaded first. Any name or code clashes resulting from custom checks will not affect these core system checks. An example data integrity check yaml file is located here for reference. Note the name property.

The data integrity code is calculated dynamically by using the first letter of each word in the name. Some examples:

名称

码

my_custom_check

MCC	Skip headers in the response.	MSCC
displayColumnOrder	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	If there is a `name` clash, a warning log like this will be present:
dataFilters	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	dataFilters
Data Integrity Check Schema	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	```text
09:48:43.136 WARN o.h.d.d.DataIntegrityYamlReader: JsonSchema validation errors found for Data Integrity Check `categories/my_custom_check.yaml`. Errors: [$.name: is missing but it is required]
```
Any schema violations must be fixed before that check can be loaded and used.	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	```text
10:30:37.858 WARN o.h.d.d.DataIntegrityYamlReader: JsonSchema validation errors found for Data Integrity Check `my_custom_check.yaml`. Errors: [$: string found, object expected]
```
To view and use the custom checks please refer to the main Data Integrity section	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	Data Integrity File
Details of the data integrity check yaml file, taken from the JSON schema file	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	required
info	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	yes
unique name of the check	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	yes
描述	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	yes
used for logical grouping of checks e.g. categories, users	A data integrity check file must comply with this JSON schema.
If a check does not comply with the schema then a warning like this will be present:	yes

the order of the check when displayed in the UI

summary_sql

yes

an SQL query which should return a single result which represents the total count of issues

details_sql

yes

an SQL query which should return a list of identified objects from this particular issue. Should return at least uid and name

details_id_type

yes

a short string which identifies the section of the details SQL

severity

yes

level of severity of the issue. One of [INFO, WARNING, SEVERE, CRITICAL]

introduction

yes

默认值	译	Parameter name
outlining how to resolve identified issues	端点支持POST方法注册数据集
完成。端点在功能上非常类似于
dataValueSets 端点,支持批量导入完整
注册。	An example of a custom check could be for determining if users have an email. Emails are useful to be
able to communicate with users and sent them notifications, as well as password recovery. So, in some
instllations of DHIS2, it could be a policy that all users should have emails. An example of this type
of custom check is shown below.
programStageIdScheme	端点支持POST方法注册数据集
完成。端点在功能上非常类似于
dataValueSets 端点,支持批量导入完整
注册。	完整的数据集注册 { #webapi_complete_data_set_registrations }
End date for the time span of the values to export	端点支持POST方法注册数据集
完成。端点在功能上非常类似于
dataValueSets 端点,支持批量导入完整
注册。	本节说明如何将数据集注册为完整。这是
通过与 completeDataSetRegistrations 交互实现
资源:
描述	端点支持POST方法注册数据集
完成。端点在功能上非常类似于
dataValueSets 端点,支持批量导入完整
注册。	支持导入 XML 和 JSON 格式的有效负载。这
这个有效负载的基本格式,在这个例子中以 XML 给出,就像
所以:
假	假	source.target.request.categoryOptionComboIdScheme
总览	假	Values
Sets import strategy, `CREATE_AND_UPDATE` will try and match on identifier, if it doesn't exist, it will create the object.	dataSetIdScheme	id \| name \| code \| attribute:ID
Property of the data set to use to map the complete registrations.	假	id \| name \| code \| attribute:ID
异步导入时,会立即返回一个 Location 标头,指向 importReport 的位置。有效载荷还包含一个已创建任务的 json 对象。	假	id \| name \| code \| attribute:ID

Property of the attribute option combos to use to map the complete registrations.

方案 id | name | code | attribute:ID

Property of all objects including data sets, org units and attribute option combos, to use to map the complete registrations.

preheatCache

false | true

Whether to save changes on the server or just return the import summary.

默认值	Parameter name
描述	importStrategy
eventDate	Save objects of all, new or update import status on the server.
dueDate	false \| true
lastUpdatedDate	async
GET /api/metadata/proposals?filter=status:eq:ACCEPTED	Indicates whether the import should be done asynchronous or synchronous. The former is suitable for very large imports as it ensures that the request does not time out, although it has a significant performance overhead. The latter is faster but requires the connection to persist until the process is finished.
The `idScheme`, `dataSetIdScheme`, `orgUnitIdScheme`, `attributeOptionComboIdScheme`,
`dryRun` and `strategy` (note the dissimilar naming to parameter `importStrategy`)
can also be set as part of the payload.
In case of XML these are attributes, in case of JSON these are members in the
`completeDataSetRegistrations` node.	例如:
`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`	Should both URL parameter and payload set a scheme the payload takes precedence.
读取完整的数据集注册 { #webapi_reading_complete_data_sets }	本节说明如何检索数据集完整性
注册。我们将使用 completeDataSetRegistrations
资源。要使用的查询参数如下:
Table: Data value set query parameters	Parameter
不	dataSet
描述	period
outlining how to resolve identified issues	开始日期
programStageIdScheme	结束日期
End date for the time span of the values to export	created
Include only registrations which were created since the given timestamp

createdDuration

JSON 格式的有效载荷如下所示,其中attributes指元数据属性,groupSets指组织单位组集,dataItems指数据元素、指标、数据集和计划指标:

orgUnit

Organisation unit identifier, can be specified multiple times. Not applicable if orgUnitGroup is given.

orgUnitGroup

Organisation unit group identifier, can be specified multiple times. Not applicable if orgUnit is given.

yes

Whether to include the children in the hierarchy of the organisation units

yes

eventCreatedPeriod	检索和删除项目通知模板	Parameter name
Table: Query parameters	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	描述
E7228	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	必须是至少一个期间或开始日期和结束日期
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	/ api / 33 / system / taskSummaries / {task-category-id}
```bash
GET /api/33/completeDataSetRegistrations?dataSet=pBOMPrpg1QX
&startDate=2014-01-01&endDate=2014-01-31&orgUnit=YuQRtpLP10I
&orgUnit=vWbkYPRmKyS&children=true
```	您可以获得 xml 和 json 格式的响应。你可以指出
通过 Accept HTTP 标头,您更喜欢哪种响应格式
在上面的例子中。对于 xml,您使用 application/xml;对于 json 你
使用应用项目/json。	未完成的数据集 { #webapi_uncompleting_data_sets }
本节说明如何取消注册数据的完整性
放。要取消完成数据集,您将与
completeDataSetRegistrations 资源:	您可以获得 xml 和 json 格式的响应。你可以指出
通过 Accept HTTP 标头,您更喜欢哪种响应格式
在上面的例子中。对于 xml,您使用 application/xml;对于 json 你
使用应用项目/json。	此资源支持DELETE 取消注册。以下查询
支持参数:
Table: Complete data set registrations query parameters	查询参数	Values

描述

ds

是的

Data set identifier

聚乙烯

是的
期间标识符
欧
是的

Organisation unit identifier

No (must combine with cp)

false | true

eventCreatedPeriod	检索和删除项目通知模板	Parameter name
数	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	Whether registration applies to sub units
E7228	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	必须是至少一个期间或开始日期和结束日期
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	/ api / 33 / system / taskSummaries / {task-category-id}
可选类别组合	Program notification template	状态取决于数据是否被批准用于属性

获取批准状态 { #webapi_data_approval_get_status }

要获取数据集的批准信息,您可以发出GET请求:

/ api / dataApprovals?wf = rIUL3hYOjJc&pe = 201801&ou = YuQRtpLP10I

Table: Data approval query parameters

查询参数

需要	Parameter name
wf	是的
数据批准工作流标识符	聚乙烯
是的	期间标识符
欧	是的
对于与您可能需要的类别组合关联的数据集
获取单个属性选项组合的数据批准记录
从具有 GET 请求的以下资源:	冠捷
不	属性选项组合标识符
> 注意
>
> 为了向后兼容,在此和其他数据批准请求中,可能会为数据集提供参数`ds`而不是`wf`,如下所述。如果给出了数据集,则将使用与该数据集关联的工作流。	这将产生类似于以下的响应:
```json
{
"mayApprove": false,
"mayUnapprove": false,
"mayAccept": false,
"mayUnaccept": false,
"state": "APPROVED_HERE",
"approvedBy": "User A",
"approvedAt": "2022-01-13T12:56:07.005",
"acceptedBy": "User A",
"acceptedAt": "2022-01-13T12:56:07.005"
}
```	返回的参数是:
Table: Data approval returned parameters	返回参数

描述

mayApprove	Parameter name
mayUnapprove	Whether the current user may unapprove this data selection.
mayAccept	Whether the current user may accept this data selection.
mayUnaccept	Whether the current user may unaccept this data selection.
州	One of the data approval states from the table below.
approvedBy	If the selection is approved, and if present (not always needed), the user's name who made this approval.
approvedAt	If the selection is approved, and if present (not always needed), the date and time at which the highest level of approval was created.
acceptedBy	If the selection is approved, and if present (not always needed), the user's name who made the last update.
acceptedAt	If the selection is approved, and if present (not always needed), the date and time at which the highest level of approval was last updated.

Table: Data approval states

State 描述 UNAPPROVABLE
Data approval does not apply to this selection. (Data is neither approved nor unapproved.) UNAPPROVED_WAITING Data could be approved for this selection, but is waiting for some lower-level approval before it is ready to be approved. 未经批准_其他地方
Data is unapproved, and is waiting for approval somewhere else (not approvable here.) UNAPPROVED_READY Data is unapproved, and is ready to be approved for this selection. APPROVED_HERE

Data is approved, and was approved here (so could be unapproved here.)

APPROVED_ELSEWHERE

Data is approved, but was not approved here (so cannot be unapproved here.) This covers the following cases:
* Data is approved at a higher level.
* Data is approved for wider scope of category options.
* Data is approved for all sub-periods in selected period.
In the first two cases, there is a single data approval object that covers the selection. In the third case there is not.

ACCEPTED_HERE

Data is approved and accepted here (so could be unapproved here.)

ACCEPTED_ELSEWHERE

Data is approved and accepted, but elsewhere.

注意查询数据审批状态时,可以指定查询参数的任意组合。您指定的组合不需要描述数据被批准的地方审批级别。例如:

组织单位可能不在审批级别。这

/api/dataApprovals/approvals?wf=rIUL3hYOjJc&pe=201801,201802&ou=YuQRtpLP10I

参数 wf、pe、ou 和 aoc 与获取单个批准状态的参数相同,但您可以为每个参数提供一个以逗号分隔的一个或多个值的列表。

这将为您提供一个包含批准参数和状态列表的响应,如下所示:

[
  {
    "aoc": "HllvX50cXC0",
    "pe": "201801",
    "level": "KaTJLhGmU95",
    "ou": "YuQRtpLP10I",
    "permissions": {
      "mayApprove": false,
      "mayUnapprove": true,
      "mayAccept": true,
      "mayUnaccept": false,
      "mayReadData": true,
      "approvedBy": "User A",
      "approvedAt": "2022-01-13T12:56:07.005",
      "acceptedBy": "User A",
      "acceptedAt": "2022-01-13T12:56:07.005"      
    },
    "state": "APPROVED_HERE",
    "wf": "rIUL3hYOjJc"
  },
  {
    "aoc": "HllvX50cXC0",
    "pe": "201802",
    "ou": "YuQRtpLP10I",
    "permissions": {
      "mayApprove": true,
      "mayUnapprove": false,
      "mayAccept": false,
      "mayUnaccept": false,
      "mayReadData": true
    },
    "state": "UNAPPROVED_READY",
    "wf": "rIUL3hYOjJc"
  }
]

下表描述了返回的字段。

领域

描述

冠捷	检索和删除项目通知模板	Parameter name
数	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	Whether registration applies to sub units
E7228	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	必须是至少一个期间或开始日期和结束日期
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	/ api / 33 / system / taskSummaries / {task-category-id}
可选类别组合	Program notification template	状态取决于数据是否被批准用于属性

要接受已经批准的数据,您可以发出 POST 请求到 dataAcceptances 资源。要取消接受数据,您可以发出 DELETE 对 dataAcceptances 资源的请求。

POST DELETE /api/33/dataAcceptances 这些请求包含以下参数:
Table: Data approval action parameters Action parameter

需要

描述

是的

数据批准工作流标识符

聚乙烯

是的

期间标识符

欧

是的

Organisation unit identifier

冠捷

不

属性选项组合标识符

注意,与查询数据审批状态不同,必须指定

对应于可以选择的数据的参数得到正式认可的。特别是,以下两项都必须为真:

组织单位的级别必须由审批级别指定
在工作流程中。

介绍

工作流程。

批量批准数据 { #webapi_data_approval_bulk_approve_data }

您可以通过发布到批准大量数据记录 /api/dataApprovals/approvals 资源。

POST /api/33/dataApprovals/approvals

您可以通过发布到 /api/dataApprovals/unapprovals 资源。

POST /api/33/dataApprovals/unapprovals

您可以通过发布到 /api/dataAcceptances/acceptances 资源。

POST /api/33/dataAcceptances/acceptances

您可以通过发布到

/api/dataAcceptances/unacceptances 资源。

POST /api/33/dataAcceptances/unacceptances

批准有效负载受JSON支持,如下所示:

{
  "wf": [
    "pBOMPrpg1QX", "lyLU2wR22tC"
  ],
  "pe": [
    "201601", "201602"
  ],
  "approvals": [
    {
      "ou": "cDw53Ej8rju",
      "aoc": "ranftQIH5M9"
    }, 
    {
      "ou": "cDw53Ej8rju",
      "aoc": "fC3z1lcAW5x"
    }
  ]
}

Get data approval levels 要检索数据审批工作流及其数据审批级别,您可以发出类似这样的 GET 请求: /api/dataApprovalWorkflows? fields=id,name,periodType,dataApprovalLevels[id,name,level,orgUnitLevel]

Authorities for data approval

F_DATA_APPROVAL_WORKFLOW : allow user to Add/Update Data Approval Workflow

F_DATA_APPROVAL_LEVEL : allow user to Add/Update Data Approval Level 分享中

分享中

共享解决方案允许您共享系统中的大多数对象特定的用户组并定义对象是否应该公开可访问或私有。要获取和设置对象的共享状态,您可以与*共享*资源互动。 /api/33/sharing 获取共享状态 { #webapi_get_sharing_status } 要请求对象的共享状态,请使用GET请求执行以下操作: / api / 33 / sharing?type = dataElement&id = fbfJHSPpUQD 响应如下所示。

{
  "meta": {
    "allowPublicAccess": true,
    "allowExternalAccess": false
  },
  "object": {
    "id": "fbfJHSPpUQD",
    "name": "ANC 1st visit",
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}

设定分享状态 { #webapi_set_sharing_status } 您可以使用相同的 URL 定义对象的共享状态一个 POST 请求,其中 JSON 格式的有效负载如下所示:

{
  "object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}

在此示例中,有效负载定义了具有读写权限的对象

公共访问,无外部访问(无需登录),读写访问一个用户组和另一个用户组的只读访问权限。你可以使用 curl 将其提交到共享资源:

Data summary Prometheus metrics

Note
It is possible to create surprising sharing combinations. For instance, if externalAccess is set to true but publicAccess is set to --------, then users will have access to the object only when they are logged out.
New Sharing object
From 2.36 a new sharing property has been introduced in order to replace the old sharing properties userAccesses, userGroupAccesses, publicAccess, externalAccess in all metadata classes that have sharing enabled. This Sharing object is saved as a JSONB column in database. However, in order make it backward compatible the old sharing objects still work normally as before, for both import and export. In backend sharing data will be saved to new JSONb sharing column instead of the old *accesses tables.
The format looks like this:
```json { "name": "ANC 1^st visit", "publicAccess": "rw------", "externalAccess": false, "userGroupAccesses": [ { "access": "r-r-----", "userGroupUid": "Rg8wusV7QYi", "displayName": "HIV Program Coordinators", "id": "Rg8wusV7QYi" } ], "userAccesses": [], "user": { "displayName": "Tom Wakiki", "name": "Tom Wakiki", "id": "GOLswS44mh8", "username": "system" }, "sharing": { "owner": "GOLswS44mh8", "external": false, "users": {}, "userGroups": { "Rg8wusV7QYi": { "access": "r-r-----", "id": "Rg8wusV7QYi" } }, "public": "rw------" } }
```
### 使用新的 JSON 补丁应用项目设置共享状态{ #webapi_set_sharing_status_using_json_patch_api } 

- You can use [JSON Patch API](developer-manual.md#webapi_partial_updates) to update sharing for an object by sending a `PATCH` request to this endpoint with header `Content-Type: application/json-patch+json`
- ```
api/dataElements/fbfJHSPpUQD
```
Please note that this function only supports new sharing format. The payload in JSON format looks like this:

``json [ { "op": "replace", "path": "/sharing/users", "value": { "NOOF56dveaZ": { "access": "rw------", "id": "NOOF56dveaZ" }, "Kh68cDMwZsg": { "access": "rw------", "id": "Kh68cDMwZsg" } } } ] ### You can add users to `sharing` property of an object like this

- ```json
[
  {
    "op": "add",
    "path": "/sharing/users",
    "value": {
      "NOOF56dveaZ": {
        "access": "rw------",
        "id": "NOOF56dveaZ"
      },
      "Kh68cDMwZsg": {
        "access": "rw------",
        "id": "Kh68cDMwZsg"
      }
    }
  }
]
 You can add one user to

sharing` like this

```json

[ { "op": "add", "path": "/sharing/users/NOOF56dveaZ", "value": { "access": "rw------", "id": "NOOF56dveaZ" } } ]

| 类型 | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name |
| --- | --- | -- |
| 总览 | subjectTemplate | This function will not copy `METADATA_WRITE` access. The copied `UserAccess` and `UserGroupAccess` will **only** receive the `METADATA_READ` permission. 
| The bulk sharing API allow you to apply sharing settings to multiple metadata objects. This means the ability to add or remove many users and user groups to many objects in one API operation. | subjectTemplate | The current user must have `METADATA_READ` sharing permission to all target objects. If the user does not, error `E5001` is thrown.

The current user must have `METADATA_WRITE` sharing permission to update any target objects. If a target object should be updated and the user does not have this permission, error `E3001` is thrown.

Sample use case

### DashboardA is shared to userA with `METADATA_READ_WRITE` permission. 

- DashboardA has VisualizationA which has DataElementA.
- VisualizationA, DataElementA have `publicAccess` *disabled* and are *not shared* to userA.
- After executing cascade sharing for DashboardA, userA will have `METADATA_READ` access to VisualizationA and DataElementA.

## 应用项目接口端点 
- Send `POST` request to endpoint 
- ```
api/dashboards/cascadeSharing/{dashboardUID}

- 应用项目接口参数 - 名称 - 默认

描述

dryRun
假

If this is set to true, then cascade sharing function will proceed without updating any objects. The response will includes errors if any and all objects which will be updated. This helps user to know the result before actually executing the cascade sharing function. atomic

假

If this is set to true, then the cascade sharing function will stop and not updating any objects if there is an error. Otherwise, if this is false then the function will try to proceed with best effort mode.

<attribute id>

{
  "errorReports": [
    {
      "message": "No matching object for reference. Identifier was s46m5MS0hxu, and object was DataElement.",
      "mainKlass": "org.hisp.dhis.dataelement.DataElement",
      "errorCode": "E5001",
      "errorProperties": [
        "s46m5MS0hxu",
        "DataElement"
      ]
    }
  ],
  "countUpdatedDashBoardItems": 1,
  "updateObjects": {
    "dataElements": [
      {
        "id": "YtbsuPPo010",
        "name": "Measles doses given"
      },
      {
        "id": "l6byfWFUGaP",
        "name": "Yellow Fever doses given"
      }
    ]
  }
}

Response properties:

errorReports: includes all errors during cascade sharing process.

| 类型 | 仪表板资源将提供仪表板列表。请记住仪表板对象是共享的,因此列表将受当前已验证的用户。您可以检索有关一个的更多信息特定的仪表板,请点击其链接,类似于: | Parameter name | | ---- | ---- | -------------------- | | The bulk sharing API allow you to apply sharing settings to multiple metadata objects. This means the ability to add or remove many users and user groups to many objects in one API operation. | subjectTemplate | 应用项目接口需要尊重共享访问控制,即当前用户必须有权限编辑正在更新的对象的共享。 |

创建

Please note that those PATCH request must use header Content-type:application/json-patch+json
Using /api/{object-type}/sharing with PATCH request
This endpoint allows user to apply one set of Sharing settings for multiple metadata objects of one object-type.

元数据 CSV 导出{ #webapi_metadata_csv_export }

Example:

```

curl -X PATCH -d @payload.json -H "Content-Type: application/json-patch+json" "https://play.dhis2.org/dev/api/dataElements/sharing"

- Using `/api/metadata/sharing` with `PATCH` request
```json
{
  "dataSets":[
    "cYeuwXTCPkU",
    "aYeuwXTCPkU"
  ],
  "patch":[
    {
      "op":"add",
      "path":"/sharing/users/DXyJmlo9rge",
      "value":{
        "access":"rw------",
        "id":"DXyJmlo9rge"
      }
    },
    {
      "op":"remove",
      "path":"/sharing/users/N3PZBUlN8vq"
    }
  ]
}

This endpoint allows user to apply Sharing settings for multiple object-types in one payload.

{
  "dataElements": {
    "fbfJHSPpUQD": [
      {
        "op": "replace",
        "path": "/sharing/users",
        "value": {
          "NOOF56dveaZ": {
            "access": "rw------",
            "id": "CotVI2NX0rI"
          },
          "Kh68cDMwZsg": {
            "access": "rw------",
            "id": "DLjZWMsVsq2"
          }
        }
      }
    ]
  },
  "dataSets": {
    "cYeuwXTCPkA": [
      {
        "op": "remove",
        "path": "/sharing/users/N3PZBUlN8vq"
      }
    ],
    "cYeuwXTCPkU": [
      {
        "op": "add",
        "path": "/sharing/users/DXyJmlo9rge",
        "value": {
          "access": "rw------",
          "id": "DXyJmlo9rge"
        }
      }
    ]
  },
  "programs": {
    "GOLswS44mh8": [
      {
        "op": "add",
        "path": "/sharing/userGroups",
        "value": {
          "NOOF56dveaZ": {
            "access": "rw------",
            "id": "NOOF56dveaZ"
          },
          "Kh68cDMwZsg": {
            "access": "rw------",
            "id": "Kh68cDMwZsg"
          }
        }
      }
    ]
  }
}

例:

```

curl -X PATCH -d @payload.json -H "Content-Type: application/json-patch+json" "https://play.dhis2.org/dev/api/metadata/sharing"

Parameters

两个补丁应用项目端点的参数相同:

名称

默认

描述

## atomic
假

If this is set to true, then the batch function will stop and not updating any objects if there is an error <br> Otherwise, if this is false then the function will try to proceed with best effort mode.

| 指标组 | Parameter name | Potential duplicate status |
|---|---|---|
| displayColumnOrder | Response | 具有以下要求: |
| Payload formats | Payload for single object type using `/api/{object-type}/sharing` looks like this | Payload for multiple object types in one payload using `api/metadata/sharing` |
| 排程 { #webapi_scheduling } | Get available job types { #types } | 要获取所有可用作业类型的列表,可以使用以下端点: |
|     GET /api/jobConfigurations/jobTypes | 响应包含有关每个作业类型的信息,包括名称、作业类型、键、调度类型和可用参数。调度类型可以是 `CRON`,这意味着可以使用带有 `cronExpression` 字段的 cron 表达式来调度作业,或者是`FIXED_DELAY`,意味着可以使用 `delay` 字段将作业调度为以固定延迟运行.场延迟以秒为单位。 | 响应将类似于以下内容: |
|     /api/pushAnalysis/<id>/run | Job Configurations  | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 |



### Table: Main properties

Property

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| 串 | A number related to date of execution which resembles the end of the period to monitor | The cron expression which defines the interval for when the job should run. | String (Cron expression) |
| jobType   | 创建_并_更新&#124;创建&#124;更新&#124;删除            | String (Enum)   | jobParameters                       |

Job parameters, if applicable for job type.

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| empty | number of tracked entities processed as a unit  | false       | 类型 |
| 默认 | 描述  | `dataValuesPageSize`    | array of string |
| `[]` = all | 项目阶段 | flushMode   | Event analytics explain { #webapi_event_analytics_explain } |
| `REPORT` | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize`    | 名称 |

类型

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| empty | number of tracked entities processed as a unit | false | 类型 |
| 默认 | 描述 | `dataValuesPageSize`    | array of string |
| `false` | number of tracked entities processed as a unit           | 名称     | array of string |

`[]`

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| 默认 | number of tracked entities processed as a unit | `pageSize` | int |

empty

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| Skip generation of tables; Possible values: `DATA_VALUE`, `COMPLETENESS`, `COMPLETENESS_TARGET`, `ORG_UNIT_TARGET`, `EVENT`, `ENROLLMENT`, `VALIDATION_RESULT` | number of tracked entities processed as a unit | int | `0` |
| Hour of day for full update of analytics tables (0-23) | number of tracked entities processed as a unit | 名称 | 类型           |
| 默认 | number of tracked entities processed as a unit | `pageSize` | int  |

`10000`

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| Set `true` if job should send notifications based on validation rule groups | number of tracked entities processed as a unit | 名称 | 类型 |
| Set `true` if job should persist validation results | number of tracked entities processed as a unit | 名称 | int |
| `60` | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize` | int |
| `10000` | 项目阶段 | flushMode | 名称 |
| 类型 | 项目阶段 | flushMode | `relativeStart` |

int

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| `0` | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize` |  array of string |

`[]`

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| Set `true` if job should send notifications based on validation rule groups | number of tracked entities processed as a unit | 名称 | 类型 |
| Set `true` if job should persist validation results | number of tracked entities processed as a unit | 名称 | 类型 |
| 默认 | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize` | array of string                                                      |
| `[]` | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize` | 名称                                                |

类型

| 类型          | Potential duplicate status          | 仪表板资源将提供仪表板列表。请记住
仪表板对象是共享的,因此列表将受
当前已验证的用户。您可以检索有关一个的更多信息
特定的仪表板,请点击其链接,类似于: | Parameter name                                      |
|---------------|---------------|---------|--------------------------------------------------|
| `0`    | A number related to date of execution which resembles the end of the period to monitor | `dataValuesPageSize` | int |


### `0`

A number related to date of execution which resembles the start of the period to monitor

`predictors`

array of string

`[]`

Predictors (UIDs) to include in job

`predictorGroups`

array of string

`[]`

Predictor groups (UIDs) to include in job

Table: `MATERIALIZED_SQL_VIEW_UPDATE` job parameters

### 名称

类型

默认

描述

`sqlViews`

array of string

`[]`

### The UIDs of the SQL views that are updated by the job

Create a Job Configuration

要配置作业,您可以对以下资源发出POST请求:

    /api/jobConfigurations

### 不含JSON格式参数的作业如下所示:

```json
{
  "name": "",
  "jobType": "JOBTYPE",
  "cronExpression": "0 * * ? * *",
}

参数为JSON格式的分析表作业的示例:

{
  "name": "Analytics tables last two years",
  "jobType": "ANALYTICS_TABLE",
  "cronExpression": "0 * * ? * *",
  "jobParameters": {
    "lastYears": "2",
    "skipTableTypes": [],
    "skipResourceTables": false
  }
}

作为带有JSON格式参数的推送分析作业的示例:

{
   "name": "Push anlysis charts",
   "jobType": "PUSH_ANALYSIS",
   "cronExpression": "0 * * ? * *",
   "jobParameters": {
     "pushAnalysis": [
       "jtcMAKhWwnc"
     ]
    }
 }

An example of a job with scheduling type FIXED_DELAY and 120 seconds delay:

```json

{ "name": "Continuous analytics table", "jobType": "CONTINUOUS_ANALYTICS_TABLE", "delay": "120", "jobParameters": { "fullUpdateHourOfDay": 4 } }

Get Job Configurations

列出所有作业配置:

    GET /api/jobConfigurations

检索作业:

    GET /api/jobConfigurations/{id}

响应有效负载如下所示:

```json
{
  "lastUpdated": "2018-02-22T15:15:34.067",
  "id": "KBcP6Qw37gT",
  "href": "http://localhost:8080/api/jobConfigurations/KBcP6Qw37gT",
  "created": "2018-02-22T15:15:34.067",
  "name": "analytics last two years",
  "jobStatus": "SCHEDULED",
  "displayName": "analytics last two years",
  "enabled": true,
  "externalAccess": false,
  "jobType": "ANALYTICS_TABLE",
  "nextExecutionTime": "2018-02-26T03:00:00.000",
  "cronExpression": "0 0 3 ? * MON",
  "jobParameters": {
    "lastYears": 2,
    "skipTableTypes": [],
    "skipResourceTables": false
  },
  "favorite": false,
  "configurable": true,
  "access": {
    "read": true,
    "update": true,
    "externalize": true,
    "delete": true,
    "write": true,
    "manage": true
  },
  "lastUpdatedBy": {
    "id": "GOLswS44mh8"
  },
  "favorites": [],
  "translations": [],
  "userGroupAccesses": [],
  "attributeValues": [],
  "userAccesses": []
}

Update a Job Configuration
使用以下端点和JSON有效负载格式,通过参数更新作业:
PUT /api/jobConfigurations/{id}

```json { "name": "analytics last two years", "enabled": true, "cronExpression": "0 0 3 ? * MON", "jobType": "ANALYTICS_TABLE", "jobParameters": { "lastYears": "3", "skipTableTypes": [], "skipResourceTables": false } }

* Delete a Job Configuration
* 使用以下方法删除作业:

    DELETE /api/jobConfigurations/{id}

请注意,某些具有自定义配置参数的作业可能不会被添加,如果
未配置所需的系统设置。一个例子是数据
同步,这需要远程服务器配置。

Run Jobs Manually { #execute }

Jobs can be run manually using:

    POST /api/jobConfigurations/{id}/execute

Searching for jobs with execution errors


## Since version 2.41 jobs can store errors of the job run to allow inspection
at a later point in time. 
> **Note** This feature is only accessible for administrator
> with the `F_JOB_LOG_READ` authority and superusers.

### To view the errors associated with a specific job use:
    GET /api/jobConfigurations/{id}/errors

To search for jobs that match user specified search criteria use:

    GET /api/jobConfigurations/errors

with one or more of the following search parameters

`user`: include jobs ran by this user

`from`: include jobs that started after this point in time

`to`: include jobs that did not start later than this point in time

`code`: include jobs that have errors with one of the given error codes

`object`: include jobs that have errors linked to one of the given object IDs

`type`: include job with errors of the specified type(s)

When multiple criteria are used all have to be met (AND logic).
If multiple `code`, `object` or `type` parameters are given just one has to match (OR logic).
* For example, to find tracker import errors for the 1. of January 2024 with error code `E1002` 
(tracked entity already exists) the following search is made:
*     GET /api/jobConfigurations/errors?type=TRACKER_IMPORT_JOB&code=E1002&from=2024-01-01&to=2024-01-02
* The results show the job run error details. By default, the `input` (the payload of the impport) 
is excluded from the results. To include it add `includeInput=true`:
*     GET /api/jobConfigurations/errors?includeInput=true

### > **Note**
> Not all job types do store their errors. Currently, this feature is mostly
> supported by import jobs.
调度项目接口

而 `/api/jobConfigurations` 则以作业配置对象为中心
API 反映调度项目的状态,而 `/api/scheduler` API 则提供作业进度跟踪信息。 
和 `/api/scheduling` API 提供作业进度跟踪信息。  

Observe Running Jobs { #running}

The execution steps and state can be observed while the job is running.
A list of all types of jobs that are currently running is provided by:

    GET /api/scheduling/running/types

To get an overview of all running jobs by job type use:

###     GET /api/scheduling/running
As there only can be one job running for each type at a time the status of a
running job can be viewed in details using:

    GET /api/scheduling/running/{type}

For example, to see status of a running `ANALYTICS_TABLE` job use

    GET /api/scheduling/running/ANALYTICS_TABLE

A job is a sequence of processes. Each process has a sequence of `stages`.
Within each stage there might be zero, one or many `items`. Items could be
processed strictly sequential or parallel, n items at a time. Often the
number of `totalItems` is known up-front.

In general the stages in a process and the items in a stage are "discovered"
as a "side effect" of processing the data. While most processes have a fixed
sequence of stages some processed might have varying stages depending on the
data processed. Items are usually data dependent. Most jobs just include a
single process.

`code`: include jobs that have errors with one of the given error codes

`RUNNING`: is currently processed (not yet finished)

### `SUCCESS`: when completed successful
`ERROR`: when completed with errors or when an exception has occurred

`CANCELLED`: when cancellation was requested and the item will not complete

See Completed Job Runs { #completed }

## Once a job has completed successful or with a failure as a consequence of an
exception or cancellation the status moves from the set of running states to
the completed job states. This set keeps only the most recent execution
state for each job type. The overview is available at:
    GET /api/scheduling/completed

### Details on a particular job type are accordingly provided at:
    GET /api/scheduling/completed/{type}

In case of the `ANALYTICS_TABLE` job this would be:

    GET /api/scheduling/completed/ANALYTICS_TABLE
Request Cancelling a Running Jobs { #cancel }

### Once a job is started it works through a sequence of steps. Each step might
in turn have collections of items that are processed. While jobs usually
cannot be stopped at any point in time we can request cancellation and the
process gives up cooperatively once it has completed an item or step and
recognises that a cancellation was requested. This means jobs do not stop
immediately and leave at an unknown point right in the middle of some
processing. Instead, they give up when there is an opportunity to skip to
the end. This still means that the overall process is unfinished and is not
rolled back. It might just have done a number of steps and skipped others at
the end.
To cancel a running job use:

    POST /api/scheduling/cancel/{type}

For example, to cancel the `ANALYTICS_TABLE` job run:

    POST /api/scheduling/cancel/ANALYTICS_TABLE

### Depending on the current step and item performed this can take from
milliseconds to minutes before the cancellation becomes effective.
However, the status of the overall process will be shown as `CANCELLED`
immediately when check using
    GET /api/scheduling/running/ANALYTICS_TABLE

Only jobs that have been split into processes, stages and items can be
cancelled effectively. Not all jobs have been split yet. These will run till
completion even if cancellation has been requested.

Reset a Job stuck in RUNNING state

When a server shuts down while a job is in `RUNNING` state the job 
needs to be reverted back to its initial state manually.
To revert a job that has `RUNNING` state but is not running use:

    POST /api/jobConfigurations/{uid}/revert

### Job Queues { #queues }
Sequences of jobs (configurations) can be created using job queues.
The queue always uses a unique name and a CRON expression trigger. 
Once a queue is started it runs all jobs in the queue in the given sequence.
The second in sequence starts when the first is finished and so forth.

List Names of Job Queues { #queues-list } 

To list the unique names of existing queues use:

    GET /api/scheduler/queues

### The response is a array of the names:
```json
["queue_a", "queue_b"]

Get A Job Queue { #queues-info }

To get all details of a specific queue use:

GET /api/scheduler/queues/{name}

The details include its name, CRON expression and job sequence:

{
  "name": "myQ",
  "cronExpression": "0 0 1 ? * *",
  "sequence": ["FgAxa6eRSzQ", "BeclVERfWbg" ]
}

Create a new Job Queue { #queues-add }

To create a new queue send a POST request with a payload object having name, CRON expression and the job sequence:

POST /api/scheduler/queues/{name}

To create a queue with name myQ use a POST to /api/scheduler/queues/myQ:

{
  "cronExpression": "0 0 1 ? * *",
  "sequence": ["FgAxa6eRSzQ", "BeclVERfWbg" ]
}

A name can be present in the payload as well but name specified in the URL path takes precedence.

NOTE

The cron expression of all job configurations but the first in a queue is cleared as they do not have a trigger on their own any longer. It needs to be restored manually once a job is removed from a queue.

Update a Job Queue

To update an existing queue CRON expression or sequence use a PUT request

PUT /api/scheduler/queues/{name}

The payload has to state both new CRON expression and job sequence like in the example above to create a new queue.

To rename a queue the new name can be stated in the payload, while the old name is used in the URL path.

Delete a Job Queue { #queues-delete }

To delete a job queue send a DELETE request to its resource URL:

DELETE /api/scheduler/queues/{name}

> NOTE

Deleting a queue does not delete any referenced job configurations. Any job configuration that is removed from a queue either by changing the sequence or deleting the queue is disabled. To use it individually supply a CRON expression and enable the configuration again.

Job Scheduler { #scheduler }

调度项目中的计划是一个基于作业配置和作业队列的列表。和作业队列的列表。计划表中的条目要么是一个简单的作业配置,要么是一个作业队列、或作业队列。两者使用相同的条目格式表示。

要获取调度项目列表,请使用

GET /api/scheduler

A job configuration in this list looks like this:

  {
    "name": "User account expiry alert",
    "type": "ACCOUNT_EXPIRY_ALERT",
    "cronExpression": "0 0 2 ? * *",
    "nextExecutionTime": "2023-03-15T02:00:00.000",
    "status": "SCHEDULED",
    "enabled": true,
    "configurable": false,
    "sequence": [
      {
        "id": "fUWM1At1TUx",
        "name": "User account expiry alert",
        "type": "ACCOUNT_EXPIRY_ALERT",
        "cronExpression": "0 0 2 ? * *",
        "nextExecutionTime": "2023-03-15T02:00:00.000",
        "status": "SCHEDULED"
      }
    ]
  }

Most notably the sequence has only a single item. Information on top level object and the object in the sequence both originate from the job configuration.

A job queue in the list looks like this:

  {
    "name": "myQ",
    "type": "Sequence",
    "cronExpression": "0 0 1 ? * *",
    "nextExecutionTime": "2023-03-15T01:00:00.000",
    "status": "SCHEDULED",
    "enabled": true,
    "configurable": true,
    "sequence": [
      {
        "id": "FgAxa6eRSzQ",
        "name": "test Q1",
        "type": "ANALYTICS_TABLE",
        "cronExpression": "0 0 1 ? * *",
        "nextExecutionTime": "2023-03-15T01:00:00.000",
        "status": "SCHEDULED"
      },
      {
        "id": "BeclVERfWbg",
        "name": "est Q2",
        "type": "DATA_INTEGRITY",
        "status": "SCHEDULED"
      }
    ]
  }

The top level object originates from the queue and aggregate information. The objects within the sequence originate from the job configurations that are part of the sequence.

List Jobs Entries addable to a Job Queue

Not all jon configurations can be added to a queue.

System jobs and jobs that are already part of a queue cannot be used in another queue. To list job configurations that can be part of any queue use:

GET /api/scheduler/queueable

To list job configurations that can be part of a particular queue use:

GET /api/scheduler/queueable?name={queue}

This will also exclude all jobs that are already part the named queue.

同步化 { #webapi_synchronization }

默认值	Validation rule	Parameter name
Table: Query parameters	元数据拉取 { #webapi_sync_metadata_pull }	要从远程 JSON 文档中启动元数据拉取,您可以创建一个
使用 url 作为请求负载的 POST 请求到以下资源:
Any delete operation will require the authority Perform maintenance tasks.	> Note
>
> The supplied URL will be checked against the config property `metadata.sync.remote_servers_allowed` in the `dhis.conf` file.
> If the base URL is not one of the configured servers allowed then the operation will not be allowed. See failure example below.
> Some examples where the config set is `metadata.sync.remote_servers_allowed=https://server1.org/,https://server2.org/`
> - supply `https://server1.org/path/to/resource` -> this will be accepted
> - supply `https://server2.org/resource/path` -> this will be accepted
> - supply `https://oldserver.org/resource/path` -> this will be rejected
>
Sample failure response	```json
{
"httpStatus": "Conflict",
"httpStatusCode": 409,
"status": "ERROR",
"message": "Provided URL is not in the remote servers allowed list",
"errorCode": "E1004"
}
```
E7228	To retrieve information about a form (which corresponds to a data set
and its sections) you can interact with the `form` resource. The form
response is accessible as XML and JSON and will provide information
about each section (group) in the form as well as each field in the
sections, including labels and identifiers. By supplying period and
organisation unit identifiers the form response will be populated with
data values.	/ api / 33 /同步/可用性
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
["www.google.com", "www.dhis2.org", "www.who.int"]
```	DHIS2 will audit updates and deletions of aggregate data values, tracked entity data values, tracked entity attribute values and data approval records. This section explains how to retrieve audit records for the mentioned entities. Note that several of the query parameters can be repeated any number of times.
数	The endpoint for aggregate data value audits is located at:	```
/api/audits/dataValue
```
Table: Aggregate data value query parameters	假	选项
true	ds	Tracked Entity UIDS
定义要返回的页码。	Parameter	Data approval workflow ID
定义每页返回的元素数量。	Parameter	Organisation unit ID

欧

Organisation unit ID

One or more org unit identifiers

auditType

UPDATE | DELETE

Filter by one or more audit types

skipPaging

false | true

默认值	Validation rule	Parameter name
Absolute end date. Applicable only when `type` is ABSOLUTE	Enable or disable paging	page
> Note
>
> The `repetition` attribute (in `rows`, `columns` or `filters`) indicates the events indexes to be retrieved. Taking the example above (in the previous `json` payload), it can be read as follows:
>
1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default)	Sharing of data store keys follows the same principle as for other metadata sharing (see
Sharing).	pageSize
数	Page size (default 50)	```
/api/audits/dataValue
```
dueDate	The endpoint for data approval audits is located at:	/api/33/audits/trackedEntity.json?trackedEntities=wNiQ2coVZ39
lastUpdatedDate	Once auditing is enabled for tracked entities (by setting `allowAuditLog` of tracked entity types to `true`), all read and search operations are logged. The endpoint for accessing audit logs is located at:	```
/api/audits/trackedEntityInstance
```
Table: Aggregate data value query parameters	假	选项
true	ds	Tracked Entity UIDS
定义要返回的页码。	Parameter	One or more user identifiers
定义每页返回的元素数量。	Parameter	Filter by one or more audit types

开始日期

Start date

Start date for audits in yyyy-mm-dd format

结束日期

End date

End date for audits in yyyy-mm-dd format

skipPaging

false | true

默认值	Validation rule	Parameter name
Absolute end date. Applicable only when `type` is ABSOLUTE	Enable or disable paging	page
> Note
>
> The `repetition` attribute (in `rows`, `columns` or `filters`) indicates the events indexes to be retrieved. Taking the example above (in the previous `json` payload), it can be read as follows:
>
1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default)	Sharing of data store keys follows the same principle as for other metadata sharing (see
Sharing).	pageSize
数	Page size (default 50)	```
/api/audits/dataValue
```
dueDate	The endpoint for data approval audits is located at:	/api/33/audits/trackedEntity.json?trackedEntities=wNiQ2coVZ39
lastUpdatedDate	Once auditing is enabled for tracked entities (by setting `allowAuditLog` of tracked entity types to `true`), all read and search operations are logged. The endpoint for accessing audit logs is located at:	```
/api/audits/trackedEntityInstance
```
Table: Aggregate data value query parameters	假	选项
true	ds	Tracked Entity UIDS
定义要返回的页码。	Parameter	One or more user identifiers
定义每页返回的元素数量。	Parameter	Filter by one or more audit types

开始日期

Start date

Start date for audits in yyyy-mm-dd format

结束日期

End date

End date for audits in yyyy-mm-dd format

skipPaging

false | true

默认值	Validation rule	Parameter name
真正	Whether to enable or disable paging	page
数	Page number (default 1)	pageSize
Filter on whether the current user can manage the returned users through the managed user group relationships.	```json
["www.google.com", "www.dhis2.org", "www.who.int"]
```	Example: Get audits of audit type `READ` with `startDate` 2018-03-01 and `endDate` 2018-04-24 with a page size of 5:
可选类别组合	Example: Get audits for tracked entity `wNiQ2coVZ39`:	/api/33/audits/trackedEntityInstance.json?trackedEntities=wNiQ2coVZ39
dueDate	The endpoint for data approval audits is located at:	```
/api/audits/dataApproval
```
lastUpdatedDate	Once auditing is enabled for tracked entities (by setting `allowAuditLog` of tracked entity types to `true`), all read and search operations are logged. The endpoint for accessing audit logs is located at:	选项
Table: Aggregate data value query parameters	假	选项
定义要返回的页码。	Parameter	Data approval workflow ID
定义每页返回的元素数量。	Parameter	Organisation unit ID

One or more organisation unit identifiers

冠捷

Attribute option combo ID

One or more attribute option combination identifiers

开始日期

Start date

Start date for approvals in yyyy-mm-dd format

结束日期

End date

End date for approvals in `yyyy-mm-dd` format

skipPaging

false | true

Turn paging on / off

page

数

Page number (default 1)

pageSize

数

Page size (default 50)

Example: Get audits for data approval workflow i5m0JPw4DQi:

/api/33/audits/dataApproval?wf=i5m0JPw4DQi

Exaple: Get audits between 2021-01-01 and 2022-01-01 for org unit DiszpKrYNg8:

/api/33/audits/dataApproval?ou=DiszpKrYNg8&startDate=2021-01-01&endDate=2022-01-01

讯息传递

讯息对话 { #webapi_message_conversations }

DHIS2 具有发送消息的机制,例如用户反馈、通知和给用户的一般信息。留言被分组到对话中。与消息对话交互您可以向 messageConversations 发送 POST 和 GET 请求资源。

/ api / 33 / messageConversations

消息会传送到 DHIS2 消息收件箱,但也可以发送以短信形式发送到用户的电子邮件地址和手机。在这个例子中, 我们将看到如何利用 Web API 来发送、读取和管理消息。我们将伪装成*DHIS2管理员*用户并发送给*移动*用户的消息。然后我们会假装是手机用户并阅读我们的新消息。在此之后,我们将管理管理员用户收件箱通过标记和删除邮件。

撰写和阅读邮件 { #webapi_writing_messages }

我们在发送和阅读消息时需要交互的资源是 messageConversations 资源。我们首先访问 Web API 在 http://play.dhis2.org/demo/api 的入口点我们找到并跟随 messageConversations 资源的链接位于 http://play.dhis2.org/demo/api/messageConversations 。说明告诉我们可以使用 POST 请求来创建新消息发送给多个用户的以下 XML 格式:

<message xmlns="http://dhis2.org/schema/dxf/2.0">
  <subject>This is the subject</subject>
  <text>This is the text</text>
  <users>
    <user id="user1ID" />
    <user id="user2ID" />
    <user id="user3ID" />
  </users>
</message>

为了发送给一个或多个用户组中的所有用户,我们可以用:

<message xmlns="http://dhis2.org/schema/dxf/2.0">
  <subject>This is the subject</subject>
  <text>This is the text</text>
  <userGroups>
    <userGroup id="userGroup1ID" />
    <userGroup id="userGroup2ID" />
    <userGroup id="userGroup3ID" />
  </userGroups>
</message>

为了发送给连接到一个或多个组织单位的所有用户,我们可以使用:

```xml

This is the subject This is the text

Since we want to send a message to our friend the mobile user we need to
look up her identifier. We do so by going to the Web API entry point and
follow the link to the *users* resource at `/api/users`. We continue by 
following link to the mobile user at `/api/users/PhzytPW3g2J` where we learn
that her identifier is *PhzytPW3g2J*. We are now ready to put our XML
message together to form a message where we want to ask the mobile user
whether she has reported data for January 2014:

```xml
<message xmlns="http://dhis2.org/schema/dxf/2.0">
  <subject>Mortality data reporting</subject>
  <text>Have you reported data for the Mortality data set for January 2014?</text>
  <users>
    <user id="PhzytPW3g2J" />
  </users>
</message>

为了测试这一点,我们将 XML 内容保存到一个名为 message.xml 的文件中。我们使用 cURL 将消息发送到 DHIS2 演示实例指示内容类型是 XML 并以 admin 身份进行身份验证用户:

curl -d @message.xml "https://play.dhis2.org/demo/api/messageConversations"
  -H "Content-Type:application/xml" -u admin:district -X POST

JSON和POST命令中的相应有效负载如下所示:

{
  "subject": "Hey",
  "text": "How are you?",
  "users": [
    {
      "id": "OYLGMiazHtW"
    },
    {
      "id": "N3PZBUlN8vq"
    }
  ],
  "userGroups": [
    {
      "id": "ZoHNWQajIoe"
    }
  ],
  "organisationUnits": [
    {
      "id": "DiszpKrYNg8"
    }
  ]
}

curl -d @message.json "https://play.dhis2.org/demo/api/33/messageConversations"
  -H "Content-Type:application/json" -u admin:district -X POST

如果一切顺利,我们会收到一个 201 Created HTTP 状态代码。另外,请注意我们收到一个 Location HTTP 标头,该标头的值通知我们新创建的消息对话资源的 URL - 这可以是消费者使用它来执行进一步的操作。

我们现在将假装是移动用户并阅读消息刚刚通过向 messageConversations 发送 GET 请求发送资源。我们提供一个带有 application/xml 的 Accept 标头作为表示我们对 XML 资源感兴趣的值表示,我们以*移动*用户身份进行身份验证:

curl "https://play.dhis2.org/demo/api/33/messageConversations"
  -H "Accept:application/xml" -u mobile:district

作为响应,我们得到以下XML:

<messageConversations xmlns="http://dhis2.org/schema/dxf/2.0"
  link="https://play.dhis2.org/demo/api/messageConversations">
  <messageConversation name="Mortality data reporting" id="ZjHHSjyyeJ2"
    link="https://play.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"/>
  <messageConversation name="DHIS2 version 2.7 is deployed" id="GDBqVfkmnp2"
    link="https://play.dhis2.org/demo/api/messageConversations/GDBqVfkmnp2"/>
</messageConversations>

从响应中,我们能够读取新发送的标识符消息是 ZjHHSjyyeJ2。注意具体链接资源已嵌入,可以关注以阅读完整内容信息。一旦我们知道,我们可以直接回复现有的消息对话通过包含消息文本作为请求负载来获取 URL。我们现在可以构造一个 URL 来发送我们的回复:

curl -d "Yes the Mortality data set has been reported"
  "https://play.dhis2.org/demo/api/messageConversations/ZjHHSjyyeJ2"
  -H "Content-Type:text/plain" -u mobile:district -X POST

如果一切按计划进行,您将收到 200 OK 状态代码。

在2.30中,我们添加了URL搜索参数:

queryString =?&queryOperator =?

过滤器在主题、文本和发件人中搜索消息的匹配项对话。默认查询运算符是 token,但是其他运算符可以在查询中定义。

管理讯息 { #webapi_managing_messages }

随着用户接收和发送消息,对话将开始堆积在他们的收件箱中,最终变得难以跟踪。我们现在将看看通过删除和标记来管理用户的消息收件箱通过 Web-API 进行对话。我们将通过执行一些在“DHIS 管理员”用户的收件箱中维护。

首先,让我们看看从收件箱中删除一些邮件。是一定要注意这里描述的所有删除操作只删除用户和消息对话之间的关系。实际上这意味着我们不会删除消息本身(或任何内容),但只是从用户使其不再列在 /api/messageConversations 资源。

To remove a message conversation from a users inbox we need to issue a DELETE request to the resource identified by the id of the message conversation and the participating user. For example, to remove the user with id xE7jOejl9FI from the conversation with id jMe43trzrdi:

curl "https://play.dhis2.org/demo/api/33/messageConversations/jMe43trzrdi

如果请求成功,服务器将回复 200 OK。这

响应正文包含一个 XML 或 JSON 对象(根据接受请求的标头)包含已删除用户的 ID。

{
  "removed" : ["xE7jOejl9FI"]
}

失败时,返回的对象将包含一个消息有效负载描述错误。

{
  "message" : "No user with uid: dMV6G0tPAEa"
}

细心的读者已经注意到对象返回了在我们的例子中,成功实际上是一个 id 列表(包含一个入口)。这是因为端点也支持批量删除。这对相同的 messageConversations 资源发出请求,但遵循语义略有不同。对于批处理操作,会话 ID 作为查询字符串参数给出。以下示例删除了两个当前用户的单独消息对话:

curl "https://play.dhis2.org/demo/api/messageConversations?mc=WzMRrCosqc0&mc=lxCjiigqrJm"
  -X DELETE -u admin:district

如果您有足够的权限,可以删除对话通过提供可选的用户 ID 参数代表另一个用户。

curl "https://play.dhis2.org/demo/api/messageConversations?mc=WzMRrCosqc0&mc=lxCjiigqrJm&user=PhzytPW3g2J"
  -X DELETE -u admin:district

如上所述,批量删除将返回与单一操作。删除的对象列表将反映成功执行的移除。部分错误的请求(即不存在的 ID) 因此不会取消整个批处理操作。

消息带有布尔 read 属性。这允许跟踪是否用户是否看到(打开)了一条消息。在典型应用中场景(例如 DHIS2 网络门户),消息将被标记为已读用户第一次打开它。然而,用户可能想要管理他们的消息的已读或未读状态,以保持跟踪某些对话。

标记消息已读或未读遵循与批处理类似的语义移除,并且还支持批量操作。将消息标记为已读我们向 messageConversations/read 资源发出一个 POST 包含一个或多个消息 ID 的请求正文。将消息标记为未读我们向 messageConversations/unread 发出相同的请求资源。与删除的情况一样,可选的 user 请求参数可以给。

让我们将几条消息标记为当前用户已读:

curl "https://play.dhis2.org/dev/api/messageConversations/read"
  -d '["ZrKML5WiyFm","Gc03smoTm6q"]' -X POST
  -H "Content-Type: application/json" -u admin:district

响应是带有以下 JSON 正文的 200 OK:

{
  "markedRead": ["ZrKML5WiyFm", "Gc03smoTm6q"]
}

您可以将收件人添加到现有的消息对话中。该资源位于:

/ api / 33 / messageConversations / id /收件人

此资源的选项是用户、用户组和组织单位。请求应如下所示:

{
  "users": [
    {
      "id": "OYLGMiazHtW"
    },
    {
      "id": "N3PZBUlN8vq"
    }
  ],
  "userGroups": [
    {
      "id": "DiszpKrYNg8"
    }
  ],
  "organisationUnits": [
    {
      "id": "DiszpKrYNg8"
    }
  ]
}

邮件附件 { #webapi_message_attachments }

创建带附件的消息分两步完成:上传文件添加到 attachments 资源,然后包括一个或几个创建新邮件时的附件 ID。

| Additionally, the following endpoint will return the import summary of the import job. This import summary will only be available after the import has completed: | curl -F file=@attachment.png“ https://play.dhis2.org/demo/api/messageConversations/attachments” -u管理员:区 | |---|---| | 该请求返回一个表示附件的对象。的标识创建消息时必须使用此对象以链接邮件附件。 | json { "created": "2018-07-20T16:54:18.210", "lastUpdated": "2018-07-20T16:54:18.212", "externalAccess": false, "publicAccess": "--------", "user": { "name": "John Traore", "created": "2013-04-18T17:15:08.407", "lastUpdated": "2018-03-09T23:06:54.512", "externalAccess": false, "displayName": "John Traore", "favorite": false, "id": "xE7jOejl9FI" }, "lastUpdatedBy": { "id": "xE7jOejl9FI", "name": "John Traore" }, "favorite": false, "id": "fTpI4GOmujz" } | | 创建新消息时,可以在请求正文中传递 id 将上传的文件链接到正在创建的消息。 | json { "subject": "Hey", "text": "How are you?", "users": [ { "id": "OYLGMiazHtW" }, { "id": "N3PZBUlN8vq" } ], "userGroups": [ { "id": "ZoHNWQajIoe" } ], "organisationUnits": [ { "id": "DiszpKrYNg8" } ], "attachments": [ "fTpI4GOmujz", "h2ZsOxMFMfq" ] } | | 回复消息时,可以将 id 作为请求传递范围。 | bash curl -d "Yes the Mortality data set has been reported" "https://play.dhis2.org/demo/api/33/messageConversations/ZjHHSjyyeJ2?attachments=fTpI4GOmujz,h2ZsOxMFMfq" -H "Content-Type:text/plain" -u mobile:district -X POST | | 创建带有附件的邮件后,附加文件可以通过对以下 URL 的 GET 请求访问: ||

/ api / messageConversations / <mcv-id> / <msg-id> / attachments / <attachment-id>

其中是*消息对话* ID, 是包含附件和的 message 是特定*消息附件*的 ID。

票证和验证结果通知

您可以使用“写反馈”工具来创建工单和消息。

一张票和一条消息的唯一区别是你可以给票证的状态和优先级。设置状态:

POST / api / messageConversations / <uid> / status

设置优先级:

POST / api / messageConversations / / priority

在 2.29 中,验证分析生成的消息现在也用于状态和优先级属性。默认情况下,消息由验证分析将继承验证规则的优先级问题,或者如果消息包含多个最重要的规则。

在 2.30 中,可以将验证规则分配给任何用户,同时工单仍然需要分配给系统反馈接收者中的一个用户团体。

Table: A list of valid status and priority values

状态

Priority

OPEN

LOW

PENDING

MEDIUM

INVALID

HIGH

SOLVED

也可以给工单添加内部消息,只能看到拥有“管理票证”权限的用户。创建一个内部回复,包括“内部”参数,并将其设置为

curl -d "This is an internal message"
  "https://play.dhis2.org/demo/api/33/messageConversations/ZjHHSjyyeJ2?internal=true"
  -H "Content-Type:text/plain" -u admin:district -X POST

可视化
仪表板 { #webapi_dashboard }
仪表板旨在为您提供多个分析的概览地图、图表、数据透视表和报告等项目,它们一起可以提供您数据的全面概览。仪表板可用通过 dashboards 资源在 Web API 中。仪表板包含一个仪表板*项目*列表。一个项目可以代表一个单一的资源,比如图表、地图或报告表,或表示指向分析的链接列表资源,如报告、资源、表格报告和用户。一种仪表板项目最多可以包含八个链接。通常,仪表板客户可以选择直接在一个用户界面,同时将多对象项目渲染为可点击链接。

/ api /仪表板

| eventCreatedPeriod | Parameter name | Potential duplicate status | 仪表板资源将提供仪表板列表。请记住仪表板对象是共享的,因此列表将受当前已验证的用户。您可以检索有关一个的更多信息特定的仪表板,请点击其链接,类似于: | |---|---|---|---| | /api/dashboards/vQFhmLJU5sK.json | 仪表板包含名称和创建日期等信息以及仪表板项目数组。 JSON 格式的响应看起来类似对此回复(某些信息已被删除,以便简洁)。 | 搜索仪表板 { #webapi_searching_dasboards } | 6 | | 通过指定特定字段可以获得更定制的响应在请求中。下面提供了一个示例,它将返回更多有关用户仪表板上每个对象的详细信息。 | / api / dashboards / vQFhmLJU5sK /?fields =:all,dashboardItems [:all] | 搜索仪表板 { #webapi_searching_dasboards } | 25 | | 最小-最大数据元素 { #webapi_min_max_data_elements } | /api/dashboards/q/my-query.json /api/dashboards/search?q=my-query | 例如,此查询: | Relationship Type {0} constraint requires a {1} but a {2} was found. |

将搜索以下内容:

分析对象名称包含字符串“ ma”

每种类型最多返回6

For REPORT and MAP types, return up to 20 items

Table: dashboards/q and dashboards/search query parameters

查询参数

描述

类型

默认

计数

The number of items of each type to return

Positive integer

String [MAP|USER|REPORT|RESOURCE|VISUALIZATION#124;EVENT_VISUALIZATION,EVENT_CHART,EVENT_REPORT]

The number of items of max types to return

Positive integer

最大

The type to return the maxCount for

String [MAP|USER|REPORT|RESOURCE|VISUALIZATION#124;EVENT_VISUALIZATION,EVENT_CHART,EVENT_REPORT]

不适用

支持 JSON 和 XML 响应格式。 JSON 格式的响应

将包含对匹配资源的引用和数量总共找到匹配项,并为每种类型的资源找到匹配项。它会看起来类似于:

{
  "visualizations": [{
    "name": "ANC: ANC 3 Visits Cumulative Numbers",
    "id": "arf9OiyV7df",
    "type": "LINE"
  }, {
    "name": "ANC: 1st and 2rd trends Monthly",
    "id": "jkf6OiyV7el",
    "type": "PIVOT_TABLE"
  }],
  "eventVisualizations": [{
    "name": "Inpatient: Cases 5 to 15 years this year (case)",
    "id": "TIuOzZ0ID0V",
    "type": "LINE_LIST"
  }, {
    "name": "Inpatient: Cases last quarter (case)",
    "id": "R4wAb2yMLik",
    "type": "LINE_LIST"
  }],
  "maps": [{
    "name": "ANC: 1st visit at facility (fixed) 2013",
    "id": "YOEGBvxjAY0"
  }, {
    "name": "ANC: 3rd visit coverage 2014 by district",
    "id": "ytkZY3ChM6J"
  }],
  "reports": [{
    "name": "ANC: 1st Visit Cumulative Chart",
    "id": "Kvg1AhYHM8Q"
  }, {
    "name": "ANC: Coverages This Year",
    "id": "qYVNH1wkZR0"
  }],
  "searchCount": 8,
  "visualizationCount": 2,
  "eventVisualizationCount": 2,
  "mapCount": 2,
  "reportCount": 2,
  "userCount": 0,
  "eventReports": 0,
  "eventCharts" :0,
  "resourceCount": 0
}

String [MAP|USER|REPORT|RESOURCE|VISUALIZATION#124;EVENT_VISUALIZATION,EVENT_CHART,EVENT_REPORT]

创建、更新和删除仪表板遵循标准 REST

语义。为了创建一个新的仪表板,您可以创建一个 POST 请求/api/dashboards 资源。从消费者的角度首先创建仪表板然后添加项目可能会很方便到它。请求有效负载支持 JSON 和 XML 格式。至创建一个名为“我的仪表板”的仪表板,您可以在其中使用有效负载像这样的 JSON:

{
  “名称”:“我的仪表板”
}

更新,例如重命名,仪表板,您可以使用 PUT 请求类似的请求负载相同的 api/dashboards 资源。

要删除仪表板,您可以向特定的人发出 DELETE 请求与此类似的仪表板资源:

/ api /仪表板/ vQFhmLJU5sK

ValidationRuleGroup	Parameter name	Potential duplicate status
To add a visualization to a specific dashboard, send a PUT request to:	```
/api/dashboards/ChZ236jPgXs
```	UID \
```json
{
"name": "test",
"layout": {
"columns": []
},
"itemConfig": {
"insertPosition": "END"
},
"restrictFilters": false,
"allowedFilters": [],
"favorites": [],
"displayName": "test",
"user": {
"id": "xE7jOejl9FI",
"code": null,
"name": "John Traore",
"username": "admin"
},
"id": "ChZ236jPgXs",
"dashboardItems": [
{
"x": 0,
"y": 0,
"w": 20,
"h": 29,
"id": "cKd9PKBuHv6",
"type": "VISUALIZATION",
"position": null,
"visualization": {
"id": "LW0O27b7TdD",
"name": "ANC: 1-3 dropout rate Yearly"
},
"i": "cKd9PKBuHv6",
"minH": 4,
"firstOfType": true,
"width": 20,
"height": 29
}
],
"starred": false
}
```	Update an Item	UID \
不	The payload must be the latest Dashboard object, including all its items with the updated property value.	Remove an Item

To remove an item from a dashboard, remove it from the Dashboard payload and send a PUT request to:

 /api/dashboards/ChZ236jPgXs

Defining a dashboard layout { #webapi_dasboard_layout }

You can define and save a layout for each dashboard. The following object is responsible to hold this setting.

{
  "layout": {
    "spacing": {
      "column": 5,
      "row": 5
    },
    "columns": [{
      "index": 0,
      "span": 2
    }, {
      "index": 1,
      "span": 1
    }]
  }
}

The layout definition will be applied for all dashboard items related to the given dashboard, respecting layout attributes like spacing, columns, span and so on. See, below, a brief description of each attribute.

The repetition attribute (in rows, columns or filters) indicates the events indexes to be retrieved. Taking the example above (in the previous json payload), it can be read as follows:
1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default) | 名称 |
| The name of the EventVisualiation | type | | The type of the Visualization. The valid types are: COLUMN, STACKED_COLUMN, BAR, STACKED_BAR, LINE, AREA, PIE, RADAR, GAUGE, YEAR_OVER_YEAR_LINE YEAR_OVER_YEAR_COLUMN, SINGLE_VALUE, PIVOT_TABLE. | title | | A custom title. | subtitle | | A custom subtitle. | 描述 | | Defines a custom description for the Visualization. | created | | The date/time of the Visualization creation. | 开始日期 | | The beginning date used during the filtering. | 结束日期 | | The ending date used during the filtering. | sortOrder | | Events resource only. Custom period on scheduledDate. See "custom date periods" section. | user | | An object representing the creator of the Visualization. | 结束日期 | | The ending date used during the filtering. | sortOrder | | The sorting order of this EventVisualiation. Integer value. | user | | An object representing the creator of the Visualization. | publicAccess | | Sets the permissions for public access. | displayDensity | | The display density of the text. | fontSize | | The font size of the text. | relativePeriods | | An object representing the relative periods used in the analytics query. | 传说 | | An object representing the definitions for the legend and legend set, display style (FILL or TEXT) and display strategy (FIXED or BY_DATA_ITEM). | aggregationType | | Determines how the values are aggregated (if applicable). Valid options: SUM, AVERAGE, AVERAGE_SUM_ORG_UNIT, LAST, LAST_AVERAGE_ORG_UNIT, FIRST, FIRST_AVERAGE_ORG_UNIT, COUNT, STDDEV, VARIANCE, MIN, MAX, NONE, CUSTOM or DEFAULT. | regressionType | | A valid regression type: NONE, LINEAR, POLYNOMIAL or LOESS. | targetLineValue | | The chart target line. Accepts a Double type. | targetLineLabel | | The chart target line label. | rangeAxisLabel | | 请求查询参数 { #webapi_analytics_query_parameters } | domainAxisLabel | | The chart horizontal axis (x) label/title. | rangeAxisMaxValue | | The chart axis maximum value. Values outside of the range will not be displayed. | rangeAxisMinValue | | The chart axis minimum value. Values outside of the range will not be displayed. | rangeAxisSteps | | The chart axis minimum value. Values outside of the range will not be displayed. | rangeAxisDecimals | | The number of axis steps between the minimum and maximum values. | rangeAxisDecimals | | The number of decimals for the axes values. | baseLineValue | | A chart baseline value. | digitGroupSeparator | | The digit group separator. Valid values: COMMA, SPACE or NONE. | topLimit | | A chart baseline label. | digitGroupSeparator | | The digit group separator. Valid values: COMMA, SPACE or NONE. | topLimit | | The top limit set for the Pivot table. | measureCriteria | | Describes the criteria applied to this measure. | percentStackedValues | | Uses stacked values or not. More likely to be applied for graphics/charts. Boolean value. | externalAccess | | The program stage associated. | 项目状态 | | 不 | externalAccess | | 项目状态。可以是 "激活"、"已完成 "或 "已取消"。 | userOrganisationUnitGrandChildren | | The event status. It can be ACTIVE, COMPLETED, VISITED, SCHEDULE, OVERDUE, SKIPPED. | reportingParams | | Indicates whether the EventVisualization is available as external read-only. Boolean value. | userOrganisationUnit | | sortOrder | colTotals | | Indicates if the user has an organisation unit. Boolean value. | userOrganisationUnitChildren | | Indicates if the user has a children organisation unit. Boolean value. | userOrganisationUnitGrandChildren | | Indicates if the user has a grand children organisation unit. Boolean value. | rowTotals | | Indicates whether the visualization is using cumulative values. Boolean value. | hideEmptyColumns | | Custom period on incidentDate. See "custom date periods" section. | colTotals | | Displays (or not) the columns totals. Boolean value. | rowSubTotals | | Displays (or not) the row sub-totals. Boolean value. | fixRowHeaders | | 不 | completedOnly | | Indicates whether the EventVisualization is using cumulative values. Boolean value. | hideEmptyRows | | Indicates whether to hide rows with no data values. Boolean value. | showDimensionLabels | | Flag used in analytics requests. If true, only completed events/enrollments will be taken into consideration. Boolean value. | showDimensionLabels | | Hides the title or not. Boolean value. | hideSubtitle | | Hides the subtitle or not. Boolean value. | hideLegend | | Defines a custom description for the EventVisualiation. | showHierarchy |

Displays (or not) the organisation unit hierarchy names. Boolean value.

showData

Used by charts to hide or not data/values within the rendered model. Boolean value.

lastUpdatedBy

Object that represents the user that applied the last changes to the Visualization.

lastUpdated

The date/time of the last time the Visualization was changed. favorites

List of user ids who have marked this object as a favorite.

subscribers

The dimensions defined for the rows.

filterDimensions

Set of available object translation, normally filtered by locale.

outlierAnalysis

Object responsible to keep settings related to outlier analysis. The internal attribute 'outlierMethod' supports: IQR, STANDARD_Z_SCORE, MODIFIED_Z_SCORE. The 'normalizationMethod' accepts only Y_RESIDUALS_LINEAR for now.

seriesKey

Styling options for and whether or not to display the series key.

传说

Options for and whether or not to apply legend colors to the chart series.

检索可视化

To retrieve a list of all existing visualizations, in JSON format, with some basic information (including identifier, name and pagination) you can make a GET request to the URL below. You should see a list of all public/shared visualizations plus your private ones.

GET /api/visualizations.json

如果要检索特定可视化的JSON定义,可以将其各自的标识符添加到URL:

GET /api/visualizations/hQxZGXqnLS9.json

| The manual merge is suitable when there are resolvable conflicts or when not all the data needs to be moved during the merge. For example, if an attribute has different values in both tracked entities , the user can specify whether to keep the original value or move over the duplicate's value. Since the manual merge involves the user explicitly requesting to move data, there are some additional checks: | Parameter name | |---|---| | Two mappings for the Referrals Age category. A program indicator can choose which mapping | Endpoint responses { #webapi_data_items_possible_responses } | | 是的 | json { "interpretations": [ { "id": "Lfr8I2RPU0C" }, { "id": "JuwgdJlJPGb" }, { "id": "WAoU2rSpyZp" } ] } | | displayColumnOrder | 创建,更新和删除可视化 { #webapi_visualization_add_update_remove_visualizations } | | 枚举(参见元数据和渲染类型表中的列表) | json { "columns": [ { "dimension": "J5jldMd8OHv", "items": [ { "name": "CHP", "id": "uYxK4wmcPqA", "displayName": "CHP", "displayShortName": "CHP", "dimensionItemType": "ORGANISATION_UNIT_GROUP" }, { "name": "Hospital", "id": "tDZVQ1WtwpA", "displayName": "Hospital", "displayShortName": "Hospital", "dimensionItemType": "ORGANISATION_UNIT_GROUP" } ] } ], "rows": [ { "dimension": "SooXFOUnciJ", "items": [ { "name": "DOD", "id": "B0bjKC0szQX", "displayName": "DOD", "displayShortName": "DOD", "dimensionItemType": "CATEGORY_OPTION_GROUP" }, { "name": "CDC", "id": "OK2Nr4wdfrZ", "displayName": "CDC", "displayShortName": "CDC", "dimensionItemType": "CATEGORY_OPTION_GROUP" } ] } ], "filters": [ { "dimension": "ou", "items": [ { "name": "Sierra Leone", "id": "ImspTQPwCqd", "displayName": "Sierra Leone", "displayShortName": "Sierra Leone", "dimensionItemType": "ORGANISATION_UNIT" }, { "name": "LEVEL-1", "id": "LEVEL-H1KlN4QIauv", "displayName": "LEVEL-1" } ] } ], "name": "HIV Cases Monthly", "description": "Cases of HIV across the months", "category": "XY1vwCQskjX", "showDimensionLabels": true, "hideEmptyRows": true, "hideEmptyColumns": true, "skipRounding": true, "aggregationType": "SUM", "regressionType": "LINEAR", "type": "PIVOT_TABLE", "numberType": "VALUE", "measureCriteria": "Some criteria", "showHierarchy": true, "completedOnly": true, "displayDensity": "NORMAL", "fontSize": "NORMAL", "digitGroupSeparator": "SPACE", "legendDisplayStyle": "FILL", "legendDisplayStrategy": "FIXED", "hideEmptyRowItems": "BEFORE_FIRST_AFTER_LAST", "fixColumnHeaders": true, "fixRowHeaders": false, "regression": false, "cumulative": true, "sortOrder": 1, "topLimit": 2, "rowTotals": true, "colTotals": true, "hideTitle": true, "hideSubtitle": true, "hideLegend": true, "showData": true, "percentStackedValues": true, "noSpaceBetweenColumns": true, "rowSubTotals": true, "colSubTotals": true, "userOrgUnitType": "TEI_SEARCH", "externalAccess": false, "publicAccess": "--------", "reportingParams": { "reportingPeriod": true, "organisationUnit": true, "parentOrganisationUnit": true, "grandParentOrganisationUnit": true }, "parentGraphMap": { "ImspTQPwCqd": "" }, "access": { "read": true, "update": true, "externalize": true, "delete": false, "write": true, "manage": false }, "optionalAxes": [ { "dimensionalItem": "fbfJHSPpUQD", "axis": 1 }, { "dimensionalItem": "cYeuwXTCPkU", "axis": 2 } ], "relativePeriods": { "thisYear": false, "quartersLastYear": true, "last52Weeks": false, "thisWeek": false, "lastMonth": false, "last14Days": false, "biMonthsThisYear": false, "monthsThisYear": false, "last2SixMonths": false, "yesterday": false, "thisQuarter": false, "last12Months": false, "last5FinancialYears": false, "thisSixMonth": false, "lastQuarter": false, "thisFinancialYear": false, "last4Weeks": false, "last3Months": false, "thisDay": false, "thisMonth": false, "last5Years": false, "last6BiMonths": false, "last4BiWeeks": false, "lastFinancialYear": false, "lastBiWeek": false, "weeksThisYear": false, "last6Months": false, "last3Days": false, "quartersThisYear": false, "monthsLastYear": false, "lastWeek": false, "last7Days": false, "thisBimonth": false, "lastBimonth": false, "lastSixMonth": false, "thisBiWeek": false, "lastYear": false, "last12Weeks": false, "last4Quarters": false }, "user": {}, "yearlySeries": [ "THIS_YEAR" ], "userGroupAccesses": [ { "access": "rwx-----", "userGroupUid": "ZoHNWQajIoe", "displayName": "Bo District M&E officers", "id": "ZoHNWQajIoe" } ], "userAccesses": [ { "access": "--------", "displayName": "John Barnes", "id": "DXyJmlo9rge", "userUid": "DXyJmlo9rge" } ], "legendSet": { "name": "Death rate up", "id": "ham2eIDJ9k6", "legends": [ { "startValue": 1, "endValue": 2, "color": "red", "image": "some-image" }, { "startValue": 2, "endValue": 3, "color": "blue", "image": "other-image" } ] }, "outlierAnalysis": { "enabled": true, "outlierMethod": "IQR", "thresholdFactor": 1.5, "normalizationMethod": "Y_RESIDUALS_LINEAR", "extremeLines": { "enabled": true, "value": 3.5 } }, "legend": { "strategy": "FIXED", "style": "FILL", "set": { "id": "fqs276KXCXi", "displayName": "ANC Coverage" }, "showKey": false }, "seriesKey": { "hidden": true, "label": { "fontStyle": { "textColor": "#cccddd" } } }, "axes": [ { "index": 0, "type": "RANGE", "label": { "fontStyle": { "textColor": "#cccddd" } }, "title": { "text": "Range axis title", "textMode": "CUSTOM", "fontStyle": { "textColor": "#000000" } }, "decimals": 1, "maxValue": 100, "minValue": 20, "steps": 5, "baseLine": { "value": 50, "title": { "text": "My baseline", "fontStyle": { "textColor": "#000000" } } }, "targetLine": { "value": 80, "title": { "text": "My targetline", "fontStyle": { "textColor": "#cccddd" } } } }, { "index": 1, "type": "DOMAIN", "label": { "fontStyle": { "textColor": "#000000" } }, "title": { "text": "Domain axis title", "textMode": "CUSTOM", "fontStyle": { "textColor": "#cccddd" } } } ], "axes": [ { "index": 0, "type": "RANGE", "label": { "fontStyle": { "textColor": "#cccddd" } }, "title": { "text": "Range axis title", "fontStyle": { "textColor": "#000000" } }, "decimals": 1, "maxValue": 100, "minValue": 20, "steps": 5, "baseLine": { "value": 50, "title": { "text": "My baseline", "fontStyle": { "textColor": "#000000" } } }, "targetLine": { "value": 80, "title": { "text": "My targetline", "fontStyle": { "textColor": "#cccddd" } } } }, { "index": 1, "type": "DOMAIN", "label": { "fontStyle": { "textColor": "#000000" } }, "title": { "text": "Domain axis title", "fontStyle": { "textColor": "#cccddd" } } } ] } | | 列 | Stores specific parameters related to columns (at the moment, index and span) | | Array of objects | 可视化 { #webapi_visualization } | | dataFilters | The EventVisualization API is designed to help clients to interact with event charts and reports. The endpoints of this API are used by the Event Visualization application which allows the creation, configuration and management of charts and reports based on the client's definitions. The main idea is to enable clients and users to have a unique and centralized API providing all types of event charts and reports as well as specific parameters and configuration for each type of event visualization. This API was introduced with the expectation to unify both eventCharts and eventReports APIs and entirely replace them in favour of the eventVisualizations API (which means that the usage of eventCharts and eventReports APIs should be avoided). In summary, the following resources/APIs: /api/eventCharts, /api/eventReports are being replaced by /api/eventVisualizations | | GET /api/metadata/proposals?filter=status:eq:ACCEPTED | An EventVisualization object is composed of many attributes (some of them related to charting and others related to reporting), but the most important ones responsible to reflect the core information of the object are: "id", "name", "type", "dataDimensionItems", "columns", "rows" and "filters". The root endpoint of the API is /api/eventVisualizations, and the list of current attributes and elements are described in the table below. | | dueDate | 领域 | | lastUpdatedDate | id | | 这种访问级别的限制稍多一些。受保护项目中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。只有当所有者组织单位属于用户的捕获范围时,用户才能访问受保护项目内的数据。但是,如果用户用户可以通过打破玻璃获得临时所有权。玻璃](#webapi_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。他们为什么要访问手头的数据。然后,系统会将理由和访问审核记录在案,并提供 3 个月的临时访问权限。访问审计日志,并为用户提供 3 小时的临时访问权限。请注意,打破玻璃时时,所有者组织单位保持不变,只有打碎玻璃的用户才能获得临时访问权。获得临时访问权。 | 码 | | > Note

The repetition attribute (in rows, columns or filters) indicates the events indexes to be retrieved. Taking the example above (in the previous json payload), it can be read as follows:
1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default) | 名称 |
| The name of the EventVisualiation | type | | The type of the Visualization. The valid types are: COLUMN, STACKED_COLUMN, BAR, STACKED_BAR, LINE, AREA, PIE, RADAR, GAUGE, YEAR_OVER_YEAR_LINE YEAR_OVER_YEAR_COLUMN, SINGLE_VALUE, PIVOT_TABLE. | title | | A custom title. | subtitle | | Defines a custom description for the Visualization. | created | | Defines a custom description for the EventVisualiation. | created | | Events resource only. Custom period on scheduledDate. See "custom date periods" section. | 开始日期 | | An object representing the creator of the Visualization. | 结束日期 | | The ending date used during the filtering. | sortOrder | | The sorting order of this EventVisualiation. Integer value. | user | | An object representing the creator of the Visualization. | publicAccess | | Sets the permissions for public access. | displayDensity | | The display density of the text. | fontSize | | The font size of the text. | relativePeriods | | An object representing the relative periods used in the analytics query. | 传说 | | An object representing the definitions for the legend and legend set, display style (FILL or TEXT) and display strategy (FIXED or BY_DATA_ITEM). | aggregationType | | Determines how the values are aggregated (if applicable). Valid options: SUM, AVERAGE, AVERAGE_SUM_ORG_UNIT, LAST, LAST_AVERAGE_ORG_UNIT, FIRST, FIRST_AVERAGE_ORG_UNIT, COUNT, STDDEV, VARIANCE, MIN, MAX, NONE, CUSTOM or DEFAULT. | regressionType | | A valid regression type: NONE, LINEAR, POLYNOMIAL or LOESS. | targetLineValue | | The chart target line. Accepts a Double type. | targetLineLabel | | The chart target line label. | rangeAxisLabel | | 请求查询参数 { #webapi_analytics_query_parameters } | domainAxisLabel | | The chart horizontal axis (x) label/title. | rangeAxisMaxValue | | The chart axis maximum value. Values outside of the range will not be displayed. | rangeAxisMinValue | | The chart axis minimum value. Values outside of the range will not be displayed. | rangeAxisSteps | | The number of axis steps between the minimum and maximum values. | rangeAxisDecimals | | The number of decimals for the axes values. | baseLineValue | | A chart baseline value. | baseLineLabel | | A chart baseline label. | digitGroupSeparator | | The digit group separator. Valid values: COMMA, SPACE or NONE. | topLimit | | The top limit set for the Pivot table. | measureCriteria | | Describes the criteria applied to this measure. | percentStackedValues | | Uses stacked values or not. More likely to be applied for graphics/charts. Boolean value. | noSpaceBetweenColumns | | 不 | externalAccess | | Indicates whether the EventVisualization is available as external read-only. Boolean value. | userOrganisationUnit | | Indicates if the user has an organisation unit. Boolean value. | userOrganisationUnitChildren | | Indicates if the user has a children organisation unit. Boolean value. | userOrganisationUnitGrandChildren | | Indicates if the user has a grand children organisation unit. Boolean value. | rowTotals | | Custom period on incidentDate. See "custom date periods" section. | colTotals | | Displays (or not) the columns totals. Boolean value. | rowSubTotals | | Displays (or not) the row sub-totals. Boolean value. | colSubTotals | | 不 | cumulativeValues | | Indicates whether the EventVisualization is using cumulative values. Boolean value. | hideEmptyRows | | Indicates whether to hide rows with no data values. Boolean value. | completedOnly | | Flag used in analytics requests. If true, only completed events/enrollments will be taken into consideration. Boolean value. | showDimensionLabels | | { "periodFrom": -15, "periodTo": 15} | hideTitle | | See an example payload below. | hideSubtitle | | 结束日期 | showHierarchy | | "displayOrderColumns": ["enrollmentDate", "program"] | showData | | Used by charts to hide or not data/values within the rendered model. Boolean value. | lastUpdatedBy | | Object that represents the user that applied the last changes to the EventVisualization. | lastUpdated | | The date/time of the last time the EventVisualization was changed. | favorites | | List of user ids who have marked this object as a favorite. | subscribers | | 不 | translations | | 不 | 项目 | | The program associated. | 项目阶段 | | The program stage associated. | 项目状态 | | 项目状态。可以是 "激活"、"已完成 "或 "已取消"。 | eventStatus | | The event status. It can be ACTIVE, COMPLETED, VISITED, SCHEDULE, OVERDUE, SKIPPED. | dataType |

The event data type. It can be AGGREGATED_VALUES or EVENTS.

columnDimensions

The dimensions defined for the columns.

rowDimensions

The dimensions defined for the rows.

filterDimensions

The dimensions defined for the filters.

outputType

Indicates output type of the EventVisualization. It can be EVENT, ENROLLMENT or TRACKED_ENTITY_INSTANCE.

collapseDataDimensions

<attribute id>

hideNaData

Indicates whether to hide N/A data. Boolean value.

hideEmptyColumns

Indicates whether to hide columns with no data values. Boolean value.

fixColumnHeaders

Fixes (or not) the pivot table column headers. Boolean value.

fixRowHeaders

Fixes (or not) the pivot table row headers. Boolean value.

Retrieving event visualizations { #webapi_event_visualization_retrieving_event_visualizations }

To retrieve a list of all existing event visualizations, in JSON format, with some basic information (including identifier, name and pagination) you can make a GET request to the URL below. You should see a list of all public/shared event visualizations plus your private ones. GET /api/eventVisualizations.json If you want to retrieve the JSON definition of a specific EventVisualization you can add its respective identifier to the URL: GET /api/eventVisualizations/hQxZGXqnLS9.json The following representation is an example of a response in JSON format (for brevity, certain information has been removed). For the complete schema, please use GET /api/schemas/eventVisualization.

{
    "lastUpdated": "2021-11-25T17:18:03.834",
    "href": "http://localhost:8080/dhis/api/eventVisualizations/EZ5jbRTxRGh",
    "id": "EZ5jbRTxRGh",
    "created": "2021-11-25T17:18:03.834",
    "name": "Inpatient: Mode of discharge by facility type this year",
    "publicAccess": "rw------",
    "userOrganisationUnitChildren": false,
    "type": "STACKED_COLUMN",
    "subscribed": false,
    "userOrganisationUnit": false,
    "rowSubTotals": false,
    "cumulativeValues": false,
    "showDimensionLabels": false,
    "sortOrder": 0,
    "favorite": false,
    "topLimit": 0,
    "collapseDataDimensions": false,
    "userOrganisationUnitGrandChildren": false,
    "displayName": "Inpatient: Mode of discharge by facility type this year",
    "percentStackedValues": false,
    "noSpaceBetweenColumns": false,
    "showHierarchy": false,
    "hideTitle": false,
    "showData": true,
    "hideEmptyRows": false,
    "hideNaData": false,
    "regressionType": "NONE",
    "completedOnly": false,
    "colTotals": false,
    "sharing": {
      "owner": "GOLswS44mh8",
      "external": false,
      "users": {},
      "userGroups": {},
      "public": "rw------"
    },
    "programStatus": "CANCELLED",
    "hideEmptyRowItems": "NONE",
    "hideSubtitle": false,
    "outputType": "EVENT",
    "hideLegend": false,
    "externalAccess": false,
    "colSubTotals": false,
    "rowTotals": false,
    "digitGroupSeparator": "SPACE",
    "program": {
      "id": "IpHINAT79UW"
    },
    "access": {
      "read": true,
      "update": true,
      "externalize": true,
      "delete": true,
      "write": true,
      "manage": true
    },
    "lastUpdatedBy": {
      "displayName": "John Traore",
      "name": "John Traore",
      "id": "xE7jOejl9FI",
      "username": "admin"
    },
    "relativePeriods": {
      "thisYear": false,
      ...
    },
    "programStage": {
      "id": "A03MvHHogjR"
    },
    "createdBy": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "user": {
      "displayName": "Tom Wakiki",
      "name": "Tom Wakiki",
      "id": "GOLswS44mh8",
      "username": "system"
    },
    "attributeDimensions": [],
    "translations": [],
    "legend": {
      "set": {
        "id": "gFJUXah1uRH"
      },
      "showKey": false,
      "style": "FILL",
      "strategy": "FIXED"
    },
    "filterDimensions": [
      "ou",
      "H6uSAMO5WLD"
    ],
    "interpretations": [],
    "userGroupAccesses": [],
    "subscribers": [],
    "columns": [
      {
        "id": "X8zyunlgUfM"
      }
    ]
    "periods": [],
    "categoryDimensions": [],
    "rowDimensions": [
      "pe"
    ],
    "itemOrganisationUnitGroups": [],
    "programIndicatorDimensions": [],
    "attributeValues": [],
    "columnDimensions": [
      "X8zyunlgUfM"
    ],
    "userAccesses": [],
    "favorites": [],
    "dataDimensionItems": [],
    "categoryOptionGroupSetDimensions": [],
    "organisationUnitGroupSetDimensions": [],
    "organisationUnitLevels": [],
    "organisationUnits": [
      {
        "id": "ImspTQPwCqd"
      }
    ],
    "filters": [
      {
        "id": "ou"
      },
      {
        "id": "H6uSAMO5WLD"
      }
    ],
    "rows": [
      {
        "id": "pe"
      }
    ]
}

A more tailored response can be obtained by specifying, in the URL, the fields you want to extract. Ie.: GET /api/eventVisualizations/hQxZGXqnLS9.json?fields=interpretations will return

The repetition attribute (in rows, columns or filters) indicates the events indexes to be retrieved. Taking the example above (in the previous json payload), it can be read as follows:
1 = First event
2 = Second event
3 = Third event
...
-2 = Third latest event
-1 = Second latest event
0 = Latest event (default) | To update a specific EventVisualization, you can send a `PUT` request to the same `/api/eventVisualizations` resource with a similar payload `PLUS` the respective EventVisualization's identifier, ie.:
PUT /api/eventVisualizations/hQxZGXqnLS9
Finally, to delete an existing EventVisualization, you can make a DELETE request specifying the identifier of the EventVisualization to be removed, as shown: DELETE /api/eventVisualizations/hQxZGXqnLS9 | | 释义 { #webapi_interpretations } | For resources related to data analysis in DHIS2, such as visualizations, maps, event reports, event charts and even visualizations you can write and share data interpretations. An interpretation can be a comment, question, observation or interpretation about a data report or visualization. | | / api /解释 | 阅读口译 { #webapi_reading_interpretations } | | 为了阅读解释,我们将与 /api/interpretations 资源。使用字段的典型 GET 请求过滤可以是这样的: | GET /api/interpretations?fields=*,comments[id,text,user,mentions] | | JSON 响应格式的输出可能如下所示(附加为简洁起见省略了字段): | json { "interpretations": [ { "id": "XSHiFlHAhhh", "created": "2013-05-30T10:24:06.181+0000", "text": "Data looks suspicious, could be a data entry mistake.", "type": "MAP", "likes": 2, "user": { "id": "uk7diLujYif" }, "reportTable": { "id": "LcSxnfeBxyi" }, "visualization": { "id": "LcSxnfeBxyi" } }, { "id": "kr4AnZmYL43", "created": "2013-05-29T14:47:13.081+0000", "text": "Delivery rates in Bo looks high.", "type": "VISUALIZATION", "likes": 3, "user": { "id": "uk7diLujYif" }, "visualization": { "id": "HDEDqV3yv3H" }, "mentions": [ { "created": "2018-06-25T10:25:54.498", "username": "boateng" } ], "comments": [ { "id": "iB4Etq8yTE6", "text": "This report indicates a surge.", "user": { "id": "B4XIfwOcGyI" } }, { "id": "iB4Etq8yTE6", "text": "Likely caused by heavy rainfall.", "user": { "id": "B4XIfwOcGyI" } }, { "id": "SIjkdENan8p", "text": "Have a look at this @boateng.", "user": { "id": "xE7jOejl9FI" }, "mentions": [ { "created": "2018-06-25T10:03:52.316", "username": "boateng" } ] } ] } ] } | | Table: Interpretation fields | 领域 | | 描述 | id | | The interpretation identifier. | created | | The time of when the interpretation was created. | type |

The type of analytical object being interpreted. Valid options: VISUALIZATION, MAP, EVENT_REPORT, EVENT_CHART, EVENT_VISUALIZATION, DATASET_REPORT.

user

Association to the user who created the interpretation.

visualization

Association to the visualization if type is VISUALIZATION

eventVisualization

Association to the event visualization if type is EVENT_VISUALIZATION

map

Association to the map if type is MAP.

eventReport

Association to the event report is type is EVENT_REPORT.

eventChart

Association to the event chart if type is EVENT_CHART.

dataSet

Association to the data set if type is DATASET_REPORT.

comments

Array of comments for the interpretation. The text field holds the actual comment.

mentions

Array of mentions for the interpretation. A list of users identifiers.

对于所有分析对象,您可以将 /data 附加到 URL 以检索与资源关联的数据(相对于元数据)。作为一个例子,通过跟随地图链接并附加 /data 可以通过检索主题地图的 PNG(图像)表示以下网址:

https://play.dhis2.org/demo/api/maps/bhmHJ4ZCdCd/data

对于所有分析对象,您可以通过*提及*进行过滤。检索所有您提到的用户的解释/评论三个选项。您可以通过解释提及(提及在解释中描述):

GET /api/interpretations?fields=*,comments[*]&filter=mentions.username:in:[boateng]

您可以通过解释评论提及(在任何评论):

GET / api / interpretations?fields = ,评论[]

  &filter = comments.mentions.username:in:[boateng]

您可以按包含提及的解释进行过滤在解释或任何评论中(或结点):

GET /api/interpretations?fields=*,comments[*]&filter=mentions:in:[boateng]

写作解释 { #webapi_writing_interpretations }

在编写解释时,您将提供解释文本作为使用内容类型为“text/plain”的 POST 请求的请求正文。 URL 模式如下所示,其中 {object-type} 指的是被解释的对象的类型,{object-id} 指的是被解释对象的标识符。

/ api / interpretations / {object-type} /

Valid options for object type are visualization, map, eventReport, eventChart, eventVisualization and dataSetReport.

下面列出了一些有效的解释示例。

Note

The eventCharts and eventReports APIs are deprecated. We recommend using the eventVisualizations API instead.

/api/interpretations/visualization/hQxZGXqnLS9
/api/interpretations/map/FwLHSMCejFu
/api/interpretations/eventReport/xJmPLGP3Cde
/api/interpretations/eventChart/nEzXB2M9YBz
/api/interpretations/eventVisualization/nEzXB2M9YBz
/api/interpretations/dataSetReport/tL7eCjmDIgM

As an example, we will start by writing an interpretation for the visualization with identifier EbRN2VIbPdV. To write visualization interpretations we will interact with the /api/interpretations/visualization/{visualizationId} resource. The interpretation will be the request body. Based on this we can put together the following request using cURL:

```bash

curl -d "This visualization shows a significant ANC 1-3 dropout" -X POST "https://play.dhis2.org/demo/api/interpretations/visualization/EbRN2VIbPdV" -H "Content-Type:text/plain" -u admin:district

请注意,响应提供了一个带有值的 Location 标头
指示创建的解释的位置。这很有用
从客户的角度来看,当您想向
解释。

更新和删除解释 { #webapi_updating_removing_interpretations } 

要更新现有解释,您可以使用 PUT 请求,其中
解释文本是使用以下 URL 模式的请求正文,
其中 {id} 指的是解释标识符:

    / api / interpretations / {id}

基于此,我们可以使用curl来更新解释:

```bash
curl -d "This visualization shows a high dropout" -X PUT
  "https://play.dhis2.org/demo/api/interpretations/visualization/EV08iI1cJRA" -H "Content-Type:text/plain" -u admin:district

您可以使用与上面相同的 URL 模式使用 DELETE 请求来删除解释。

创建解释注释 { #webapi_creating_interpretation_comments }

在为解释撰写评论时,您将提供评论

text 作为使用内容类型的 POST 请求的请求正文 “文本/纯文本”。 URL 模式如下所示,其中 {interpretation-id} 指的是解释标识符。

/ api / interpretations / {interpretation-id} /评论

其次,我们将对我们在上面的例子。通过查看解释响应,您将看到返回一个 Location 标头。这个标题告诉我们的 URL 新创建的解释,从中我们可以阅读它的标识符。此标识符是随机生成的,因此您必须用您自己的命令替换下面命令中的那个。写评论我们可以与/api/interpretations/{id}/comments进行交互像这样的资源:

curl -d "An intervention is needed" -X POST
  "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments"
  -H "Content-Type:text/plain" -u admin:district

更新和删除解释注释 { #webapi_updating_removing_interpretation_comments }

要更新解释注释,您可以使用 PUT 请求,其中评论文本是使用以下 URL 模式的请求正文:

/ api / interpretations / {interpretation-id} / comments / {comment-id}

基于此,我们可以使用curl来更新注释:

curl "https://play.dhis2.org/demo/api/interpretations/j8sjHLkK8uY/comments/idAzzhVWvh2"
  -d "I agree with that." -X PUT -H "Content-Type:text/plain" -u admin:district

您可以使用与上面相同的 URL 模式,使用 DELETE 请求到删除解释注释。

喜欢的解释 { #webapi_liking_interpretations }

要喜欢一个解释,你可以使用一个空的 POST 请求到 *喜欢*资源:

POST / api / interpretations / {id} / like

将为当前经过身份验证的用户添加一个赞。一个用户可以只喜欢解释一次。
要删除解释的赞,您可以使用 DELETE 请求与类似操作相同的资源。可以通过查看解释的类似状态来查看常规 Web API 表示: GET /api/interpretations/{id}

在 likes 字段中可以找到喜欢的信息,它代表喜欢的数量,以及 likedBy 数组,它枚举了喜欢的用户喜欢这个解释。 ```json { "id": "XSHiFlHAhhh", "text": "Data looks suspicious, could be a data entry mistake.", "type": "VISUALIZATION", "likes": 2, "likedBy": [ { "id": "k7Hg12fJ2f1" }, { "id": "gYhf26fFkjFS" } ] }

### SQL视图 { #webapi_sql_views } 

SQL 视图资源允许您创建和检索结果集
SQL 视图。 SQL 视图可以直接针对
数据库并通过 Web API 资源呈现结果集。

    / api / sqlViews

SQL 视图对于创建可能更容易的数据视图很有用
用SQL构造比较结合Web的多个对象
应用项目接口。举个例子,假设我们被要求提供一个视图
所有组织单位及其名称、父名称、组织单位
级别和名称,以及数据库中列出的坐标。风景
可能看起来像这样:

```sql
select ou.name as orgunit, par.name as parent, ou.coordinates, ous.level, oul.name 
from organisationunit ou
inner join _orgunitstructure ous on ou.organisationunitid = ous.organisationunitid
inner join organisationunit par on ou.parentid = par.organisationunitid
inner join orgunitlevel oul on ous.level = oul.level
where ou.coordinates is not null
order by oul.level, par.name, ou.name;

我们将使用 curl 首先在 DHIS2 服务器上执行视图。这

本质上是一个物化过程,并确保我们拥有检索时可通过 SQL 视图获得的最新数据从服务器。您可以先从 SQL 视图中查找 api/sqlViews 资源,然后使用以下命令进行 POST:

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/execute" -X POST -u admin:district

The next step in the process is the retrieval of the data. The endpoint is available at:

/api/sqlViews/{id}/data(.csv)

The id path represents the SQL view identifier. The path extensions refers to the format of the data download. Append either data for JSON data or data.csv for comma separated values. Support response formats are json, xml, csv, xls, html and html+css.

As an example, the following command would retrieve CSV data for the SQL view defined above.

curl "https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv" -u admin:district

SQL视图有三种类型:

SQL 视图: 标准 SQL 视图。

*物化的SQL视图:*物化的SQL视图,意思是

写入磁盘。需要更新以反映变化

底层表。支持过滤结果集的标准。

SQL 查询: 普通 SQL 查询。支持内联变量	自定义查询。
标准 { #webapi_sql_view_criteria }	您可以通过以下方式对结果集中的列进行简单过滤
使用列名将 criteria 查询参数附加到 URL
并过滤由列分隔的值作为参数值,在
以下格式:
/ api / sqlViews / {id} / data?criteria = col1:value1&criteria = col2:value2	As an example, to filter the SQL view result set above to only return
organisation units at level 4 you can use the following URL:

https://play.dhis2.org/demo/api/sqlViews/dI68mLkP1wN/data.csv?criteria=level:4

变数 { #webapi_sql_view_variables }

SQL 视图支持变量替换。变量替换只是可用于 query 类型的 SQL 视图,这意味着 SQL 视图不是在数据库中创建,但只是作为常规 SQL 查询执行。变量可以直接插入到 SQL 查询中,并且必须在这种格式:

$

例如,检索给定的所有数据元素的 SQL 查询通过变量定义值类型的值类型可以看像这样:

从dataelement中选择*,其中valuetype ='$ {valueType}';

然后可以在请求时将这些变量作为 URL 的一部分提供通过 sqlViews Web API 资源。可以提供变量以下格式:

/ api / sqlViews / {id} / data?var = key1:value1&var = key2:value2

与上面的示例相对应的示例查询如下所示:

/api/sqlViews/dI68mLkP1wN/data.json?var=valueType:int

valueType 变量将替换为 int 值,并且查询将返回具有 int 值类型的数据元素。

变量参数必须仅包含字母数字字符。这

变量必须包含字母数字、破折号、下划线和空格仅字符。

query 类型的 SQL 视图还支持两个系统定义的变量,这些变量允许查询访问有关执行视图的用户的信息:

变量

手段

${_current_user_id}

用户的数据库ID

${_current_username}

用户的用户名

这些变量的值不能作为URL的一部分提供。它们始终充满有关用户的信息。

例如,以下 query 类型的 SQL 视图显示分配给用户的所有组织单位:

select ou.path, ou.name
from organisationunit ou_user
join organisationunit ou on ou.path like ou_user.path || '%'
join usermembership um on um.organisationunitid = ou_user.organisationunitid
where um.userinfoid = ${_current_user_id}
order by ou.path;

筛选

The SQL view API supports data filtering, equal to the metadata object_filter. For a complete list of filter operators you can look at the documentation for metadata object_filter.

To use filters, simply add them as parameters at the end of the request URL for your SQL view like this. This request will return a result including org units with "bo" in the name at level 2 of the org unit hierarchy:

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:eq:2&filter=orgunit_name:ilike:bo

以下示例将返回所有带有 `orgunit_level` 2 或

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_level:in:[2,4]

And last, an example to return all org units that does not start with "Bo":

/api/sqlViews/w3UxFykyHFy/data.json?filter=orgunit_name:!like:Bo

数据项 { #webapi_data_items }

This endpoint allows the user to query data related to a few different dimensional items. These items are: INDICATOR, DATA_ELEMENT, DATA_SET, PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT, PROGRAM_ATTRIBUTE, OPTION_SET. The endpoint supports only GET requests and, as other endpoints, can return responses in JSON or XML format.

该URL是/ api / dataItems,并且可以想象,它能够在同一GET请求中通过同一端点检索不同的对象。因此,某些可用的可查询属性将根据要查询的维项目而有所不同。

为了理解上面的陈述,让我们看一下以下请求示例:

1)GET /api/dataItems?filter=dimensionItemType:eq:DATA_ELEMENT&filter=valueType:eq:TEXT 在这个例子中,项目类型DATA_ELEMENT 有一个valueType 属性,可以在查询中使用。

2) GET /api/dataItems?pageSize=50&order=displayName:asc&filter=dimensionItemType:eq:PROGRAM_INDICATOR&filter=displayName:ilike:someName&filter=programId:eq:WSGAb5XwJ3Y

For elements where there is an associated Program, the program name should also be returned as part of the element name (as a prefix). The only exception is Program Indicators. We will not prefix the element name in this case, in order to keep the same behavior as existing endpoints.

The /dataItems endpoint will bring only data items that are defined as aggregatable type. The current list of valid aggregatable types is: TEXT, LONG_TEXT, LETTER, BOOLEAN, TRUE_ONLY, NUMBER, UNIT_INTERVAL, PERCENTAGE, INTEGER, INTEGER_POSITIVE, INTEGER_NEGATIVE, INTEGER_ZERO_OR_POSITIVE, COORDINATE.

Even though the response returns several different attributes, the filtering can only be applied to specific ones: displayName, name, valueType, id, dimensionItemType, programId.

The order will be considered invalid if it is set on top of name (ie.: order=name:asc) and a filter is set to displayName (ie.: filter=displayName:ilike:aName), and vice-versa. | | 名称 | 现在,我们已经了解了此端点的主要功能和用法,让我们看一下响应中返回的属性列表。 | | Table: Data items attributes | 领域 | | 描述 | id |

The unique identifier.

码

A custom code to identify the dimensional item.

名称	Parameter name	displayName	The display name defined.
shortName	DHIS2 has several resources for data analysis. These resources include
maps, visualizations, eventVisualizations, reports and documents. By visiting these resources you will retrieve information about the resource. For instance, by navigating to `/api/visualizations/R0DVGvXDUNP` the response will contain the name, last date of modification and so on for the chart. To retrieve the analytical representation, for instance, a PNG representation of the visualization, you can append /data to all these resources. For instance, by visiting `/api/visualizations/R0DVGvXDUNP/data` the system will return a PNG image of the visualization.	displayShortName	The display short name defined.
dimensionItemType	The dimension type. Possible types: INDICATOR, DATA_ELEMENT, REPORTING_RATE, PROGRAM_INDICATOR, PROGRAM_DATA_ELEMENT, PROGRAM_ATTRIBUTE.	valueType	The display short name defined.
simplifiedValueType	The genereal representation of a value type. Valid values: NUMBER, BOOLEAN, DATE, FILE_RESOURCE, COORDINATE, TEXT	项目Id	相关的项目 ID。
查看分析性资源表示 { #webapi_viewing_analytical_resource_representations }	DHIS2 has several resources for data analysis. These resources include
maps, visualizations, eventVisualizations, reports and documents. By visiting these resources you will retrieve information about the resource. For instance, by navigating to `/api/visualizations/R0DVGvXDUNP` the response will contain the name, last date of modification and so on for the chart. To retrieve the analytical representation, for instance, a PNG representation of the visualization, you can append /data to all these resources. For instance, by visiting `/api/visualizations/R0DVGvXDUNP/data` the system will return a PNG image of the visualization.	Table: Analytical resources	Resource
The display short name defined.
Data URL	Resource representations	eventCharts	活动图
/api/eventCharts/<identifier>/data	png	maps	地图

/api/maps/<identifier>/data

png

| eventCreatedPeriod | json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } | Parameter name | |---|---|---| | json | jsonp | html | xml | pdf | xls | csv | Event chart view | 活动图 |

/api/eventVisualizations/<identifier>/data

eventCreatedPeriod	Parameter name
reports	标准报告
/api/reports/<identifier>/data	pdf \| xls \| html

documents

资源资源

/api/documents/<identifier>/data

<follows document>

解析表示的数据内容可以通过以下方式修改提供 date 查询参数。这就要求分析为期间维度的相对期间设置资源。

Table: Data query parameters

查询参数

值

选项值

eventCreatedPeriod	检索和删除项目通知模板	Parameter name
周期(pe)	```json
{
"name": "Case notification",
"notificationTrigger": "ENROLLMENT",
"subjectTemplate": "Case notification V{org_unit_name}",
"displaySubjectTemplate": "Case notification V{org_unit_name}",
"notifyUsersInHierarchyOnly": false,
"sendRepeatable": false,
"notificationRecipient": "ORGANISATION_UNIT_CONTACT",
"notifyParentOrganisationUnitOnly": false,
"displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
"messageTemplate": "Case notification A{h5FuguPFF2j}",
"deliveryChannels": [
"EMAIL"
]
}
```	width	/api/visualizations/R0DVGvXDUNP/data
/api/visualizations/R0DVGvXDUNP/data?date=2013-06-01

/api/visualizations/jIISuEWxmoI/data.html
/api/visualizations/jIISuEWxmoI/data.html?date=2013-01-01
/api/visualizations/FPmvWs7bn2P/data.xls
/api/visualizations/FPmvWs7bn2P/data.pdf

/api/eventVisualizations/x5FVFVt5CDI/data
/api/eventVisualizations/x5FVFVt5CDI/data.png

/api/maps/DHE98Gsynpr/data
/api/maps/DHE98Gsynpr/data?date=2013-07-01

/api/reports/OeJsA6K1Otx/data.pdf
/api/reports/OeJsA6K1Otx/data.pdf?date=2014-01-01 |

| 数据值 | Program notification template | 用于检索各种分析的有效 URL 的一些示例代表如下。 | /api/visualizations/R0DVGvXDUNP/data /api/visualizations/R0DVGvXDUNP/data?date=2013-06-01

/api/visualizations/jIISuEWxmoI/data.html
/api/visualizations/jIISuEWxmoI/data.html?date=2013-01-01
/api/visualizations/FPmvWs7bn2P/data.xls
/api/visualizations/FPmvWs7bn2P/data.pdf

/api/eventVisualizations/x5FVFVt5CDI/data
/api/eventVisualizations/x5FVFVt5CDI/data.png

/api/maps/DHE98Gsynpr/data
/api/maps/DHE98Gsynpr/data?date=2013-07-01

/api/reports/OeJsA6K1Otx/data.pdf
/api/reports/OeJsA6K1Otx/data.pdf?date=2014-01-01 |

| Events resource only. Custom period on scheduledDate. See "custom date periods" section. | Program notification template | 要访问 DHIS2 中的分析汇总数据,您可以使用 *分析*资源。分析资源非常强大,因为它可以让您查询和检索沿所有可用数据维度聚合的数据。例如,您可以要求分析资源提供一组数据元素、时间段和组织单位。此外,您可以检索聚合数据基于数据元素的任意数量维度的组合和组织单位组集。 | no | | 请求查询参数 { #webapi_analytics_query_parameters } | Program notification template | Table: Query parameters | 查询参数 | | 需要 | Program notification template | 选项(默认为默认) | 查询参数 | | dueDate | Program notification template | Any dimension | query | | lastUpdatedDate | Program notification template | Any dimension | query | | 不 | Program notification template | SUM | AVERAGE | AVERAGE_SUM_ORG_UNIT | LAST | LAST_AVERAGE_ORG_UNIT | COUNT | STDDEV | VARIANCE | MIN | MAX | 假 | | 不 | Program notification template | ASC | DESC | 假 | | sortOrder | Program notification template | EQ | GT | GE | LT | LE | 假 | | stage | Program notification template | Program stage identifier. | 假 | | 不 | Program notification template | 日期 | 假 | | 不 | Program notification template | false | true | 假 | | 不 | Program notification template | false | true | 假 | | The program stage associated. | Program notification template | false | true | 假 | | Custom period on incidentDate. See "custom date periods" section. | Program notification template | lastUpdated | 假 | | 不 | Program notification template | false | true | 假 | | 不 | Program notification template | ouname | programstatus | createdbydisplayname | lastupdatedbydisplayname | enrollmentdate | incidentdate | lastupdated | <dimension identifier> | 假 | | Custom period on lastUpdated. See "custom date periods" section. | Program notification template | DESCENDANTS, CHILDREN, SELECTED | 查询参数 | | json { "httpStatus": "OK", "httpStatusCode": 200, "status": "OK", "response": { "responseType": "ObjectReport", "uid": "pG4bBTMiCqO", "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange", "errorReports": [] } } | Program notification template | false | true | page | | Required / Notes | Program notification template | false | true | includeNumDen | | 是的 | Program notification template | false | true | includeNumDen | | The name of the headers to be returned as part of the response. One or more headers name separated by comma | Program notification template | 不 | displayProperty | | 不 | Program notification template | NAME | SHORTNAME | outputIdScheme | | 描述 | Program notification template | 需要 | query | | 不 | Program notification template | UUID | CODE | NAME | ATTRIBUTE:<ID> | outputDataElementIdScheme | | 不 | Program notification template | UUID | CODE | NAME | ATTRIBUTE:<ID> | hierarchyMeta | | 不 | Program notification template | UID | CODE | ATTRIBUTE:<ID> | hierarchyMeta | | iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。 | Program notification template | Identifier of approval level | 价值 | | 不 | Program notification template | 日期 | userOrgUnit | | 事件聚合资源不返回事件信息本身,而不是与请求匹配的事件总数询问。事件维度包括数据元素、人员属性、人员标识符、期间和组织单位。聚合事件查询应该是下面描述的格式。 | Program notification template | false | true | skipMeta | | 不 | Program notification template | Any dimension (must be query dimension) | 假 |

不

Dimensions to use as rows for table layout, separated by semi-colon.

Any dimension (must be query dimension)

order

不

Specify the ordering of rows based on value.

ASC | DESC

timeField

不

The time field to base event aggregation on. Applies to event data items only. Can be a predefined option or the ID of an attribute or data element with a time-based value type.

orgUnitField

不

The organisation unit field to base event aggregation on. Applies to event data items only. Can be the ID of an attribute or data element with the Organisation unit value type. The default option is specified as omitting the query parameter.

enhancedConditions

不

Enable enhanced conditions for dimensions and filters.

false | true

dimension 查询参数定义了哪些维度应该是包含在分析查询中。可以是任意数量的维度指定的。每个维度都应该重复维度参数包含在查询响应中。查询响应可能包含指定的所有组合的聚合值维度项。

| /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &columns=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP &pageSize=10&page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS | 值不引用数字元素或项目一部分的数据元素或属性 | aggregationType 查询参数允许您定义哪个聚合运算符应该用于查询。默认情况下,聚合将使用为查询中包含的数据元素定义的运算符。如果您的查询不包含任何数据元素但包含数据元素组,第一个数据元素的聚合运算符将使用第一组。组和数据元素的顺序是不明确的。此查询参数允许您覆盖默认值和指定特定的聚合运算符。例如,您可以设置使用以下 URL 进行“计数”的聚合运算符: | |---|---|---| | /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2014Q1&dimension=ou:O6uvpzGd5pu &aggregationType=COUNT | measureCriteria 查询参数可让您过滤掉数据范围要返回的记录。您可以指示系统仅返回记录其中聚合数据值等于、大于、大于或等于、小于或小于或等于某些值。您可以指定任何以下格式的标准数量,其中 criteria 和 value 应替换为实际值: | /api/analytics?measureCriteria=criteria:value;criteria:value | | 例如,以下查询将仅返回以下记录数据值大于或等于 6500 且小于 33000: | E7228 | Fallback coordinate field is invalid | | /api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU&dimension=pe:2014 &dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw&preAggregationMeasureCriteria=GE:10;LT:100 | Filter on whether the current user can manage the returned users through the managed user group relationships. | /api/analytics.json?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU &dimension=ou:ImspTQPwCqd&startDate=2018-01-01&endDate=2018-06-01 | | 为了让分析资源生成形状中的数据一个现成的表格,你可以提供 tableLayout 参数 true 作为值。而不是生成一个普通的、规范化的数据源, 分析资源现在将生成表格布局中的数据。你可以将 columns 和 rows 参数与维度标识符一起使用用分号分隔作为值以指示使用哪些值表格列和行。列和行维度必须存在作为查询中的数据维度(不是过滤器)。这样的请求可以看像这样: | 描述 | order 参数可用于分析资源生成有序数据。数据将按升序(或降序)排序值。以降序对值进行排序的示例请求顺序是: | | /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:LAST_12_MONTHS &dimension=ou:O6uvpzGd5pu&order=DESC | 尺寸和项目 { #webapi_analytics_dimensions_and_items } | DHIS2 features a multi-dimensional data model with several fixed and dynamic data dimensions. The fixed dimensions are the data element, period (time) and organisation unit dimension. You can dynamically add dimensions through categories, category option group sets, organisation unit group sets, data element group sets and organisation unit group sets. The table below displays the available data dimensions in DHIS2. Each data dimension has a corresponding dimension identifier, and each dimension can have a set of dimension items: | | Table: Dimensions and dimension items | 尺寸 | Dimension id | | Dimension items | Data elements, indicators, data set reporting rate metrics, data element operands, program indicators, program data elements, program attributes, validation rules | dx | | /api/analytics/events | Data elements, indicators, data set reporting rate metrics, data element operands, program indicators, program data elements, program attributes, validation rules | 聚乙烯 | | ISO periods and relative periods, see "date and period format" | Data elements, indicators, data set reporting rate metrics, data element operands, program indicators, program data elements, program attributes, validation rules | 欧 |

Organisation unit identifiers, and keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL-<level> and OU_GROUP-<group-id>

Category option combinations

Category option combo identifiers (omit to get all items)

Attribute option combinations

Category option combo identifiers (omit to get all items)

分类目录

Category option identifiers (omit to get all items)

数据元素组集

Data element group identifiers (omit to get all items) Organisation unit group sets Organisation unit group identifiers (omit to get all items) Category option group sets Category option group identifiers (omit to get all items) 没有必要知道哪些对象用于设计分析查询时的各种动态维度。你可以得到通过访问 Web API 中的此 URL 获得动态维度的完整列表: /api/dimensions If you want to retrieve only the dimensional items for a given dynamic dimension you can use the example below. Pagination is disabled by default. It can be enabled by adding the pagination parameter `paging=true` to the URL. /api/dimensions/J5jldMd8OHv/items?paging=true The `/dimensions` API also provides an endpoint where the clients can get the *recomendations* for a given set of *dimensions*. For example: /api/33/dimensions/recommendations?fields=id&dimension=dx:fbfJHSPpUQD In the example above, the response will contain the categories which are configured as data dimensions and associated, through data sets and category combos, with the data element `fbfJHSPpUQD`. In addition, all org unit group sets which are configured as data dimensions will be returned. The endpoint supports multiple data elements. If one wishes to send multiple data elements, they should be separated by `;`. For example: /api/33/dimensions/recommendations?fields=id&dimension=dx:fbfJHSPpUQD;JuTpJ2Ywq5b > Note > > This endpoint returns only dimensions that can be read by the current logged user. It will check if the current user can read the data or the metadata of the respective recommended dimension. Non-authorized dimensions are omitted from the list. 分析资源的基本 URL 是`/api/analytics`。请求您可以在其上使用查询字符串的特定维度和维度项目以下格式,其中 `dim-id` 和 `dim-item` 应替换为实际值: /api/analytics?dimension=dim-id:dim-item;dim-item&dimension=dim-id:dim-item;dim-item 如上所示,维度标识符后跟一个冒号而维度项之间用分号分隔。例如,一个查询两个数据元素,两个期间和两个组织单位可以使用以下 URL 完成: /api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU &dimension=pe:2016Q1;2016Q2&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw 查询按类别选项组合细分的数据,而不是您可以在查询中包含类别维度的数据元素总计字符串,例如像这样: /api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU &dimension=co&dimension=pe:201601&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw When selecting data elements you can also select all data elements in a group as items by using the `DE_GROUP-` syntax: /api/analytics?dimension=dx:DE_GROUP-h9cuJOkOwY2 &dimension=pe:201601&dimension=ou:O6uvpzGd5pu 选择数据集报告率时,语法包含数据设置标识符后跟报告率指标: /api/analytics?dimension=dx:BfMAe6Itzgt.REPORTING_RATE;BfMAe6Itzgt.ACTUAL_REPORTS &dimension=pe:201601&dimension=ou:O6uvpzGd5pu - To query for program data elements (of tracker domain type) you can get those by specifying the program for each data element using the `.` syntax: /api/analytics.json?dimension=dx:eBAyeGv0exc.qrur9Dvnyt5;eBAyeGv0exc.GieVkTxp4HH &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd To query for program attributes (tracked entity attributes) you can get those by specifying the program for each attribute using the `.` syntax: /api/analytics.json?dimension=dx:IpHINAT79UW.a3kGcGDCuk6;IpHINAT79UW.UXz7xuGCEhU &dimension=pe:LAST_4_QUARTERS&dimension=ou:ImspTQPwCqd 要查询可以使用的组织单位组集和数据元素以下网址。请注意如何将组集标识符用作维度标识符和作为维度项的组: - /api/analytics?dimension=Bpx0589u8y0:oRVt7g429ZO;MAs88nJc9nL &dimension=pe:2016&dimension=ou:ImspTQPwCqd 要查询数据元素和类别,您可以使用此 URL。使用类别标识符作为维度标识符,类别选项作为维度项目: /api/analytics?dimension=dx:s46m5MS0hxu;fClA2Erf6IO&dimension=pe:2016 &dimension=YNZyaJHiHYq:btOyqprQ9e8;GEqzEKCHoGA&filter=ou:ImspTQPwCqd - 使用相关期间和组织单位进行查询当前用户可以使用这样的 URL: /api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU &dimension=pe:LAST_12_MONTHS&dimension=ou:USER_ORGUNIT When selecting organisation units for a dimension you can select an entire level optionally constrained by any number of boundary organisation units with the `LEVEL-` syntax. Boundary refers to a top node in a sub-hierarchy, meaning that all organisation units at the given level below the given boundary organisation unit in the hierarchy will be included in the response, and is provided as regular organisation unit dimension items. The level value can either be a numerical level or refer to the identifier of the organisation unit level entity. A simple query for all org units at level three: /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016&dimension=ou:LEVEL-3 - 具有两个边界组织单位的三级和四级查询可以是指定如下: /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016 &dimension=ou:LEVEL-3;LEVEL-4;O6uvpzGd5pu;lc3eMKXaEf When selecting organisation units you can also select all organisation units in an organisation unit group to be included as dimension items using the `OU_GROUP-` syntax. The organisation units in the groups can optionally be constrained by any number of boundary organisation units. Both the level and the group items can be repeated any number of times: /api/analytics?dimension=dx:fbfJHSPpUQD&dimension=pe:2016 &dimension=ou:OU_GROUP-w0gFTTmsUcF;OU_GROUP-EYbopBOJWsW;O6uvpzGd5pu;lc3eMKXaEf 您可以将标识符方案用于元数据部分具有 outputIdScheme 属性的分析响应,如下所示。你可以使用 ID、代码和属性作为标识符方案: /api/analytics?dimension=dx:fbfJHSPpUQD;cYeuwXTCPkU &dimension=pe:2017Q1;2017Q2&dimension=ou:O6uvpzGd5pu&outputIdScheme=CODE 指定的组织单位。 - 标识为“dx”。这意味着您可以使用任何数据元素、指标和数据集标识符以及“dx” 查询中的维度标识符。对于类别、数据元素组集和组织单元组设置维度,如果没有,将在查询中使用所有维度项 - 维度项目被指定。对于期间维度,维度项为 ISO 期间标识符和/或相对周期。请参阅部分上面称为“日期和期间格式”的期间格式和 - 可用的相对时期。 For the organization unit dimension, you can specify items as either the organization unit or its sub-units associated with the currently ### authenticated user. Use the keys `USER_ORGUNIT` for the organization unit itself or `USER_ORGUNIT_CHILDREN` for its sub-units. You may also specify organization unit identifiers directly or use a combination of both. | Potential duplicate status | for the designated organization units. If no organization unit permissions | Parameter name | will be applied instead. | |---|---|---|---| | 对于组织单位维度,您可以指定组织 | 层次结构级别和用于请求的边界单元 | 格式`LEVEL--`;举个例子 | 类型 | | 层次结构中第 3 级的边界单元。 | 对于组织单位维度,维度项是 | 组织单位及其子层次结构 - 数据将被聚合 | 类型 | | 描述 | 您不能为类别选项指定维度项目 | 组合维度。相反,响应将包含项目 | 类型 | | dx尺寸 { #webapi_analytics_dx_dimension } | `dx` 维度是一个特殊的维度,它可以包含所有的以下数据类型。 | Table: Data dx dimension types | 类型 | | Syntax | 描述 | 数据源 | 指示符 | | | Indicator identifier. | 汇总数据 | Indicator grop | | IN_GROUP- | Keyword followed by an indicator group identifier. Will include all indicators in the group in the response. | 汇总数据 | 数据元素 | | | 数据元素标识符。 | 汇总数据 | 数据元素组 | | DE_GROUP- | Keyword followed by a data element group identifier. Will include all data elements in the group in the response. | 汇总数据 | 数据元素操作数 | .. Data element identifier followed by one or both of category option combination and attribute option combo identifier. Wildcard "\*" symbol can be used to indicate any option combination value. The attribute option combination identifier can be completely left out. 汇总数据资料集 . Data set identifier followed by reporting rate metric. Can be REPORTING_RATE | REPORTING_RATE_ON_TIME | ACTUAL_REPORTS | ACTUAL_REPORTS_ON_TIME | EXPECTED_REPORTS. Data set completeness registrations ### 项目数据元素 . - 临界点 - Not like, ignoring case (free text match) - E7126 - 组织单位分析资源使您可以指定一系列查询参数: - One or more headers name separated by comma - page - Table: Org unit analytics query parameters Validation rule identifier. Will include validation rule violations for the validation rule, requires that validation results are generated and persisted. Validation results Items from all of the various `dx` types can be combined in an analytics request. An example looks like this: /api/analytics.json ?dimension=dx:Uvn6LCg7dVU;BfMAe6Itzgt.REPORTING_RATE;IpHINAT79UW.a3kGcGDCuk6 &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd 组语法也可以与任何其他项目一起使用。一个示例如下所示: /api/analytics.json ?dimension=dx:DE_GROUP-qfxEYY9xAl6;IN_GROUP-oehv9EO3vP7;BfMAe6Itzgt.REPORTING_RATE &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd 数据元素操作数可以选择性地指定属性选项组合并使用通配符,例如指定所有类别选项组合值: ### /api/analytics.json ?dimension=dx:Uvn6LCg7dVU.*.j8vBiBqGf6O;Uvn6LCg7dVU.Z4oQs46iTeR &dimension=pe:LAST_12_MONTHS&filter=ou:ImspTQPwCqd > **Tip** > > A great way to learn how to use the analytics API is to use the DHIS2 > Data Visualizer web app and create a pivot table. You can play around > with pivot tables using the various dimensions and items and click > **Download** > **Plain data source** > **JSON** to see the resulting analytics > API calls in the address bar of your web browser. 回应格式 { #webapi_analytics_response_formats } 包含聚合数据的分析响应可以在各种表现形式。像往常一样,您可以表示对某个项目感兴趣通过将文件扩展名附加到 URL,通过 `Accept` HTTP 标头或通过 `format` 查询参数。这默认格式为 JSON。可用的格式和内容类型是下面列出。 | json(应用项目/ json) | Validation report | | ---------- | ------- | | xml(应用项目/ xml) | csv(应用项目/ csv) | | html(text / html) | html + css(text / html) | | xls(application / vnd.ms-excel) | 例如,要请求 XML 格式的分析响应,您可以使用以下网址: | | /api/analytics.xml?dimension=dx:fbfJHSPpUQD &dimension=pe:2016&dimension=ou:O6uvpzGd5pu;lc3eMKXaEfw | JSON响应如下所示: | | ```json { "headers": [ { "name": "dx", "column": "Data", "valueType": "TEXT", "meta": true }, { "name": "pe", "column": "Period", "valueType": "TEXT", "meta": true }, { "name": "value", "column": "Value", "valueType": "NUMBER", "meta": false } ], "height": 4, "metaData": { "pe": [ "2016Q1", "2016Q2" ], "ou": [ "ImspTQPwCqd" ], "names": { "2016Q1": "Jan to Mar 2016", "2016Q2": "Apr to Jun 2016", "FbKK4ofIv5R": "Measles Coverage <1 y", "ImspTQPwCqd": "Sierra Leone", "eTDtyyaSA7f": "Fully Immunized Coverage" } }, "rows": [ [ "eTDtyyaSA7f", "2016Q2", "81.1" ], [ "eTDtyyaSA7f", "2016Q1", "74.7" ], [ "FbKK4ofIv5R", "2016Q2", "88.9" ], [ "FbKK4ofIv5R", "2016Q1", "84.0" ] ], "width": 3 } ``` | 响应表示维度数据表。 *headers* 数组概述了表中包含哪些列以及哪些列列包含。 *column* 属性显示列维度标识符,或者如果列包含度量,则为“值”一词。这 *meta* 属性为 *true* 如果列包含维度项或 *false* 如果列包含度量(聚合数据值)。这 *name* 属性类似于 column 属性,不同之处在于它显示如果列包含度量,则为“值”。 *type* 属性表示列值的 Java 类类型。 | | *height* 和 *width* 属性表示有多少数据列和行分别包含在响应中。 | *metaData period* 属性包含一个唯一的有序数组响应中包含的时间段。 *metaData ou* 属性包含一个响应中包含的组织单位标识符数组。 *metaData names* 属性包含标识符之间的映射用于数据响应和它们代表的对象的名称。客户端可以使用它来替换数据中的标识符响应名称以提供更有意义的数据视图桌子。 | | *rows* 数组包含维度数据表。它包含具有维度项(对象或期间标识符)和一列的列具有聚合数据值。上面的示例响应有一个数据/指标列、期间列和值列。首先列包含指标标识符,第二列包含 ISO 句点标识符,第三个包含聚合数据值。 | 约束与验证 { #webapi_analytics_constraints } | | 您可以提供给分析资源。如果违反任何约束,API 将返回一个 *409 Conflict* 响应和一个类似于下面的响应消息: | ```json { "httpStatus": "Conflict", "httpStatusCode": 409, "status": "ERROR", "message": "Only a single indicator can be specified as filter", "errorCode": "E7108" } ``` | | `httpStatus` 和 `httpStatusCode` 字段表示 HTTP 状态和根据 HTTP 规范的状态代码。 `message` 字段提供了一个验证错误的人类可读描述。 `errorCode` 字段提供一个机器可读的代码,客户端可以使用它来处理验证错误。聚合分析的可能验证错误 API 如下表所述。 | 错误代码 | | 信息 | E7100 | | 查询参数不能为空 | E7101 | | 必须至少指定一个尺寸 | 事件聚类分析 { #webapi_event_clustering_analytics } | | 必须至少指定一个数据维项目或数据元素组集合维项目 | E7103 | | 尺寸不能同时指定为尺寸和过滤器 | E7104 | | 必须至少指定一个期间作为维度或过滤器,或者开始和日期 | E7105 | | 不能同时指定期间,开始日期和结束日期 | E7106 | | 开始日期不能晚于结束日期 | E7107 | | 无法为报告费率指定开始日期和结束日期 | E7108 | | 只能将一个指标指定为过滤器 | E7109 | | 只能将单个报告率指定为过滤器 | E7110 | | 类别选项组合不能指定为过滤器 | E7111 | | 尺寸不能多次指定 | E7112 | | 只能与类型的尺寸一起指定报告率 | E7113 | | 未指定数据元素时无法指定分配的类别 | E7114 | | 指定的类别只能与数据元素一起指定,不能与指标或报告率一起指定 | E7115 | | 数据元素必须具有允许聚合的值和聚合类型 | E7116 | | 指标表达式不能包含循环引用 | E7117 | | 当输出格式为DATA_VALUE_SET时,必须指定数据尺寸“ dx” | E7118 | | 当输出格式为DATA_VALUE_SET时,必须指定期间尺寸“ pe” | E7119 | | 当输出格式为DATA_VALUE_SET时,必须指定组织单位维度“ ou” | E7120 | | 不允许用户查看组织单位 | E7121 | | 不允许用户读取对象的数据 | E7122 | ### 数据批准级别不存在 E7123 当前用户受维度限制,但无权访问任何维度项目 E7124 维度存在于查询中,没有任何有效的维度选项您可以从原始数据值集格式中检索数据数据值集资源: - 临界点 - E7126 列必须作为查询中的维存在 - E7127 - 行必须作为查询中的维存在 - E7128 查询结果集超出最大限制 E7129 项目已指定但不存在 E7130 已指定项目阶段,但不存在 E7131 查询失败,可能是因为查询超时 ### 数据值设定格式 { #webapi_analytics_data_value_set_format } 分析 *dataValueSet* 资源允许返回聚合数据值集格式的数据。这种格式代表原始数据值,而不是按照各种方式汇总的数据方面。将聚合数据导出为常规数据值很有用当目标系统包含数据时,用于系统之间的数据交换与目标系统存储的内容相比具有更精细的粒度。例如,可以在目标系统中指定一个指标来汇总多个数据元素的数据并将此数据导入目标系统中的单个数据元素。再举一个例子,一个可以汇总在目标的组织单位级别 4 收集的数据系统级别 2 并将该数据导入目标系统。您可以从原始数据值集格式中检索数据数据值集资源: - 临界点 - 组织单位分析资源使您可以指定一系列查询参数: json(应用项目/ json) 选项值 | eventCreatedPeriod | 资料(dx) | |---|---| | 周期(pe) | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | dueDate | A request which aggregates data for data element operands and uses `CODE` as output identifier scheme looks like the below. When defining the output identifier scheme, all metadata objects part of the response are affected: | | lastUpdatedDate | A request which aggregates data for data element operands and uses `CODE` as output identifier scheme looks like the below. When defining the output identifier scheme, all metadata objects part of the response are affected: | | 不 | Program notification template | | 不 | Program notification template | | stage | Program notification template | | Custom period on `incidentDate`. See "custom date periods" section. | Program notification template | | Custom period on `lastUpdated`. See "custom date periods" section. | Program notification template | | ```json { "httpStatus": "OK", "httpStatusCode": 200, "status": "OK", "response": { "responseType": "ObjectReport", "uid": "pG4bBTMiCqO", "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange", "errorReports": [] } } ``` | Program notification template | | Required / Notes | Program notification template | | 是的 | Program notification template | | The name of the headers to be returned as part of the response. One or more headers name separated by comma | Program notification template | | 不 | Program notification template | 不 skipData 不 hierarchyMeta 不 showHierarchy 不 displayProperty 不 outputIdScheme 不 ### outputOrgUnitIdScheme 不 outputDataElementIdScheme ## 不 inputIdScheme 不 ### userOrgUnit 不 *dimension* 查询参数定义了哪些维度(表列) 应包含在响应中。它可以选择性地受到约束与项目。 *filter* 查询参数定义了哪些项目和维度(表格列)应用作响应的过滤器。 | /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &columns=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP &pageSize=10&page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS | 值不引用数字元素或项目一部分的数据元素或属性 | Parameter name | |---|---|---| | *startDate* 和 *endDate* 参数允许获取链接的数据到这些日期之间的任何时间段。这避免了定义所有期间明确在要求: | 维度不是有效的查询项目 | *filter* 参数可用于过滤响应,而无需包括该维度作为响应的一部分,这次是在 CSV 中格式: | | createdAtClient | 维度不是有效的查询项目 | E7227 | | 来自 *rawData* 资源的响应看起来与定期分析资源;不同之处在于响应包含原始的、非聚合的数据,适合进一步聚合第三方系统。 | E7228 | Fallback coordinate field is invalid | | E7229 | Filter on whether the current user can manage the returned users through the managed user group relationships. | 组织单位标识符和关键字 USER_ORGUNIT、USER_ORGUNIT_CHILDREN、USER_ORGUNIT_GRANDCHILDREN、LEVEL- 和 OU_GROUP- 。它可以分阶段运行，即：`A03MvHHogjR.ou`。 | | /api/analytics/events | 尺寸和项目 { #webapi_event_analytics_dimensions_items } | 事件维度包括数据元素、属性、组织单位和时期。聚合的事件分析资源将返回聚合信息,例如计数或平均值。查询分析资源将简单地返回匹配一组条件的事件,并且不会不执行任何聚合。您可以在表单中指定维度项来自选项集的选项和来自数据图例集的图例与此相关的元素和属性。事件尺寸如下表所示。 | | Table: Dimensions and dimension items | 尺寸 | Dimension id | ### 描述资料元素 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | Attribute identifiers | |---|---|---|---| | `{ "periodFrom": -15, "periodTo": 15}` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | LT | 组织单位 | | 欧 | Program notification template | Organisation unit group sets | | | dueDate | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | Event chart view | | lastUpdatedDate | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Table: Query parameters for both event query and aggregate analytics | Event chart view | | 周期(pe) | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Table: Query parameters for enrollment query endpoint | 查询参数 | | 数据值 | Program notification template | 任何项目标识符 || | stage | Program notification template | Program stage identifier. | 假 | | `"displayOrderColumns": ["enrollmentDate", "program"]` | Program notification template | Start date for events. | outputIdScheme | | 结束日期 | Program notification template | NAME | SHORTNAME | includeMetadataDetails | | 描述 | 不区分大小写的字符串结尾匹配 | Program notification template | Date in yyyy-MM-dd format | | 不 | Program notification template | 维度标识符包括数据元素、属性、期间、组织单位和组织单位组集。参数可以重复任意次数。项目过滤器可以应用于维度,格式为::。过滤器值不区分大小写。 | hierarchyMeta | | 不 | Program notification template | false | true | hierarchyMeta | | 不 | Program notification template | ACTIVE | COMPLETED | SCHEDULE | OVERDUE | SKIPPED. Can be comma separated (*for query only*). | 项目状态 | ** 在某些情况下，可以通过 `dimension` 参数请求特定字段。它们不是真正的维度，但提供了更好的灵活性。它们是 #### 事件日期 (`EVENT_DATE`) 根据事件发生的日期进行筛选。可用作根级维度或特定阶段的范围。 | 价值形式 | 描述 | 意义 | |---|---|---| | `{stageUid}.event_date:{period}` | `dimension=A03MvHHogjR.EVENT_DATE:202205`. | 阶段 "A03MvHHogjR "中的事件，事件发生日期为 2022 年 5 月。 | | `{stageUid}.event_date:{start}_{end}` | `dimension=A03MvHHogjR.EVENT_DATE:2022-05-01_2022-05-10` | 该阶段中事件日期在给定包含日期范围内的事件。 | | `event_date:{period}` | `dimension=EVENT_DATE:2022Sep`(事件日期：2022 年 9 月) | 使用财政年度过滤根级事件日期。 | #### 预定日期 (`SCHEDULED_DATE`) 根据事件的计划日期（而不是实际发生日期）进行筛选。此外，它还可以扩展到特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | `scheduled_date:{period}` | `dimension=SCHEDULED_DATE:202107` | 活动处于既定阶段，预定日期为 2021 年 7 月。 | #### 创建日期 (`CREATED`) 根据报名记录在系统中创建的时间进行筛选。此外，它还可以针对特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | `CREATED:{period}` | dimension=CREATED:2016Sep | 自 2016 年 9 月起的财政年度内创建的注册人数。 | #### 完成日期 (`COMPLETED`) 根据注册被标记为完成的时间进行筛选。此外，它还可以扩展到特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | 完成：{period}` | 尺寸=COMPLETED:2022年9月 | 自 2022 年 9 月起的财政年度内完成的注册。 | #### 事件状态 (`EVENT_STATUS`) 根据阶段内事件的状态进行筛选。 | 价值形式 | 描述 | 意义 | |---|---|---| | `{stageUid}.event_status:{status}` | `dimension=A03MvHHogjR.EVENT_STATUS:ACTIVE`. | 阶段中状态为 "ACTIVE "的事件。 | | `{stageUid}.event_status:{s1};{s2}` | `dimension=edqlbukwRfQ.EVENT_STATUS:COMPLETED;ACTIVE`. | 状态为 `COMPLETED` **或** `ACTIVE` 的事件（OR 逻辑）。 | 有效状态值：活动"、"已完成"、"已排定"、"逾期"、"已跳过"。 #### 程序状态 (`PROGRAM_STATUS`) 根据注册本身的状态（而不是单个事件）进行筛选。 | 价值形式 | 描述 | 意义 | |---|---|---| | `program_status:{status}` | dimension=PROGRAM_STATUS:ACTIVE | 仅指具有指定计划状态的注册人数。 | 有效状态值：活动"、"已完成"、"已取消"。不 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | 用户设置 { #webapi_user_settings } | |---|---|---|---| | `{"type":"RELATIVE","period":"TODAY"}` | Program notification template | 列 | 不 | | Dimensions to use as columns for table layout. | Program notification template | rows | 不 | | filter | Program notification template | timeField | 不 | | 不 | Program notification template | Table: Query parameters for event query analytics only | 假 | | 需要 | Program notification template | 选项 | 假 | | 不 | Program notification template | DESCENDANTS, CHILDREN, SELECTED | pageSize | | Start date for interval tocheck for outliers | Program notification template | 选项(默认为默认) | ouMode | | 定义要返回的页码。 | Program notification template | `ouname` | `programstatus` | `eventstatus` | `createdbydisplayname` | `lastupdatedbydisplayname` | `eventdate` | `enrollmentdate` | `incidentdate` | `lastupdated` | item identifier | asc | | 定义每页返回的元素数量。 | Program notification template | false | true | coordinateOuFallback | | "assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"] | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | false | true | pageSize | | The *analytics/trackedEntities/query* endpoint provides queries for captured TEs, allowing querying and filtering for information related to TEs, along with their respective enrollments and events. It does not perform any aggregation. | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | NAME | CODE | UID | pageSize | | You can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of the data elements in program stages, program attributes, tracked entity attributes, fixed and relative periods, and organization units. Dimensions can optionally have a query operator and a filter. TEs queries should be in the format described below. | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | One or more headers name separated by comma | pageSize | | For example, to retrieve TEs of type `Person` from the "Child Program" and "Antenatal care" programs, where the "First name" is "James": | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | Numeric positive value | pageSize | | 不 | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | Numeric zero or positive value | pageSize | no | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | 用户设置 { #webapi_user_settings } | |---|---|---|---| | 日期时间 | Program notification template | scheduledDate | 数据元素或属性标识符。它可以是阶段范围，即：`value=stageId.dimensionid`。 | | Events resource only. Custom period on `scheduledDate`. See "custom date periods" section. | Program notification template | incidentDate | no | | Custom period on `incidentDate`. See "custom date periods" section. | Program notification template | lastUpdated | 假 | | Custom period on `lastUpdated`. See "custom date periods" section. | Program notification template | `DESCENDANTS`, `CHILDREN`, `SELECTED` | 查询参数 | | 这种访问级别的限制稍多一些。受保护项目中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。只有当所有者组织单位属于用户的捕获范围时,用户才能访问受保护项目内的数据。但是,如果用户用户可以通过 [打破玻璃](#webaptrl) 获得临时所有权。玻璃](#webapi_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。他们为什么要访问手头的数据。然后,系统会将理由和访问审核记录在案,并提供 3 个月的临时访问权限。访问审计日志,并为用户提供 3 小时的临时访问权限。请注意,打破玻璃时时,所有者组织单位保持不变,只有打碎玻璃的用户才能获得临时访问权。获得临时访问权。 | Program notification template | 选项 | 价值 | | 不 | Program notification template | Data element or attribute identifier | asc | | 不 | Program notification template | SUM | AVERAGE | AVERAGE_SUM_ORG_UNIT | LAST | LAST_AVERAGE_ORG_UNIT | COUNT | STDDEV | VARIANCE | MIN | MAX | showHierarchy | | 不 | Program notification template | false | true | 假 | | 不 | Program notification template | NAME | SHORTNAME | 假 | | 不 | Program notification template | ASC | DESC | 假 | | sortOrder | Program notification template | Numeric positive value | 假 | | 不 | Program notification template | EVENT | ENROLLMENT | TRACKED_ENTITY_INSTANCE | 假 | | 事件聚合资源不返回事件信息本身,而不是与请求匹配的事件总数询问。事件维度包括数据元素、人员属性、人员标识符、期间和组织单位。聚合事件查询应该是下面描述的格式。 | Program notification template | false | true | skipMeta | 不 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | 用户设置 { #webapi_user_settings } | |---|---|---|---| | Exclude the data part of the response. | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | skipRounding | asc | | Skip rounding of aggregate data values. | Program notification template | aggregateData | 不 | | Produce aggregate values for the data dimensions (as opposed to dimension items). | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | orgUnitField | 具有以下要求: | | The organisation unit field to base event aggregation on. Applies to event data items only. Can be the ID of an attribute or data element with the Organisation unit value type. The default option is specified as omitting the query parameter. | Program notification template | Table: Query parameters for cluster event analytics only | 假 | ### 需要描述选项 clusterSize 是的 Size of clusters in meters. Numeric positive value coordinateField 不 Field to base geospatial event analytics on. Default is event. Can be set to identifiers of attributes and data elements of value type coordinate. EVENT | | bbox 是的 #### Enrollment Organisation units 串 includeClusterPoints 不 Include information about underlying points for each cluster, be careful if cluster represent a very high number of points. false | true 注册查询分析 { #webapi_enrollment_query_analytics } *analytics/events/query* 资源可让您查询捕获的事件。此资源不执行任何聚合,而是让您查询和过滤有关事件的信息。 /api/analytics/enrollments/query 例如,您可以过滤“ Weight”数据元素以获取大于2000且小于4000的值,如下所示: /api/analytics/events/query/?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd &dimension=ou:;&dimension=&dimension=:: | 所需值 | Parameter name | |---|---| | 检索“Child”的“Birth”项目阶段的事件 2016 年 3 月至 12 月期间的“计划”计划,其中“重量” 数据元素,过滤大于 2000年: | /api/analytics/events/query/IpHINAT79UW?stage=A03MvHHogjR&startDate=2016-03-01 &endDate=2016-12-31&dimension=ou:O6uvpzGd5pu&dimension=UXz7xuGCEhU:GT:2000 | | 排序可以应用于查询事件的事件日期和任何尺寸。按事件日期降序和升序排序您可以使用的“年龄”数据元素维度用: | /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5 | | 分页可以通过指定页码和页面大小参数。如果指定了页码但未指定页面大小, 将使用 50 的页面大小。如果指定了页面大小但页面 number 不是,将使用页码 1。获取第三页页面大小为 20 的响应,您可以使用类似的查询这: | /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&page=3&pageSize=20 | | Filtering | 过滤器可以应用于数据元素,人员属性和人员标识符。过滤是通过以下格式的查询参数值完成的: | | &dimension = :: | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | &dimension = UXz7xuGCEhU:GT:2000&dimension = UXz7xuGCEhU:LT:4000 | 您可以使用以下方法过滤多个特定年龄的“年龄”数据元素像这样的 IN 运算符: | | &dimension = qrur9Dvnyt5:IN:18; 19; 20 | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | &dimension = qrur9Dvnyt5:GT:5:LT:15 | Filter by AGE is not null | | &dimension=qrur9Dvnyt5:NE:NV | /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5 | | &dimension=qrur9Dvnyt5:IN:18;19;NV | `NV` can be used with `EQ`, `NE` and `IN` operators | | Equal to | !EQ | | Not equal to | IEQ | | Equal to, ignoring case | !IEQ | | Operators | GT | #### Greater than GE Greater than or equal to #### LT Less than LE !LIKE NE Not equal to `` Like (free text match) !LIKE Not like (free text match) #### 欧 Like, ignoring case (free text match) - 临界点 - Not like, ignoring case (free text match) - Table: Org unit analytics query parameters Equal to one of multiple values separated by ";" Time Field Filtering By default, the `query` endpoints filter periods based on `eventDate`. However, it is possible to filter entries based on `lastUpdated` or `schedule` instead, by using the `timeField` query parameter. For example: &timeField=LAST_UPDATED &timeField=SCHEDULED_DATE Numeric positive value By default `enhancedConditions` flag is set to `false`. This means all conditions expressed in `dimension` and `filter` are meant as `AND` conditions. For example: dimension=a:GT:20:LT:40&dimension=b:GT:1:LT:5 translates into the following logical condition: a>20 and a<40 and b>1 and b<5 However, there are cases in which more control on conditions might be needed and can be enabled by setting `enhancedConditions` query parameter to `true`. By doing so, a client can use a special `_OR_` separator to join conditions using `OR` logical operator. 例: ### dimension=a:GT:20:LT:40_OR_b:GT:1:LT:5&dimension=c:EQ:test translates into the following logical condition: ((a>20 and a<40) or (b>1 and b<5)) and c = "test" Response formats 默认的响应表示格式是 JSON。请求必须使用 HTTP *GET* 方法。支持以下响应格式。 json(应用项目/ json) jsonp(应用项目/ javascript) xls(application / vnd.ms-excel) 例如,要获得Excel格式的响应,可以在请求URL中使用文件扩展名,如下所示: /api/analytics/events/query/eBAyeGv0exc.xls?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=oZg33kd9taw&dimension=qrur9Dvnyt5 您可以将hierarchyMeta 查询参数设置为true,以便在元部分中包括所有祖先组织单位的名称响应: /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:YuQRtpLP10I&dimension=qrur9Dvnyt5:EQ:50&hierarchyMeta=true 默认响应JSON格式将类似于以下内容:

{
  "headers": [
    {
      "name": "psi",
      "column": "Event",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ps",
      "column": "Program stage",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "eventdate",
      "column": "Event date",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "storedby",
      "column": "Stored by",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdated",
      "column": "Last Updated",
      "valueType": "DATE",
      "hidden": false,
      "meta": true
    },
    {
      "name": "createdbydisplayname",
      "column": "Created by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "lastupdatedbydisplayname",
      "column": "Last updated by (display name)",
      "valueType": "TEXT",
      "hidden": false,
      "meta": true
    },
    {
      "name": "coordinates",
      "column": "Coordinates",
      "valueType": "COORDINATE",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ouname",
      "column": "Organisation unit name",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "oucode",
      "column": "Organisation unit code",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "ou",
      "column": "Organisation unit",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "oZg33kd9taw",
      "column": "Gender",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    },
    {
      "name": "qrur9Dvnyt5",
      "column": "Age",
      "valueType": "TEXT",
      "hidden": false,
      "meta": false
    }
  ],
  "metaData": {
    "names": {
      "qrur9Dvnyt5": "Age",
      "eBAyeGv0exc": "Inpatient morbidity and mortality",
      "ImspTQPwCqd": "Sierra Leone",
      "O6uvpzGd5pu": "Bo",
      "YuQRtpLP10I": "Badjia",
      "oZg33kd9taw": "Gender"
    },
    "ouHierarchy": {
      "YuQRtpLP10I": "/ImspTQPwCqd/O6uvpzGd5pu"
    }
  },
  "width": 8,
  "height": 4,
  "rows": [
    [
      "yx9IDINf82o",
      "Zj7UnCAulEk",
      "2016-08-05",
      "system",
      "2018-08-07",
      "[5.12, 1.23]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "IPNa7AsCyFt",
      "Zj7UnCAulEk",
      "2016-06-12",
      "system",
      "2018-08-07",
      "[5.22, 1.43]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "ZY9JL9dkhD2",
      "Zj7UnCAulEk",
      "2016-06-15",
      "system",
      "2018-08-07",
      "[5.42, 1.33]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ],
    [
      "MYvh4WAUdWt",
      "Zj7UnCAulEk",
      "2016-06-16",
      "system",
      "2018-08-07",
      "[5.32, 1.53]",
      "Ngelehun",
      "OU_559",
      "YuQRtpLP10I",
      "Female",
      "50"
    ]
  ]
}

响应的* header *部分描述了查询的内容结果。事件唯一标识符,项目阶段标识符, 活动日期,组织单位名称,组织单位代码和组织单位标识符显示为的前六个维度回应,并将永远存在。接下来是数据元素指定为的人员属性和人员标识符请求中的尺寸,在这种情况下,为“性别”和“年龄”数据元素尺寸。标头部分包含 “名称”属性中的尺寸项目和可读尺寸 “列”属性中的说明。 *metaData* 部分,*ou* 对象包含映射到表示层次结构的字符串的响应中存在的所有组织单位的标识符。此层次结构字符串从根开始列出组织单位的祖先(父)的标识符。 *names* 对象包含响应中映射到其名称的所有项目的标识符。 *rows* 部分包含查询产生的事件。每一行正好代表一个事件。为了让事件分析资源在一个现成的表格的形状,你可以提供*行*和*列* 具有请求的维度标识符的参数以分号分隔作为值来指示哪些用作表列和行。事件不是生成一个普通的、规范化的数据源分析资源现在将生成表格布局中的数据。这列和行维度必须作为数据维度出现在查询(不是过滤器)。这样的请求可能如下所示: /api/analytics.html+css?dimension=dx:cYeuwXTCPkU;fbfJHSPpUQD&dimension=pe:WEEKS_THIS_YEAR &filter=ou:ImspTQPwCqd&displayProperty=SHORTNAME&columns=dx&rows=pe 事件汇总分析 { #webapi_event_aggregate_analytics } `/analytics/events/aggregate` 资源可让您检索 *aggregated DHIS2 中捕获的事件数量*。此资源可让您检索基于项目和可选的项目阶段聚合数据,以及允许您过滤任何事件维度。 /api/analytics/events/aggregate | 事件聚合资源不返回事件信息本身,而不是与请求匹配的事件总数询问。事件维度包括数据元素、人员属性、人员标识符、期间和组织单位。聚合事件查询应该是下面描述的格式。 | Parameter name | | --- | --- | | 例如,要从 1 月至 10 月期间的“住院发病率和死亡率”计划 2016 年,其中包含“性别”和“年龄”数据元素,“年龄” 维度项目在“18”上过滤,“性别”项目在过滤上 “女性”,您可以使用以下查询: | /api/analytics/events/aggregate/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=oZg33kd9taw:EQ:Female&dimension=qrur9Dvnyt5:GT:50 | | 检索固定和相对时期的数据,而不是开始和结束日期,在本例中为 2016 年 5 月和过去 12 个月,以及组织与当前用户关联的单位,可以使用以下查询: | /api/analytics/events/aggregate/eBAyeGv0exc?dimension=pe:201605;LAST_12_MONTHS &dimension=ou:USER_ORGUNIT;fdc6uOvgo7ji&dimension=oZg33kd9taw | | 为了将“女性”指定为数据的“性别”过滤器响应,意思是“性别”不会是响应的一部分,但会过滤其中的聚合数字,您可以使用以下语法: | /api/analytics/events/aggregate/eBAyeGv0exc?dimension=pe:2016; &dimension=ou:O6uvpzGd5pu&filter=oZg33kd9taw:EQ:Female | | PERIOD_STRUCTURE | /api/analytics/events/aggregate/eBAyeGv0exc?filter=pe:2016&filter=ou:O6uvpzGd5pu &dimension=fWIAEtYVEGk&dimension=oZg33kd9taw:EQ:Male | | 要为_出院模式_创建“前 3 名报告”,您可以使用限制和 sortOrder 查询参数类似: | /api/analytics/events/aggregate/eBAyeGv0exc?filter=pe:2016&filter=ou:O6uvpzGd5pu &dimension=fWIAEtYVEGk&limit=3&sortOrder=DESC | | 要指定具有相应聚合类型的值维度,您可以使用 value 和aggregationType 查询参数。指定一个值维度将使分析引擎返回聚合值对于响应中该维度的值,而不是计数事件。 | /api/analytics/events/aggregate/eBAyeGv0exc.json?stage=Zj7UnCAulEk &dimension=ou:ImspTQPwCqd&dimension=pe:LAST_12_MONTHS&dimension=fWIAEtYVEGk &value=qrur9Dvnyt5&aggregationType=AVERAGE | #### 基于特定数据元素或属性的事件分析聚合对于值类型日期或日期时间,您可以使用 `timeField` 参数: /api/analytics/events/aggregate/IpHINAT79UW.json?dimension=ou:ImspTQPwCqd &dimension=pe:LAST_12_MONTHS&dimension=cejWyOfXge6&stage=A03MvHHogjR &timeField=ENROLLMENT_DATE 基于特定数据元素或属性的事件分析聚合对于值类型的组织单元,您可以使用 `orgUnitField` 参数: /api/analytics/events/aggregate/eBAyeGv0exc.json?dimension=ou:ImspTQPwCqd &dimension=pe:THIS_YEAR&dimension=oZg33kd9taw&stage=Zj7UnCAulEk &orgUnitField=S33cRBsnXPo The `orgUnitField` parameter value may be one of the following: #### 欧描述 ID of an attribute with the organisation unit value type ### ID of a data element with the organisation unit value type REGISTRATION The organization unit at which the tracked entity instance was registered (created) 注册 ### The organization unit at which the tracked entity instance was enrolled in the program OWNER_AT_START The tracked entity instance's owning organisation unit at the start of the reporting period OWNER_AT_END The tracked entity instance's owning organisation unit at the end of the reporting period ### Ranges / legend sets 对于聚合查询,您可以为数值指定范围/图例集数据元素和属性维度。目的是将数值范围内。举个例子,而不是生成数据对于不同年份的“年龄”数据元素,您可以将年龄组的信息。为了实现这一点,数据元素或属性必须与图例集相关联。格式是如下面所描述的: ?dimension = - 一个示例如下所示: | json(应用项目/ json) | Validation report | | ---------- | ------- | | 默认的响应表示格式是 JSON。请求必须是使用 HTTP *GET* 方法。响应将类似于以下内容: | 默认响应使用单个 `count` 列进行标准化。通过使用 `columns` 查询参数指定至少一个组织单位组集,可以在表格布局中呈现响应。 | | 请注意,单个响应中返回的行的最大限制为 10 000。如果查询产生超过最大限制,*409 Conflict* 状态代码将被退回。 | 事件聚类分析 { #webapi_event_clustering_analytics } | | *analytics/events/cluster* 资源提供集群地理空间事件数据。请求如下所示: | /api/analytics/events/cluster/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:LEVEL-2&clusterSize=100000 &bbox=-13.2682125,7.3721619,-10.4261178,9.904012&includeClusterPoints=false | | 集群响应提供基础点的计数,中心每个集群的点和范围。如果 `includeClusterPoints` 查询参数设置为 true,以逗号分隔的字符串与标识符包括基础事件。示例响应如下所示: | ```json { "headers": [ { "name": "count", "column": "Count", "valueType": "INTEGER", "meta": false }, { "name": "center", "column": "Center", "valueType": "TEXT", "meta": false }, { "name": "extent", "column": "Extent", "valueType": "TEXT", "meta": false }, { "name": "points", "column": "Points", "valueType": "TEXT", "meta": false } ], "width": 3, "height": 4, "rows": [ [ "3", "POINT(-13.15818 8.47567)", "BOX(-13.26821 8.4St7215,-13.08711 8.47807)", "" ], [ "9", "POINT(-13.11184 8.66424)", "BOX(-13.24982 8.51961,-13.05816 8.87696)", "" ], [ "1", "POINT(-12.46144 7.50597)", "BOX(-12.46144 7.50597,-12.46144 7.50597)", "" ], [ "7", "POINT(-12.47964 8.21533)", "BOX(-12.91769 7.66775,-12.21011 8.49713)", "" ] ] } ``` | | 事件计数和范围分析 { #webapi_event_count_extent_analytics } | The *analytics/events/count* resource is suitable for geometry-related requests for retrieving the count and extent (bounding box) of events for a specific query. The query syntax is equal to the *events/query* resource. A request looks like this: | | /api/analytics/events/count/eBAyeGv0exc?startDate=2016-01-01 &endDate=2016-10-31&dimension=ou:O6uvpzGd5pu | 响应将以JSON格式提供计数和范围: | | ```json { "extent": "BOX(-13.2682125910096 7.38679562779441,-10.4261178860988 9.90401290212795)", "count": 59 } ``` | 约束与验证 { #webapi_event_analytics_constraints } | | 您可以提供给事件分析资源。如果违反任何约束,API 将返回一个 *409 Conflict* 响应和一个类似于下面的响应消息: | ```json { "httpStatus": "Conflict", "httpStatusCode": 409, "status": "ERROR", "message": "At least one organisation unit must be specified", "errorCode": "E7200" } ``` | | 描述了事件分析 API 的可能验证错误在下表中。 | 错误代码 | | 信息 | E7200 | | 必须至少指定一个组织单位 | E7201 | | 尺寸不能多次指定 | E7202 | | 不能多次指定查询项 | E7203 | | 值维也不能指定为项目或项目过滤器 | E7204 | | 指定聚合类型时,必须指定值维或聚合数据 | E7205 | | 必须指定开始和结束日期或至少一个期间 | E7206 | | 开始日期晚于结束日期 | E7207 | | 页码必须为正数 | E7208 | | 页面大小必须为零或正数 | E7209 | | 限制大于最大限制 | E7210 | | 时间字段无效 | E7211 | | 组织单位字段无效 | E7212 | | 群集大小必须为正数 | E7213 | | Bbox无效,必须采用以下格式:'min-lng,min-lat,max-lng,max-lat' | E7214 | | 当指定bbox或集群大小时,必须指定集群字段 | E7215 | | 查询项目不能同时指定图例集和选项集 | E7216 | | 在汇总查询中使用时,查询项必须是可汇总的 | E7217 | | 不允许用户查看事件分析数据 | E7218 | | 未启用空间数据库支持 | E7219 | | 数据元素必须是值类型坐标才能用作坐标字段 | E7220 | | E7230 | 页眉参数不存在 | | E7231 | 遗产只能通过事件可视化进行更新 | | E7232 | E7219 | | E7234 | 查询过滤器对查询项目值类型无效 | | E7235 | 必须指定 programId 或 programStageId | | E7236 | 程序阶段与程序无关 | | E7237 | 排序必须有有效的维度和方向 | | E7238 | 排序维度不是列 | | E7239 | 空 "值的运算符无效 | | E7240 | 具有组织单位所有权的事件查询不支持时间字段 | | E7241 | 阶段参数不能与特定阶段的维度标识符一起使用 | | E7242 | 周期维度不能与特定阶段的日期维度（即：EVENT_DATE、SCHEDULED_DATE）一起使用 | | E7243 | 重复的阶段标注标识符 | | E7244 | 不允许在特定阶段的尺寸中设置多个阶段 | | E7245 | 程序阶段不属于程序 | ## 属性必须是坐标值类型,才能用作坐标域 E7221 ### 座标栏位无效 E7222 查询项目或过滤器无效 | /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &columns=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP &pageSize=10&page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS | 值不引用数字元素或项目一部分的数据元素或属性 | Parameter name | |---|---|---| | 项目标识符未引用项目的任何数据元素,属性或指标部分 | E7225 | 计划阶段对于注册分析查询中的数据元素维度是必需的 | | createdAtClient | 维度不是有效的查询项目 | E7227 | | 来自 *rawData* 资源的响应看起来与定期分析资源;不同之处在于响应包含原始的、非聚合的数据,适合进一步聚合第三方系统。 | E7228 | Fallback coordinate field is invalid | | E7229 | Filter on whether the current user can manage the returned users through the managed user group relationships. | 入学分析 { #webapi_enrollment_analytics } | #### 注册分析 API 允许您访问聚合事件数据并查询*注册及其在 DHIS2 中捕获的事件数据*。除了跟踪的实体属性之外,此资源还允许您根据项目阶段和数据元素检索项目的数据。在每个注册中查询特定项目阶段的事件数据时,每个项目阶段的数据元素值将作为来自 api 的响应中的一行返回。如果在可重复的项目阶段查询数据元素,则最新的数据元素值将用于 api 响应中的该数据元素。尺寸和项目 { #webapi_enrollment_analytics_dimensions } 注册维度包括数据元素,属性,组织单位和期间。查询分析资源将仅返回符合一组条件的注册,并且不执行任何汇总。 | /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &columns=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP &pageSize=10&page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS | 尺寸 | Dimension id | |--------------------------------------------|------------------------------|--------------------------------------------------------------------------------------------| | 描述 | Relationship Type `{0}` constraint requires a {1} but a {2} was found. | 属性 | | Data element identifiers must include the program stage when querying data for enrollments. dimension=edqlbukwRfQ.vANAXwtLwcT | 0 | 属性 | | | -2 | Attribute identifiers | | 句号 | 1 | 聚乙烯 | | ISO periods and relative periods, see "date and period format" | 3 | 组织单位 | 欧 ### Organisation unit identifiers and keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL- and OU_GROUP- Repeatable stages 数据元素标识符必须包括计划阶段。项目阶段可以重复。例如,维度 edqlbukwRfQ.vANAXwtLwcT 可指可重复的项目阶段。可通过索引参数(用 [ ]括起来)访问该阶段的数据元素。 Table: Possible indexing of repeatable stages 尺寸 Index parameters DataElement value refers to edqlbukwRfQ.vANAXwtLwcT 不适用 last execution date edqlbukwRfQ[0].vANAXwtLwcT 最后执行日期 dqlbukwRfQ[-2].vANAXwtLwcT #### Enrollment Organisation units dqlbukwRfQ[1].vANAXwtLwcT includeClusterPoints dqlbukwRfQ[3].vANAXwtLwcT third execution date 警告:对不可重复的项目阶段进行索引会导致参数验证错误。注册查询分析 { #webapi_enrollment_query_analytics } The `analytics/enrollments/query` resource lets you query for captured enrollments. This resource does not perform any aggregation, rather it lets you query and filter for information about enrollments. /api/analytics/enrollments/query #### Greater than /api/analytics/enrollments/query/?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd &dimension=ou:;&dimension=&dimension=:: 例如,要从2019年1月起从“产前护理”计划中检索入学申请,该计划从属性中提取“名字”,则在第一个计划阶段包括“慢性病”和“吸烟”数据元素,并且来自以下项目阶段的“血红蛋白值”,并且仅包括具有“疯子病”的女性,您可以使用以下查询: ##### /api/analytics/enrollments/query/WSGAb5XwJ3Y.json ?dimension=ou:ImspTQPwCqd &dimension=w75KJ2mc4zz &dimension=WZbXY0S00lP.de0FEHSIoxh:eq:1 &dimension=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=edqlbukwRfQ.vANAXwtLwcT &startDate=2019-01-01&endDate=2019-01-31 要从上个月(相对于执行查询的时间点)的“产前护理”项目中检索入学登记,其中“慢性病”和“吸烟”数据元素包含在第一项目阶段,而“后续计划阶段的“血红蛋白价值”,仅包括吸烟的血红蛋白少于20岁的女性: /api/analytics/enrollments/query/WSGAb5XwJ3Y.json ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh&dimension=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD:eq:1 &dimension=edqlbukwRfQ.vANAXwtLwcT:lt:20 &dimension=pe:LAST_MONTH 可以将排序应用于注册的查询和注册的事件日期: /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &columns=w75KJ2mc4zz&dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP&pageSize=10 &page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS 通过指定页码和页面大小参数,可以将分页应用于查询。如果指定了页码,但未指定页码,则将使用50页码。如果指定了页面大小,但未指定页面号,则将使用页面号1。要获得页面大小为10的响应的第二页,可以使用如下查询: /api/analytics/enrollments/query/WSGAb5XwJ3Y.json ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &dimension=w75KJ2mc4zz &dimension=pe:LAST_MONTH &dimension=WZbXY0S00lP.sWoqcoByYmD&pageSize=10 &page=2 Filtering 过滤器可以应用于数据元素,人员属性和人员标识符。过滤是通过以下格式的查询参数值完成的: ##### &dimension = :: 例如,您可以过滤“ Weight”数据元素以获取大于2000且小于4000的值,如下所示: /api/analytics/events/query/?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd &dimension=ou:;&dimension=&dimension=:: | 所需值 | Parameter name | |---|---| | 检索“Child”的“Birth”项目阶段的事件 2016 年 3 月至 12 月期间的“计划”计划,其中“重量” 数据元素,过滤大于 2000年: | /api/analytics/events/query/IpHINAT79UW?stage=A03MvHHogjR&startDate=2016-03-01 &endDate=2016-12-31&dimension=ou:O6uvpzGd5pu&dimension=UXz7xuGCEhU:GT:2000 | | &dimension = :: | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | &dimension = UXz7xuGCEhU:GT:2000&dimension = UXz7xuGCEhU:LT:4000 | 您可以使用以下方法过滤多个特定年龄的“年龄”数据元素像这样的 IN 运算符: | | &dimension = qrur9Dvnyt5:IN:18; 19; 20 | 字符串、布尔值、整数、浮点、集合(检查大小)、日期 | | &dimension = qrur9Dvnyt5:GT:5:LT:15 | Filter by AGE is not null | | &dimension=qrur9Dvnyt5:NE:NV | /api/analytics/events/query/eBAyeGv0exc?startDate=2016-01-01&endDate=2016-10-31 &dimension=ou:O6uvpzGd5pu&dimension=qrur9Dvnyt5&desc=EVENTDATE&asc=qrur9Dvnyt5 | | &dimension=qrur9Dvnyt5:IN:18;19;NV | `NV` can be used with `EQ`, `NE` and `IN` operators | | Operators | GT | ### Table: Filter operators Operator 描述 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | Attribute identifiers | |---|---|---|---| | `{ "periodFrom": -15, "periodTo": 15}` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | LT | 组织单位 | | dueDate | Program notification template | NE | Event chart view | | lastUpdatedDate | Program notification template | IN | Event chart view | | 周期(pe) | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Table: Query parameters for enrollment query endpoint | 查询参数 | | 数据值 | Program notification template | 任何项目标识符 || | 结束日期 | Program notification template | Program identifier. | 任何项目标识符 | | 描述 | 不区分大小写的字符串结尾匹配 | Program notification template | Date in yyyy-MM-dd format | | `{"type":"RELATIVE","period":"TODAY"}` | Program notification template | End date for enrollments. | 不 | | Dimensions to use as columns for table layout. | Program notification template | 维度标识符包括数据元素、属性、项目指标、期间、组织单元和组织单元组集。参数可以重复任意次数。项目过滤器可以应用于维度的格式::。过滤器值不区分大小写。 | 项目状态 | | filter | Program notification template | 维度标识符包括数据元素、属性、期间、组织单位和组织单位组集。参数可以重复任意次数。项目过滤器可以应用于维度,格式为::。过滤器值不区分大小写。 | 项目状态 | | 不 | Program notification template | ACTIVE | COMPLETED | CANCELLED | 假 | | Start date for interval tocheck for outliers | Program notification template | 选项(默认为默认) | ouMode | | 定义要返回的页码。 | Program notification template | `ouname` | `programstatus` | `eventstatus` | `createdbydisplayname` | `lastupdatedbydisplayname` | `eventdate` | `enrollmentdate` | `incidentdate` | `lastupdated` | item identifier | asc | | 定义每页返回的元素数量。 | Program notification template | false | true | coordinateOuFallback | | 不 | Program notification template | `ouname` | `programstatus` | `createdbydisplayname` | `lastupdatedbydisplayname` | `enrollmentdate` | `incidentdate` | `lastupdated` | item identifier | coordinatesOnly | ** 在某些情况下，可以通过 `dimension` 参数请求特定字段。它们不是真正的维度，但提供了更好的灵活性。它们是 #### 事件日期 (`EVENT_DATE`) 根据事件发生的日期进行筛选。可用作根级维度或特定阶段的范围。 | 价值形式 | 描述 | 意义 | |---|---|---| | `{stageUid}.event_date:{period}` | `dimension=A03MvHHogjR.EVENT_DATE:202205`. | 阶段 "A03MvHHogjR "中的事件，事件发生日期为 2022 年 5 月。 | | `{stageUid}.event_date:{start}_{end}` | `dimension=A03MvHHogjR.EVENT_DATE:2022-05-01_2022-05-10` | 该阶段中事件日期在给定包含日期范围内的事件。 | | `event_date:{period}` | `dimension=EVENT_DATE:2022Sep`(事件日期：2022 年 9 月) | 使用财政年度过滤根级事件日期。 | #### 预定日期 (`SCHEDULED_DATE`) 根据事件的计划日期（而不是实际发生日期）进行筛选。此外，它还可以扩展到特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | `scheduled_date:{period}` | dimension=SCHEDULED_DATE:202107 | 活动处于既定阶段，预定日期为 2021 年 7 月。 | #### 创建日期 (`CREATED`) 根据报名记录在系统中创建的时间进行筛选。此外，它还可以针对特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | `CREATED:{period}` | dimension=CREATED:2016Sep | 自 2016 年 9 月起的财政年度内创建的注册人数。 | #### 完成日期 (`COMPLETED`) 根据注册被标记为完成的时间进行筛选。此外，它还可以扩展到特定阶段（如 `EVENT_DATE`）。 | 价值形式 | 描述 | 意义 | |---|---|---| | 完成：{period}` | 尺寸=COMPLETED:2022年9月 | 自 2022 年 9 月起的财政年度内完成的注册。 | #### 事件状态 (`EVENT_STATUS`) 根据阶段内事件的状态进行筛选。 | 价值形式 | 描述 | 意义 | |---|---|---| | `{stageUid}.event_status:{status}` | `dimension=A03MvHHogjR.EVENT_STATUS:ACTIVE`. | 阶段中状态为 "ACTIVE "的事件。 | | `{stageUid}.event_status:{s1};{s2}` | `dimension=edqlbukwRfQ.EVENT_STATUS:COMPLETED;ACTIVE`. | 状态为 `COMPLETED` **或** `ACTIVE` 的事件（OR 逻辑）。 | 有效状态值：活动"、"已完成"、"已排定"、"逾期"、"已跳过"。 #### 程序状态 (`PROGRAM_STATUS`) 根据注册本身的状态（而不是单个事件）进行筛选。 | 价值形式 | 描述 | 意义 | |---|---|---| | `program_status:{status}` | dimension=PROGRAM_STATUS:ACTIVE | 仅指具有指定计划状态的注册人数。 | 有效状态值：活动"、"已完成"、"已取消"。 #### 欧 Whether to only return enrollments which have coordinates. - 临界点 - E7126 - Table: Org unit analytics query parameters - 作为响应的一部分返回的标头的名称。 - One or more headers name separated by comma - page 不 The page number. Default page is 1. Numeric positive value pageSize 不 The page size. Default size is 50 items per page. Numeric zero or positive value ### timeField 不 Time field used in aggregations/queries on enrollments. Applies to enrollment data items only. Can be a predefined option or the ID of an attribute or data element with a time-based value type. For "/analytics/enrollments/" endpoints, the default "timeField" is ENROLLMENT_DATE. ENROLLMENT_DATE | LAST_UPDATED | | Response formats 默认的响应表示格式是 JSON。请求必须使用 HTTP *GET* 方法。支持以下响应格式。 json(应用项目/ json) xml(应用项目/ xml) ## xls(application / vnd.ms-excel) csv(应用项目/ csv) ### html(text / html) html + css(text / html) 例如,要获得Excel格式的响应,可以在请求URL中使用文件扩展名,如下所示: | /api/analytics/enrollments/query/WSGAb5XwJ3Y.xls ?dimension=ou:ImspTQPwCqd &dimension=WZbXY0S00lP.de0FEHSIoxh &columns=w75KJ2mc4zz &dimension=WZbXY0S00lP.sWoqcoByYmD &dimension=pe:LAST_MONTH &stage=WZbXY0S00lP &pageSize=10&page=1 &asc=ENROLLMENTDATE &ouMode=DESCENDANTS | 值不引用数字元素或项目一部分的数据元素或属性 | Parameter name | |------------------------------------|-------------------------------------------------------------|---| | 响应的 *headers* 部分描述了查询结果的内容。注册唯一标识符、被跟踪实体实例标识符、注册日期、事件日期、几何形状、纬度、经度、组织单位名称和组织单位代码作为响应中的第一个维度出现并且将始终存在。接下来是数据元素和在请求中指定为维度的跟踪实体属性,在本例中为“WHOMCH 慢性条件”和“WHOMCH 吸烟”数据元素维度。标题部分在“名称”属性中包含维度项的标识符,在“列”属性中包含可读的维度描述。 | *metaData* 部分,*ou* 对象包含映射到表示层次结构的字符串的响应中存在的所有组织单位的标识符。此层次结构字符串从根开始列出组织单位的祖先(父)的标识符。 *names* 对象包含响应中映射到其名称的所有项目的标识符。 | *rows* 部分包含查询生成的注册。每一行正好代表一个注册。 | 项目标识符未引用项目的任何数据元素,属性或指标部分 | 非汇总注册分析API还支持将项目指示器链接到关系类型,以显示应用于所列出的跟踪实体实例的相关实体的特定项目指示器的计算结果。 | ![](resources/images/enrollments/enrollments-pi-relationship.jpg) | | 来自 *rawData* 资源的响应看起来与定期分析资源;不同之处在于响应包含原始的、非聚合的数据,适合进一步聚合第三方系统。 | /api/analytics/enrollments/query/ ?dimension=. | 例如,要从“ WHO RMNCH Tracker”项目中检索2019年1月的注册列表,并按“与人相关的疟疾病例”类型的关系显示与该注册相关的疟疾病例数,则可以使用以下查询 | | /api/analytics/enrollments/query/WSGAb5XwJ3Y.json?dimension=mxZDvSZYxlw.nFICjJluo74 &startDate=2019-01-01&endDate=2019-01-31 | API 支持使用与“主”项目(即在`/query/` 之后指定的项目 ID)无关的项目指示符。 | Dimension id | | The tracked entity (TE) analytics API allows querying *TEs with their enrollments and event data* captured in DHIS2. This resource retrieves data from TE, enrollments, events, and data elements across multiple programs, for a given tracked entity type. | Dimensions and items { #webapi_te_analytics_dimensions } | Dimension id | | Table: TE dimensions | 尺寸 | Dimension id | #### 描述项目属性(TE 属性) `` 项目属性的标识符。 ### Data elements in program stages `.[offset].` 数据元素标识符必须包括项目和项目阶段,即:`dimension=IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO`。句号 N.A. There's no direct support for `period` dimension. Periods are supported through several different specific parameters. See the *Periods* section below. TEI Organisation units `ou` Organisation unit identifiers, and also the keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL- and OU_GROUP-. #### Enrollment Organisation units `.ou` includeClusterPoints Event Organisation units `.ou` #### Organisation unit identifiers, and also the keywords USER_ORGUNIT, USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN, LEVEL- and OU_GROUP-. Offset | 默认值 | Parameter name | |----------------|----------------------------------------------------------------------------------| | "assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"] | Tracked entity (TE) query analytics { #webapi_te_query_analytics } | | The *analytics/trackedEntities/query* endpoint provides queries for captured TEs, allowing querying and filtering for information related to TEs, along with their respective enrollments and events. It does not perform any aggregation. | /api/41/analytics/trackedEntities/query | | You can specify any number of dimensions and any number of filters in a query. Dimension item identifiers can refer to any of the data elements in program stages, program attributes, tracked entity attributes, fixed and relative periods, and organization units. Dimensions can optionally have a query operator and a filter. TEs queries should be in the format described below. | /api/41/analytics/trackedEntities/query/?dimension=ou:;& dimension=&dimension=:: | | For example, to retrieve TEs of type `Person` from the "Child Program" and "Antenatal care" programs, where the "First name" is "James": | /api/41/analytics/trackedEntities/query/nEenWmSyUEp?program=IpHINAT79UW,WSGAb5XwJ3Y&dimension=IpHINAT79UW.w75KJ2mc4zz:eq:James | | 不 | /api/41/analytics/trackedEntities/query/nEenWmSyUEp?program=IpHINAT79UW,WSGAb5XwJ3Y&dimension=IpHINAT79UW.w75KJ2mc4zz:eq:James &pageSize=10&page=2 | | GET /api/metadata/proposals?filter=status:eq:ACCEPTED | Filters can be applied to data elements, tracked entity attributes, and tracked entity identifiers. The filtering is done through a query parameter in the following format: | &dimension = :: For example, you can filter the "MCH Infant Weight (g)" data element, of the program "Child Program" and program stage "Baby Postnatal" looking for values greater than 2000 and lower than 4000. The filter is defined like this: * &dimension=IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO:GT:2000&dimension=IpHINAT79UW.ZzYYXq4fJie.GQY2lXrypjO:LT:4000 Periods * Unlike enrollment and event query endpoints, the TE endpoint supports multiple ways to specify the period the data belongs to. They are based on different *date* params as shown below: Parameter * 描述 eventDate * TEs will be filtered based on the date the event occurred. enrollmentDate ### TEs will be filtered based on the date of enrollment. scheduledDate TEs will be filtered based on the date the event was scheduled. | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | Attribute identifiers | |-------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `{"organisationUnit": "a3kGcGDCuk7"}` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Some periods, mentioned above, can be applied to Tracked Entities, Enrollments, or Events, depending on the way they are expressed. | 例子: | | `{ "periodFrom": -15, "periodTo": 15}` | Program notification template | filtering TEs whose latest enrollment in the program "Child Program" has been updated during the last year: | `lastUpdated=IpHINAT79UW.LAST_YEAR` | | 周期(pe) | Program notification template | filtering TEs whose latest enrollment in the "Child Program" occurred in the last year: | 查询参数 | | 数据值 | Program notification template | Table: Query parameters for the TE query endpoint | 查询参数 | | Start date for interval tocheck for outliers | Program notification template | 选项(默认为默认) | trackedEntityType | | 描述 | Program notification template | Any tracked entity type identifier. | 项目 | | `{"type":"RELATIVE","period":"TODAY"}` | Program notification template | 任何项目标识符。接受多个逗号分隔的标识符。 | 维度 | | Dimensions to use as columns for table layout. | Program notification template | Operators: EQ | IEQ | GT | GE | LT | LE | NE | LIKE | ILIKE | IN | filter | | filter | Program notification template | Operators: EQ | IEQ | GT | GE | LT | LE | NE | LIKE | ILIKE | IN | filter | | 定义要返回的页码。 | Program notification template | One or more header names (separated by a comma). | relativePeriodDate | | 定义每页返回的元素数量。 | Program notification template | Example: "2016-01-01" | ouMode | | Custom period on `lastUpdated`. See "custom date periods" section. | Program notification template | `DESCENDANTS`, `CHILDREN`, `SELECTED` | 查询参数 | | 不 | Program notification template | `ouname` | `programstatus` | `createdbydisplayname` | `lastupdatedbydisplayname` | `enrollmentdate` | `incidentdate` | `lastupdated` | `` | 假 | | ```json { "httpStatus": "OK", "httpStatusCode": 200, "status": "OK", "response": { "responseType": "ObjectReport", "uid": "pG4bBTMiCqO", "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange", "errorReports": [] } } ``` | Program notification template | `ouname` | `programstatus` | `createdbydisplayname` | `lastupdatedbydisplayname` | `enrollmentdate` | `incidentdate` | `lastupdated` | `` | page | | 不 | Program notification template | Numeric positive value. | pageSize | | 结束日期 | Program notification template | Numeric zero or positive value. | includeMetadataDetails | | DateTime | Program notification template | NAME | SHORTNAME | includeMetadataDetails | | `"displayOrderColumns": ["enrollmentDate", "program"]` | Program notification template | false | true | outputIdScheme | | 不 | Program notification template | UID | UUID | CODE | NAME | ATTRIBUTE: | 假 | | 不 | Program notification template | NAME | CODE | UID | 假 | | 不 | Program notification template | ACTIVE | COMPLETED | CANCELLED. Can be comma separated (*for query only*). | enrollmentStatus | | 不 | Program notification template | ACTIVE | COMPLETED | CANCELLED. Can be comma separated (*for query only*). | 假 | | 不 | Program notification template | ACTIVE | COMPLETED | SCHEDULE | OVERDUE | SKIPPED. Can be comma separated (*for query only*). | 假 | | sortOrder | Program notification template | false | true | 假 | | 不 | Program notification template | false | true | 假 | | Common request parameters | Program notification template | Any organization unit identifier. | 假 | | Custom period on `lastUpdated`. See "custom date periods" section. | Program notification template | `DESCENDANTS`, `CHILDREN`, `SELECTED` | 查询参数 | ## 不 Skip data in the response. - false | true - skipRounding - 不 - Skip rounding of data values. - false | true skipHeaders | eventCreatedPeriod | Skip headers in the response. | Parameter name | 用户设置 { #webapi_user_settings } | |-----------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | 数据值 | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | false | true | displayProperty | | 默认过滤器是`id,displayName` | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | NAME | SHORTNAME | | 定义要返回的页码。 | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | [Event Query data dimensions](developer-manual.md#webapi_event_query_analytics_dimension)`/analytics/events/query/dimensions` | [Event Aggregate data dimensions](developer-manual.md#webapi_event_aggregate_analytics_dimension) `/analytics/events/aggregate/dimensions` | | 定义每页返回的元素数量。 | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | [Tracked Entities query data dimensions](developer-manual.md#webapi_teis_query_analytics_dimensions)) `/analytics/teis/query/dimensions` | Resources mentioned above share the following request parameter: | | true | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | 描述 | 选项 | | iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。 | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions` | Allows field value filtering on the format:
`filter=field:OP:value&filter=field:OP:value&...` | See [dimension filters section].(#webapi_analytics_dimension_filters) | #### fields no Allows field filtering - page - no - Page number - Defaults to 1 (first page) - pageSize - no - Page size - Defaults to 50 elements per page - paging - no - Disables pagination when `false` - `true` or `false`, defaults to `true` order - no - Allows sorting on the format: `order=field:direction` - Sortable fields: `created` (default), `lastUpdated`, `code`, `uid`, `id`, `name`, `displayName`, `dimensionType`

Direction can be `ASC` (default) or `DESC` - Dimension filters { #webapi_analytics_dimension_filters } - Dimensions endpoints support filtering the output to narrow down the response to desired elements. Filters are in the format `filter=field:op:value&filter=field:op:value&...&filter=field:op:value`. - Supported `field` values are: - **id**/**uid** - dimension id - **code** - dimension code - **valueType** - dimension value type - **name** - the name of the dimension - **dimensionType** - the type of the dimension ### `DATA_ELEMENT` #### `PROGRAM_INDICATOR` `PROGRAM_ATTRIBUTE` - `CATEGORY` - `CATEGORY_OPTION_GROUP_SET` - **displayName** - displayName of the dimension **displayShortName** - displayShortName of the dimension - Supported `op`values are: - `startsWith` - field starts with - `!startsWith` - field does not start with `endsWith` - field ends with - `!endsWith` - field does not end with- - `eq` - equals - `ieq` - equals ignoring case - `ne` - not equals - `like` - contains **Tracked entity attributes** of *supported types* associated with the program that are not confidential #### `ilike` - contains ignoring case `!ilike` - does not contain ignoring case - `eq` - equals - `ieq` - equals ignoring case - `ne` - not equals - a tracker `program` `UNIT_INTERVAL` - both `program` and `programStage` - `INTEGER` - If only `program` is specified, the resource returns data dimensions for each program stage in the provided program - If only `programStage` is specified, the resource returns data dimensions for the provided `programStage` - If both `program` and `programStage` are specified, the resource returns data dimensions for the provided `programStage` if it belongs to the provided `program`. Returns an error otherwise. - the returned data dimensions are: - **Program indicators** associated with the program (derived from programStageId) - Enrollment analytics dimensions - **Tracked entity attributes** of *supported types* associated with the program (derived from programStageId) ### 与项目相关联的类别组合中的**类别**(源自项目阶段 ID) #### **Category option group sets** of type `ATTRIBUTE` All value types for data elements and tracked entity attributes are considered *supported types*, except `IMAGE` and `FILE_RESOURCE`. - Event aggregate dimensions { #webapi_event_aggregate_analytics_dimension } - Data elements and tracked entity attributes are considered *supported types* if their value type is one of the following: - **Data elements** of *supported types* in the program stage **Tracked entity attributes** of *supported types* associated with the program that are not confidential #### 与项目相关联的类别组合中的**类别**(源自项目阶段 ID) **Category option group sets** of type `ATTRIBUTE` associated with program (derived from programStageId) - Data elements and tracked entity attributes are considered *supported types* if their value type is one of the following: - **Data elements** of *supported types* in the program stage `UNIT_INTERVAL` - both `program` and `programStage` - `INTEGER` - If only `program` is specified, the resource returns data dimensions for each program stage in the provided program - If only `programStage` is specified, the resource returns data dimensions for the provided `programStage` - If both `program` and `programStage` are specified, the resource returns data dimensions for the provided `programStage` if it belongs to the provided `program`. Returns an error otherwise. - the returned data dimensions are: - **Program indicators** associated with the program (derived from programStageId) - Enrollment analytics dimensions - **Tracked entity attributes** of *supported types* associated with the program (derived from programStageId) ### The `/analytics/enrollments/query/dimensions?programId=...` resource accepts a mandatory id of a tracker program and returns the following data dimensions: #### 与项目连接的**项目指示器** **Data elements** of *supported types* in the program, with program stage for each data element **Tracked entity attributes** of *supported types* associated with the program that are not confidential - All value types for data elements and tracked entity attributes are considered *supported types*, except `IMAGE` and `FILE_RESOURCE`. - Enrollment aggregate dimensions { #webapi_enrollment_aggregate_analytics_dimension } - **Data elements** of *supported types* in the program stage - **Data elements** of *supported types* in the program, with program stage for each data element **Tracked entity attributes** of *supported types* associated with the program that are not confidential ### Data elements and tracked entity attributes are considered *supported types* if their value type is one of the following: `NUMBER` `UNIT_INTERVAL` ## `PERCENTAGE` `INTEGER` `INTEGER_POSITIVE` `INTEGER_NEGATIVE` ### `INTEGER_ZERO_OR_POSITIVE` `BOOLEAN` `TRUE_ONLY` | 指标组 | Parameter name | 检索和删除项目通知模板 | |---|---|---| | Filter on whether the current user can manage the returned users through the managed user group relationships. | **Program indicators** associated to `P` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | **Tracked entity attributes** of *supported types* associated with the program that are not confidential | **Program attributes** of `P` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | GET /api/analytics/teis/query/dimensions?programStageId=A03MvHHogjR&order=code&filter=name:ilike:weight | Program notification template | 组织单位分析 { #webapi_org_unit_analytics } 组织单位分析API提供有关按组织单位组集分类的组织单位的统计信息,即组织单位组集中每个组织单位组的组织单位计数。 ### 欧该API需要至少一个组织单位和至少一个组织单位组集。可以提供多个组织单位和组集,以分号分隔。 - 临界点 - 组织单位分析资源使您可以指定一系列查询参数: - Table: Org unit analytics query parameters - Property ### 整数需要欧 Org unit identifiers, potentially separated by a semicolon. 是的 ougs Org unit group set identifiers, potentially separated by a semicolon. ### 是的列 | json(应用项目/ json) | Validation report | | ---------- | ------- | | 响应将包含用于父组织单位的列,用于请求的每个组织单位组集部分的列以及用于计数的列。统计信息包括组织单位的数量,该组织单位是请求中指定的组织单位的子层次结构的一部分。该响应包含一个元数据部分,该元数据部分指定由其标识符引用的响应的每个组织单位和组织单位组部分的名称。 | 默认响应使用单个 `count` 列进行标准化。通过使用 `columns` 查询参数指定至少一个组织单位组集,可以在表格布局中呈现响应。 | | Response formats | 组织单位分析端点支持以下表示格式: | ## json(应用项目/ json) csv(应用项目/ csv) xls(application / vnd.ms-excel) ### `INTEGER_ZERO_OR_POSITIVE` 例子要获取组织单位和组织单位组集的组织单位分析,请执行以下操作: | 默认值 | Parameter name | Potential duplicate status | 检索和删除项目通知模板 | |---|---|---|---| | Table: Query parameters | Constraints and validation | 下表描述了专门针对组织单位分析API的可能的验证错误。为汇总分析API指定的某些错误也相关。 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | E7228 | E7300 | 必须至少指定一个组织单位 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | Filter on whether the current user can manage the returned users through the managed user group relationships. | 数据集报告 { #webapi_data_set_report } | 可以使用 web api 生成数据集报告 `/dataSetReport` 资源。此资源生成有关数据集的报告并以 HTML 表格的形式返回结果。 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 数据值 | 该请求支持以下参数: | Table: Data set report query parameters | Program notification template | | 描述 | 类型 | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | Program notification template | Data set to create the report from. Data set UID 是的聚乙烯 Period(s) to create the report from. May be a comma-separated list. ISO String 是的 ### 欧 Organisation unit to create the report from. - 临界点 - Property - Table: Org unit analytics query parameters ### Filters to be used as filters for the report. Can be repeated any number of times. Follows the analytics API syntax. One or more UIDs 不 selectedUnitOnly Whether to use captured data only or aggregated data. ## Boolean 不 The data set report resource accepts `GET` requests only. The response content type is `application/json` and returns data in a grid. This endpoint works for all types of data sets, including default, section and custom forms. An example request to retrieve a report for a monthly data set and org unit for October 2018 looks like this: GET /api/dataSetReport?ds=BfMAe6Itzgt&pe=201810&ou=ImspTQPwCqd&selectedUnitOnly=false An example request to retrieve a report for a monthly data set and org unit for October, November, and December 2018 looks like this: GET /api/dataSetReport?ds=BfMAe6Itzgt&pe=201810,201811,201812&ou=ImspTQPwCqd&selectedUnitOnly=false 要获得带有过滤器的数据集报告,可以使用`filter`参数。在这种情况下,过滤器基于一个组织单位组集和两个组织单位组: | 指标组 | Parameter name | Potential duplicate status | 检索和删除项目通知模板 | |---|---|---|---| | pdf(应用项目/ pdf) | xls(application / vnd.ms-excel) | Custom forms | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 技术性更强、对开发人员更友好的消息(目前尚未使用)。 | 否则,此端点的语法等于常规数据集报告端点。要检索自定义HTML数据集报告,您可以发出如下请求: | 具有以下要求: | Program notification template | | 推送分析 API 包括用于预览推送分析的端点报告登录用户并手动触发系统生成和发送推送分析报告,除了正常的 CRUD 操作。使用创建和更新端点进行推送时分析,推送分析将根据推分析的性质。删除或更新一个禁用推送分析,作业也将停止运行将来。 | 要获得现有推送分析的 HTML 预览,您可以执行 GET 请求到以下端点: | /api/pushAnalysis//render | 要手动触发推送分析作业,您可以执行 POST 请求以这个端点: | | /api/pushAnalysis//run | 推送分析包含以下属性,其中一些是自动运行推送分析作业所需: | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | Property | | 描述 | 类型 | 需要 | dashboard | | Dashboard on which reports are based | Dashboard UID | 是的 | message | ## Appears after title in reports 串不 recipientUserGroups ### A set of user groups who should receive the reports One or more user Group UID - No. Scheduled jobs without any recipient will be skipped. - enabled ### Indicated whether this push analysis should be scheduled or not. False by default. Boolean Yes. Must be true to be scheduled. schedulingFrequency The frequency of which reports should be scheduled. "DAILY", "WEEKLY", "MONTHLY" | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | Parameter name | |---|---| | The day in the frequency the job should be scheduled. | Integer. Any value when frequency is "DAILY". 0-7 when frequency is "WEEKLY". 1-31 when frequency is "MONTHLY" | | No. Push analysis without a valid day of frequency for the frequency set will not be scheduled. | 数据使用情况分析 { #webapi_usage_analytics } | | 使用情况分析 API 可让您访问有关人们使用情况的信息使用基于数据分析的 DHIS2。当用户访问收藏夹时, 事件被记录。事件由用户名、UID 组成最喜欢的、事件发生的时间以及事件的类型。这表中列出了不同类型的事件。 | /api/dataStatistics | | 使用情况分析 API 可让您检索使用情况的汇总快照基于时间间隔的分析。 API 捕获用户视图(对于例如,图表或数据透视表被用户查看的次数用户)和保存的分析收藏夹(例如收藏夹图表和数据透视表)。 DHIS2 将捕获夜间快照,然后应要求汇总。 | 请求查询参数 { #webapi_usage_analytics_request_query_parameters } | | 使用情况分析(数据统计)API支持两种操作: | *POST:* 创建一个视图事件 | | *GET:* 检索汇总统计信息 | 创建视图事件(POST) { #webapi_usage_analytics_create_view_events } | | 使用情况分析 API 可让您创建事件视图。这 dataStatisticsEventType 参数描述了项目的类型看过。最喜欢的参数表示相关的标识符最喜欢的。 | 创建新事件视图的 URL 图表: | | POST /api/dataStatistics?eventType=CHART_VIEW&favorite=LW0O27b7TdD | 成功的保存操作会返回 HTTP 状态代码 201。表下面显示了支持的事件类型。 | ### Table: Supported event types 键描述 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | 用户设置 { #webapi_user_settings } | |---|---|---|---| | dueDate | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | EVENT_CHART_VIEW | Event chart view | | lastUpdatedDate | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | DASHBOARD_VIEW | Event chart view | | PASSIVE_DASHBOARD_VIEW | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | DATA_SET_REPORT_VIEW | Data set report view | 检索汇总的使用情况分析报告(GET) { #webapi_aggregated_usage_analytics } 使用情况分析(数据统计)API 允许您指定特定查询请求汇总报告时的参数。 Table: Query parameters for aggregated usage analytics (data statistics) ### 查询参数需要描述 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | 用户设置 { #webapi_user_settings } | |---|---|---|---| | Date in yyyy-MM-dd format | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | 是的 | End date for period | | 定义每页返回的元素数量。 | Program notification template | 是的 | Type of interval to be aggregated | | 这种访问级别的限制稍多一些。受保护项目中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。只有当所有者组织单位属于用户的捕获范围时,用户才能访问受保护项目内的数据。但是,如果用户用户可以通过 [打破玻璃](#webaptrl) 获得临时所有权。玻璃](#webapi_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。他们为什么要访问手头的数据。然后,系统会将理由和访问审核记录在案,并提供 3 个月的临时访问权限。访问审计日志,并为用户提供 3 小时的临时访问权限。请注意,打破玻璃时时,所有者组织单位保持不变,只有打碎玻璃的用户才能获得临时访问权。获得临时访问权。 | Program notification template | 用于创建每月查询的 API 查询聚合: | GET /api/dataStatistics?startDate=2014-01-02&endDate=2016-01-01&interval=MONTH | | createdBy | Program notification template | Table: Query parameters for top favorites | 查询参数 | 需要描述选项 eventType ### 是的 The data statistics event type - 临界点 - E7126 - One or more headers name separated by comma Size of the list returned For example 5, 10, 25. Default is 25 sortOrder 不 Descending or ascending ASC or DESC. Default is DESC. 用户名 ### 不 If specified, the response will only contain favorites by this user. For example 'admin' API 查询可以不用用户名,然后会找到顶部系统的最爱。 /api/dataStatistics/favorites?eventType=CHART_VIEW&pageSize=25&sortOrder=ASC ## 如果指定了用户名,则响应将仅包含该用户的最爱。 /api/dataStatistics/favorites?eventType=CHART_VIEW&pageSize=25 &sortOrder=ASC&username=admin 回应格式 { #webapi_usage_analytics_response_format } 您可以在使用情况分析响应中返回聚合数据几种表示格式。默认格式为 JSON。这可用的格式和内容类型有: json(应用项目/ json) xml(应用项目/ xml) html(text / html) - 请求 XML 格式的使用情况分析响应的 API 查询格式: - /api/dataStatistics.xml?startDate=2014-01-01&endDate=2016-01-01&interval=WEEK 要以 JSON 格式获取使用情况分析响应: /api/dataStatistics?startDate=2016-02-01&endDate=2016-02-14&interval=WEEK JSON响应如下所示:

[
  {
    "year": 2016,
    "week": 5,
    "mapViews": 2181,
    "chartViews": 2227,
    "reportTableViews": 5633,
    "eventReportViews": 6757,
    "eventChartViews": 9860,
    "eventVisualizationViews": 2387,
    "dashboardViews": 10082,
    "passiveDashboardViews": 0,
    "totalViews": 46346,
    "averageViews": 468,
    "averageMapViews": 22,
    "averageChartViews": 22,
    "averageReportTableViews": 56,
    "averageEventReportViews": 68,
    "averageEventChartViews": 99,
    "averageEventVisualizationViews": 10,
    "averageDashboardViews": 101,
    "averagePassiveDashboardViews": 0,
    "savedMaps": 1805,
    "savedCharts": 2205,
    "savedReportTables": 1995,
    "savedEventReports": 1679,
    "savedEventCharts": 1613,
    "savedEventVisualizations": 1231,
    "savedDashboards": 0,
    "savedIndicators": 1831,
    "activeUsers": 99,
    "users": 969
  },
  {
    "year": 2016,
    "week": 6,
    "mapViews": 2018,
    "chartViews": 2267,
    "reportTableViews": 4714,
    "eventReportViews": 6697,
    "eventChartViews": 9511,
    "dashboardViews": 12181,
    "passiveDashboardViews": 0,
    "totalViews": 47746,
    "averageViews": 497,
    "averageMapViews": 21,
    "averageChartViews": 23,
    "averageReportTableViews": 49,
    "averageEventReportViews": 69,
    "averageEventChartViews": 99,
    "averageDashboardViews": 126,
    "averagePassiveDashboardViews": 0,
    "savedMaps": 1643,
    "savedCharts": 1935,
    "savedReportTables": 1867,
    "savedEventReports": 1977,
    "savedEventCharts": 1714,
    "savedDashboards": 0,
    "savedIndicators": 1646,
    "activeUsers": 96,
    "users": 953
  }
]

| 指标组 | Parameter name | |---|---| | Two mappings for the `Referrals Age` category. A program indicator can choose which mapping | /api/dataStatistics/favorites/{favorite-id}.json | | 响应将包含给定收藏的观看次数和看起来像这样: | ```json { "views": 3 } ``` | | 地理空间特征 { #webapi_geospatial_features } | *geoFeatures* 资源可让您从中检索地理空间信息 DHIS2。地理空间特征与组织单位一起存储。检索特征的语法与用于检索特征的语法相同分析资源的组织单位维度。这是建议在继续之前阅读分析 api 资源阅读本节。您必须使用 GET 请求类型,并且只能使用 JSON 支持响应格式。 | | 例如,在以下位置检索所有组织单位的地理特征组织单位层次结构中的第 3 级,您可以使用 GET 请求使用以下网址: | /api/geoFeatures.json?ou=ou:LEVEL-3 | | true | /api/geoFeatures.json?ou=ou:LEVEL-4;O6uvpzGd5pu | | The response coordinates value can be read from two properties which is decided by the parameter `coordinateField`. | The `geometry` property of the OrganisationUnit: this is the default behaviour which is applied when parameter `coordinateField` is not provided. | | The OrgansationUnit attribute of value type GeoJSON: the api will use the provided `coordinateField={attributeId}` to get the GeoJSON coordinates from this attribute value. | For example, to retrieve geo features for all organisation units at level 3 as above but get the coordinates from OrganisationUnit attribute `tJqtSV4quLb` | | /api/geoFeatures.json?ou=ou:LEVEL-3&coordinateField=tJqtSV4quLb | 响应属性的语义描述如下桌子。 | | Table: Geo features response | Property | | 描述 | id | ### Organisation unit / geo feature identifier na Organisation unit / geo feature name hcd Has coordinates down, indicating whether one or more children organisation units exist with coordinates (below in the hierarchy) hcu Has coordinates up, indicating whether the parent organisation unit has coordinates (above in the hierarchy) ## le Level of this organisation unit / geo feature. pg Parent graph, the graph of parent organisation unit identifiers up to the root in the hierarchy ### pi Parent identifier, the identifier of the parent of this organisation unit pn | The manual merge is suitable when there are resolvable conflicts or when not all the data needs to be moved during the merge. For example, if an attribute has different values in both tracked entities , the user can specify whether to keep the original value or move over the duplicate's value. Since the manual merge involves the user explicitly requesting to move data, there are some additional checks: | 用户设置 { #webapi_user_settings } | Parameter name | |---|---|---| | displayColumnOrder | TRACKER_EVENT | GeoJSON | | 要导出 GeoJSON,您只需添加 *.geosjon* 作为扩展名端点 */api/organisationUnits*,或者您可以使用 *Accept* 标头 *应用项目/json+geojson*。 | 支持两个参数:`level`(默认为 1)和 `parent`(默认为根组织单位)。两者都可以多次包含。一些例子: | 获得第2级和第4级的所有功能: | | /api/organisationUnits.geojson?level=2&level=4 | Analytics 表挂钩提供了一种调用 SQL 脚本的机制在分析表生成过程的不同阶段。这对于自定义资源和分析表中的数据很有用,例如在以实现计算和聚合的特定逻辑。可以在以下 API 端点操作分析表挂钩: | /api/organisationUnits.geojson?parent=fdc6uOvgoji&level=3 | | 分析表挂钩 { #webapi_analytics_table_hooks } | Analytics 表挂钩提供了一种调用 SQL 脚本的机制在分析表生成过程的不同阶段。这对于自定义资源和分析表中的数据很有用,例如在以实现计算和聚合的特定逻辑。可以在以下 API 端点操作分析表挂钩: | / api / analyticsTableHooks | | 分析表钩子 API 支持标准的 HTTP CRUD 操作用于创建(POST)、更新(PUT)、检索(GET)和删除 (删除)实体。 | TRACKER_EVENT | Analytics表挂钩具有以下字段: | Table: Analytics table hook fields 领域选项描述名称文本 | Name of the hook. | phase | RESOURCE_TABLE_POPULATED, ANALYTICS_TABLE_POPULATED | |---|---|---| | The phase for when the SQL script should be invoked. | resourceTableType | See column "Table type" in table "Phases, table types and temporary tables" below | || The type of resource table for which to invoke the SQL script. Applies only for hooks defined with the RESOURCE_TABLE_POPULATED phase. |analyticsTableType | || See column "Table type" in table "Phases, table types and temporary tables" below | The type of analytics table for which to invoke the SQL script. Applies only for hooks defined with the ANALYTICS_TABLE_POPULATED phase. | || sql | 文本 | || The SQL script to invoke. |The *ANALYTICS_TABLE_POPULATED* phase takes place after the analytics table has been populated, but before indexes have been created and the temp table has been swapped with the main table. As a result, the SQL script should refer to the analytics temp table, e.g. *analytics_temp*, *analytics_completeness_temp*, *analytics_event_temp_ebayegv0exc*. | || 这也适用于 *RESOURCE_TABLE_POPULATED* 阶段,它需要放置在资源表被填充之后,索引之前已创建并且临时表已与主表交换桌子。因此,SQL 脚本应参考资源临时表,例如*_orgunitstructure_temp*,*_categorystructure_temp*。 | 您应该只定义 *resourceTableType* 和 *analyticsTableType* 字段,取决于定义的 *phase*。 | || 可以参考匹配的临时数据库表仅指定挂钩表类型(其他临时表不会可用的)。例如,如果您指定 *ORG_UNIT_STRUCTURE* 作为资源表类型,可以参考*_orgunitstructure_temp* 仅临时数据库表。 | 下表显示了阶段、表格类型的有效组合和临时表。 | || Table: Phases, table types and temporary tables | 相 | || Table type | Temporary table | || RESOURCE_TABLE_POPULATED | ORG_UNIT_STRUCTURE | || \_orgunitstructure\_temp | DATA_SET_ORG_UNIT_CATEGORY | || \_datasetorgunitcategory\_temp | CATEGORY_OPTION_COMBO_NAME | | \_categoryoptioncomboname\_temp | DATA_ELEMENT_GROUP_SET_STRUCTURE | \_dataelementgroupsetstructure\_temp | || INDICATOR_GROUP_SET_STRUCTURE | \_indicatorgroupsetstructure\_temp | || ORG_UNIT_GROUP_SET_STRUCTURE | \_organisationunitgroupsetstructure\_temp | || CATEGORY_STRUCTURE | \_categorystructure\_temp | || DATA_ELEMENT_STRUCTURE | \_dataelementstructure\_temp | || PERIOD_STRUCTURE | \_periodstructure\_temp | || DATE_PERIOD_STRUCTURE | \_dateperiodstructure\_temp | ### DATA_ELEMENT_CATEGORY_OPTION_COMBO \_dataelementcategoryoptioncombo\_temp DATA_APPROVAL_MIN_LEVEL \_dataapprovalminlevel\_temp ANALYTICS_TABLE_POPULATED DATA_VALUE analytics\_temp COMPLETENESS analytics\_completeness\_temp ## COMPLETENESS_TARGET analytics\_completenesstarget\_temp ORG_UNIT_TARGET analytics\_orgunittarget\_temp EVENT 选项值 | eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name | |---|---|---| | analytics\_validationresult\_temp | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | 您可以使用维护项目或应用项目接口创建钩子。 | | To create a hook which should run after the resource tables have been populated you can do a *POST* request like this using *JSON* as content type: | Program notification template | ```json { "name": "Update 'Area' in org unit group set resource table", "phase": "RESOURCE_TABLE_POPULATED", "resourceTableType": "ORG_UNIT_GROUP_SET_STRUCTURE", "sql": "update _organisationunitgroupsetstructure_temp set \"uIuxlbV1vRT\" = 'b0EsAxm8Nge'" } ``` | ## To create a hook which should run after the data value analytics table has been populated you can do a *POST* request like this using *JSON* format:

{
  "name": "Update 'Currently on treatment' data in analytics table",
  "phase": "ANALYTICS_TABLE_POPULATED",
  "analyticsTableType": "DATA_VALUE",
  "sql": "update analytics_temp set monthly = '200212' where monthly in ('200210', '200211')"
}

- To create a hook which should run after the event analytics tables are populated you can do a *POST* request like this using *JSON* format: ### ```json { "name": "Delete data for a data element", "phase": "ANALYTICS_TABLE_POPULATED", "analyticsTableType": "EVENT", "sql": "delete from analytics_event_temp_lxaq7zs9vyr where dx = 'uDX9LKGRwaH'" }

SVG转换 { #webapi_svg_conversion } 

| eventCreatedPeriod    | Parameter name                                                                                                 | 检索和删除项目通知模板                                            | Attribute identifiers                                                                          |                                                                          
|--------------------|-------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------|
| Table: Query parameters                 | <indicator-id\>                                                                                                    | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```                                                 | 描述                                                                              |
| dueDate          | 是的                                                                | Analytics outlier detection { #webapi_analytics_outlier_detection }  | ds                                                                                |
| lastUpdatedDate            | The file name for the returned attachment without file extension                                                                 | Analytics outlier detection { #webapi_analytics_outlier_detection }  | ds                                                                                |
| E7228                 | Request  { #webapi_analytics_outlier_detection_request }                                                                             | **Query parameters**   | 查询参数                                                                     |
| 描述 | 需要                                                                    | Program notification template                                                  | ds                                                                                |
| Filter on whether the current user can manage the returned users through the managed user group relationships.                 | 是的                                      | Program notification template                                                  | 开始日期                                                      |
| Start date for interval tocheck for outliers            | No (relative date period is mandatory in this case) | Program notification template                                                  | 结束日期                                                               |
| End date for interval to check for outliers            | No (relative date period is mandatory in this case)                                                                        | Program notification template                                                  | 聚乙烯 |
| 这种访问级别的限制稍多一些。受保护项目中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。
只有当所有者组织单位属于用户的捕获范围时,用户才能访问受保护项目内的数据。但是,如果用户
用户可以通过 [打破玻璃](#webaptrl) 获得临时所有权。
玻璃](#webapi_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。
他们为什么要访问手头的数据。然后,系统会将理由和访问审核记录在案,并提供 3 个月的临时访问权限。
访问审计日志,并为用户提供 3 小时的临时访问权限。请注意,打破玻璃时
时,所有者组织单位保持不变,只有打碎玻璃的用户才能获得临时访问权。
获得临时访问权。          | No (start and end date is mandatory in this case)                                       | Program notification template                                                  | relativePeriodDate                                                                                        |
| Date used as basis for relative periods.          | 不                                                                      | Program notification template                                                  | 欧                                                                        |
| Organisation unit, organisation unit level or groups (can be combined)          | 不                                                    | Program notification template                                                  | 标头                                                         |
| The name of the headers to be returned as part of the response. One or more headers name separated by comma      | 不 | Program notification template                                                  | 订购                                                                              |
| Sort the records on the value column         | 不                                                                                    | Program notification template                                                  | 500                                                                                              |
| sortOrder       | Sort the records on the value column in ascending or descending order                                       | Program notification template                                                  | 跳过验证                                                                                      |

算法

Algorithm to use for outlier detection

### 不

Z_SCORE, MODIFIED_Z_SCORE

  - 临界点
  - E7126
  - 不
  - 组织单位分析资源使您可以指定一系列查询参数:
  - One or more headers name separated by comma
  - page

不

UID, ID, CODE, NAME
### maxResults

| Maximum rows (responses) | 不 | Parameter name | Skip rounding of data values, i.e. provide fine precision (scale 10). |
|---|---|---|---|
| ```json
{
  "object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userAccesses": [],
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}
``` | 日期时间 | **Request example** | |
|     GET api/analytics/outlierDetection?ds=BfMAe6Itzgt&ou=ImspTQPwCqd&startDate=2022-07-26&endDate=2022-10-26&algorithm=Z_SCORE&maxResults=30&orderBy=value&threshold=3.0&sortOrder=asc&outputIdScheme=code | Response { #webapi_analytics_outlier_detection_response }  |Response is delivered in several representation formats. The default format is JSON. The
available formats and content types are:| json(应用项目/ json) |
| xml(应用项目/ xml) | xsl (application/vnd.ms-excel) | csv(应用项目/ csv) | html(text / html) |
| html + css(text / html) | **Response example** | ```json
{
  "headers":[
    {
      "name":"dx",
      "column":"Data",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"dxname",
      "column":"Data name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"pe",
      "column":"Period",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"pename",
      "column":"Period name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ou",
      "column":"Organisation unit",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ouname",
      "column":"Organisation unit name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"ounamehierarchy",
      "column":"Organisation unit name hierarchy",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"coc",
      "column":"Category option combo",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"cocname",
      "column":"Category option combo name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"aoc",
      "column":"Attribute option combo",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"aocname",
      "column":"Attribute option combo name",
      "valueType":"TEXT",
      "hidden":false,
      "meta":false
    },
    {
      "name":"value",
      "column":"Value",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"mean",
      "column":"Mean",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"stddev",
      "column":"Standard deviation",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"absdev",
      "column":"Absolute deviation",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"zscore",
      "column":"zScore",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"lowerbound",
      "column":"Lower boundary",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    },
    {
      "name":"upperbound",
      "column":"Upper boundary",
      "valueType":"NUMBER",
      "hidden":false,
      "meta":false
    }
  ],
  "metaData":{
    "maxResults":30,
    "count":3,
    "orderBy":"VALUE",
    "threshold":3.0,
    "algorithm":"Z_SCORE"
  },
  "rowContext":{

  },
  "width":18,
  "rows":[
    [
      "DE_22",
      "Q_Early breastfeeding (within 1 hr after delivery) at BCG",
      "202209",
      "September 2022",
      "OU_204860",
      "Sandaru CHC",
      "/Sierra Leone/Kailahun/Penguia/Sandaru CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "105.0",
      "18.3",
      "28.7",
      "86.7",
      "3.0",
      "-67.9",
      "104.4"
    ],
    [
      "DE_359706",
      "BCG doses given",
      "202208",
      "August 2022",
      "OU_595",
      "Ngalu CHC",
      "/Sierra Leone/Bo/Bargbe/Ngalu CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "220.0",
      "41.6",
      "57.4",
      "178.3",
      "3.1",
      "-130.7",
      "213.9"
    ],
    [
      "DE_35",
      "Yellow Fever doses given",
      "202209",
      "September 2022",
      "OU_1027",
      "Yemoh Town CHC",
      "/Sierra Leone/Bo/Kakua/Yemoh Town CHC",
      "COC_292",
      "Fixed, <1y",
      "default",
      "default",
      "466.0",
      "48.1",
      "114.2",
      "417.8",
      "3.6",
      "-294.6",
      "391.0"
    ]
  ],
  "headerWidth":18,
  "height":3
}
``` | Statistics in response { #webapi_analytics_outlier_detection_stats_in_response } |
| Statistical Measure | Header name | 描述 | 链接 |
| 值 | 价值 | The data set/ data element numeric value (Penta1 doses given, Measles doses given, etc.) | Mean |
| 意思是 | The average value of a set of numbers. Calculated by summing all values and dividing by the count. | https://www.khanacademy.org/math/statistics-probability/summarizing-quantitative-data | Standard Deviation |
| stddev | A measure of the amount of variation or dispersion in a set of values. | https://www.statisticshowto.com/probability-and-statistics/standard-deviation/ | |
| Absolute Deviation| absdev | The absolute difference between each data value and the middle value. | |

### https://www.mathsisfun.com/data/mean-absolute-deviation.html

Z Score

| zscore | Validation report |
|---|---|
| https://www.statisticshowto.com/probability-and-statistics/z-score/ | Modified Z Score |
| modifiedzscore | Similar to the Z score but robust to outliers. It uses the median and median absolute deviation. |
| https://www.statisticshowto.com/modified-z-scores/ | Median Absolute Deviation |
| medianabsdeviation | A robust measure of the spread of data values, calculated as the median of the absolute deviations from the median. | 
| https://math.stackexchange.com/questions/2232309/median-absolute-deviation-mad-formula | Minimum |
| lowerbound | The minimum is the smallest value in a dataset. It represents the lowest observed value among all the data values. |
| Maximum | upperbound |
| The maximum is the largest value in a dataset. It represents the highest observed value among all the data values. | Error messages { #webapi_analytics_outlier_detection_error_messages }  |
| All error messages are delivered with http status code 409. | 码 |
| 信息 | E2200 |
| At least one data element must be specified. | E2201 |
| Start date and end date or relative period must be specified. | E2202 |
| Start date must be before end date. | E2203 |
| 必须至少指定一个组织单位。 | E2204 |
| Threshold must be a positive number. | E2205 |
| Max results must be a positive number. | E2206 |

Max results exceeds the allowed max limit: *500*.

E2207
Data start date must be before data end date.
## E2208

Non-numeric data values encountered during outlier value detection.

- E2209
- Data start date not allowed.
- E2210

Data end date not allowed.

E2211

Algorithm min-max values not allowed.

E2212

Specifying both a start date/end date and a relative period is not allowed.

E2213

## Value of param orderBy is not compatible with algorithm *Z_SCORE*.

E7180

## The analytics outliers data does not exist. Please ensure analytics job was run and did not skip the outliers.

E7181

## Column *dxname* specified in orderBy, is not eligible for orderBy or does not exist.

The values in error messages are examples only.

## **Error message example**

```json
{
  "httpStatus": "Conflict",
  "httpStatusCode": 409,
  "status": "ERROR",
  "message": "Start date and end date or relative period must be specified",
  "errorCode": "E2201"
}

# Analytics query execution plan and costs including execution time estimation ## The analytics API provides endpoints for investigation of query performance issues. It is implemented as part of all analytics endpoints: analytics/explain analytics/event/explain analytics/enrollment/explain **例** GET /api/analytics/explain?displayProperty=NAME &dimension=dx:Uvn6LCg7dVU;sB79w2hiLp8,ou:USER_ORGUNIT &filter=pe:THIS_YEAR&includeNumDen=false&skipMeta=false &skipData=true&includeMetadataDetails=true 响应将显示 PostgreSQL 计划项目为所提供语句生成的执行计划。 | eventCreatedPeriod | 用户设置 { #webapi_user_settings } | Parameter name | |---|---|---| | Analytics explain { #webapi_analytics_explain } | 假 | Event analytics explain { #webapi_event_analytics_explain } | | /api/analytics/event/aggregate/{program}/explain /api/analytics/event/query/{program}/explain | 假 | /api/analytics/enrollment/query/{program}/explain | | Outliers analytics explain { #webapi_analytics_outlier_detection_explain } | 假 | 保养 | | Resource and analytics tables { #webapi_generating_resource_analytics_tables } | 假 | 资源表由 DHIS2 应用项目内部使用各种分析功能。这些表对用户也很有价值编写高级 SQL 报告。它们可以通过 POST 或 PUT 生成请求到以下 URL: | | / api / 33 / resourceTables | 假 | / api / 33 / resourceTables / analytics | | Table: Analytics tables optional query parameters | 查询参数 | 选项 | 描述 skipResourceTables false | true Skip generation of resource tables skipAggregate ## false | true Skip generation of aggregate data and completeness data skipEvents false | true Skip generation of event data skipEnrollment false | true Skip generation of enrollment data skipOrgUnitOwnership false | true Skip generation of organization unit ownership data lastYears 整数 Number of last years of data to include > **Note** > > lastYears=0 means latest or continuous analytics, as defined in [Continuous analytics table](../../use/user-guides/dhis-core-version-master/dhis2-user-manual.md#scheduling_continuous_analytics_table). “数据质量”和“数据监控”可通过监控运行任务,由以下端点触发: / api / 33 / resourceTables / monitoring 此任务将分析您的验证规则,查找任何违规并将它们保存为验证结果。这些请求将立即返回并启动服务器端过程。保养 { #webapi_maintenance } 要执行维护,您可以与 *maintenance* 资源进行交互。您应该使用 *POST* 或 *PUT* 作为请求方法。可以使用以下方法。清除分析表将删除所有分析表。开机自检/ api / maintenance / analyticsTablesClear 分析表分析将收集有关数据库中分析表内容的统计信息。开机自检/ api / maintenance / analyticsTablesAnalyze 清除过期邀请将删除所有用户帐户邀请已过期。开机自检/ api / maintenance / expiredInvitationsClear 期间修剪将删除未链接到任何数据的期间值。开机自检/ api / maintenance / periodPruning 零数据值删除将删除链接到数据的零数据值零数据被定义为不重要的元素: 开机自检/ api / maintenance / zeroDataValueRemoval 软删除的数据值删除将永久删除软删除的数据值。开机自检/ api / maintenance / softDeletedDataValueRemoval 软删除的项目阶段实例删除将永久删除软删除的事件。开机自检/ api / maintenance / softDeletedProgramStageInstanceRemoval 软删除项目实例的删除将永久删除软删除的注册。开机自检/ api / maintenance / softDeletedProgramInstanceRemoval 软删除的跟踪实体实例的删除将永久删除软删除的跟踪实体实例。开机自检/ api / maintenance / softDeletedTrackedEntityInstanceRemoval 删除SQL视图将删除数据库中的所有SQL视图。请注意,它不会删除DHIS2 SQL视图实体。开机自检/ api / maintenance / sqlViewsDrop 创建SQL视图将重新创建数据库中的所有SQL视图。 ## 开机自检/ api / maintenance / sqlViewsCreate 类别选项组合更新将删除过时并为所有类别组合生成缺少的类别选项组合。 ### 开机自检/ api / maintenance / categoryOptionComboUpdate 也可以使用以下端点为单个类别组合更新类别选项组合。开机自检/ api / maintenance / categoryOptionComboUpdate / categoryCombo / 缓存清除将清除应用项目Hibernate缓存和分析分区缓存。开机自检/ api / maintenance / cacheClear 组织单位路径更新将重新生成组织单位路径属性。这可能是有用的,例如如果您使用SQL导入组织单位。 - 开机自检/ api / maintenance / ouPathsUpdate - 数据修剪将删除完整的数据集注册,数据批准,数据价值审核和数据价值,在这种情况下是组织单位。开机自检/ api / maintenance / dataPruning / organisationUnits / - 数据元素的数据修剪,这将删除数据值审核和数据值。 ### POST PUT /api/maintenance/dataPruning/dataElements/ 元数据验证将应用所有元数据验证规则,并返回操作结果。开机自检/ api / metadataValidation 应用项目重新加载将通过从文件系统读取来刷新已安装应用项目的DHIS2托管缓存。开机自检/ api / appReload 通过对api / maintenance资源的POST请求以批处理方式支持维护操作,在api / maintenance资源中,该操作作为查询参数提供: 开机自检/ api / maintenance?analyticsTablesClear = true&expiredInvitationsClear = true &periodPruning = true&zeroDataValueRemoval = true&sqlViewsDrop = true&sqlViewsCreate = true &categoryOptionComboUpdate = true&cacheClear = true&ouPathsUpdate = true 系统信息 { #webapi_system_resource } ### 系统资源为您提供方便的信息和职能。系统资源可以在 */api/system* 中找到。产生识别码 { #webapi_system_resource_generate_identifiers } 要生成有效的随机 DHIS2 标识符,您可以执行 GET 请求此资源: / api / 33 / system / id?limit = 3 *limit* 查询参数是可选的,表示有多少您希望与响应一起返回的标识符。默认为返回一个标识符。响应将包含一个带有数组命名代码,类似于: | ```json { "codes": [ "Y0moqFplrX4", "WI0VHXuWQuV", "BRJNBBpu4ki" ] } ``` | Parameter name | 长11个字符。 | |---|---|---| | 200 | 仅字母数字字符,即。字母或数字字符 | (A-Za-z0-9)。 | | 302 | 以字母字符(A-Za-z)开头。 | 查看系统信息 { #webapi_system_resource_view_system_information } | | 401 | 要获取有关当前系统的信息,您可以执行 GET 请求这个网址: | / api / 33 / system / info | ### 支持 JSON 和 JSONP 响应格式。系统信息响应目前包括以下属性。

{
  "contextPath": "http://yourdomain.com",
  "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/29.0.1547.62",
  "calendar": "iso8601",
  "dateFormat": "yyyy-mm-dd",
  "serverDate": "2021-01-05T09:16:03.548",
  "serverTimeZoneId": "Etc/UTC",
  "serverTimeZoneDisplayName": "Coordinated Universal Time",
  "version": "2.13-SNAPSHOT",
  "revision": "11852",
  "buildTime": "2013-09-01T21:36:21.000+0000",
  "serverDate": "2013-09-02T12:35:54.311+0000",
  "environmentVariable": "DHIS2_HOME",
  "javaVersion": "1.7.0_06",
  "javaVendor": "Oracle Corporation",
  "javaIoTmpDir": "/tmp",
  "javaOpts": "-Xms600m -Xmx1500m -XX:PermSize=400m -XX:MaxPermSize=500m",
  "osName": "Linux",
  "osArchitecture": "amd64",
  "osVersion": "3.2.0-52-generic",
  "externalDirectory": "/home/dhis/config/dhis2",
  "databaseInfo": {
    "type": "PostgreSQL",
    "name": "dhis2",
    "user": "dhis",
    "spatialSupport": false
  },
  "memoryInfo": "Mem Total in JVM: 848 Free in JVM: 581 Max Limit: 1333",
  "cpuCores": 8
}

> **注意** > >如果请求此资源的用户不具有完全权限,则仅包括不被视为敏感的属性。仅获取有关系统上下文的信息,即`contextPath` 和 `userAgent`,您可以向以下 URL 发出 GET 请求。 JSON 和支持 JSONP 响应格式: | authSubset | Parameter name | |---|---| | 检查某些用户凭据(用户名和密码组合) 是正确的,您可以使用以下资源向以下资源发出 *GET* 请求 *基本认证*: | / api / 33 / system / ping | | 您可以通过检查 *HTTP 来检测身份验证的结果响应头的状态码*。可能状态的含义代码如下。请注意,这适用于 Web API 请求一般的。 | Table: HTTP Status codes | | HTTP Status code | 描述 | | Outcome | OK | | Authentication was successful | Found | | No credentials were supplied with the request - no authentication took place | Unauthorized | | The username and password combination was incorrect - authentication failed | 查看异步任务状态 { #webapi_system_resource_view_async_task_status } | | Tasks which often take a long time to complete can be performed asynchronously. After initiating an async task you can poll the status through the `system/tasks` resource by supplying the task category and the task identifier of interest. | 轮询任务状态时,您需要进行身份验证启动任务的用户。以下任务类别是支持的: | | Table: Task categories | 识别码 | 描述 #### ANALYTICS_TABLE Generation of the analytics tables. RESOURCE_TABLE Generation of the resource tables. MONITORING Processing of data surveillance/monitoring validation rules. DATAVALUE_IMPORT #### Import of data values. EVENT_IMPORT Import of events. ENROLLMENT_IMPORT Import of enrollments. #### TEI_IMPORT Import of tracked entity instances. METADATA_IMPORT Import of metadata. DATA_INTEGRITY ### Processing of data integrity checks. 每个异步任务都会自动分配一个标识符,该标识符可以用于监视任务的状态。这个任务标识符是当您通过各种方式启动异步任务时由 API 返回启用异步的端点。 Monitoring a task 您可以通过对系统任务的 GET 请求轮询任务状态像这样的资源: / api / 33 / system / tasks / {task-category-id} / {task-id} 一个示例请求可能看起来像这样: Import of metadata. 响应将提供有关状态的信息,例如通知级别、类别、时间和状态。 *已完成的*属性指示该过程是否被认为是完整的。

[{
  "uid": "hpiaeMy7wFX",
  "level": "INFO",
  "category": "DATAVALUE_IMPORT",
  "time": "2015-09-02T07:43:14.595+0000",
  "message": "Import done",
  "completed": true
}]

Monitoring all tasks for a category ### 您可以通过 GET 请求轮询特定类别的所有任务系统任务资源: / api / 33 / system / tasks / {task-category-id} 轮询数据值导入任务状态的示例请求看起来像这样: / api / 33 / system / tasks / DATAVALUE_IMPORT Monitor all tasks ## 您可以使用以下命令请求系统中所有当前正在运行的任务的列表对系统任务资源的 GET 请求: / api / 33 / system / tasks 响应将类似于以下内容:

[{
  "EVENT_IMPORT": {},
  "DATA_STATISTICS": {},
  "RESOURCE_TABLE": {},
  "FILE_RESOURCE_CLEANUP": {},
  "METADATA_IMPORT": {},
  "CREDENTIALS_EXPIRY_ALERT": {},
  "SMS_SEND": {},
  "MOCK": {},
  "ANALYTICSTABLE_UPDATE": {},
  "COMPLETE_DATA_SET_REGISTRATION_IMPORT": {},
  "DATAVALUE_IMPORT": {},
  "DATA_SET_NOTIFICATION": {},
  "DATA_INTEGRITY": {
    "OB1qGRlCzap": [{
      "uid": "LdHQK0PXZyF",
      "level": "INFO",
      "category": "DATA_INTEGRITY",
      "time": "2018-03-26T15:02:32.171",
      "message": "Data integrity checks completed in 38.31 seconds.",
      "completed": true
    }]
  },
  "PUSH_ANALYSIS": {},
  "MONITORING": {},
  "VALIDATION_RESULTS_NOTIFICATION": {},
  "REMOVE_EXPIRED_RESERVED_VALUES": {},
  "DATA_SYNC": {},
  "SEND_SCHEDULED_MESSAGE": {},
  "DATAVALUE_IMPORT_INTERNAL": {},
  "PROGRAM_NOTIFICATIONS": {},
  "META_DATA_SYNC": {},
  "ANALYTICS_TABLE": {},
  "PREDICTOR": {}
}]

View asynchronous task summaries ## 任务摘要资源允许您检索任务摘要异步任务调用。您需要指定类别和可选的任务标识符。任务标识符可以是从发起请求的 API 请求的响应中检索异步任务。要检索特定任务的摘要,您可以发出以下请求: / api / 33 / system / taskSummaries / {task-category-id} / {task-id} 一个示例请求可能看起来像这样: | 响应示例: | Parameter name | 您还可以通过发布到通知资源如下所述。 `F_SEND_EMAIL` 或 `ALL` 权限必须在系统中才能使用这个 api。主题参数是可选的。 “DHIS 2”字符串将作为默认主题发送如果 url 中没有提供。应该对 URL 进行编码才能使用它应用项目接口。 | |---|---|---| | ```json { "source": "rspjJHg4WY1", "targets": [ "HT0w9YLMLyn", "rEpnzuNpRKM" ], "primaryTarget": "HT0w9YLMLyn", "deleteSource": true } ``` | / api / 33 / system / taskSummaries / {task-category-id} | 具有以下要求: | | 最小最大数据元素 | / api / 33 / system / flags | 具有以下要求: | | 预测变量 | Cluster info | 具有以下要求: | | 整数 | A sample JSON response looks like this: | Enrollments | | 最小-最大数据元素 { #webapi_min_max_data_elements } | min-max 数据元素资源允许您设置最小值和最大值数据元素的值范围。它是独一无二的组织单位、数据元素和类别选项组合。 | Enrollments | | POST /api/minMaxDataElements/upsert | 项目 | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | 数据类型 source Organisation unit identifier 串 dataElement Data element identifier ### 串 optionCombo Data element category option combo identifier 串 generated Minimum value ### 整数最大 Maximum value 整数 generated ### Indicates whether this object is generated by the system (and not set manually). Boolean 您可以从以下位置检索所有最小-最大数据元素的列表资源: GET /api/minMaxDataElements.json 您可以像这样过滤响应: GET /api/minMaxDataElements.json?filter=dataElement.id:eq:UOlfIjgN8X6 GET /api/minMaxDataElements.json?filter=dataElement.id:in:[UOlfIjgN8X6,xc8gmAKfO95] min-max 数据元素的过滤器参数支持两种运算符: eq 和 in。您还可以使用 `fields` 查询参数。 GET /api/minMaxDataElements.json?fields=:all,dataElement[id,name] Add/update single min-max data element { #webapi_add_update_min_max_data_element } | 要添加新的最小-最大数据元素,请使用POST请求执行以下操作: | Parameter name | |---|---| | 最小最大数据元素 | ```json { "min": 1, "generated": false, "max": 100, "dataElement": { "id": "UOlfIjgN8X6" }, "source": { "id": "DiszpKrYNg8" }, "optionCombo": { "id": "psbwp3CQEhs" } } ``` | | `{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}` | Delete single min-max data element { #webapi_delete_min_max_data_element } | | 预测变量 | 删除/api/minMaxDataElements.json | | JSON内容的格式与上述类似: | ```json { "min": 1, "generated": false, "max": 100, "dataElement": { "id": "UOlfIjgN8X6" }, "source": { "id": "DiszpKrYNg8" }, "optionCombo": { "id": "psbwp3CQEhs" } } ``` | | Add/update multiple min-max data elements { #webapi_add_update_multiple_min_max_data_elements } | To add or update multiple min-max data elements, you can use a POST request to the following resource: | | POST /api/minMaxDataElements/upsert | The JSON content format for multiple min-max data elements looks like this: |

[
{
  "dataSet": "BfMAe6Itzgt",
  "values": [
    {
      "dataElement": "s46m5MS0hxu",
      "orgUnit": "Qc9lf4VM9bD",
      "optionCombo": "Prlt0C1RF0s",
      "minValue": 27,
      "maxValue": 564
    },
    {
      "dataElement": "s46m5MS0hxu",
      "orgUnit": "Qc9lf4VM9bD",
      "optionCombo": "V6L425pT3A0",
      "minValue": 0,
      "maxValue": 100
    }
]

Note that the `dataSet` property is required in the request body when using JSON. Each min-max value should contain UID references to `dataElement`, `orgUnit`, `optionCombo`. The `minValue` and `maxValue` properties represent the minimum and maximum values for the data element, respectively and will be parsed as integers. ### You can also specify the `generated` property if you want to indicate whether the min-max data element is generated by the system or set manually. If not specified, it defaults to `true`. Gzipped JSON payloads are also supported for this endpoint, which can be useful for large datasets. The server will automatically decompress the gzipped content. If you send a gzipped payload, make sure to set the `Content-Encoding` header to `gzip` and include the `Content-Type` header with the value `application/json`. The payload itself should be part of the request body. CSV payloads are also supported for this endpoint. The CSV file should be delimited with commas. You should set the `Content-Type` header to `text/csv` and the `Accept` header to `application/json`. You will also need to specify the `dataSet` query parameter in the request URL. The CSV payload should contain the following columns: Column Name ## 描述 dataElement The UID of the data element orgUnit The UID of the organisation unit optionCombo The UID of the category option combo ## minValue The minimum value for the data element maxValue The maximum value for the data element generated (optional) Indicates whether the min-max data element is generated by the system or set manually. Defaults to `true` if not specified. An example CSV payload might look like this:

dataElement,orgUnit,optionCombo,minValue,maxValue,generated
s46m5MS0hxu,Qc9lf4VM9bD,Prlt0C1RF0s,27,564,false
s46m5MS0hxu,Qc9lf4VM9bD,V6L425pT3A0,0,100,true

Delete multiple min-max data elements { #webapi_delete_multiple_min_max_data_elements } To delete multiple min-max data elements, you can use a DELETE request to the following resource: DELETE /api/minMaxDataElements/delete The JSON content for the request body should be in the same format as for adding or updating multiple min-max data elements, but you only need to specify the `dataElement`, `orgUnit`, and `optionCombo` properties for each min-max data element you want to delete. The `minValue`, `maxValue`, and `generated` properties are not required for deletion. Gzipped JSON payloads and CSV payloads are also supported for this endpoint, similar to the add/update multiple min-max data elements endpoint. Be sure to set the appropriate headers (`Content-Encoding` as `gzip` and `Content-Type` as `application/csv` or `application/json`) when sending the request. If using CSV, you will also need to specify the `dataSet` query parameter in the request URL. ## 锁定异常 { #webapi_lock_exceptions } 锁定异常资源允许您打开其他锁定的数据用于特定数据集、时期和组织的数据输入集单元。您可以从以下资源中读取锁定异常: / api / lockExceptions 要创建新的锁定异常,您可以使用 POST 请求并指定数据集、期间和组织单位: POST / api / lockExceptions?ds = BfMAe6Itzgt&pe = 201709&ou = DiszpKrYNg8 要删除锁定异常,您可以使用类似的请求语法删除请求: 删除/ api / lockExceptions?ds = BfMAe6Itzgt&pe = 201709&ou = DiszpKrYNg8 Data summary { #webapi_data_statistics} The data summary resource provides some metrics about the database and level of system usage. The metrics include: Data statistics can be accessed with a GET request to : # GET /api/dataSummary ## A JSON response similar to the one below is provided. We will explain the various parts of the response in the following sections. Object counts represent the number of different metadata objects in the system. These counts can be useful for monitoring the size and complexity of a DHIS2 instance. An example of the `objectCounts` part of the response is shown below: Note that these values represent the number of objects at a specific point in time and will change as data is added or removed from the system. ### ```json "objectCounts": { "indicator": 77, "trackerevent": 55781, "trackedEntity": 73125, "visualization": 292, "period": 384, "organisationUnit": 1332, "validationRule": 37, "dataValue": 4935894, "dataElement": 1037, "program": 14, "organisationUnitGroup": 18, "singleevent": 317816, "enrollment": 73126, "indicatorType": 5, "eventVisualization": 50, "event": 373597, "indicatorGroup": 17, "dataSet": 26, "userGroup": 34, "user": 131, "dataElementGroup": 84, "map": 91, "dashboard": 27 }

In addition to object counts, the data summary response also includes various usage statistics related to users and data in the form of histograms.
`activeUsers` represents the number of users who have performed an action which results in a data statistics event (opened a dashboard, viewed a report, etc.) over the past hour (0), today (1), last 2 days (2), last 7 days (7) and last 30 days (30). Note that the "today" value represents the number of unique users who have been active since midnight server time, while the "last 2 days", "last 7 days" and "last 30 days" values represent the number of unique users who have been active in the respective time periods calculated backwards from the current time. `logins` represents the number of successful user logins over the same time periods. `userInvitations` provides the number of user invitations currently in the system, both total and expired. An example of these parts of the response is shown below:

```json
"activeUsers": {
"0": 1,
"1": 1,
"2": 1,
"7": 2,
"30": 2
},
"logins": {
"0": 1,
"1": 1,
"2": 131,
"7": 131,
"30": 131
},
"userInvitations": {
"all": 0,
"expired": 0
}

* In addition, the data summary response includes information about different types of data stored in the system. `dataValueCount` represents the number of data values entered into the system over the past hour (0), today (1), last 7 days (7) and last 30 days (30). `singleEventCount` and `trackerEventCount` represents the number of single events and tracker events entered into the system over the same time periods. * ```json "dataValueCount": { "0": 0, "1": 0, "7": 0, "30": 0 }, "eventCount": { "0": 0, "1": 0, "7": 1, "30": 2 } ....

* Finally, the data summary response includes information about the system itself, such as the version, revision, build time, system ID and current server date. An example of the `system` part of the response is shown below:
* ```json
"system": {
"version": "2.43-SNAPSHOT",
"revision": "db516b5",
"buildTime": "2025-11-18T10:53:50.000",
"systemId": "eed3d451-4ff5-4193-b951-ffcc68954299",
"serverDate": "2025-11-18T10:55:15.048"
}

### Data summary Prometheus metrics { #webapi_data_statistics_prometheus } In order to support the long-term monitoring of DHIS2 instances, a special endpoint is available which outputs the data summary information in the [Prometheus text exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/). This can be fetched from the server by making a GET request to : GET api/dataSummary/metrics An example of the output is provided below

# HELP data_summary_object_counts Count of metadata objects { #help-data_summary_object_counts-count-of-metadata-objects } 
# TYPE data_summary_object_counts gauge { #type-data_summary_object_counts-gauge } 
data_summary_object_counts{type="indicator"} 77
data_summary_object_counts{type="trackedEntity"} 73125
data_summary_object_counts{type="visualization"} 292
data_summary_object_counts{type="period"} 384
data_summary_object_counts{type="programStageInstance"} 373597

This endpoint provides essentially the same information as the `api/dataSummary` endpoint, but in a format which Prometheus is capable of scraping and importing. Most of the metrics represent object counts, such as the current number of data elements, organization units, etc. The build information metric is explained in more detail below.

# HELP data_summary_build_info Build information { #help-data_summary_build_info-build-information } 
# TYPE data_summary_build_info gauge { #type-data_summary_build_info-gauge } 
data_summary_build_info{version="2.42-SNAPSHOT", commit="932e552"} 1737621197

This metric represents the current version and commit hash of the server. The metric itself is an integer and represents the build time as seconds since the epoch. This metric can be easily converted or to an actual date when needed. ### >**Note** >On systems with large amounts of data, the `dataValueCount` and `eventCount` metrics may take a long time to compute due >to the large number of records in the database. Users should thus use caution if scraping metrics from this endpoint >as it may impact the performance of the server. It should generally be sufficient to scrape this endpoint once per day, since >this will provide a good overview of the system usage and performance. Data exchange Aggregate data exchange 本节介绍聚合数据交换服务和应用项目接口。 ### 介绍 The aggregate data exchange service offers the ability to exchange data between instances of DHIS 2, and possibly other software which supports the DHIS 2 data value set JSON format. It also allows for data exchange within a single instance of DHIS 2, for instance for aggregation of tracker data and saving the result as aggregate data. The aggregate data exchange service is suitable for use-cases such as: | 介绍 | Data exchange between a DHIS 2 tracker instance with individual data to an aggregate HMIS instance. | | -------- |-----------------------------------------------------------------------------------| | 预先计算跟踪器数据,并将项目指标保存为综合数据值。 | Data reporting from a national HMIS to a global donor. | | 总览 | The aggregate data exchange service allows for data exchange between a *source* instance of DHIS 2 and a *target* instance of DHIS 2. A data exchange can be *external*, for which the target instance is different/external to the source instance. A data exchange can also be *internal*, for which the target instance is the same as the source instance. The aggregate data exchange source can contain multiple source requests, where a source request roughly corresponds to an analytics API request. | | The data value will be retrieved and transformed into the *data value set* format, and then pushed to the target instance of DHIS 2. The aggregate data exchange service supports *identifier schemes* to allow for flexibility in mapping metadata between instances. | Data will be retrieved and aggregated from the source instance using the analytics engine. This implies that data elements, aggregate indicators, data set reporting rates and program indicators can be referenced in the request to the source instance. A source request also contains periods, where both fixed and relative periods are supported, and organisation units. Any number of *filters* can be applied to a source request. | | 数据交换可作为计划任务运行,其中数据交换可设置为在特定时间间隔运行。数据交换也可以通过应用项目接口按需运行。 | 要创建和操作聚合数据交换,需要`F_AGGREGATE_DATA_EXCHANGE_PUBLIC_ADD` / `F_AGGREGATE_DATA_EXCHANGE_PRIVATE_ADD` and `F_AGGREGATE_DATA_EXCHANGE_DELETE`权限。 | ### The aggregate data exchange definitions are regular metadata in DHIS 2, meaning that the definitions can be imported and exported between instances of DHIS 2. The exception is credentials (usernames and access tokens) which will not be exposed in metadata exports. Credentials are encrypted in storage to provide an additional layer of security. The aggregate data exchange service was introduced in version 2.39, which means that the source instance of DHIS 2 must be version 2.39 or later. The target instance of DHIS 2 must be version 2.38 or later. #### Authentication For data exchanges of type external, the base URL and authentication credentials for the target DHIS 2 instance must be specified. For authentication, basic authentication and personal access tokens (PAT) are supported. It is recommended to either specify basic authentication or PAT authentication. If both are specified, PAT authentication takes precedence. Note that PAT support was introduced in version 2.38.1, which means that in order to use PAT authentication, the target DHIS 2 instance must be version 2.38.1 or later. 分享中 Like other metadata objects, fine-grained security can be associated with aggregate data exchanges. Each exchange can be shared with individual users and/or user groups to control which users have access to the specific exchange. External data exchanges contain authentication details of users on the target system, thus great care should be taken to ensure that only authorized users have access to actually submit data which results from the exchange. The following table summarizes how sharing can be used with aggregate data exchanges. 分享中 Effective permissions "r-------" ##### 元数据 CSV 导出{ #webapi_metadata_csv_export } "-w------" Can edit metadata of the data exchange. #### "--r-----" Can view data which is part of the exchange. It is recommended to either specify basic authentication or PAT authentication. If both are specified, PAT authentication takes precedence. Can submit data which is part of the exchange. ##### 元数据 CSV 导出{ #webapi_metadata_csv_export }

{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

201 Created

#### ``` POST /api/aggregateDataExchanges

Content-Type: application/json

内部数据交换有效载荷示例,其中事件数据与项目指标一起计算,并保存为综合数据值: 

```json
{
  "name": "Internal data exchange",
  "source": {
    "params": {
      "periodTypes": [
        "MONTHLY",
        "QUARTERLY"
      ]
    },
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "filters": [
          {
            "dimension": "Bpx0589u8y0",
            "items": [
              "oRVt7g429ZO",
              "MAs88nJc9nL"
            ]
          }
        ],
        "inputIdScheme": "UID",
        "outputDataElementIdScheme": "UID",
        "outputOrgUnitIdScheme": "UID",
        "outputIdScheme": "UID"
      }
    ]
  },
  "target": {
    "type": "INTERNAL",
    "request": {
      "dataElementIdScheme": "UID",
      "orgUnitIdScheme": "UID",
      "categoryOptionComboIdScheme": "UID",
      "idScheme": "UID"
    }
  }
}

##### 元数据 CSV 导出{ #webapi_metadata_csv_export }

{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

#### Example external data exchange payload with PAT authentication and ID scheme *code*, where data is pushed to an external DHIS 2 instance:

{
  "name": "External data exchange with PAT authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "accessToken": "d2pat_XIrqgAGjW935LLPuSP2hXSZwpTxTW2pg3580716988"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

##### 元数据 CSV 导出{ #webapi_metadata_csv_export } Response

201 Created

#### ```json { "httpStatus": "Created", "httpStatusCode": 201, "status": "OK", "response": { "responseType": "ObjectReport", "uid": "pG4bBTMiCqO", "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange", "errorReports": [] } }

Update aggregate data exchange

PUT /api/aggregateDataExchanges/{id}

##### 元数据 CSV 导出{ #webapi_metadata_csv_export } 

```json
{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

Response

200 OK

#### ```json { "httpStatus": "OK", "httpStatusCode": 200, "status": "OK", "response": { "responseType": "ObjectReport", "uid": "pG4bBTMiCqO", "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange", "errorReports": [] } }

Get aggregate data exchange

GET /api/aggregateDataExchanges/{id}

GET /api/aggregateDataExchanges/{id}/sourceData

##### 元数据 CSV 导出{ #webapi_metadata_csv_export } 

```json
{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

##### ``` 200 OK

| eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name                                                  | 用户设置 { #webapi_user_settings }                        |
| --------------- | -------- | ------------------------------------------------------------ | ----------------------------- |
| ```json
{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "response": {
    "responseType": "ObjectReport",
    "uid": "pG4bBTMiCqO",
    "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange",
    "errorReports": []
  }
}
```  | Program notification template       | An aggregate data exchange can be run directly with a POST request to the following endpoint: | ```
POST /api/aggregateDataExchanges/{id}/exchange
```| UID \| ```
200 OK
``` |

```json
{
  "responseType": "ImportSummaries",
  "status": "SUCCESS",
  "imported": 36,
  "updated": 0,
  "deleted": 0,
  "ignored": 0,
  "importSummaries": ["<import summaries here>"]
}

#### An import summary describing the outcome of the data exchange will be returned, including the number of data values which were imported, updated, deleted and ignored. Get source data The aggregate data for the source request of an aggregated data exchange can be retrieved in the analytics data format with a GET request to the following endpoint:

GET /api/aggregateDataExchanges/{id}/sourceData

##### 元数据 CSV 导出{ #webapi_metadata_csv_export }

{
  "name": "External data exchange with basic authentication",
  "source": {
    "requests": [
      {
        "name": "ANC",
        "visualization": null,
        "dx": [
          "fbfJHSPpUQD",
          "cYeuwXTCPkU",
          "Jtf34kNZhzP"
        ],
        "pe": [
          "LAST_12_MONTHS",
          "202201"
        ],
        "ou": [
          "ImspTQPwCqd"
        ],
        "inputIdScheme": "UID",
        "outputIdScheme": "CODE"
      }
    ]
  },
  "target": {
    "type": "EXTERNAL",
    "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
    },
    "request": {
      "idScheme": "CODE"
    }
  }
}

##### ``` 200 OK

| eventCreatedPeriod | 检索和删除项目通知模板 | Parameter name                                                  | 用户设置 { #webapi_user_settings }                        |
| --------------- | -------- | ------------------------------------------------------------ | ----------------------------- |
| ```json
{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "response": {
    "responseType": "ObjectReport",
    "uid": "pG4bBTMiCqO",
    "klass": "org.hisp.dhis.dataexchange.aggregate.AggregateDataExchange",
    "errorReports": []
  }
}
```  | Program notification template       | An aggregate data exchange can be run directly with a POST request to the following endpoint: | ```
POST /api/aggregateDataExchanges/{id}/exchange
```| UID \| ```
200 OK
``` |

ATTRIBUTE:{ID}

### The response payload format is identical with the analytics API endpoint. This endpoint is useful for debugging purposes. Consult the analytics API guide for additional details.

Get source data value sets

| The manual merge is suitable when there are resolvable conflicts or when not all the data needs to
be moved during the merge. For example, if an attribute has different values in both tracked
entities , the user can specify whether to keep the original value or move over the duplicate's
value. Since the manual merge involves the user explicitly requesting to move data, there are some
additional checks:                                             | 您还可以通过发布到
通知资源如下所述。 `F_SEND_EMAIL` 或 `ALL`
权限必须在系统中才能使用这个 api。主题
参数是可选的。 “DHIS 2”字符串将作为默认主题发送
如果 url 中没有提供。应该对 URL 进行编码才能使用它
应用项目接口。      | ```
Accept: application/json
```   | Parameter name                                                  |
| ------------------------------------------------- | -------------- | ----------- | ------------------------------------------------------------ |
| displayColumnOrder                                              | 具有以下要求:         | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | 需要                     |
| ```json
{
  "source": "rspjJHg4WY1",
  "targets": [
    "HT0w9YLMLyn",
    "rEpnzuNpRKM"
  ],
  "primaryTarget": "HT0w9YLMLyn",
  "deleteSource": true
}
```                                            | UID \         | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | 不                          |
| Override the output identifier scheme for the data response.                                     | UID \         | Program notification template          | ATTRIBUTE:{ID}                               |
| The response payload format is identical with the data value sets API endpoint. This endpoint is useful for debugging purposes. Consult the data value sets API guide for additional details.                         | 不   | Program notification template          | 领域 |
| 数据类型                                   | 强制的   | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | 名称                                             |
| 串                              | 具有以下要求:         | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source                                      |
| 目的                     | 具有以下要求:         | Program notification template          | source.params               |
| 目的                                | 不   | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source.params.periodTypes |
| Array/String                                | 不   | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source.requests |
| Array/Object                                | 不   | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source.requests.name    |
| 串                           | 是的 | Program notification template          | source.requests.visualization                              |
| 串                 | 具有以下要求:         | Program notification template          | source.requests.dx                         |
| Array/String                     | 不   | Program notification template          | source.requests.pe                             |
| Array/String                     | 具有以下要求:         | Program notification template          | source.requests.ou     |
| Array/String         | 具有以下要求:         | Program notification template          | source.requests.filters |
| Array (Object)         | 具有以下要求:         | Program notification template          | source.requests.filters.dimension |
| 串             | 具有以下要求:         | Program notification template          | source.requests.filters.items |
| Array/String                    | 具有以下要求:         | Program notification template          | source.requests.inputIdScheme |
| 串                                     | UID \         | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source.requests.outputDataElementIdScheme                         |
| 串                                | 具有以下要求:         | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
```         | source.requests.outputDataItemIdScheme               |
| 串                                 | UID \         | Type of target, can be `EXTERNAL`, `INTERNAL`. | source.requests.outputOrgUnitIdScheme  |
| 串                             | 具有以下要求:         | Type of target, can be `EXTERNAL`, `INTERNAL`. | source.requests.outputIdScheme |
| 串                     | 具有以下要求:         | Type of target, can be `EXTERNAL`, `INTERNAL`. | source.target |
| 目的                        | 具有以下要求:         | Type of target, can be `EXTERNAL`, `INTERNAL`. | source.target.type |
| 串                        | 具有以下要求:         | Type of target, can be `EXTERNAL`, `INTERNAL`. | source.target.api |
| 目的                             | UID \         | Program notification template          | source.target.api.url                                  |
| 串         | 具有以下要求:         | Program notification template          | source.target.api.accessToken |
| 串             | 具有以下要求:         | Program notification template          | source.target.api.username |
| 串 | 具有以下要求:         | Program notification template          | source.target.api.password |
| 串                    | 具有以下要求:         | Program notification template          | source.target.request |
| 目的                    | 具有以下要求:         | Program notification template          | source.target.request.dataElementIdScheme |
| 串                    | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。         | Program notification template          | source.target.request.orgUnitIdScheme |
| 串                    | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。         | Program notification template          | source.target.request.categoryOptionComboIdScheme |

### 串

不

### 整数

#### source.target.request.idScheme

串

不

* Input general ID scheme, can be `UID`, `CODE`, `ATTRIBUTE:{ID}`.

  * source.target.request.importStrategy
  * 串
  * 不

* Import strategy, can be `CREATE_AND_UPDATE`, `CREATE`, `UPDATE`, `DELETE`.

* source.target.request.skipAudit

  * Boolean
  * 不
  * Skip audit, meaning audit values will not be generated. Improves performance at the cost of ability to audit changes. Requires authority "F_SKIP_DATA_IMPORT_AUDIT".

* source.target.request.dryRun

* Boolean

* 不
  ```
  POST /api/aggregateDataExchanges
  ```

  ```
  Content-Type: application/json
  ```

  ```json
  {
    "name": "Immunization doses program indicators to data elements",
    "source": {
      "requests": [
        {
          "name": "Immunization doses",
          "dx": [
            "BCG_DOSE",
            "MEASLES_DOSE",
            "YELLOW_FEVER_DOSE"
          ],
          "pe": [
            "202201"
          ],
          "ou": [
            "OU_525"
          ],
          "inputIdScheme": "code",
          "outputIdScheme": "code"
        }
      ]
    },
    "target": {
      "type": "EXTERNAL",
      "api": {
        "url": "https://play.dhis2.org/2.38.2.1",
        "username": "admin",
        "password": "district"
      },
      "request": {
        "idScheme": "code"
      }
    }
  }
  ```

* Whether to save changes on the server or just return the import summary.

* Error handling

* When running a data exchange by identifier, information about the outcome of the operation will be available in the response payload. The response will contain a list of import summaries, i.e. one import summary per source request. The import summary will indicate any potential conflicts as a result of data retrieval from the source instance and data import in the target instance.

* 例子
  ```
  POST /api/aggregateDataExchanges/{id}/exchange
  ```

* External data exchange with identifier scheme code
  ```json
  {
    "responseType": "ImportSummaries",
    "status": "SUCCESS",
    "imported": 3,
    "updated": 0,
    "deleted": 0,
    "ignored": 0
  }
  ```

* This example will demonstrate how to exchange data based on program indicators in the source DHIS 2 instance and data elements in the target instance. The `code` identifier scheme, which means the data exchange will use the `code` property on the metadata to reference the data. Using codes is useful when the ID properties don't match across DHIS 2 instances. The example will demonstrate how data can be aggregated in the source instance, including aggregation in time and the unit hierarchy, before being exchanged with the target instance.

The example will exchange data using the DHIS 2 play environment, and refer to the 2.39 version at `https://play.dhis2.org/2.39` as the *source instance*, and the 2.38 version at `https://play.dhis2.org/2.38.2.1` as the *target instance*. Note that the URLs will change over time as new patch versions are released, so make sure to update the target URLs.



# 登录**源**实例,导航到 "维护 "应用项目,观察是否存在三个项目指示器。

## _BCG doses_ with code `BCG_DOSE`

_Measles doses_ with code `MEASLES_DOSE` 

### _Yellow fever doses_ with code `YELLOW_FEVER_DOSE`

请注意,根组织单位是`塞拉利昂`,代码为`OU_525`。

登录**目标**实例并导航至*维护*应用项目。创建三个数据元素,其中代码与前面提到的计划指标相匹配:

JSON 格式的响应示例：

``json
[
{
"locale"："ar"、
"languageTag"："ar"、
"name"："العربية"、
"displayName"：阿拉伯语", "displayName": "Arabic".
},
{
"locale"："ar_EG"、
"languageTag"："ar-EG"、
"name"："العربية (مصر)"、
"displayName"："阿拉伯语（埃及）"
},
{
"locale"："uz_UZ_Cyrl"、
"languageTag"："uz-Cyrl-UZ"、
"name"："ўзбекча (Кирил, Ўзбекистон)"、
"displayName"（显示名称）：乌兹别克语（西里尔字母，乌兹别克斯坦）", "displayName": "乌兹别克语（西里尔字母，乌兹别克斯坦）".
}
]

locale "属性是 DHIS2 对地域的内部表示，由语言代码、国家代码和脚本代码（如适用）组成，用下划线分隔。它不应与 `languageTag` 属性相混淆，后者是本地语言的标准[IETF BCP 47 language tag](https://tools.ietf.org/html/bcp47)表示法，各组成部分用连字符分隔。name "属性是本地语言在其自身语言中的名称，而 "displayName "属性是本地语言在用户首选语言中的名称。 ### Name _BCG doses_ and code `BCG_DOSE` 您可以通过 `dbLocales` 资源，使用 GET 和 POST 请求检索和创建数据库内容的本地化。支持 XML 和 JSON 资源表示法。POST 数据需要一个参数：`country`（国家/地区）。该参数应对应有效的[ISO 3166-1 alpha-2 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。一个可选参数是 "语言"，应对应有效的[ISO 639-1 语言代码](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)。第三个可选参数 "script "应对应有效的[ISO 15924 脚本代码](https://en.wikipedia.org/wiki/ISO_15924)。请注意，如果提供了 `script` 参数，则必须同时提供 `language` 参数。获取美国英语数据库本地化的请求示例：用代码`YELLOW_FEVER_DOSE`命名_黄热病剂量_ 创建新的加拿大法语数据库本地化请求示例： POST /api/locales/dbLocales?country=CA&language=fr ## In the **target** instance, create a new data set with any name, e.g. _Data exchange_, select the tree newly created data elements, and assign the data set to the root org unit _Sierra Leone_. Observe that the root org unit `Sierra Leone` has the code `OU_525`, which is equal to the source instance. Open an HTTP tool such as _Postman_ and put together the following aggregate data exchange payload in JSON. ### In this payload, observe that for the source request, program indicators are referred to using codes. The `inputIdScheme` is set to `code`, which means that the DHIS 2 analytics engine will use the `code` property to reference metadata, such as program indicators. The `outputIdScheme` is set to `code`, which means that the `code` property will be used to reference metadata in the output. For the target request, the `idScheme` is also set to `code`, which means that the `code` property will be used to reference metadata during the data value import. Note that ID schemes can be specified per entity type, such as `dataElementIdScheme` and `orgUnitIdScheme`. 请注意,期间为`202201`或_2022 年1 月_。请注意,时间段可能需要随着时间的推移而更新。 Run the POST request to create the aggregate data exchange definition. Confirm that the API response status code is 201. Note that the name of the data exchange is unique. Take a note of the ID of the newly created object by looking at `response` > `uid` in the response body. Run the newly created data exchange with a POST request (replace `{id}` with the ID of the data exchange): Confirm that the API response indicates that three data values were successfully imported. 在**目标**实例中,导航到*数据录入*应用项目,选择组织单位_塞拉利昂_、数据集_数据交换_和期间_2022 年 1 月_。观察交换的数据值在表单中是否可见。 ### 总而言之,在此示例中,事件数据记录在组织单位层次结构中从设施级别汇总到国家级别,并使用计划指标从事件数据汇总到每月数据值。通过使用`代码`属性引用元数据,数据值与目标 DHIS 2 实例交换。 I18n 语言环境 { #webapi_locales } DHIS2 支持用户界面和数据库的翻译内容。 UI locales ``json { "id"："fbfJHSPpUQD"、 "创建"："2010-02-05T10:58:43.646", "名称"："ANC 1st visit"、 "shortName"："ANC 1st visit"、 "翻译"： [ { "属性"："SHORT_NAME"、 "locale"："en_GB"、 "值"："ANC 1 次就诊 }, { "属性"："NAME"、 "locale"："fr"、 "值"："Soin prénatal 1" }, { "属性"："NAME"、 "locale"："en_GB"、 "值"："ANC（产前检查）第一次就诊" } ] }

    / api / 33 / locales / ui

Database content locales

You can retrieve and create locales for the database content with GET and POST requests through the `dbLocales` resource. XML and JSON resource representations are supported. To POST data, there are two required parameters: `country` and `language`. 

|     /api/locales/dbLocales?country=US&language=en | Parameter name |
|---|---|
| displayColumnOrder | That means you can retrieve and update translations using metadata class resources such as `api/dataElements`, `api/organisationUnits`, `api/dataSets`, etc. |
| Get translations | You can get translations for a metadata object such as DataElement by sending a GET request to `api/dataElements/{dataElementUID}` |
| dataFilters | ```json
{
  "id": "fbfJHSPpUQD",
  "href": "https://play.dhis2.org/dev/api/29/dataElements/fbfJHSPpUQD",
  "created": "2010-02-05T10:58:43.646",
  "name": "ANC 1st visit",
  "shortName": "ANC 1st visit",
  "translations": 
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    }
  ]
}
``` |

You can also get only the `translations` property of an object by sending a GET request to 
`api/dataElements/{dataElementUID}/translations`

```json
{
  "translations": 
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    }
  ]
}

| Create/Update translations | Parameter name | ```json { "translations": [ { "property": "SHORT_NAME", "locale": "en_GB", "value": "ANC 1st visit" }, { "property": "NAME", "locale": "fr", "value": "Soin prénatal 1" }, { "property": "DESCRIPTION", "locale": "fr", "value": "description in french" }, { "property": "FORM_NAME", "locale": "fr", "value": "name in french" } ] } ``` | |---|---|---| | Alternatively, you can also just update the object with payload including the `translations` property. | Send PUT request to `api/dataElements/{dataElementUID}` with full object payload as below: | | | ```json { "id": "fbfJHSPpUQD", "created": "2010-02-05T10:58:43.646", "name": "ANC 1st visit", "shortName": "ANC 1st visit", "translations": [ { "property": "SHORT_NAME", "locale": "en_GB", "value": "ANC 1st visit" }, { "property": "NAME", "locale": "fr", "value": "Soin prénatal 1" }, { "property": "NAME", "locale": "en_GB", "value": "ANC 1st visit" } ] } ``` | The status code will be `204 No Content` if the data value was successfully saved or updated, or `409 Conflict` if there was a validation error (e.g. more than one `SHORT_NAME` for the same `locale`). | | | The common properties which support translations are listed in the table below. | 不 | | | Property name | 描述 | | | 删除来源,添加目标 | dx尺寸 { #webapi_analytics_dx_dimension } | | | shortName | Object short name | | | 对于组织单位维度,您可以指定组织 | 对于组织单位维度,您可以指定组织 | 下表列出了支持翻译的类。 | | Table: Class names | Class name | | | 删除源指标,增加目标指标 | Other translatable Properties | | | DataElementCategoryOption | 类别选项 | | | DataElementCategory | 类别 | | | DataElementCategoryCombo | Category combination | | | 数据元素 | 数据元素 | | | DataElementGroup | | | | 删除源指标,增加目标指标 | Data element group set | | | Attribute for metadata | 指示符 | numeratorDescription, denominatorDescription | | IndicatorType | Indicator type | | | IndicatorGroup | IndicatorGroup | IndicatorGroupSet | | Indicator group set | 组织单位 | 组织单位 | | OrganisationUnitGroup | 组织单位组 | | | OrganisationUnitGroupSet | Organisation unit group set | | | 数据集 | 资料集 | Section | | Data set section | 网址 | | | Validation rule | Validation rule | | | ValidationRuleGroup | Validation rule group | | | 项目 | 项目 | TrackedEntity | | 项目阶段 | 项目阶段 | TrackedEntity | | 跟踪实体属性 | 跟踪实体属性 | TrackedEntity | | 将任何源引用替换为目标引用作为排序维度 | 将任何源引用替换为目标引用作为排序维度 | Relationship type for tracked entity instances | | fromToName, toFromName | 选项集 | 项目规则--动作类型 | | 选项 | 选项 | 属性 | | Attribute for metadata | Attribute for metadata | Program Notification template | ## subjectTemplate, messageTemplate ValidationNotificationTemplate Validation Notification template subjectTemplate, messageTemplate DataSetNotificationTemplate DataSet Notification template subjectTemplate, messageTemplate Visualization Visualization # title, subtitle, rangeAxisLabel, baseLineLabel, targetLineLabel, domainAxisLabel ## 项目规则行动 Program Rule Actions ### content 预测变量预测变量 Name, ShortName, Description, Generator Description ValidationRule ValidationRule Name, Description, Instruction, Leftside expression, Rightside expression 国际化 { #webapi_i18n } 为了检索翻译字符串的键值对,您可以使用 *i18n* 资源。 / api / 33 / i18n 端点位于 */api/i18n* 并且请求格式是一个简单的键值对数组: #### ```json [ "access_denied", "uploading_data_notification" ]

请求必须是 *POST* 类型并使用 *application/json* 作为
内容类型。使用 curl 的示例,假设请求数据已保存
作为文件`keys.json`:



```bash
curl -d @keys.json "play.dhis2.org/demo/api/33/i18n" -X POST
  -H "Content-Type: application/json" -u admin:district

| 结果将如下所示: | ```json { "access_denied":"Access denied", "uploading_data_notification":"Uploading locally stored data to the server" } ``` | SMS | |---|---|---| | 短消息服务(SMS) { #webapi_sms } | 本节介绍用于发送和接收短文本的 SMS Web API 消息。 | Outbound SMS service | | Web API 支持使用 POST 方法发送外发 SMS。短信可以发送到单个或多个目的地。一个或多个网关需要在使用服务之前进行配置。如果出现以下情况,将不会发送短信没有配置网关。它需要一组接收者和 JSON 格式的消息文本,如下所示。 | / api / sms / outbound | ```json { "message":"Sms Text", "recipients": [ "004712341234", "004712341235" ] } ``` | | > **Note** > > Recipients list will be partitioned if the size exceeds `MAX_ALLOWED_RECIPIENTS` limit of 200. | Web API 也支持查询参数版本,但参数化 API 只能用于发送短信到单个目的地。 | / api / sms / outbound?message = text&recipient = 004712341234 | | 可以使用GET资源提取出站邮件。 | GET / api / sms / outbound GET / api / sms / outbound?filter = status:eq:SENT GET / api / sms / outbound?filter = status:eq:SENT&fields = * | 可以使用DELETE资源删除出站邮件。 | | 删除/ api / sms / outbound / {uid} 删除/ api / sms / outbound?ids = uid1,uid2 | Gateway response codes | 网关可以使用以下响应代码进行响应。 | | Table: Gateway response codes | Response code | Response Message | | Detail Description | RESULT_CODE_0 | success | | Message has been sent successfully | RESULT_CODE_1 | scheduled | | Message has been scheduled successfully | RESULT_CODE_22 | internal fatal error | | Internal fatal error | RESULT_CODE_23 | authentication failure | | Authentication credentials are incorrect | 本节介绍用于发送和接收短文本的 SMS Web API 消息。 | data validation failed | | Parameters provided in request are incorrect | RESULT_CODE_25 | insufficient credits | | Credit is not enough to send message | RESULT_CODE_26 | upstream credits not available | | Upstream credits not available | RESULT_CODE_27 | exceeded your daily quota | | You have exceeded your daily quota | RESULT_CODE_40 | temporarily unavailable | | Service is temporarily down | RESULT_CODE_201 | maximum batch size exceeded | | Maximum batch size exceeded | RESULT_CODE_200 | success | | The request was successfully completed | RESULT_CODE_202 | accepted | | The message(s) will be processed | RESULT_CODE_207 | multi-status | | 向应用项目接口提交了多条信息,但并非所有信息的状态都相同 | RESULT_CODE_400 | bad request | | Validation failure (such as missing/invalid parameters or headers) | RESULT_CODE_401 | unauthorized | ### Authentication failure. This can also be caused by IP lockdown settings RESULT_CODE_402 payment required Not enough credit to send message RESULT_CODE_404 not found Resource does not exist RESULT_CODE_405 method not allowed Http method is not support on the resource 用法 | 默认值 | Potential duplicate status | Parameter name | |---|---|---| | 技术性更强、对开发人员更友好的消息(目前尚未使用)。 | 具有以下要求: | RESULT_CODE_503 | | service unavailable | 具有以下要求: | Inbound SMS service | | Web API 支持使用 POST 收集传入的 SMS 消息方法。路由到 DHIS2 Web API 的传入消息可以是使用此 API 接收。 API 收集入站 SMS 消息和根据短信内容(SMS 命令)。下面给出了 JSON 格式的示例负载。文本, 发起者、接收日期和发送日期是强制性参数。这其余是可选的,但系统将使用这些默认值参数。 | 具有以下要求: | ```json { "text": "sample text", "originator": "004712341234", "gatewayid": "unknown", "receiveddate": "2016-05-01", "sentdate":"2016-05-01", "smsencoding": "1", "smsstatus":"1" } ``` | | 可以使用GET resourcef获取入站消息 | query | 可以使用DELETE资源删除入站邮件 | ### 删除/ api / sms / inbound / {uid} 删除/ api / sms / inbound?ids = uid1,uid2 导入所有未解析的消息 POST /api/sms/入站/导入 Table: User query parameters Parameter 类型描述 message 串 This is mandatory parameter which carries the actual text message. originator 串 This is mandatory parameter which shows by whom this message was actually sent from. gateway 串 This is an optional parameter which gives gateway id. If not present default text "UNKNOWN" will be stored ### receiveTime 日期 #### This is an optional parameter. It is timestamp at which message was received at the gateway. Gateway service administration #### Web API 公开资源,这些资源提供了一种配置和更新短信网关配置。可以使用 GET 检索配置的不同网关的列表方法。 #### GET /api/33/gateways 还可以使用特定网关类型检索配置获取方法。 #### GET /api/33/gateways/{uid} 可以使用 POST 添加新的网关配置。 POST api 需要类型请求参数,目前它的值可以有一个 *http,bulksms,clickatell,smpp*。第一个添加的网关将设置为默认值。一次只能默认一个网关。默认网关只能通过其 api 更改。如果删除了默认网关,则列表中的下一个网关将自动变为默认网关。 POST / api / 33 / gateways 可以通过提供如下所述的uid和网关配置来更新配置 | 默认值 | Potential duplicate status | Parameter name | |---|---|---| | displayColumnOrder | 具有以下要求: | 可以使用PUT方法设置默认网关。 | | PUT /api/33/gateways/default/{uid} | 具有以下要求: | Web API 允许您创建和更新网关配置。对于每个网关类型 JSON 有效负载中有不同的参数。下面给出了每个网关的示例 JSON 有效负载。 POST 用于 create 和 PUT 以更新配置。标头参数可用于 GenericHttpGateway 将一个或多个参数作为 http 标头发送的情况。 | | Clickatell | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | Bulksms | | ```json { "type": "bulksms", "name": "bulkSMS", "username": "bulkuser", "password": "abc123" } ``` | 具有以下要求: | ```json { "type": "smpp", "name": "smpp gateway2", "systemId": "smppclient1", "host": "localhost", "systemType": "cp", "numberPlanIndicator": "UNKNOWN", "typeOfNumber": "UNKNOWN", "bindType": "BIND_TX", "port": 2775, "password":"password", "compressed": false } ``` | | Generic HTTP | 具有以下要求: | 在通用的http网关中,可以添加任意数量的参数。 | | Table: Generic SMS gateway parameters | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | 类型 | | 描述 | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | 串 | | 产生价值终点 { #webapi_generate_values } | 具有以下要求: | 串 | | 日期时间 | 具有以下要求: | Boolean | | Http POST nethod will be used by default. In order to change it and Http GET, user can set useGet flag to true. | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | 串 | | Content type specify what type of data is being sent. Supported types are APPLICATION_JSON, APPLICATION_XML, FORM_URL_ENCODED, TEXT_PLAIN | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | 串 | Url template ## header Boolean If parameter needs to be sent in Http headers encode Boolean If parameter needs to be encoded key 串 parameter key 价值串 parameter value #### confidential | Potential duplicate status | If parameter is confidential. This parameter will not be exposed through API | |---|---| |sendUrlParameters | 类型| |If this flag is checked then urlTemplate can be appended with query parameters. This is usefull if gateway API only support HTTP GET. Sample urlTemplate looks like this `"urlTemplate":"https://samplegateway.com/messages?apiKey={apiKey}&to={recipients},content={text},deliveryreport={dp}"` | 如果配置保存成功则返回 HTTP.OK 否则 *Error*| |短信命令 { #webapi_sms_commands } | SMS 命令用于通过 SMS 收集数据。这些命令属于特定的解析器类型。每个解析器都有不同的功能。| |可以使用GET检索命令列表。 | KEY_VALUE_PARSER| |可以使用GET检索一个特定的命令。 | GET /api/smsCommands/uid| |可以使用PUT更新一个特定的命令。 | PUT /api/smsCommands/uid| #### 可以使用POST创建命令。 POST / api / smsCommands | Potential duplicate status | If parameter is confidential. This parameter will not be exposed through API | |---|---| |SMS command types | 类型| |PERIOD_STRUCTURE | KEY_VALUE_PARSER| |用于汇总数据收集。 | ALERT_PARSER| |发送警报消息。 | 未注册_解析器| |用于疾病监测病例报告。 | TRACKED_ENTITY_REGISTRATION_PARSER| |用于跟踪器实体注册。 | PROGRAM_STAGE_DATAENTRY_PARSER| # This is a note ## EVENT_REGISTRATION_PARSER 单个事件的注册。这用于事件项目。 SMS command types for Android ### 当互联网不可用时,Android应用项目可以使用这些命令类型通过SMS提交数据。 SMS由Android应用项目组成。类型用法 | 默认值 | Potential duplicate status | Parameter name | |---|---|---| | 仅与当前用户相关联的数据视图组织单位,可退回到数据采集组织单位。 | TRACKER_EVENT | 跟踪器项目的事件注册。 | | SIMPLE_EVENT | TRACKER_EVENT | 关系 | | 建立关系。 | 假 | 删除事件。 | | Users | 假 | 本节介绍用户资源方法。 | | /api/users | query | *users* 资源提供了额外的查询参数标准参数(例如分页)。在用户处查询用户资源可以使用以下参数。 | | Table: User query parameters | Parameter | 类型 | | 描述 | query | 文本 | | Query value for first name, surname, username and email, case in-sensitive. | 假 | 文本 | | Query for phone number. | canManage | false | true | | Filter on whether the current user can manage the returned users through the managed user group relationships. | authSubset | false | true | | Filter on whether the returned users have a subset of the authorities of the current user. | 假 | 日期 | | 查询参数 | 假 | 数 | | 定义要返回的页码。 | Parameter | 日期 | | 定义每页返回的元素数量。 | Parameter | false | true | | Filter on users who have self-registered their user account. | invitationStatus | none | all | expired | Filter on user invitations, including all or expired invitations. 欧识别码 Filter on users who are associated with the organisation unit with the given identifier. #### userOrgUnits false | true Filter on users who are associated with the organisation units linked to the currently logged in user. includeChildren false | true ### Includes users from all children organisation units of the ou parameter. page 数 The page number. #### pageSize 数 The page size. orgUnitBoundary - 串 - Restrict search to users having a common organisation unit with the current user for the given boundary - createdBy JSON 格式的有效载荷如下所示,其中`attributes `指元数据属性,`groupSets `指组织单位组集,`dataItems `指数据元素、指标、数据集和计划指标: To retrieve all user accounts which were initially self-registered:

/api/users?selfRegistered=true

User query by identifier #### You can retrieve full information about a user with a particular identifier with the following syntax.

/api/users/{id}

An example for a particular identifier looks like this:

/api/users/OYLGMiazHtW

- User lookup - 用户查找 API 提供了一个端点来检索用户响应包含最少的信息集。它不需要一个特定权限,适合客户端查询信息例如用户名和姓氏,不会暴露潜在的敏感信息用户信息。 - ``` / api / userLookup

- updatedAtClient

User lookup by identifier

JSON 格式的有效载荷如下所示,其中`attributes `指元数据属性,`groupSets `指组织单位组集,`dataItems `指数据元素、指标、数据集和计划指标:

GET / api / userLookup / {id}

用户 `id` 将与以下用户属性匹配
按照指定的顺序:

用户标识

### 用户名

用户名

请求示例如下所示:

/ api / userLookup / QqvaU7JjkUV

该响应将包含有关用户的最少信息。

```json
{
  "id": "QqvaU7JjkUV",
  "username": "nkono",
  "firstName": "Thomas",
  "surname": "Nkono",
  "displayName": "Thomas Nkono"
}

User lookup query 您可以使用以下API请求向用户查询。

GET / api / userLookup?query = {string}

`query` 请求参数是强制性的。查询`string`将被匹配针对以下用户属性: 名字 ### 姓电子邮件用户名 In addition to the `query` parameter the search can be restricted by the `orgUnitBoundary` parameter as described in table of parameters for users above. 请求示例如下所示:

/ api / userLookup?query = John

响应将包含有关与请求匹配的用户的信息。

{
  "users": [
    {
      "id": "DXyJmlo9rge",
      "username": "jbarnes",
      "firstName": "John",
      "surname": "Barnes",
      "displayName": "John Barnes"
    },
    {
      "id": "N3PZBUlN8vq",
      "username": "jkamara",
      "firstName": "John",
      "surname": "Kamara",
      "displayName": "John Kamara"
    }
  ]
}

用户帐户创建和更新 { #webapi_users_create_update } 通过 API 支持创建和更新用户。一个基本的创建用户的有效负载类似于以下示例。注意密码将以纯文本形式发送,因此请记住为网络传输启用 SSL/HTTPS。

{
  "id": "Mj8balLULKp",
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "id": "lWCkJ4etppc",
    "userInfo": {
    "id": "Mj8balLULKp"
  },
  "username": "johndoe123",
  "password": "Your-password-123",
  "skype": "john.doe",
  "telegram": "joh.doe",
  "whatsApp": "+1-541-754-3010",
  "facebookMessenger": "john.doe",
  "avatar": {
    "id": "<fileResource id>"
  },
  "userRoles": [
    {
      "id": "Ufph3mGRmMo"
    }
  ]
  },
  "organisationUnits": [
    {
      "id": "Rp268JB6Ne4"
    }
  ],
  "userGroups": [
    {
      "id": "wl5cDMuUhmF"
    }
  ]
}

- ```bash curl -X POST -d @u.json "http://server/api/33/users" -u user:pass -H "Content-Type: application/json"

  - 在用户创建负载中,仅在导入时支持用户组
或一次*发布*一个用户。如果您尝试创建多个
user 在指定用户组时,您将不会收到错误,并且
将创建用户,但不会分配用户组。这是设计使然
并且由于用户和用户之间的多对多关系而受到限制
用户组,其中用户组是关系的所有者。更新
或者创建多个用户和他们的用户组,考虑一个项目来*POST*
一次一个,或 *POST* 所有用户,然后执行另一个操作
在指定新用户的标识符的同时更新他们的用户组。

  - When creating a user the payload may also contain user settings.
These are added as `settings` object to the root object.
Each key-value pair becomes a member in the `settings` object, for example:
    ```json
{
    "id": "Mj8balLULKp",
    "firstName": "John",
    "surname": "Doe",
    "settings": {
        "keyUiLocale": "de"
    },
    //...
}

创建用户后,*Location* 标头与新生成的 ID(你也可以使用 `/api/system/id` 提供你自己的端点)。然后可以使用相同的有效负载进行更新,但请记住然后使用 *PUT* 而不是 *POST* 并且端点现在是`/api/users/ID`。 ### ```bash curl -X PUT -d @u.json "http://server/api/33/users/ID" -u user:pass -H "Content-Type: application/json"

有关可用的全部有效负载的更多信息,请参见`/ api / schemas / user`。

有关上传和检索用户头像的更多信息,请参阅
`/fileResources` 端点。

用户帐户邀请 { #webapi_user_invitations } 
The Web API supports inviting people to create user accounts through the
`invite` resource. To create an invitation you should POST a user in XML
or JSON format to the invite resource. A specific username can be forced
by defining the username in the posted entity. By omitting the username,
the person will be able to specify it herself. The system will send out
an invitation through email. This requires that email settings have been
properly configured.

邀请资源可用于安全地
允许人们在其他人不知道密码的情况下创建帐户
或通过以纯文本形式传输密码。用于的有效载荷
邀请与创建用户相同。 JSON 格式的示例负载
看起来像这样:


### ```json
{
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "username": "johndoe",
    "userRoles": [{
      "id": "Euq3XfEIEbx"
    }]
  },
  "organisationUnits": [ {
    "id": "ImspTQPwCqd"
  } ],
  "userGroups": [ {
    "id": "vAvEltyXGbD"
  }]
}

用户邀请实体可以这样发布:

curl -d @invite.json "localhost/api/33/users/invite" -u admin:district
  -H "Content-Type:application/json"

要同时向多个用户发送邀请,您必须使用格式略有不同。对于 JSON:

{
  "users": [ {
    "firstName": "John",
    "surname": "Doe",
    "email": "johndoe@mail.com",
    "userCredentials": {
      "username": "johndoe",
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }, {
    "firstName": "Tom",
    "surname": "Johnson",
    "email": "tomj@mail.com",
    "userCredentials": {
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }
  ]
}

The Web API supports inviting people to create user accounts through the `invite` resource. To create an invitation you should POST a user in XML or JSON format to the invite resource. A specific username can be forced by defining the username in the posted entity. By omitting the username, the person will be able to specify it herself. The system will send out an invitation through email. This requires that email settings have been properly configured.

curl -d @invites.json "localhost/api/33/users/invites" -u admin:district
  -H "Content-Type:application/json"

### 发送用户账号邀请有一定的要求出去: 电子邮件SMTP服务器必须在服务器上正确配置。被邀请的用户必须指定了有效的电子邮件。如果指定了用户名,则它不得已被其他人使用现有用户。 ### 如果不满足这些要求中的任何一个,邀请资源将返回带有 *409 Conflict* 状态代码和描述性消息。 User login (Experimental) { #webapi_user_login } 该端点不用于外部使用,除非你正在实施一个自定义登录应用项目,除非你有非常好的理由,否则你可能不应该这样做。 A user can log in and get a session cookie with the following example: `POST` `/api/auth/login` with `JSON` body: ### ```json { "username": "username", "password": "password", "twoFactorCode": "two_factor_code" }

Successful response looks like:  

```json
{
    "loginStatus": "SUCCESS",
    "redirectUrl": "/dhis-web-dashboard/"
}

User account confirm invite (Experimental) { #webapi_user_confirm_invite } ### > **Important** > Before confirming an invitation, an admin user should have set up the User and sent an invitation link. That prerequisite also adds some required data in the `userinfo` database table (`idToken`, `restoreToken`, `restoreExpiry`) for that user, in order to complete the invite. A user can confirm an invitation through the following endpoint: `POST` `/api/auth/invite` with `JSON` body:

{
    "username": "TestUser",
    "firstName": "Test",
    "surname": "User",
    "password": "Test123!",
    "email": "test@test.com",
    "phoneNumber": "123456789",
    "g-recaptcha-response": "recaptchaResponse",
    "token": "aWRUb2tlbjpJRHJlc3RvcmVUb2tlbg=="
}

> **Note** > The `g-recaptcha-response` value would be populated through the use of the core Login App UI normally. > The `token` field expects a Base64-encoded value. In this example, decoded, it's `idToken:IDrestoreToken`. This would be sent by email to the invited user (it is actually created internally (and populated in the database) during the `/api/users/invite` operation). Successful response looks like:

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Account updated"
}

User account registration (Experimental) { #webapi_user_registration } ### A user can register directly through the following endpoint: `POST` `/api/auth/registration` with `JSON` body:

{
    "username": "testSelfReg",
    "firstName": "test",
    "surname": "selfReg",
    "password": "P@ssword123",
    "email": "test@test.com",
    "phoneNumber": "12345oooo",
    "g-recaptcha-response": "recap response"
}

A successful response looks like:

{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Account created"
}

### User forgot password (Experimental) { #webapi_user_forgot_password } This endpoint is used to trigger the forgotten password flow. It can be triggered by supplying the username or email of the user whose password needs resetting. `POST` `/api/auth/forgotPassword` with `JSON` body:

{
    "emailOrUsername": "testUsername1"
}

A successful response returns an empty `200 OK`. This should trigger an email to be sent to the user which allows them to reset their password. User password reset (Experimental) { #webapi_user_password_reset } Once a user has received an email with a link to reset their password, it will contain a token which can be used to reset their password. `POST` `/api/auth/passwordReset` with `JSON` body: ### ```json { "newPassword": "ChangeMe123!", "resetToken": "token-value-from-email-link" }

A successful response returns an empty `200 OK`. The user should now be able to log in using the new password.

用户复制 { #webapi_user_replication }

要复制用户,您可以使用 *replica* 资源。复制一个
用户在调试或重现报告的问题时很有用
特定用户。您需要提供新的用户名和密码
您稍后将用于验证的复制用户。请注意,您
需要 ALL 权限才能执行此操作。要复制用户,您
可以发布如下所示的 JSON 有效负载:

```json
{
  "username": "user_replica",
  "password": "SecretPassword"
}

此有效负载可以发布到您提供的副本资源要在 URL 中复制的用户标识符: ### / api / 33 / users / /副本使用curl复制用户的示例如下所示:

curl -d @replica.json "localhost/api/33/users/N3PZBUlN8vq/replica"
  -H "Content-Type:application/json" -u admin:district

### Reset user password { #webapi_user_reset } User administrators (with appropriate rights) can reset another user's account by triggering password recovery. Once triggered an email is sent to the user containing a recovery link. Users following the link get to a form which allows to set a new password. To trigger this workflow for user `tH7WIiIJ0O3` use: POST /api/37/users/tH7WIiIJ0O3/reset 禁用和启用用户帐户 { #webapi_user_disable } 可以将用户帐户标记为禁用。禁用的用户无法再登录。要将具有UID`tH7WIiIJ0O3`的用户标记为已禁用(需要具有适当权限的用户): ## POST / api / 36 / users / tH7WIiIJ0O3 / disabled 要再次启用禁用的用户,请相应地使用(要求具有适当权限的用户): POST / api / 36 / users / tH7WIiIJ0O3 / enabled 用户有效期 { #webapi_user_expiration } 可以为用户帐户设置到期日期。它标记了用户帐户已过期的时间点并且无法再使用。过期的用户无法再登录。 To update the expiration date of user with UID `tH7WIiIJ0O3` and set it to the date `2021-01-01` use (requires user with appropriate rights): POST / api / 36 / users / tH7WIiIJ0O3 / expired?date = 2021-01-01 取消设置到期日期,以使帐户永不过期相应地使用(需要具有适当权限的用户): POST / api / 36 / users / tH7WIiIJ0O3 /未过期 User data approval workflows 要查看用户可以访问哪些数据批准工作流和级别, 您可以按以下方式使用* dataApprovalWorkflows *资源:

GET / api / users / {id} / dataApprovalWorkflows

Switching between user accounts connected to the same identity provider account If [linked accounts are enabled in dhis.conf](#connect_single_identity_to_multiple_accounts) and a user has logged in via OIDC, then it is possible for the user to switch between DHIS2 accounts that are linked to the same identity provider account using this API call:

GET /dhis-web-commons-security/logout.action?current={current_username}&switch={username_to_switch_to}

This has the effect of signing out the current user and signing in the new user. It looks seamless as it is happening, except that the new user ends up on the default page of the DHIS2 instance. Note that this API call will likely change in the future, but its general function will remain the same. To see a list of users that can be switched to, use this API call: # ``` GET /api/account/linkedAccounts

## 当前用户信息 { #webapi_current_user_information } 

为了获取有关当前已验证用户的信息和
它与其他资源的关联,您可以使用 *me* 资源
(您也可以通过其旧名称 *currentUser* 来引用它)。目前
用户相关资源为您提供有用的信息
构建客户端,例如用于数据输入和用户管理。这
下面描述了这些资源及其用途。

提供有关您当前登录的用户的基本信息
in as,包括用户名、用户凭据、分配的组织
单位:

不

提供有关当前未读消息和解释的信息:

    / api / me / dashboard

为了更改密码,此端点可用于验证
新输入的密码。密码验证将基于
系统中配置的 PasswordValidationRules。这个端点支持
POST 和密码字符串应在 POST 正文中发送。

    / api / me / validatePassword

更改密码时,此端点(支持 POST)可用于
验证旧密码。密码字符串应在 POST 正文中发送。

    / api / me / verifyPassword

返回授予当前用户的权限集:

    / api / me / authorization

返回 true 或 false,表示当前用户是否已被
授予给定的`<auth>`授权:

    / api / me / authorization / <auth>

给出与当前用户相关的数据批准级别:

    / api / me / dataApprovalLevels

提供当前用户可以访问的数据批准工作流。
对于每个工作流程,显示用户可能看到的数据批准级别,以及
他们在每个级别上具有什么权限:

    / api / me / dataApprovalWorkflows

Settings and configuration

系统设置 { #webapi_system_settings } 

您可以通过与
*系统设置*资源。系统设置是一个简单的键值对,
其中键和值都是纯文本字符串。保存或
更新系统设置,您可以向以下 URL 发出 *POST* 请求:

    / api / 33 / systemSettings / my-key?value = my-val

或者,您可以将设置值作为请求正文提交,
其中内容类型设置为“文本/纯文本”。例如,您可以使用
像这样卷曲:

```bash
curl "play.dhis2.org/demo/api/33/systemSettings/my-key" -d "My long value"
  -H "Content-Type: text/plain" -u admin:district

要批量设置系统设置,您可以发送带有使用 POST 请求的每个系统设置键值对的属性和值:

{
  "keyApplicationNotification": "Welcome",
  "keyApplicationIntro": "DHIS2",
  "keyApplicationFooter": "Read more at dhis2.org"
}

可以通过指定语言环境来设置可翻译设置键的翻译可以指定的查询参数和翻译值作为查询参数或与正文有效负载一起使用。查看示例网址: / api / 33 / systemSettings / ?locale = &value = 您应该将 my-key 替换为您的真实密钥,并将 my-val 替换为您的真实密钥价值。检索给定键的值(以 JSON 或纯文本形式) 您可以向以下 URL 发出 *GET* 请求: | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | Parameter name | / api / 33 / systemSettings?key =我的密钥 | |---|---|---| | 例如,要将当前用户的 UI 语言环境设置为法语,您可以使用以下命令。 | ```json { "httpStatus": "Not Found", "httpStatusCode": 404, "status": "ERROR", "message": "Setting does not exist or is marked as confidential", "errorCode": "E1005" } ``` | Program notification template | | ```bash curl "play.dhis2.org/demo/api/33/systemSettings?key=keyApplicationNotification&key=keyApplicationIntro" -u admin:district ``` | 您可以使用GET请求检索所有系统设置: | Program notification template | | Table: User settings | / api / 33 / systemSettings / ?locale = | Program notification template | | 可翻译键的优先级如下: | 指定的区域设置>用户的默认UI区域设置> defaut值 | Program notification template | | 描述 | / api / 33 / systemSettings / ?locale = &value = | Program notification template | | User interface locale. | 键 | Program notification template | | Translatable | keyUiLocale | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyDbLocale | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyAnalysisDisplayProperty | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyAnalysisDigitGroupSeparator | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyCurrentDomainType | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyTrackerDashboardLayout | Program notification template | | 不 | 应用项目标题 | Program notification template | | 是的 | keyApplicationIntro | Program notification template | | 是的 | 关键应用项目通知 | Program notification template | | 是的 | keyApplicationFooter | Program notification template | | 是的 | keyApplicationRightFooter | Program notification template | | 是的 | keyFlag | Program notification template | | 不 | keyFlagImage | Program notification template | | 不 | startModule | Program notification template | | 不 | startModuleEnableLightweight | Program notification template | | 不 | factorDeviation | Program notification template | | 不 | keyEmailHostName | Program notification template | | 不 | keyEmailPort | Program notification template | | 不 | keyEmailTls | Program notification template | | 不 | keyEmailSender | Program notification template | | 不 | keyEmailUsername | Program notification template | | 不 | keyEmailPassword | Program notification template | | 不 | minPasswordLength | Program notification template | | 不 | maxPasswordLength | Program notification template | | 不 | keySmsSetting | Program notification template | | 不 | keyCacheStrategy | Program notification template | | 不 | keyCacheability | Program notification template | | 不 | phoneNumberAreaCode | Program notification template | | 不 | keyAccountRecovery | Program notification template | | 不 | keyLockMultipleFailedLogins | Program notification template | | 不 | googleAnalyticsUA | Program notification template | | 不 | credentialsExpires | Program notification template | | 不 | credentialsExpiryAlert | Program notification template | | 不 | credentialsExpiresReminderInDays | Program notification template | | 不 | accountExpiryAlert | Program notification template | | 不 | accountExpiresInDays | Program notification template | | 不 | keySelfRegistrationNoRecaptcha | Program notification template | | 不 | recaptchaSecret | Program notification template | | 不 | recaptchaSite | Program notification template | | 不 | keyCanGrantOwnUserAuthorityGroups | Program notification template | | 不 | keySqlViewMaxLimit | Program notification template | | 不 | keyDataQualityMaxLimit | Program notification template | | 不 | keyRespectMetaDataStartEndDatesInAnalyticsTableExport | Program notification template | | 不 | keySkipDataTypeValidationInAnalyticsTableExport | Program notification template | | 不 | keyCustomLoginPageLogo | Program notification template | | 不 | keyCustomTopMenuLogo | Program notification template | | 不 | globalShellEnabled | Program notification template | | 不 | keyCacheAnalyticsDataYearThreshold | Program notification template | | 不 | analyticsFinancialYearStart | Program notification template | | 不 | keyIgnoreAnalyticsApprovalYearThreshold | Program notification template | | 不 | keyAnalyticsMaxLimit | Program notification template | | 不 | KeyTrackedEntityMaxLimit | Program notification template | | 不 | keyAnalyticsMaintenanceMode | Program notification template | | 不 | keyAnalyticsPeriodYearsOffset | Program notification template | | 不 | keyDatabaseServerCpus | Program notification template | | 不 | keyLastSuccessfulAnalyticsTablesRuntime | Program notification template | | 不 | keyLastSuccessfulLatestAnalyticsPartitionRuntime | Program notification template | | 不 | keyLastMonitoringRun | Program notification template | | 不 | keyLastSuccessfulDataSynch | Program notification template | | 不 | keyLastSuccessfulEventsDataSynch | Program notification template | | 不 | keyLastCompleteDataSetRegistrationSyncSuccess | Program notification template | | 不 | syncSkipSyncForDataChangedBefore | Program notification template | | 不 | keyLastSuccessfulAnalyticsTablesUpdate | Program notification template | | 不 | keyLastSuccessfulLatestAnalyticsPartitionUpdate | Program notification template | | 不 | keyLastSuccessfulResourceTablesUpdate | Program notification template | | 不 | keyLastSuccessfulSystemMonitoringPush | Program notification template | | 不 | keyLastSuccessfulMonitoring | Program notification template | | 不 | keyNextAnalyticsTableUpdate | Program notification template | | 不 | helpPageLink | Program notification template | | 不 | keyAcceptanceRequiredForApproval | Program notification template | | Where to email system notifications || Program notification template | | Where to email system notifications | 不 | Program notification template | | Default relative period for analysis. Default: "LAST_12_MONTHS" | 不 | Program notification template | | Require authority to add to view object lists. Default: "false" | 不 | Program notification template | | Allow assigning object to related objects during add or update. Default: "false" | 不 | Program notification template | | Enables the usage of a custom logo on the front page. Default: "false" | 不 | Program notification template | | Enables the usage of a custom banner on the website. Default: "false" | 不 | Program notification template | | 不 | keyDataImportStrictPeriods(关键数据严格导入期 | Program notification template | | 不 | keyDataImportStrictDataElements | Program notification template | | 不 | keyDataImportStrictCategoryOptionCombos | Program notification template | | 不 | keyDataImportStrictOrganisationUnits | Program notification template | | 不 | keyDataImportStrictAttributeOptionsCombos | Program notification template | | 不 | keyDataImportStrictDataSetApproval | Program notification template | | 不 | keyDataImportStrictDataSetLocking | Program notification template | | 不 | keyDataImportStrictDataSetInputPeriods | Program notification template | | 不 | keyDataImportRequireCategoryOptionCombo | Program notification template | | 不 | keyDataImportRequireAttributeOptionCombo | Program notification template | | 不 | keyCustomJs | Program notification template | | 不 | keyCustomCss | Program notification template | | 不 | keyCalendar | Program notification template | | 不 | keyDateFormat | Program notification template | | 不 | keyStyle | Program notification template | | 不 | keyRemoteInstanceUrl | Program notification template | | 不 | keyRemoteInstanceUsername | Program notification template | | 不 | keyRemoteInstancePassword | Program notification template | | 不 || Program notification template | | Google Maps API key || Program notification template | | keyGoogleCloudApiKey | Google Cloud API key | Program notification template | | keyLastMetaDataSyncSuccess | Keeps timestamp of last successful metadata synchronization | Program notification template | | keyVersionEnabled | Enables metadata versioning | Program notification template | | keyMetadataFailedVersion | Keeps details about failed metadata version sync | Program notification template | | keyMetadataLastFailedTime | Keeps timestamp of last metadata synchronization failure | Program notification template | | keyLastSuccessfulScheduledProgramNotifications | 不 | Program notification template | | 不 | keyRemoteMetadataVersion | Program notification template | | 不 | keySystemMetadataVersion | Program notification template | | 不 | keyStopMetadataSync | Program notification template | | 不 || Program notification template | | 确定与已删除或更新的值相关联的文件资源保留的时间长度。NONE,THREE_MONTHS,ONE_YEAR或FOREVER。 | 不 | Program notification template | | Specifies how many times the availability of remote server will be checked before synchronization jobs fail. || Program notification template | | syncMaxAttempts || Program notification template | | 不 | syncDelayBetweenRemoteServerAvailabilityCheckAttempts | Program notification template | | 不 | lastSuccessfulDataStatistics | Program notification template | | 不 | keyHideDailyPeriods | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyHideWeeklyPeriods | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | keyHideBiWeeklyPeriods | Boolean flag used to hide/show bi-weekly periods | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | keyHideMonthlyPeriods | 不 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | | 不 | keyGatherAnalyticalObjectStatisticsInDashboardViews | Program notification template | | 不 | keyCountPassiveDashboardViewsInUsageAnalytics | Program notification template | | 不 | keyDashboardContextMenuItemSwitchViewType | Program notification template | | 是的 | keyDashboardContextMenuItemOpenInRelevantApp | Program notification template | | 是的 | keyDashboardContextMenuItemShowInterpretationsAndDetails | Program notification template | | 是的 | keyDashboardContextMenuItemViewFullscreen | Program notification template | ## 是的 jobsRescheduleAfterMinutes If a job is in state `RUNNING` for this amount of minutes or longer without making progress in form of updating its `lastAlive` timestamp the job is considered stale and reset to `SCHEDULED` state 不 jobsCleanupAfterMinutes A "run once" job is deleted when this amount of minutes has passed since it finished successful or unsuccessful 不 jobsMaxCronDelayHours A CRON expression triggered job will only trigger in the window between its target time of the day and this amount of hours later. If it wasn't able to run in that window the execution is skipped and next execution according to the CRON expression is the next target execution 不 jobsLogDebugBelowSeconds A job with an execution interval below this number of seconds logs its information on debug rather than info 不 keyParallelJobsInAnalyticsTableExport Returns the number of parallel jobs to use for processing analytics tables. It takes priority over "keyDatabaseServerCpus". Default: -1 不 / api / 33 / systemSettings / ?locale = &value = If true, the analytics event tables are created with a centroid value for each Data Element or TEA of type OU or OU Geometry. Default: false | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | 用户设置 { #webapi_user_settings } | Parameter name | |---|---|---| | 不 | 用户未设置的用户设置,将回退到等效的系统设置。只返回用户明确设置的值, 您可以将 ?useFallback=false 附加到上述 URL,如下所示: | / api / 33 / userSettings?useFallback = false | | 要为当前经过身份验证的用户保存或更新设置,您可以向以下 URL 发出 *POST* 请求: | 假 | 您可以指定要为其显式保存设置的用户这个语法: | | / api / 33 / userSettings / my-key?user = username&value = my-val | 假 | ```bash curl "https://play.dhis2.org/demo/api/33/userSettings/my-key" -d "My long value" -H "Content-Type: text/plain" -u admin:district ``` | | 例如,要将当前用户的 UI 语言环境设置为法语,您可以使用以下命令。 | 要删除用户设置,您可以向 URL 发出 *DELETE* 请求类似于上面用于检索的那个。 | 您应该将 my-key 替换为您的真实密钥,并将 my-val 替换为您的真实密钥价值。要以纯文本形式检索给定键的值,您可以对以下 URL 的 *GET* 请求: | | ```bash curl "play.dhis2.org/demo/api/33/systemSettings?key=keyApplicationNotification&key=keyApplicationIntro" -u admin:district ``` | 要删除用户设置,您可以向 URL 发出 *DELETE* 请求类似于上面用于检索的那个。 | 可用的系统设置在下面列出。 | | Table: User settings | 键 | 选项 | | 描述 | keyStyle | light_blue/light_blue.css | green/green.css | vietnam/vietnam.css | | User interface stylesheet. | 假 | false | true | | Whether to send email notifications. | 假 | false | true | | Whether to send SMS notifications. | 假 | Locale value | | User interface locale. | 假 | Locale value | ## Database content locale. keyAnalysisDisplayProperty name | shortName 在分析应用项目中显示元数据的属性。 GET /api/33/configuration/systemId GET POST DELETE /api/configuration/feedbackRecipients GET POST DELETE /api/configuration/offlineOrganisationUnitLevel GET POST /api/configuration/infrastructuralDataElements GET POST /api/configuration/infrastructuralIndicators GET POST /api/configuration/infrastructuralPeriodType GET POST /api/configuration/dataOutputPeriodTypes GET POST DELETE /api/configuration/selfRegistrationRole GET POST DELETE /api/configuration/selfRegistrationOrgUnit GET POST /api/facilityOrgUnitGroupSet GET POST /api/facilityOrgUnitLevel all | aggregate | tracker Data element domain type to display in lists. keyAutoSaveCaseEntryForm false | true Save case entry forms periodically. | keyAutoSaveTrackedEntityForm | ```json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } ``` | |---|---| | Save person registration forms periodically. | keyAutoSaveDataEntryForm | | false | true | Save aggregate data entry forms periodically. | | keyTrackerDashboardLayout | false | true | | Tracker dasboard layout. | 组态 { #webapi_configuration } | | 要访问配置,您可以与 *configuration* 交互资源。您可以通过 *Accept* 标头获取 XML 和 JSON 响应或使用 .json 或 .xml 扩展名。你可以*GET*所有属性配置来自: | / api / 33 /配置 | | 数据输出周期类型 | 周期类型名称的 JSON 列表（如 "月度"、"季度"、"年度 "等） | | 您可以将 *GET* 和 *POST* 请求发送到以下特定资源: | GET /api/33/configuration/systemId GET POST DELETE /api/configuration/feedbackRecipients GET POST DELETE /api/configuration/offlineOrganisationUnitLevel GET POST /api/configuration/infrastructuralDataElements GET POST /api/configuration/infrastructuralIndicators GET POST /api/configuration/infrastructuralPeriodType GET POST DELETE /api/configuration/selfRegistrationRole GET POST DELETE /api/configuration/selfRegistrationOrgUnit GET POST /api/facilityOrgUnitGroupSet GET POST /api/facilityOrgUnitLevel | | For the CORS allowlist configuration you can make a POST request with an array of URLs to allowlist as payload using "application/json" as content-type, for instance: | ```json ["www.google.com", "www.dhis2.org", "www.who.int"] ``` | | GET POST /api/33/configuration/corsAllowlist | 对于 POST 请求,配置值应作为请求发送有效载荷为文本。下表显示了适当的配置每个属性的值。 | | Table: Configuration values | Configuration property | | 值 | feedbackRecipients | | User group ID | offlineOrganisationUnitLevel | | Organisation unit level ID | infrastructuralDataElements | Data element group ID infrastructuralIndicators ## Indicator group ID infrastructuralPeriodType ### Period type name (e.g. "Monthly") selfRegistrationRole User role ID selfRegistrationOrgUnit Organisation unit ID | 指标组 | Parameter name | |---|---| | remoteServerUrl | URL to remote server | | remoteServerUsername | Username for remote server authentication | | remoteServerPassword | Password for remote server authentication | corsAllowlist ## JSON list of URLs 例如,要设置反馈接收者用户组,您可以调用以下 curl 命令:

curl "localhost/api/33/configuration/feedbackRecipients" -d "wl5cDMuUhmF"
  -H "Content-Type:text/plain"-u admin:district

代币 { #webapi_tokens } | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | Parameter name | |---|---| | 您可以使用以下命令检索 Google 服务帐户 OAuth 2.0 访问令牌对以下资源的 GET 请求。 | GET /api/tokens/google | | 令牌将在一定时间内有效,之后必须从此资源请求另一个令牌。响应包含匹配令牌到期的缓存控制标头。这响应将包含以下 JSON 格式的属性。 | Table: Token response | Property 描述 access_token The OAuth 2.0 access token to be used when authentication against Google services. expires_in The number of seconds until the access token expires, typically 3600 seconds (1 hour). client_id The Google service account client id. * 假定已为DHIS2设置并配置了Google服务帐户。请查阅安装指南以获取更多信息。静态内容 { #webapi_static_content } * *staticContent* 资源允许您上传和检索自定义 DHIS2 中使用的徽标。该资源允许用户上传带有关联的密钥,稍后可以使用密钥检索。只有 PNG 文件受支持,只能上传到`logo_banner` 和 `logo_front` 键。 / api / 33 / staticContent Table: Static content keys 键描述 logo_banner ## 应用项目左侧顶部菜单中的徽标。 logo_front Logo on the login-page above the login form. 要上传文件,请将带有 *POST* 请求的文件发送至: - POST / api / 33 / staticContent / 请求将logo.png上传到`logo_front`键的示例: - ```bash curl -F "file=@logo.png;type=image/png" "https://play.dhis2.org/demo/api/33/staticContent/logo_front" -X POST -H "Content-Type: multipart/form-data" -u admin:district

    使用相同的密钥上传多个文件将覆盖现有的
文件。这样,检索任何给定键的文件只会返回
最新上传的文件。

  - 要检索徽标,您可以*获取*以下内容:
        GET /api/33/staticContent/<key>

## Example of requests to retrieve the file stored for `logo_front`:

将“Accept: text/html”添加到 HTTP 标头。*__ 在这种情况下,如果未定义任何内容,端点将返回默认图像。找到自定义或默认图像时将返回图像流。

```bash
curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front" 
  -H "Accept: text/html" -L -u admin:district

将“Accept: application/json”添加到 HTTP 标头。*__ 设置此参数后,如果未找到自定义徽标,端点将永远不会返回默认图像。相反,将返回一条错误消息。找到自定义图像后,此端点将返回一个 JSON 响应,其中包含相应图像的路径/URL。

curl "https://play.dhis2.org/demo/api/33/staticContent/logo_front" 
  -H "Accept: application/json" -L -u admin:district

成功和错误消息将如下所示:

{
  "images": {
    "png": "http://localhost:8080/dhis/api/staticContent/logo_front"
  }
}

{
  "httpStatus": "Not Found",
  "httpStatusCode": 404,
  "status": "ERROR",
  "message": "No custom file found."
}

要使用自定义标志,您需要启用相应的系统通过将其设置为 *true* 来设置。如果相应的设置为false, 将提供默认徽标。 # 用户界面定制 { #webapi_ui_customization } 要自定义 DHIS2 应用项目的 UI,您可以插入自定义 JavaScript 和 CSS 样式通过 *files* 资源。 ## ``` POST删除后/ api / 33 / files / script POST GET DELETE / api / 33 / files / style

通过此资源插入的 JavaScript 和 CSS 内容将由
DHIS2 网络应用项目。这在某些情况下特别有用:

### Side Effects

登录页面或主页。

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| storeCopy | 要创建自定义模板,建议从现有模板开始(这些模板可在登录应用项目的扩展 dhis-web-login/#download 中下载)。 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| `{"organisationUnit": "a3kGcGDCuk7"}` | Tracker { #webapi_tracker } | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| 类型 | Property | Program notification template | Program notification template | Immutable | 类型 |
| 身份证 | trackedEntity | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| String:Uid | trackedEntityType | Program notification template | Program notification template | Immutable | 类型 |
| DateTime | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| `{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}` | createdAtClient | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| YYYY-MM-DDThh:mm:ss | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| ID | updatedAtClient | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| 串 | orgUnit | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | String:Uid |
| In the case of CSV, the `fields` request parameter has no effect, and the response will always
contain the following fields: | inactive | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 是的 | String:any |
| 日期时间 | deleted | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | Boolean |
|     GET /api/metadata/proposals/ | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| Latitude of a `Point` type of Geometry | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| {<br>"type": "POINT",<br>"coordinates": [123.0, 123.0]<br>} | storedBy | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 是的 | String:Uid |
| Duration | createdBy | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 是的 | 用户 |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | updatedBy | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | String:Uid |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | 属性 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 是的 | List of TrackedEntityAttributeValue |

See Attribute

### 类型

A list of enrollments owned by the tracked entity.

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| 文本 | 是的 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| `{ "periodFrom": -15, "periodTo": 15}` | 是的 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Program notification template | 价值 | The value of the tracked entity attribute. |
| storeCopy | Property | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| 用户友好型消息,说明操作是否成功。 | enrollment | Program notification template | Program notification template | DateTime | String:Uid |
| `{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}` | 项目 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Program notification template | 价值 | The value of the tracked entity attribute. |
| 类型 | trackedEntity | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 身份证 | status | Program notification template | Program notification template | Immutable | 类型 |
| String:Uid | orgUnit | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| DateTime | createdAt | Program notification template | Program notification template | Immutable | 类型 |
| 例 | createdAtClient | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| To retrieve an event with a specific ID: | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| WKT, can be omitted it in case of a `Point` type and with `latitude` and `longitude` provided | updatedAtClient | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 日期时间 | enrolledAt | Program notification template | Program notification template | 是的 | Boolean |
| Table: Program Stage Query Criteria | occurredAt | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| ID | completedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| In the case of CSV, the `fields` request parameter has no effect, and the response will always
contain the following fields: | completedBy | Program notification template | Program notification template | 是的 | String:any |
| 日期时间 | 跟进 | Program notification template | Program notification template | 不 | Boolean |
|     GET /api/metadata/proposals/ | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| Latitude of a `Point` type of Geometry | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| {<br>"type": "POINT",<br>"coordinates": [123.0, 123.0]<br>} | storedBy | Program notification template | Program notification template | 是的 | String:Uid |
| 用于项目阶段引用的 IdScheme。默认为 `idScheme` 参数。 | createdBy | Program notification template | Program notification template | 是的 | 用户 |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | updatedBy | Program notification template | Program notification template | 不 | String:Uid |
| ABCDEF12345 | 属性 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | 用户 |
| > **注**
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。 
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo | 报名的属性选项组合。如果没有提供，则使用程序类别组合定义的默认值。 | Program notification template | Program notification template | 价值 | The value of the tracked entity attribute.

See Attribute

### events

A list of events owned by the enrollment.

不

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| The message text. | List of Relationship | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| See an example payload below. | List of Note | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Program notification template | 价值 | The value of the tracked entity attribute. |
| 文本 | Property | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| `{ "periodFrom": -15, "periodTo": 15}` | event | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| storeCopy | 项目阶段 | Program notification template | Program notification template | 价值 | The value of the tracked entity attribute. |
| 用户友好型消息,说明操作是否成功。 | enrollment | Program notification template | Program notification template | DateTime | String:Uid |
| `{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}` | 项目 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Program notification template | 价值 | The value of the tracked entity attribute. |
| 类型 | trackedEntity | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 身份证 | status | Program notification template | Program notification template | Immutable | 类型 |
| String:Uid | orgUnit | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| DateTime | createdAt | Program notification template | Program notification template | Immutable | 类型 |
| If not otherwise specified, JSON is the default response for the `GET` method. The API also 
supports CSV export for single and collection endpoints. Furthermore, it supports compressed 
JSON and CSV for the collection endpoint. | createdAtClient | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| To retrieve an event with a specific ID: | updatedAt | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| WKT, can be omitted it in case of a `Point` type and with `latitude` and `longitude` provided | updatedAtClient | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 日期时间 | scheduledAt | Program notification template | Program notification template | 是的 | Boolean |
| Table: Program Stage Query Criteria | occurredAt | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| ID | completedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| In the case of CSV, the `fields` request parameter has no effect, and the response will always
contain the following fields: | completedBy | Program notification template | Program notification template | 是的 | String:any |
| 日期时间 | 跟进 | Program notification template | Program notification template | 不 | Boolean |
|     GET /api/metadata/proposals/ | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| Latitude of a `Point` type of Geometry | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| > **注**
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。 
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo | 事件的属性选项组合。如果没有提供，则使用程序类别组合定义的默认值。 | Program notification template | Program notification template | 价值 | The value of the tracked entity attribute.
| boolean | 事件的属性类别选项。如果没有提供，则使用由程序类别组合定义的默认值 | Program notification template | Program notification template | 价值 | The value of the tracked entity attribute.
| 布尔 | updatedBy | Program notification template | Program notification template | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | attributeOptionCombo | Program notification template | Program notification template | 是的 | String:Uid |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | attributeCategoryOptions | Program notification template | Program notification template | 不 | String:Uid |
| ABCDEF12345 | assignedUser | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | 用户 |

### `GET /api/tracker/events/{uid}/changeLogs`

dataValues

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| A list of relationships connected to the event. | 不 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| Notes connected to the event. It can only be created. | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| `Relationships` are objects that link together two other tracker objects. The constraints each side
of the relationship must conform to are based on the `Relationship Type` of the `Relationship`. | Property | Program notification template | Program notification template | 不 | 类型 |
| 类型 | relationship | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| String:Uid | relationshipType | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 身份证 | relationshipName | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| Sibling | createdAt | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Date:ISO 8601 |
| YYYY-MM-DDThh:mm:ss | updatedAt | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 是的 | Date:ISO 8601 |

YYYY-MM-DDThh:mm:ss

### createdAtClient

Timestamp when the user created the relationship on the client.

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| 不 | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| 是的 | 是的 | Program notification template | Program notification template | 不 | 属性 |
| 属性是描述被跟踪实体的值。属性可以通过
通过被跟踪实体类型或项目关联。这意味着属性既可以是被追踪实体的一部分,也可以是注册的一部分。
跟踪实体和注册的一部分。重要的是,一个属性只能有一个值,即使一个
一个属性只能有一个值,即使一个被跟踪实体有多个注册表来定义该属性。这是因为
实体最终拥有属性值。 | Property | Program notification template | Program notification template | 不 | 类型 |
| 类型 | attribute | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| String:Uid | 码 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 日期时间 | displayName | Program notification template | Program notification template | 不 | Boolean |
| 名称 | createdAt | Program notification template | Program notification template | DateTime | Date:ISO 8601 |
| 日期时间 | updatedAt | Program notification template | Program notification template | 不 | Boolean |

YYYY-MM-DDThh:mm:ss

### storedBy

Client reference for who stored/created the value.

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| 最小最大数据元素 | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| 日期时间 | 不 | Program notification template | Program notification template | 不 | 123 |
| 日期时间 | While attributes describe a tracked entity, data values describe an event. | Program notification template | Program notification template | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | Immutable |
| 类型 | 例 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| String:Uid | 码 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 日期时间 | displayName | Program notification template | Program notification template | 不 | Boolean |
|     GET /api/metadata/proposals/ | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |
| Latitude of a `Point` type of Geometry | updatedAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |

YYYY-MM-DDThh:mm:ss

### storedBy

在需要记录有关具体问题的补充信息或说明的情况下，可以使用注释来记录。
可以使用注释来记录。

不

不

String:Any

John Doe

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| updatedBy | Only for reading data. User that last updated the object. Set on the server. | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| 日期时间 | 笔记 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | Notes do not have a dedicated endpoint; they are exchanged as part of the parent event and/or
enrollment payload. A sample payload is found below. |
| ```json
{
  "trackedEntity": "oi3PMIGYJH8",
  "enrollments": [
    {
      "enrollment": "EbRsJr8LSSO",
      "notes": [
        {
          "note": "vxmCvYcPdaW",
          "value": "Enrollment note 1"
        },
        {
          "value": "Enrollment note 2."
        }
      ],
      "events": [
        {
          "event": "zfzS9WeO0uM",
          "notes": [
            {
              "note": "MAQFb7fAggS",
              "value": "Event Note 1."
            },
            {
              "value": "Event Note 2."
            }
          ]
        }
      ]
    }
  ]
}
``` | Property | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Immutable | 类型 |
| 日期时间 | note | Program notification template | Program notification template | 不 | Boolean |
|     GET /api/metadata/proposals/ | createdAt | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | Sharing of data store keys follows the same principle as for other metadata sharing (see
[Sharing](developer-manual.md#webapi_sharing)). | String:Any |

### This is a note

| 指标组 | Parameter name | 检索和删除项目通知模板 | 是的 | Potential duplicate status | 描述 |
|---|---|---|---|---|---|
| storedByDataValue | Client reference for who stored/created the note. | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 价值 | The value of the tracked entity attribute. |
| createdBy | Only for reading data. User that created the object. Set on the server. | 不 | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | 123 |
| {<br>"uid": "ABCDEF12345",<br>"username": "username",<br>"firstName": "John",<br>"surname": "Doe"<br>} | Users | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | Immutable |
| 类型 | 例 | Program notification template | ```json
{
    "name": "Case notification",
    "notificationTrigger": "ENROLLMENT",
    "subjectTemplate": "Case notification V{org_unit_name}",
    "displaySubjectTemplate": "Case notification V{org_unit_name}",
    "notifyUsersInHierarchyOnly": false,
    "sendRepeatable": false,
    "notificationRecipient": "ORGANISATION_UNIT_CONTACT",
    "notifyParentOrganisationUnitOnly": false,
    "displayMessageTemplate": "Case notification A{h5FuguPFF2j}",
    "messageTemplate": "Case notification A{h5FuguPFF2j}",
    "deliveryChannels": [
        "EMAIL"
    ]
}
``` | 不 | 是的 |

String:Uid

## ABCDEF12345

用户名

Username used by the user.

* Yes*
* 是的
* String:Any

firstName

Only for reading data. First name of the user.

* 不
* 是的

String:Any

导入希望元数据标识符只使用所选的 `idScheme`。同样，元数据
只能使用所选的 `idScheme` 导出。如果元数据缺少所选 `idScheme` 的标识符、
就会收到如下错误。

surname

Only for reading data. Last name of the user.

* 不
* 是的

## String:Any

Doe

> **Note**
>
> Either `uid` or `username` must be provided. If both are provided, only username is
> considered.

* Side Effects
* 类型
* 支持的
* `GET /api/tracker/events/{uid}/changeLogs`
* [tracked entity export](developer-manual.md#webapi_tracker_export_tracked_entities)

### [event export](developer-manual.md#webapi_tracker_export_events)

See each section for request parameters.

| 允许值 | Parameter name | Potential duplicate status | `order` | The import expects metadata identifiers to only use the chosen `idScheme`. Similarly, metadata is 
exported only using the chosen `idScheme`. If metadata lacks identifiers for the chosen `idScheme`, 
you'll receive an error like the below. |
|---|---|---|---|---|
| 异步导入时,会立即返回一个 *Location* 标头,指向 *importReport* 的位置。有效载荷还包含一个已创建任务的 json 对象。 | To resolve this, either: | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | 跟踪器或事件项目的标识符。该参数为必填参数。 | Tracker import { #webapi_tracker_import } |
| ```
GET /tracker/jobs/{uid}
``` | The endpoint `POST /api/tracker` is also called the tracker importer. This endpoint allows clients
to import i.e. create, update and delete | DateTime | Enrollments | 大事记 |
| 设置整体导入模式,决定是否仅 `VALIDATE` 或也 `COMMIT` 元数据,这与我们旧的 dryRun 标志具有相似的功能。 | Objects embedded in other [tracker objects](developer-manual.md#webapi_tracker_objects) | DateTime | 跟踪器导入项目支持以下参数: | Parameter name |
| 描述 | 类型 | DateTime | Enum | Narrows response to tracked entities matching given filters. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering) |
| DateTime | enrollmentEnrolledBefore | DateTime | Enum | importMode |
| programStageIdScheme  | [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) | DateTime | Enum |importMode |
| Can either be `VALIDATE` which will report errors in the payload without making changes to the database or `COMMIT` (default) which will validate the payload and make changes to the database.  | 方案 | DateTime | Enum | importMode |
| IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`.  | `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}` | DateTime | Enum | importMode |
| programIdScheme  | `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}` | DateTime | Enum | importMode |
| `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`  | `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}` | DateTime | Enum | importMode |
| Sets import strategy, `CREATE_AND_UPDATE` will try and match on identifier, if it doesn't exist, it will create the object. | Enum | DateTime | `idScheme` parameter | 项目阶段标识方案 |
| 设置原子模式,在旧的导入器中,我们总是进行*best effort*导入,这意味着即使某些引用不存在,我们仍然会导入(即数据元素组导入时缺少数据元素)。新进口商的默认设置是不允许这样做,并且类似地拒绝任何验证错误。设置 `NONE` 模式模拟了旧的行为. | Enum | DateTime | `idScheme` parameter | categoryOptionComboIdScheme |
| 设置刷新模式,控制何时刷新内部缓存。*强烈*建议将其保留为`AUTO`(这是默认设置)。仅将 `OBJECT` 用于调试目的,您会看到休眠异常并想查明堆栈发生的确切位置(休眠只会在刷新时抛出,因此很难知道哪个对象有问题)。 | Enum | DateTime | `idScheme` parameter | categoryOptionIdScheme |
| IdScheme used for category option references. Defaults to the `idScheme` parameter. | Enum | DateTime | `idScheme` parameter | importStrategy |
| Indicates the effect the import should have. Can either be `CREATE`, `UPDATE`, `CREATE_AND_UPDATE` and `DELETE`, which respectively only allows importing new data, importing changes to existing data, importing any new or updates to existing data, and finally deleting data. | Enum | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | 跟踪器或事件项目的标识符。该参数为必填参数。 | flushMode |
| Indicates how the import responds to validation errors. If `ALL`, all data imported must be valid for any data to be committed. For `OBJECT`, only the data committed needs to be valid, while other data can be invalid. | Enum | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | 跟踪器或事件项目的标识符。该参数为必填参数。 | flushMode |
| Indicates the frequency of flushing. This is related to how often data is pushed into the database during the import. Primarily used for debugging reasons, and should not be changed in a production setting | Enum | *userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。 | 跟踪器或事件项目的标识符。该参数为必填参数。 | flushMode |

#### Indicates the completeness of the validation step. It can be skipped, set to fail fast (Return on the first error), or full (default), which will return any errors found

对于用户来说，同步导入和异步导入的主要区别在于 API 响应的时间。
API 响应的时间。同步导入会在导入完成后立即提供 [导入摘要](developer-manual.md#webapi_tracker_import_summary)
导入完成后，会立即提供 [导入摘要]（#webapi_tracker_import_summary）。相反，异步导入会立即返回导入任务的引用。
的引用。可以使用此 `response.location`来跟踪导入任务的进度。异步导入响应的示例
异步导入响应的示例如下。

`FULL`, `FAIL_FAST`, `SKIP`

`FULL`

### A list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.

If true, it will skip validating the pattern of generated attributes.

#### Boolean

`true`, `false`

``json
{
  "trackedEntities"：[
    {
      "orgUnit"："y77LiPqLMoq"、
      "trackedEntity"："Kj6vYde4LHh"、
      "trackedEntityType"："nEenWmSyUEp" }.
    },
    {
      "orgUnit"："y77LiPqLMoq"、
      "trackedEntity"："Gjaiu3ea38E"、
      "trackedEntityType"："nEenWmSyUEp" }
    }
  ],
  "注册"：[
    {
      "enrolledAt"："2019-08-19T00:00:00.000",
      "注册"："MNWZ6hnuhSw"、
      "occurredAt"："2019-08-19T00:00:00.000",
      "orgUnit"："y77LiPqLMoq"、
      "程序"： "IpHINAT79U"IpHINAT79UW"、
      "状态"："ACTIVE"、
      "trackedEntity"："Kj6vYde4LHh"、
      "trackedEntityType"："nEenWmSyUEp"、
      "attributeOptionCombo"："HllvX50cXC0"、
    }
  ],
  "事件"：[
    {
      "attributeCategoryOptions"："xYerKDKCefk"、
      "attributeOptionCombo"："HllvX50cXC0"、
      "dataValues"：[
        {
          "dataElement"："bx6fsa0t90x"、
          "值"："true
        },
        {
          "dataElement"："UXz7xuGCEhU"、
          "值"："5.7"
        }
      ],
      "注册"："MNWZ6hnuhSw"、
      "enrollmentStatus"（注册状态）："ACTIVE"、
      "事件"： "ZwwuwNp6gVd"："ZwwuwNp6gVd"、
      "occurredAt"："2019-08-01T00:00:00.000",
      "orgUnit"："y77LiPqLMoq"、
      "程序"： "IpHINAT79U"IpHINAT79UW"、
      "programStage"："A03MvHHogjR"、
      "scheduledAt"："2019-08-19T13:59:13.688",
      状态"ACTIVE"、
      "trackedEntity"："Kj6vYde4LHh"
    },
    {
      "attributeCategoryOptions"："xYerKDKCefk"、
      "attributeOptionCombo"："HllvX50cXC0"、
      "注册"： "MNWZ6hnn"MNWZ6hnuhSw"、
      "enrollmentStatus"（注册状态）："ACTIVE"、
      "事件"： "XwwuwNp6"XwwuwNp6gVE"、
      "occurredAt"："2019-08-01T00:00:00.000",
      "orgUnit"："y77LiPqLMoq"、
      "程序"： "IpHINAT79U"IpHINAT79UW"、
      "programStage"："ZzYYXq4fJie"、
      "scheduledAt"："2019-08-19T13:59:13.688",
      "状态"："ACTIVE"、
      "trackedEntity"："Kj6vYde4LHh"
    }
  ],
  "关系"：[
    {
      "来自"：{
        "trackedEntity"：{
          "trackedEntity"："Kj6vYde4LHh"
        }
      },
      "relationshipType"："dDrh5UyCyvQ"、
      "到"：{
        "trackedEntity"：{
          "trackedEntity"："Gjaiu3ea38E"
        }
      }
    }
  ]
}

#### skipSideEffects If true, it will skip running any side effects for the import > **注** > > 虽然嵌套的有效载荷更便于客户管理，但有效载荷总是会在导入前被扁平化 > 在导入之前。对于大型导入，使用扁平结构有效载荷可提供更多控制，并 > 减少导入过程中的开销。 > 减少导入过程中的开销。但是，不能嵌套新的跟踪实体、关系中的 > 注册或事件。 `true`, `false` ### `false` skipRuleEngine ### 如果为 "true",它将跳过运行导入的任何项目规则 Boolean 有效负载必须包括要更新对象的所有字段，即使这些字段没有被修改。修改。唯一的例外是集合。集合中不应更改的项目可以省略。省略，如 [update attribute values](#update-attribute-values) 和 [update data 值]（#update-data-values）中所示。 > **注** > > 已删除的跟踪器对象和关系无法更新。 #### Sync and async The main difference for the user between synchronous and asynchronous imports is the timing of the API response. Synchronous imports provide an immediate [import summary](developer-manual.md#webapi_tracker_import_summary) once the import is finished. In contrast, asynchronous imports return a reference to the import job right away. The progress of the import job can be tracked using this `response.location`. An example of an asynchronous import response is found below.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Tracker job added",
  "response": {
    "id": "cHh2OCTJvRw",
    "location": "https://play.im.dhis2.org/dev/api/tracker/jobs/cHh2OCTJvRw"
  }
}

For large imports, opting for asynchronous import can be advantageous, as it prevents long waiting times for a response. Payload #### 导入项目支持 *flat* 和 *nested* 有效载荷。 Flat payload

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Tracker job added",
  "response": {
    "id": "cHh2OCTJvRw",
    "location": "https://play.im.dhis2.org/dev/api/tracker/jobs/cHh2OCTJvRw"
  }
}

{
  "trackedEntities": [
    {
      "orgUnit": "y77LiPqLMoq",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "nEenWmSyUEp"
    },
    {
      "orgUnit": "y77LiPqLMoq",
      "trackedEntity": "Gjaiu3ea38E",
      "trackedEntityType": "nEenWmSyUEp"
    }
  ],
  "enrollments": [
    {
      "enrolledAt": "2019-08-19T00:00:00.000",
      "enrollment": "MNWZ6hnuhSw",
      "occurredAt": "2019-08-19T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh",
      "trackedEntityType": "nEenWmSyUEp"
    }
  ],
  "events": [
    {
      "attributeCategoryOptions": "xYerKDKCefk",
      "attributeOptionCombo": "HllvX50cXC0",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": "true"
        },
        {
          "dataElement": "UXz7xuGCEhU",
          "value": "5.7"
        }
      ],
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "event": "ZwwuwNp6gVd",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    },
    {
      "attributeCategoryOptions": "xYerKDKCefk",
      "attributeOptionCombo": "HllvX50cXC0",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "event": "XwwuwNp6gVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "ZzYYXq4fJie",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ],
  "relationships": [
    {
      "from": {
        "trackedEntity": {
          "trackedEntity": "Kj6vYde4LHh"
        }
      },
      "relationshipType": "dDrh5UyCyvQ",
      "to": {
        "trackedEntity": {
          "trackedEntity": "Gjaiu3ea38E"
        }
      }
    }
  ]
}

#### Nested payload Nested payloads are the most commonly used structure, where tracker objects are embedded within their parent objects, such as an enrollment within a tracked entity. The advantage of this structure is that the client does not need to provide UIDs for these references, as this is handled automatically.

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Tracker job added",
  "response": {
    "id": "cHh2OCTJvRw",
    "location": "https://play.im.dhis2.org/dev/api/tracker/jobs/cHh2OCTJvRw"
  }
}

{
  "trackedEntities": [
    {
      "enrollments": [
        {
          "attributes": [
            {
              "attribute": "zDhUuAYrxNC",
              "displayName": "Last name",
              "value": "Kelly"
            },
            {
              "attribute": "w75KJ2mc4zz",
              "displayName": "First name",
              "value": "John"
            }
          ],
          "enrolledAt": "2019-08-19T00:00:00.000",
          "events": [
            {
              "attributeCategoryOptions": "xYerKDKCefk",
              "attributeOptionCombo": "HllvX50cXC0",
              "dataValues": [
                {
                  "dataElement": "bx6fsa0t90x",
                  "value": "true"
                },
                {
                  "dataElement": "UXz7xuGCEhU",
                  "value": "5.7"
                }
              ],
              "enrollmentStatus": "ACTIVE",
              "notes": [
                {
                  "value": "need to follow up"
                }
              ],
              "occurredAt": "2019-08-01T00:00:00.000",
              "orgUnit": "y77LiPqLMoq",
              "program": "IpHINAT79UW",
              "programStage": "A03MvHHogjR",
              "scheduledAt": "2019-08-19T13:59:13.688",
              "status": "ACTIVE"
            }
          ],
          "occurredAt": "2019-08-19T00:00:00.000",
          "orgUnit": "y77LiPqLMoq",
          "program": "IpHINAT79UW",
          "status": "ACTIVE",
          "trackedEntityType": "nEenWmSyUEp"
        }
      ],
      "orgUnit": "y77LiPqLMoq",
      "trackedEntityType": "nEenWmSyUEp"
    }
  ]
}

#### Create Make a `POST` request to `/api/tracker` with the `importStrategy` set to `CREATE` or `CREATE_AND_UPDATE` and a payload as described [here](#payload).

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Tracker job added",
  "response": {
    "id": "cHh2OCTJvRw",
    "location": "https://play.im.dhis2.org/dev/api/tracker/jobs/cHh2OCTJvRw"
  }
}

Make a `POST` request to `/api/tracker` with the `importStrategy` set to `UPDATE` or `CREATE_AND_UPDATE` and a payload as described [here](#payload). ### The payload must include all fields of the object you are updating, even if they have not been modified. The only exception is collections. Items in a collection that should not be changed can be omitted, as demonstrated in [update attribute values](#update-data-values) and [update data values](#update-data-values). > **Note** > > Deleted tracker objects and rselationships cannot be updated. Update attribute values Note that it is not necessary to specify the tracked entity's enrollments. However, you must specify the non-collection fields of the tracked entity, even if you are not changing them.

POST /api/tracker?async=false

{
  "trackedEntities": [
    {
      "trackedEntity": "PQfMcpmXeFE",
      "trackedEntityType": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "code": "MMD_PER_NAM",
          "displayName": "First name",
          "createdAt": "2016-08-03T23:49:43.308",
          "updatedAt": "2016-08-03T23:49:43.308",
          "valueType": "TEXT",
          "value": "Johnny"
        }
      ]
    }
  ]
}

Note that it is not necessary to specify the tracked entity's enrollments. However, you must specify the non-collection fields of the tracked entity, even if you are not changing them. Delete attribute values The following deletes one of the attribute values of a [tracked entity](#payload): ### ``` POST /api/tracker?async=false

```json
{
  "trackedEntities": [
    {
      "trackedEntity": "PQfMcpmXeFE",
      "trackedEntityType": "nEenWmSyUEp",
      "orgUnit": "DiszpKrYNg8",
      "attributes": [
        {
          "attribute": "w75KJ2mc4zz",
          "value": null
        }
      ]
    }
  ]
}

#### 支持的 The following updates one of the data values of an [event](#payload): ##### ``` POST /api/tracker?async=false

```json
{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": "true"
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

Delete data values The following deletes one of the data values of an [event](#payload): ### ``` POST /api/tracker?async=false

```json
{
  "events": [
    {
      "event": "ZwwuwNp6gVd",
      "dataValues": [
        {
          "dataElement": "bx6fsa0t90x",
          "value": null
        }
      ],
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "enrollment": "MNWZ6hnuhSw",
      "enrollmentStatus": "ACTIVE",
      "occurredAt": "2019-08-01T00:00:00.000",
      "orgUnit": "y77LiPqLMoq",
      "program": "IpHINAT79UW",
      "programStage": "A03MvHHogjR",
      "scheduledAt": "2019-08-19T13:59:13.688",
      "status": "ACTIVE",
      "trackedEntity": "Kj6vYde4LHh"
    }
  ]
}

删除 Make a `POST` to `/api/tracker` with `importStrategy` set to `DELETE`. The payload should include only the UIDs of the `trackedEntities`, `enrollments`, `events` or `relationships` you wish to delete. The following deletes the events created with [this payload](#payload): | 允许值 | Parameter name | 描述 | | --- | --- | --- | | storedByDataValue | ```json { "trackedEntities": [ { "trackedEntity": "Kj6vYde4LHh", }, { "trackedEntity": "Gjaiu3ea38E", } ] } ``` | All the children of a tracker object will be deleted if the user making the request has the authorities `F_TEI_CASCADE_DELETE` and `F_ENROLLMENT_CASCADE_DELETE`. Relationships linked to an entity are always deleted, without the need of any authority. | #### CSV import To import events using CSV make a `POST` request with CSV body file and the `Content-Type` set to *application/csv* or *text/csv*. #### The UID of a tracker import job Every row of the CSV payload represents an event and a data value. So, for events with multiple data values, the CSV file will have `x` rows per event, where `x` is the number of data values in that event. CSV payload example Your CSV file can look like: | 允许值 | Parameter name | 描述 | | --- | --- | --- | | `fields` | > **注** > > 这些端点依赖于应用项目内存中存储的信息。这意味着信息 > 在某些情况下,如应用项目重启或大量 > 导入请求。 | The value of the tracked entity attribute. | | ``` GET /tracker/jobs/{uid} ``` | Parameter | Enrollments | #### CSV import uid #### The UID of a tracker import job eAjkbUGBcZ5 Request example ### ``` GET /tracker/jobs/PQK63sMwjQp

Response example

```json
[
  {
    "uid": "PQK63sMwjQp",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.370",
    "message": "Import complete with status OK, 0 created, 0 updated, 0 deleted, 0 ignored",
    "completed": true,
    "id": "PQK63sMwjQp"
  },
  {
    "uid": "XIfTJ1UUNcd",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.369",
    "message": "PostCommit",
    "completed": false,
    "id": "XIfTJ1UUNcd"
  },
  {
    "uid": "uCG4FNJLLBJ",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.364",
    "message": "Commit Transaction",
    "completed": false,
    "id": "uCG4FNJLLBJ"
  },
  {
    "uid": "xfOUv2Lk2MC",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.361",
    "message": "Running Rule Engine Validation",
    "completed": false,
    "id": "xfOUv2Lk2MC"
  },
  {
    "uid": "cSPfA776obb",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:16.325",
    "message": "Running Rule Engine",
    "completed": false,
    "id": "cSPfA776obb"
  },
  {
    "uid": "t9gOjotekQt",
    "level": "INFO",
    "category": "TRACKER_IMPORT_JOB",
    "time": "2024-03-19T13:18:15.837",
    "message": "Tracker import started",
    "completed": false,
    "dataType": "PARAMETERS",
    "data": {
      "userId": "xE7jOejl9FI",
      "importMode": "VALIDATE",
      "idSchemes": {
        "dataElementIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "orgUnitIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "programStageIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "idScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionComboIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        },
        "categoryOptionIdScheme": {
          "idScheme": "UID",
          "attributeUid": null
        }
      },
      "importStrategy": "CREATE_AND_UPDATE",
      "atomicMode": "ALL",
      "flushMode": "AUTO",
      "validationMode": "FULL",
      "skipPatternValidation": false,
      "skipSideEffects": false,
      "skipRuleEngine": false,
      "filename": null,
      "reportMode": "ERRORS"
    },
    "id": "t9gOjotekQt"
  }
]

#### Additionally, the following endpoint will return the import summary of the import job. This import summary will only be available after the import has completed:

GET /tracker/jobs/{uid}/report

Parameter 描述 #### 例 path `/{uid}` ID of an existing tracker import job. ABCDEF12345 报告包含一条信息和一个描述实际错误的代码（有关错误信息，请参阅 [错误代码](#error-codes) 部分获取更多关于错误的信息）。此外，报告还包括 `trackerType` 和 `uid` 。和 `uid`，旨在描述在数据的哪个位置发现了错误。在本例中，有一个 TRACKED_ENTITY"，uid 为 "Kj6vYde4LHh"，其中有一个对被跟踪实体类型的引用，但未找到。未找到。 Level of detail for the report. #### `FULL`, `ERRORS`, `WARNINGS` Request example Indicates whether the value of the given key should be encrypted Response example The response payload is the same as the one returned after a sync import request. > **Note** > > Both endpoints are used primarily for async import; however, `GET /tracker/jobs/{uid}` would also > work for sync requests as it eventually uses the same import process and logging as async > requests. Import summary response Import summaries have the following overall structure, depending on the requested `reportMode`: #### ```json { "status": "OK", "validationReport": { "errorReports": [], "warningReports": [] }, "stats": { "created": 3, "updated": 0, "deleted": 0, "ignored": 0, "total": 3 }, "bundleReport": { "typeReportMap": { "EVENT": { "trackerType": "EVENT", "stats": { "created": 1, "updated": 0, "deleted": 0, "ignored": 0, "total": 1 }, "objectReports": [ { "trackerType": "EVENT", "uid": "gTZBPT3Jq39", "errorReports": [] } ] }, "ENROLLMENT": { "trackerType": "ENROLLMENT", "stats": { "created": 1, "updated": 0, "deleted": 0, "ignored": 0, "total": 1 }, "objectReports": [ { "trackerType": "ENROLLMENT", "uid": "ffcvJvWjiNZ", "errorReports": [] } ] }, "RELATIONSHIP": { "trackerType": "RELATIONSHIP", "stats": { "created": 0, "updated": 0, "deleted": 0, "ignored": 0, "total": 0 }, "objectReports": [] }, "TRACKED_ENTITY": { "trackerType": "TRACKED_ENTITY", "stats": { "created": 1, "updated": 0, "deleted": 0, "ignored": 0, "total": 1 }, "objectReports": [ { "trackerType": "TRACKED_ENTITY", "uid": "aVcGf9iO8Xp", "errorReports": [] } ] } } } }

状态

The property, `status`, of the import summary indicates the overall status of the import. If no
errors or warnings were raised during the import, the `status` is reported as `OK`. The presence of
any error or warnings in the import will result in a status of type `ERROR` or `WARNING`.

`status` is based on the presence of the most significant `validationReport`. `ERROR` has the
highest significance, followed by `WARNING` and finally `OK`. This implies that `ERROR` is reported
as long as a single error was found during the import, regardless of how many warnings occurred.

每种类型的跟踪器对象都将被报告，每种对象都有自己的统计信息和 `objectReports`.这些
对象报告 "将提供有关每个导入对象的详细信息，如其类型、uid 以及任何
错误或警告报告（如适用）。

#### Validation report

The `validationReport` might include `errorReports` and `warningReports` if any errors or warnings
were present during the import. When present, they provide a detailed list of any errors or warnings
encountered.

### For example, a validation error while importing a `TRACKED_ENTITY`:

可在 `GET /tracker/jobs/{uid}/report` 请求中使用特定的 `reportMode` 参数检索导入摘要报告。
请求中使用特定的默认情况下，端点将返回一个 `reportMode``ERROR` 的 `importSummary`。

| ```json
{
  "object": {
    "publicAccess": "rw------",
    "externalAccess": false,
    "user": {},
    "userAccesses": [],
    "userGroupAccesses": [
      {
        "id": "hj0nnsVsPLU",
        "access": "rw------"
      },
      {
        "id": "qMjBflJMOfB",
        "access": "r-------"
      }
    ]
  }
}
``` | Parameter name |
| --- | --- |
| Statistics | The stats object provides an overview of the import operation. After an import is completed, these will be the
actual counts displaying how many objects were created, updated, deleted and ignored. |
| 响应示例: | ```json
{
  "stats": {
    "created": 2,
    "updated": 2,
    "deleted": 1,
    "ignored": 5,
    "total": 10
  }
}
``` |
| The `created` field refers to how many new objects were created. In general, objects without an existing uid
in the payload will be treated as new objects. | The `updated` field refers to the number of objects updated. If an object has a uid set in the payload, it
will be treated as an update as long as that same uid exists in the database. |

The `deleted` field refers to the number of objects deleted during the import. Deletion only happens when the
import is configured to delete data and only then when the objects in the payload have existing uids
set.

### The `ignored` field refers to objects that were not persisted. Objects can be ignored for several reasons, for
example trying to create something that already exists. Ignores should always be safe, so if
something was ignored, it was not necessary, or it was due to the configuration of the import.

不同的错误场景有不同的错误代码。下表列出了
下表列出了 Tracker API 抛出的错误代码、错误信息和一些附加说明。
说明。错误信息中的占位符（`{0}`、`{1}`、`{2}`...）通常是 uids，除非另有说明。
另有说明。

| When the import is completed, the `bundleReport` contains all the [tracker objects](#tracker-objects) imported. | An example for `TRACKED_ENTITY`: | Parameter name |
|:--|:----|:----|
| Each type of tracker object will be reported, and each has its own stats and `objectReports`. These 
`objectReports` will provide details about each imported object, like their type, their uid, and any 
error or warning reports is applicable. | 信息 | If the import ended abruptly, the `message` would contain further information in relation to what
happened. |
| Import summary report level | A import summary report can be retrieved using a specific `reportMode` parameter in a `GET /tracker/jobs/{uid}/report` 
request. By default the endpoint will return an `importSummary` with `reportMode` `ERROR`. | Parameter
| 描述 | FULL | Returns everything from `WARNINGS`, plus `timingsStats` |
| WARNINGS | Returns everything from `ERRORS`, plus `warningReports` in `validationReports` | |
| ERRORS (default) | Returns only `errorReports` in `validationReports` | In addition, all `reportModes` will return `status`, `stats`, `bundleReport` and `message` when
applicable. |
| Error codes { #webapi_tracker_error_codes } | There are various error codes for different error scenarios. The following table has the list of
error codes thrown from the new Tracker API, along with the error messages and some additional
descriptions. The placeholders in the error messages (`{0}`,`{1}`,`{2}`..) are usually uids unless
otherwise specified. | Error Code |
| Error Message | 描述 | E1000 |
| User: `{0}`, has no write access to OrganisationUnit: `{1}`. | This typically means that the OrganisationUnit `{1}` is not in the capture scope of the user `{0}` for the write operation to be authorized. | |
| E1001 | User: `{0}`, has no data write access to TrackedEntityType: `{1}`. | The error occurs when the user is not authorized to create or modify data of the TrackedEntityType `{1}` |
| E1002 | TrackedEntity: `{0}`, already exists. | This error is thrown when trying to create a new TrackedEntity with an already existing uid. Make sure a new uid is used when adding a new TrackedEntity. |
| E1003 | User: `{0}`, has no write access to TrackedEntity: `{1}`. | E1005  |
| Could not find TrackedEntityType: `{0}`. | Error thrown when trying to fetch a non existing TrackedEntityType with uid `{0}` . This might also mean that the user does not have read access to the TrackedEntityType. | E1006 |
| Attribute: `{0}`, does not exist. | Error thrown when the system was not able to find a matching TrackedEntityAttribute with uid `{0}`. This might also mean that the user does not have access to the TrackedEntityAttribute. | E1007  |
| Error validating attribute value type: `{0}`; Error: `{1}`. | Mismatch between value type of a TrackedEntityAttribute and its provided attribute value. The actual validation error will be displayed in `{1}`. | E1008 |
| 项目阶段 `{0}` 没有引用项目。检查项目阶段配置 | E1009 | File resource: `{0}`, has already been assigned to a different object.|
| The File resource uid `{0}` is already assigned to another object in the system. | E1010 | Could not find Program: `{0}`, linked to Event. |
| 系统无法找到在事件有效负载中指定了 uid `{0}` 的项目。这也可能意味着登录用户无法访问特定项目。 | E1011 | Could not find OrganisationUnit: `{0}`, linked to Event.  |
| The system was unable to find a OrganisationUnit with uid `{0}` specified inside the Event payload. | E1012 | Geometry does not conform to FeatureType: `{0}`.  |
| FeatureType provided is either NONE or an incompatible one for the provided geometry value. | E1013 | Could not find ProgramStage: `{0}`, linked to Event. |
| The system was unable to find a ProgramStage with uid `{0}` specified inside the Event payload. This might also mean that the ProgramStage is not accessible to the logged in user. | E1014 | Provided Program: `{0}`, is a Program without registration. An Enrollment cannot be created into Program without registration. |
| Enrollments can only be created for Programs with registration. | E1015 | TrackedEntity: `{0}`, already has an active Enrollment in Program `{1}`. |
| Cannot enroll into a Program if another active enrollment already exists for the Program. The active enrollment will have to be completed first at least. | E1016 | TrackedEntity: `{0}`, already has an active enrollment in Program: `{1}`, and this program only allows enrolling one time. |
| 根据项目 `{1}` 配置,一个 TrackedEntity 只能注册该项目一次。看起来 TrackedEntity `{0}` 已经在该项目中注册过一次。因此不能再添加另一个注册。 | E1018 | Attribute: `{0}`, is mandatory in program `{1}` but not declared in enrollment `{2}`. |
| 有效负载中缺少被定义为项目强制属性的属性值。确保在有效负载中提供强制属性的属性值。 | E1019 | Only Program attributes is allowed for enrollment; Non valid attribute: `{0}`. |
| 注册有效负载中指定的属性 uid `{0}` 与项目无关。 | E1020 | Enrollment date: `{0}`, cannot be a future date. |
| Cannot enroll into a future date unless the Program allows for it in its configuration. | E1021 | OccurredAt 属性为空或有效负载中的日期格式无效。 |
| 事件发生日期不能是未来日期,除非项目在配置中允许这样做。 | E1022 | |
| TrackedEntity: `{0}`, must have same TrackedEntityType as Program `{1}`. | 项目被配置为接受与注册有效负载中提供的不同的 TrackedEntityType uid。 | |
| E1023 | DisplayIncidentDate is true but property occurredAt is null. | 项目已配置 DisplayIncidentDate,但在有效负载中为空。  |
| E1025 | Property enrolledAt is null. | EnrolledAt Date is mandatory for an Enrollment. Make sure it is not null. |
| E1029 | Event OrganisationUnit: `{0}`, and Program: `{1}`, don't match. | 事件有效载荷使用项目 `{1}`,该项目未配置为可被组织单位 `{0}` 访问。 |
| E1030 | Event: `{0}`, already exists. | This error is thrown when trying to add a new Event with an already existing uid. Make sure a new uid is used when adding a new Event. |
| E1031 | Event occurredAt date is missing. | OccurredAt property is either null or has an invalidate date format in the payload.  |
| E1032 | Event: `{0}`, do not exist. | E1033 |
| Event: `{0}`, Enrollment value is NULL. | E1039 | ProgramStage: `{0}`, is not repeatable and an event already exists. |
| 特定注册的 ProgramStage 已存在一个事件。由于项目阶段被配置为不可重复,因此无法为同一项目阶段添加另一个事件。 | E1041 | Enrollment OrganisationUnit: `{0}`, and Program: `{1}`, don't match. |
| 注册有效载荷包含一个项目 `{1}`,该项目未配置为可被组织单位 `{0}` 访问。 | E1043 | Event: `{0}`, completeness date has expired. Not possible to make changes to this event. |
| 没有 "F_EDIT_EXPIRED "权限的用户无法更新已过期的事件,因为该事件已在其项目中配置。 | E1046 |
| Event: `{0}`, needs to have at least one (event or schedule) date. | Either of occurredAt or scheduledAt property should be present in the Event payload. | E1047 |
| Event: `{0}`, date belongs to an expired period. It is not possible to create such event. | Event occurredAt or scheduledAt has a value that is earlier than the PeriodType start date. | E1049 |
| Could not find OrganisationUnit: `{0}`, linked to Tracked Entity. | The system could not find an OrganisationUnit with uid `{0}`. | E1050  |
| Event ScheduledAt date is missing. | ScheduledAt property in the Event payload is either missing or an invalid date format. | E1051 |
| Event: `{0}`, completedAt must be null when status is `{1}`. | Event completedAt can only be passed in the payload if status is COMPLETED | E1052 |
| Enrollment: `{0}`, completedAt must be null when status is `{1}`. | Enrollment completedAt can only be passed in the payload if status is COMPLETED | E1054 |
| AttributeOptionCombo `{0}` 不在事件项目类别组合 `{1}` 中。 | E1055 | 由于项目具有非默认的 CategoryCombo,因此不允许使用默认的 AttributeOptionCombo。 |
| 项目被配置为包含非默认 CategoryCombo,但请求使用了默认 AttributeOptionCombo。 | E1056 | Event date: `{0}`, is before start date: `{1}`, for AttributeOption: `{2}`. |
| The CategoryOption has a start date configured , the Event date in the payload cannot be earlier than this start date. | E1057 | |
| Event date: `{0}`, is after end date: `{1}`, for AttributeOption; `{2}`. | The CategoryOption has an end date configured, the Event date in the payload cannot be later than this end date. | |
| E1063 | TrackedEntity: `{0}`, does not exist. | |
| Error thrown when trying to fetch a non existing TrackedEntity with uid `{0}` . This might also mean that the user does not have read access to the TrackedEntity. | E1064 | |
| Non-unique attribute value `{0}` for attribute `{1}` | The attribute value has to be unique within the defined scope. The error indicates that the attribute value already exists for another TrackedEntity. | |
| E1068 | Could not find TrackedEntity: `{0}`, linked to Enrollment. | 当尝试使用已存在的 uid 创建新注册表时，会出现此错误。请确保在添加新注册表时使用新的 uid。 |
| E1069 | Could not find Program: `{0}`, linked to Enrollment. | 系统无法找到注册有效负载中指定的项目。这也可能意味着用户没有项目的读取权限。 |
| E1070 | Could not find OrganisationUnit: `{0}`, linked to Enrollment. | The system could not find the OrganisationUnit specified in the Enrollment payload. |
| E1074 | FeatureType is missing. | E1075 |
| Attribute: `{0}`, is missing uid. | E1076 | `{0}` `{1}` is mandatory and can't be null |
| E1077 | Attribute: `{0}`, text value exceed the maximum allowed length: `{0}`. | E1079 |
| Event: `{0}`, program: `{1}` is different from program defined in enrollment `{2}`. | E1080 | Enrollment: `{0}`, already exists. |
| This error is thrown when trying to create a new Enrollmentt with an already existing uid. Make sure a new uid is used when adding a new Enrollment. | E1081 | Enrollment: `{0}`, do not exist.  |
| Error thrown when trying to fetch a non existing Enrollment with uid `{0}` . This might also mean that the user does not have read access to the Enrollment. | E1082 | Event: `{0}`, is already deleted and can't be modified. |
| If the event is soft deleted, no modifications on it are allowed. | E1083 | User: `{0}`, is not authorized to modify completed events. |
| Only a super user or a user with the authority "F_UNCOMPLETE_EVENT" can modify completed events. Completed Events are those Events with status as COMPLETED. | E1089 | Event: `{0}`, references a Program Stage `{1}` that does not belong to Program `{2}`. |
| The ProgramStage uid and Program uid in the Event payload is incompatible. | E1090 | Attribute: `{0}`, is mandatory in tracked entity type `{1}` but not declared in tracked entity `{2}`. |
| The payload has missing values for mandatory TrackedEntityTypeAttributes. | E1091 | User: `{0}`, has no data write access to Program: `{1}`. |
| 在项目共享配置中,用户没有该项目的写入权限。 | E1095 | User: `{0}`, has no data write access to ProgramStage: `{1}`. |
| 在项目阶段共享配置中,用户没有写入该项目阶段的权限。 | E1096 | User: `{0}`, has no data read access to Program: `{1}`. |
| 在项目共享配置中,用户没有该项目的读取权限。 | E1099 | User: `{0}`, has no write access to CategoryOption: `{1}`. |
| The CategoryOption sharing configuration is such that, the user does not have write access for this CategoryOption | E1100 | User: `{0}`, is lacking 'F_TEI_CASCADE_DELETE' authority to delete TrackedEntity: `{1}`. |
| There exists undeleted Enrollments for this TrackedEntity. If the user does not have 'F_TEI_CASCADE_DELETE' authority, then these Enrollments has to be deleted first explicitly to be able to delete the TrackedEntity. | E1102 | |
| 用户: `{0}`, 没有访问被跟踪实体的权限:`{1}`, 项目:`{2}`, 组合。 | 当用户的组织单位不拥有该特定项目的 TrackedEntity 的所有权时,就会抛出此错误。拥有 TrackedEntity-Program 组合的组织单位应属于用户的捕获范围(有时是搜索范围)。 | E1103|
| User: `{0}`, is lacking 'F_ENROLLMENT_CASCADE_DELETE' authority to delete Enrollment : `{1}`. | There exists undeleted Events for this Enrollment. If the user does not have 'F_ENROLLMENT_CASCADE_DELETE' authority, then these Events has to be deleted first explicitly to be able to delete the Enrollment. | |
| E1104 | User: `{0}`, has no data read access to program: `{1}`, TrackedEntityType: `{2}`. | |
| 与项目相关联的 TrackedEntityType 的共享配置规定,用户没有数据读取权限。 | E1112 | |
| Attribute value: `{0}`, is set to confidential but system is not properly configured to encrypt data. | Either JCE files is missing or the configuration property `encryption.password` might be missing in `dhis.conf`. | E1113 |
| Enrollment: `{0}`, is already deleted and can't be modified. | If the Enrollment is soft deleted, no modifications on it are allowed. | |
| E1114 | TrackedEntity: `{0}`, is already deleted and can't be modified. | |
| If the TrackedEntity is soft deleted, no modifications on it are allowed. | E1115 | |
| Could not find CategoryOptionCombo: `{0}`. | E1116 | |
| Could not find CategoryOption: `{0}`. | This might also mean the CategoryOption is not accessible to the user. | |
| E1117 | CategoryOptionCombo does not exist for given category combo and category options: `{0}`. | |
| E1118 | Assigned user `{0}` is not a valid uid. | |
| E1119 | A Tracker Note with uid `{0}` already exists. | |
| E1120 | 项目阶段 `{0}` 不允许用户赋值 | |
| 事件有效载荷具有 assignedUserId,但项目阶段未配置为允许用户分配。 | E1121 | |
| Missing required tracked entity property: `{0}`. | E1122 | |
| Missing required enrollment property: `{0}`. | E1123 | |
| Missing required event property: `{0}`. | E1124 | |
| Missing required relationship property: `{0}`. | E1125 | |
| Value `{0}` is not a valid option code in option set `{1}` | E1126 | |
| Not allowed to update Tracked Entity property: {0}. | E1127 | |
| Not allowed to update Enrollment property: {0}. | E1128 | |
| Not allowed to update Event property: {0}. | E1300 | |
| 由项目规则生成 (`{0}`) - `{1}` | E1301 | |
| 由项目规则生成 (`{0}`) - 不存在强制性数据元素 `{1}` | E1302 | DataElement `{0}` is not valid: `{1}` |
| E1303 | Mandatory DataElement `{0}` is not present | |
| E1304 | DataElement `{0}` is not a valid data element| |
| E1305 | 数据元素 `{0}` 不是 `{1}` 项目阶段的一部分 | |
| E1306 | 由项目规则 (`{0}`) 生成 - 不存在强制属性 `{1}` | |
| E1307 | 由项目规则生成 (`{0}`) - 无法为数据元素 `{1}` 赋值。提供的值必须为空或与计算值 `{2}` 匹配。 | |
| E1308 | 由项目规则 (`{0}`) 生成 - 数据元素 `{1}` 被事件 `{2}` 替换 | |
| E1309 | 由项目规则 (`{0}`) 生成 - 无法为属性 `{1}` 赋值。提供的值必须为空或与计算值 `{2}` 匹配。 | |
| E1310 | 由项目规则 (`{0}`) 生成 - 属性 `{1}` 被替换为 `{2}` | |
| E1313 | Event {0} of an enrollment does not point to an existing tracked entity. The data in your system might be corrupted | |
| Indicates an anomaly in the existing data whereby enrollments might not reference a tracked entity | E1314 | |
| 由项目规则 (`{0}`) 生成 - 数据元素 `{1}` 是必填项,不能删除。 | E1315 | |
| Status `{0}` does not allow defining data values. Statuses that do allow defining data values are: {1} | E1316 | |
| No event can transition from status `{0}` to status `{1}`. | E1317 | |
| 由项目规则 (`{0}`) 生成 - 属性 `{1}` 是强制性的,不能删除。 | E4000 | |
| Relationship: `{0}` cannot link to itself | E4001 | |
| Relationship Item `{0}` for Relationship `{1}` is invalid: an Item can link only one Tracker entity. | E4006 | Could not find relationship Type: `{0}`. |
| E4010 | Relationship Type `{0}` constraint requires a {1} but a {2} was found. | E4012 |

### Could not find `{0}`: `{1}`, linked to Relationship.

E4014

#### Relationship type `{0}` constraint requires a tracked entity having type `{1}` but `{2}` was found.

E4015

Relationship: `{0}`, already exists.

1. E4016
2. Relationship: `{0}`, do not exist.
3. E4017

Relationship: `{0}`, is already deleted and cannot be modified.

#### E4018

Relationship: `{0}`, linking {1}: `{2}` to {3}: `{4}` already exists.

- E4020
- User: `{0}`, has no write access to relationship: `{1}`.
- E5000

#### "{0}" `{1}` cannot be persisted because "{2}" `{3}` referenced by it cannot be persisted.

导入项目无法持久化跟踪器对象,因为引用无法持久化。

E9999

不适用

Undefined error message.

#### Validation { #webapi_tracker_validation }

使用跟踪器导入项目导入数据时,会执行一系列验证,以确保数据的有效性。
数据的有效性。本节将介绍执行的一些不同类型的验证
以便更好地了解导入验证是否失败。

Required properties

Each of the tracker objects has a few required properties that need to be present when importing
data. For an exhaustive list of required properties, have a look at the [tracker objects
section](developer-manual.md#webapi_tracker_objects).

When validating required properties, we are usually talking about references to other data or
metadata. In these cases, there are three main criteria:

#### The reference is present and not null in the payload.

The reference points to the correct type of data and exists in the database

- The user has access to see the reference
- If the first condition fails, the import will fail with a message about a missing reference.
However, suppose the reference points to something that doesn't exist or which the user cannot
access. In that case, both cases will result in a message about the reference not being found.
- Formats
- Some of the properties of tracker objects require a specific format. When importing data, each of
these properties is validated against the expected format and will return different errors depending
on which property has a wrong format. Some examples of properties that are validated this way:

UIDs (These cover all references to other data or metadata in DHIS2.)

### Dates

Geometry (The coordinates must match the format as specified by its type)

#### User access

All data imported will be validated based on the metadata ([sharing](developer-manual.md#webapi_tracker_metadata_sharing))
and the organisation units ([scopes](developer-manual.md#webapi_tracker_orgunit_scope)) referenced in the
data. You can find more information about sharing and organisation unit scopes in the following
sections.

Sharing is validated at the same time as references are looked up in the database. Metadata outside
of the user access scope will be treated as if it does not exist. The import will validate any metadata
referenced in the data.

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues

Users with the `ALL` authority will ignore the limits of sharing and organisation unit scopes when
they import data. However, they can not import enrollments in organisation units that do not have
access to the enrollment program.

#### Attributes and data values

属性和数据值分别是被跟踪实体和事件的一部分。但是
属性可以通过类型(TrackedEntityType)或项目(Program)链接到被跟踪实体。
项目(Program)。此外,属性也可以是唯一的。

The initial validation done in the import is to make sure the value provided for an attribute or
data element conforms to the type of value expected. For example, suppose you import a value for a
data element with a numeric type. In that case, the value is expected to be numeric. Any errors
related to a mismatch between a type and a value will result in the same error code but with a
specific message related to the type of violation.

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/generate?ORG_UNIT_CODE=OSLO

The import will validate unique attributes at the time of import. That means as long as the provided
value is unique for the attribute in the whole system, it will pass. However, if the unique value is
found to be used by any other tracked entity other than the one being imported, it will fail.

#### 组态

The last part of validations in the importer are validations based on the user's configuration of
relevant metadata. For more information about each configuration, check out the relevant sections.
Some examples of configurable validations:

Feature type (geometry)

GET /api/trackedEntityAttributes/Gs1ICEQTPlG/generateAndReserve?numberToReserve=3&ORG_UNIT_CODE=OSLO

Allow future dates

#### Enroll once

These configurations will further change how validation is performed during import.

Generated tracked entity attributes { #webapi_generate_te_attributes }

| 指标组 | Parameter name |
|---|---|
| A TextPattern may include variables that change based on different factors. Some of these factors are unknown to the server;
thus, the values for these variables must be supplied when generating and reserving values. | This endpoint returns a map of required and optional values that the server will inject into the TextPattern when generating new values.
Required variables must be supplied for generation, whereas optional variables should only be provided if necessary. |
| ```
GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/requiredValues
``` | ```json
{
  "REQUIRED": [
    "ORG_UNIT_CODE"
  ],
  "OPTIONAL": [
    "RANDOM"
  ]
}
``` |
| 产生价值终点 { #webapi_generate_values } | 在线网络应用项目和其他客户端可使用该端点生成一个唯一值,以供立即使用。
生成的值在生成时保证是唯一的,并保留 3 天。
如果您的 TextPattern 包含必填值,可以将它们作为参数传递。 |
| 日期时间 | ```
GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/generate?ORG_UNIT_CODE=OSLO
``` |
|     GET /api/metadata/proposals?filter=status:eq:ACCEPTED | 产生并保留价值终点 { #webapi_generate_reserve_values } |
| Offline clients can use this endpoint to reserve a number of unique IDs for later use when
registering new tracked entities. The number of IDs to generate can be specified with the
`numberToReserve` parameter (default is 1). | To override the default expiration time of 60 days, add `?expiration=<number-of-days>` to the request. |

GET /api/33/trackedEntityAttributes/Gs1ICEQTPlG/generateAndReserve?numberToReserve=3&ORG_UNIT_CODE=OSLO

### ```json
[
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "B-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "Q-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  },
  {
    "ownerObject": "TRACKEDENTITYATTRIBUTE",
    "ownerUid": "Gs1ICEQTPlG",
    "key": "RANDOM(X)-OSL",
    "value": "S-OSL",
    "created": "2018-03-02T13:22:35.175",
    "expiryDate": "2018-05-01T13:22:35.174"
  }
]

Reserved values 目前无法通过 api 访问保留值,但是,它们由`generate` 和`generateAndReserve` 端点返回。这下表解释了保留值对象的属性: | Table: Reserved values | Property | | --- | --- | | 设置必填字段 | | | 淋浴器 | | | 日程消息 | | | 名称 | | | 始终有效 | DISPLAYKEYVALUEPAIR | | 显示选项组 | DISPLAYKEYVALUEPAIR | | 隐藏选项组 | DISPLAYKEYVALUEPAIR | | The timestamp when the reservation was made | DISPLAYKEYVALUEPAIR | | The timestamp when the reservation will no longer be reserved | DISPLAYKEYVALUEPAIR | | Program rules { #webapi_tracker_program_rules }| | | 隐藏选项 | DISPLAYKEYVALUEPAIR | | 参见说明 | DISPLAYKEYVALUEPAIR | | 2.37 中为 ProgramRuleAction 模型添加了一些验证。主要目的是防止用户创建错误的项目规则,以保持数据库的一致性。这些验证取决于项目规则动作类型。每种操作类型都有各自的验证。 | DISPLAYKEYVALUEPAIR | HIDEFIELD * HIDESECTION * ASSIGN X * 程序规则操作可能会导致两种不同的结果：警告或错误。 * X * SHOWERROR * X * WARNINGONCOMPLETION * X * ERRORONCOMPLETION * X CREATEEVENT SETMANDATORYFIELD ### X SENDMESSAGE X SCHEDULEMESSAGE | X | Property | Parameter name | |--- | --- | --- | | 项目规则条件必须为真。 | DISPLAYKEYVALUEPAIR | 项目规则操作可能会导致两种不同的结果:警告或错误。 | | Errors will make the validation fail, while the warnings will be reported as a message in the import summary. | DISPLAYKEYVALUEPAIR | `SHOWERROR`, `ERRORONCOMPLETION`, and `SETMANDATORYFIELD` actions can generate only errors. | `ASSIGN` action can generate both Warnings and Errors. ### When the action is assigning a value to an empty attribute/data element, a warning is generated. When the action is assigning a value to an attribute/data element that already has the same value to be assigned, a warning is generated. When the action is assigning a value to an attribute/data element that already has a value and the value to be assigned is different, an error is generated unless the `RULE_ENGINE_ASSIGN_OVERWRITE` system setting is true. 此外,项目规则也会产生副作用,如发送和计划信息。更多有关副作用的更多信息,请参阅下一节。 > **注** > > 在导入过程中,可以使用 `skipProgramRules` 参数跳过项目规则。 Side effects { #webapi_tracker_side_effects } After an import has been completed, specific tasks might be triggered as a result of the import. These tasks are what we refer to as "Side effects". These tasks perform operations that do not affect the import itself. ## Side effects are tasks running detached from the import but are always triggered by an import. Since side effects are detached from the import, they can fail even when the import is successful. Additionally, side effects are only run when the import is successful, so they cannot fail the other way around. The following side effects are currently supported: - Side Effects - 支持的 - 类型 - `GET /api/tracker/events/{uid}/changeLogs` X ### Updates can trigger notifications. Updates which trigger notifications are *enrollment*, *event update*, *event or enrollment completion*. ProgramRule Notification - X - 项目规则可触发通知。请注意,这些通知是通过 DHIS2 规则引擎生成的项目规则效果的一部分。 - > **Note** > > Certain configurations can control the execution of side effects. `skipSideEffects` flag can be set during the import to skip side effects entirely. This parameter can be useful if you import something you don't want to trigger notifications for, as an example. - Assign user to events { #webapi_tracker_user_event_assignment } #### Specific workflows benefit from treating events like tasks, and for this reason, you can assign a user to an event. |允许值|Potential duplicate status|`order`|Parameter name| |---|---|---|---| |定义要返回的页码。|Enrollments|`paging`|追踪实体| |定义每页返回的元素数量。|Enrollments|`paging`|`Boolean`| |Common request parameters|*userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。|Events: `GET /api/tracker/events`| |true|*userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。|Request parameter| |iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:||描述| page #### 整数 Any positive integer #### Page number to return. Defaults to 1. pageSize ##### 整数 | Any positive integer | Parameter name | | --- | --- | | totalPages |Boolean | | `true`, `false` | Indicates whether to return the total number of elements and pages. Defaults to `false` as getting the totals is an expensive operation. | | paging | Boolean | | `true`, `false` | Indicates whether paging should be ignored and all rows should be returned. Defaults to `true`, meaning that by default all requests are paginated, unless `paging=false`. | | order | 串 | ### Comma-separated list of field and sort direction pairs in format `field:sortDirection`. Example: `createdAt:desc`

Entities are ordered by newest (internal ID descending) by default. Note: `field` is case sensitive. Valid `sortDirections` are `asc` and `desc`, where `sortDirection` is case insensitive, and `sortDirection` defaults to `asc` for fields or UIDs without explicit `sortDirection`. > **Note** > > Be aware that performance is directly related to the amount of data requested. Greater page > sizes will take more time to return. Organisation unit selection modes - The available organisation unit selection modes are `SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE` and `ALL`. Each mode is explained in detail in [this section](developer-manual.md#webapi_tracker_orgunit_scope). - Field filter responses { #webapi_tracker_field_filter } - All export endpoints accept a `fields` parameter which controls which fields will be returned in the JSON response. `fields` parameter accepts a comma separated list of field names or patterns. A few possible `fields` filters are shown below. Refer to [Metadata field filter](developer-manual.md#webapi_metadata_field_filter) for a more complete guide on how to use `fields`. - 例子 Query parameter example #### 使用特定项目和组织单位查询所有事件: 串 - Returns all fields - fields=createdAt,uid - Returns fields `createdAt` and `uid` - fields=enrollments[\*,!uid] - Returns all fields of `enrollments` except `uid` - fields=enrollments[uid] - Returns `enrollments` field `uid` - fields=enrollments[uid,enrolledAt] - Returns `enrollments` fields `uid` and `enrolledAt` - Tracked entities { #webapi_tracker_export_tracked_entities } - ``` GET /api/tracker/trackedEntities

    Two endpoints are dedicated to tracked entities:
  - `GET /api/tracker/trackedEntities`
  - retrieves tracked entities matching given criteria
  - `GET /api/tracker/trackedEntities/{id}`
  - retrieves a tracked entity given the provided ID
  - If not otherwise specified, JSON is the default response for the `GET` method.
The API also supports CSV export for single and collection endpoints. Furthermore, compressed
CSV types is an option for the collection endpoint.
  - CSV
  - In the case of CSV, the `fields` request parameter has no effect, and the response will always
contain the following fields:
  - trackedEntity (UID)
  - trackedEntityType (identifier in requested idScheme)
  - createdAt (Datetime)
  - createdAtClient (Datetime)

updatedAt (Datetime)

#### updatedAtClient (Datetime)

orgUnit (identifier in requested idScheme)

#### inactive (boolean)

deleted (boolean)

#### potentialDuplicate (boolean)

> **Note**
>
> Be aware that performance is directly related to the amount of data requested. Greater page
> sizes will take more time to return.

You can omit it in case of a `Point` type and with `latitude` and `longitude` provided)

latitude (Latitude of a `Point` type of Geometry)

|允许值|Potential duplicate status|`order`|Parameter name|
|---|---|---|---|
|数据值|具有以下要求:|value (String)|storedBy (String) |
|createdBy (Username of user)|具有以下要求:|See [Tracked Entities](#tracked-entities) and [Attributes](#attributes) for more field descriptions.|GZIP|
|The response is file `trackedEntities.csv.gz` containing the `trackedEntities.csv` file.|具有以下要求:|Narrows response to events matching given filters. A filter is a colon separated property or data element UID with optional operator and value pairs. Example: `filter=fazCI2ygYkq:eq:PASSIVE` with operator starts with `eq` followed by a value. A filter like `filter=fazCI2ygYkq:!null` returns all events where the given data element has a value. Characters such as `:` or `,`, as part of the filter value, need to be escaped by `/`. Likewise, `/` needs to be escaped. Multiple operators for the same data element like `filter=qrur9Dvnyt5:gt:70:lt:80` are allowed. User needs access to the data element to filter on it.|Tracked entity collections|
|`{ "periodFrom": -15, "periodTo": 15}`|具有以下要求:|The endpoint returns a list of tracked entities that match the request parameters.|Request parameter|
|See [Events](developer-manual.md#webapi_tracker_objects_events) and [Data Values](developer-manual.md#webapi_tracker_data_values) for more
field descriptions.|JSON格式|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json`
or `events.csv` file.|跟进|
|See an example payload below.|具有以下要求:|Narrows response to tracked entities matching given filters. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering)|orgUnits|
|Table: Program Stage Query Criteria|*userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。|orgUnitMode|
|串|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | 项目|
|DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | programStatus **deprecated for removal in version 43 use `enrollmentStatus`**|
|DateTime|[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)|Filter for events which occurred up until this date. | 项目阶段|
|DateTime|具有以下要求:|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json`
or `events.csv` file.|跟进|
|DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|updatedAfter|
|DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|updatedBefore|
|DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|指定项目的注册开始日期|
|Duration|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|指定项目的注册结束日期|
|`{"organisationUnit": "a3kGcGDCuk7"}`|具有以下要求:|The status of the tracked entities enrollment in the given program.|enrollmentEnrolledAfter|
|Absolute end date. Applicable only when `type` is ABSOLUTE|具有以下要求:|Start date and time for enrollment in the given program|enrollmentEnrolledBefore|
|Enum|具有以下要求:|End date and time for enrollment in the given program|enrollmentOccurredAfter|
|Property|具有以下要求:|events|enrollmentOccurredBefore|
|iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:|描述|trackedEntityType|
|`"displayOrderColumns": ["enrollmentDate", "program"]`|具有以下要求:|Narrows response to tracked entities matching given filters. Example: `filterAttributes=H9IlTX2X6SL:eq:John`. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering)|trackedEntities|
|串|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|assignedUserMode|
|串|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|assignedUsers|
|串|*userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。|order|
|串|*userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。| eventStatus |
|描述|DateTime|Enum|eventOccurredAfter|
|programStageIdScheme|DateTime|Enum|[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)|

DateTime

[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)

| Only one parameter among `trackedEntity`, `enrollment`, `event` can be passed. | Parameter name |
| --- | --- |
| Boolean | `true`, `false` |
| Indicates whether to include soft-deleted elements | potentialDuplicate |
| Boolean | `true`, `false` |
| Filter the result based on the fact that a tracked entities is a potential duplicate. `true`: returns tracked entities flagged as potential duplicates. `false`: returns tracked entities NOT flagged as potential duplicates. | 方案 |
| In summary, DHIS2 has a fine-grained sharing setting that we can use to implement access control
mechanisms both at the data and metadata level. These sharing settings can be applied directly at
the user level or user group level. How exactly to apply a sharing setting depends on the use-case
at hand. | `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}` |

IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`. Note: only metadata in fields `trackedEntity.trackedEntityType`, `orgUnit` and `attributes` is exported in this idScheme. All other fields will always be exported using UIDs.

- orgUnitIdScheme
  Enum
- `UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`
  IdScheme used for organisation unit references. Defaults to the `idScheme` parameter.
- The available assigned user modes are explained in the following table.
- Table: Assigned user modes
- Mode
- 描述
  CURRENT

- Includes events assigned to the current logged in user.

##### Filter the result down to a limited set of IDs by using `event=id1,id2`.

Includes events assigned to the user provided in the request.

NONE

Includes unassigned events only.

ANY

Includes all assigned events, regardless of who they are assigned to, as long as they are assigned to someone.

全部

Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using `assignedUser=id1,id2`.This parameter will only be considered if `assignedUserMode` is either `PROVIDED` or `null`. The API will error out, if for example, `assignedUserMode=CURRENT` and `assignedUser=someId`.

查询不区分大小写。以下规则适用于查询
参数。

At least one organisation unit must be specified using the `orgUnit`

parameter (one or many), or `orgUnitMode=ALL` must be specified.

Only one of the `program` and `trackedEntity` parameters can be

指定(零或一)。

If `programStatus` is specified, then `program` must also be specified.

If `enrollmentStatus` is specified, then `program` must also be specified.

| 所需值 | Parameter name |
| --- | --- |
| true | 过滤器项目只能指定一次。 |
| true | 查询与特定组织单位和跟踪项目相关的所有被跟踪实体的方法如下
可以这样查询 |
| true | To query for tracked entities using one attribute with a filter and one attribute without a filter,
with one organisation unit using the descendant organisation unit query mode: |
| true | 为过滤器指定了多个操作数和过滤器的查询
物品: |
| true | A query filter with a value that needs escaping and will be interpreted as `:,/`: |
| true | 要将项目注册日期指定为查询的一部分,请执行以下操作: |
| true | To query on an attribute using multiple values with an *IN* filter and semicolon-separated values: |
| ```
GET /api/tracker/trackedEntities?trackedEntityType=nEenWmSyUEp&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:IN:Scott;Jimmy;Santiago
``` | All of the following operators are supported regardless of the value type. Values are compared using
text comparison unless stated otherwise. Integer and decimal value types are treated as PostgreSQL
integer and numeric data types for the specified operators. |
| Supported binary operators: | Operator |
| 描述 | eq |
| true | ieq |
| true | ge|
| greater than or equal to (uses integer/number semantics for integer/decimal value types) | gt |
| greater than, uses integer/number semantics for integer/decimal value types | le |
| less than or equal to, uses integer/number semantics for integer/decimal value types | lt |
| less than (uses integer/number semantics for integer/decimal value types) | ne |

not equal to (uses integer/number semantics for integer/decimal value types)

neq

not equal to (uses integer/number semantics for integer/decimal value types), use `ne` instead*

nieq

| 所需值 | Parameter name |
| --- | --- |
| false | like |
| false | ilike |

##### like text match, ignoring case (use `like` instead)*

nlike

例如： `filter=H9IlTX2X6SL:sw:A` 运算符以 `sw` 开头，后面跟一个值。

过滤器如 `filter=H9IlTX2X6SL:!null` 会返回给定属性有值的所有条目。

特殊字符（如 `+`）需要按百分比编码，因此应使用 `%2B` 代替 `+`。作为过滤值的一部分，`:` 或 `,` 字符需要用 `/` 转义。同样，`/` 也需要转义。

sw

每个被跟踪实体的属性都可配置为
  - 进行搜索所需的最少字符数（0 表示没有最少字符数）。
  - ends with

*These operators are currently supported but may be removed in the future. We recommend using the operator mentioned in the description, as it provides the same functionality.
ANY
For instance, `filter=w75KJ2mc4zz:eq:Scott` would return values of the given attribute that match any variation of "Scott" regardless of case, such as SCOTT, scott, Scott...

##### Supported unary operators:

Operator

##### 数据存储 { #data-store } 

null

has no value

!null

##### 使用特定项目和组织单位查询所有事件:

Tracked entity attribute filtering { #tracked_entity_attribute_filtering }

Filtering by a tracked entity attribute narrows the response to tracked entities matching given filters. A filter is a colon separated property or attribute UID with optional operator and value pairs.

##### Example: `filter=H9IlTX2X6SL:sw:A` with operator starts with `sw` followed by a value. 

A filter like `filter=H9IlTX2X6SL:!null` returns all entries where the given attribute has a value. 

- Special characters like `+` need to be percent-encoded, so `%2B` instead of `+`. Characters such as `:` or `,`, as part of the filter value, need to be escaped by `/`. Likewise, `/` needs to be escaped. 
Multiple operators for the same attribute like `filter=AuPLng5hLbE:gt:438901703:lt:448901704` are allowed.
Each tracked entity attribute can be configured with:  
A minimum number of characters required to perform a search (0 means no minimum)  

- Blocked operators. Only `sw`, `ew`, and `like` can be blocked. All other operators cannot be blocked.
The following request:

GET /api/tracker/trackedEntities?program=IpHINAT79UW&orgUnits=DiszpKrYNg8&filter=w75KJ2mc4zz:EQ:John

would fail if the minimum character limit was set to 5 (since "John" has only 4 characters), or if the `EQ` operator was blocked for the specified tracked entity attribute.
 Tracked entities response

- The API supports CSV and JSON response for `GET /api/tracker/trackedEntities`.

JSON格式

- Responses can be filtered on desired fields, see [field filter](developer-manual.md#webapi_tracker_field_filter) for more information.

- A JSON response looks like the following:

#### ```json
{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "trackedEntities": [
    {
      "trackedEntity": "F8yKM85NbxW",
      "trackedEntityType": "Zy2SEgA61ys",
      "createdAt": "2019-08-21T13:25:38.022",
      "createdAtClient": "2019-03-19T01:12:16.624",
      "updatedAt": "2019-08-21T13:31:33.410",
      "updatedAtClient": "2019-03-19T01:12:16.624",
      "orgUnit": "DiszpKrYNg8",
      "inactive": false,
      "deleted": false,
      "potentialDuplicate": false,
      "geometry": {
        "type": "Point",
        "coordinates": [
          -11.7896,
          8.2593
        ]
      },
      "attributes": [
        {
          "attribute": "B6TnnFMgmCk",
          "displayName": "Age (years)",
          "createdAt": "2019-08-21T13:25:38.477",
          "updatedAt": "2019-08-21T13:25:38.477",
          "storedBy": "braimbault",
          "valueType": "INTEGER_ZERO_OR_POSITIVE",
          "value": "30"
        },
        {
          "attribute": "TfdH5KvFmMy",
          "displayName": "First Name",
          "createdAt": "2019-08-21T13:25:38.066",
          "updatedAt": "2019-08-21T13:25:38.067",
          "storedBy": "josemp10",
          "valueType": "TEXT",
          "value": "Sarah"
        },
        {
          "attribute": "aW66s2QSosT",
          "displayName": "Last Name",
          "createdAt": "2019-08-21T13:25:38.388",
          "updatedAt": "2019-08-21T13:25:38.388",
          "storedBy": "karoline",
          "valueType": "TEXT",
          "value": "Johnson"
        }
      ]
    }
  ]
}

CSV A CSV response looks like the following: ##### ``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=occurredAt:desc&pageSize=10&page=1

Tracked entities collection limits

| 允许值 | Potential duplicate status | `order` | Parameter name |
| --- | --- | --- | --- |
| storedByDataValue | 具有以下要求: | ```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//
``` | matches exceed this limit. No limit applies when searching within the capture scope |
| `{ "periodFrom": -15, "periodTo": 15}` | 具有以下要求: |```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//
``` | For paginated requests with non-zero `KeyTrackedEntityMaxLimit`: |
| 默认过滤器是`id,displayName` | 具有以下要求: | Tracked entities single object endpoint | ```json
{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "events": [
    {
      "event": "A7rzcnZTe2T",
      "status": "ACTIVE",
      "program": "eBAyeGv0exc",
      "programStage": "Zj7UnCAulEk",
      "enrollment": "RiLEKhWHlxZ",
      "orgUnit": "DwpbWkiqjMy",
      "occurredAt": "2023-02-13T00:00:00.000",
      "scheduledAt": "2023-02-13T00:00:00.000",
      "followUp": false,
      "deleted": false,
      "createdAt": "2017-09-08T21:40:22.000",
      "createdAtClient": "2016-09-08T21:40:22.000",
      "updatedAt": "2017-09-08T21:40:22.000",
      "attributeOptionCombo": "HllvX50cXC0",
      "attributeCategoryOptions": "xYerKDKCefk",
      "geometry": {
        "type": "Point",
        "coordinates": [-11.468912037323042, 7.515913998868316]
      },
      "dataValues": [
        {
          "createdAt": "2016-12-06T18:22:34.438",
          "updatedAt": "2016-12-06T18:22:34.438",
          "storedBy": "bjorn",
          "providedElsewhere": false,
          "dataElement": "F3ogKBuviRA",
          "value": "[-11.4880220438585,7.50978830548003]"
        },
        {
          "createdAt": "2013-12-30T14:23:57.423",
          "updatedAt": "2013-12-30T14:23:57.423",
          "storedBy": "lars",
          "providedElsewhere": false,
          "dataElement": "eMyVanycQSC",
          "value": "2018-02-07"
        },
        {
          "createdAt": "2013-12-30T14:23:57.382",
          "updatedAt": "2013-12-30T14:23:57.382",
          "storedBy": "lars",
          "providedElsewhere": false,
          "dataElement": "oZg33kd9taw",
          "value": "Male"
        }
      ],
      "notes": [],
      "followup": false
    }
  ]
}
``` |

##### Filter the result down to a limited set of IDs by using `event=id1,id2`.

Request syntax

GET /api/tracker/trackedEntities/{uid}?program={programUid}&fields={fields}

##### Request parameter

类型

###### 数据存储 { #data-store } 

Tracked entity attribute value change logs { #webapi_tracker_attribute_change_logs }

``json
{
  "trackedEntity"："PQfMcpmXeFE"、
  "trackedEntityType"："nEenWmSyUEp"、
  "createdAt"："2014-03-06T05:49:28.256",
  "createdAtClient"："2014-03-06T05:49:28.256",
  "updatedAt"："2016-08-03T23:49:43.309",
  "orgUnit"："DiszpKrYNg8"、
  "inactive": false、
  "deleted": false、
  "potentialDuplicate": false、
  "属性"： [[
    {
      "属性"： ["w75KJ2mc4zz"、
      "代码"："MMD_PER_NAM"、
      "displayName"（显示名称）："名字"、
      "创建时间"："2016-08-03T23:49:43.308",
      "updatedAt"："2016-08-03T23:49:43.308",
      "valueType"（值类型）： "TEXT"（文本"TEXT"、
      "值"："约翰"
    },
    {
      "属性"："zDhUuAYrxNC"、
      "显示名"："姓氏"、
      "创建时间"："2016-08-03T23:49:43.309",
      "updatedAt"："2016-08-03T23:49:43.309",
      "valueType"（值类型）： "TEXT"（文本"TEXT"、
      "值"："凯莉"
    }
  ],
  "注册"：[
    {
      "注册"："JMgRZyeLWOo"、
      "创建时间"："2017-03-06T05:49:28.340",
      "创建于客户端"："2016-03-06T05:49:28.340",
      "updatedAt"："2017-03-06T05:49:28.357",
      "trackedEntity"："PQfMcpmXeFE"、
      "程序"： "IpHINAT79U"IpHINAT79UW"、
      "状态"："ACTIVE"、
      "orgUnit"："DiszpKrYNg8"、
      "enrolledAt"："2024-03-06T00:00:00.000",
      "occurredAt"："2024-03-04T00:00:00.000",
      "attributeOptionCombo"："HllvX50cXC0"、
      "followUp": false、
      "deleted": false、
      "事件"： [[
        {
          "event"："Zq2dg6pTNoj"、
          "状态"："ACTIVE"、
          "程序"："IpHINAT79UW"、
          "程序阶段"： "ZzYYXq4fJie"ZzYYXq4fJie"、
          "注册"： "JMgRZyeLWOO"："JMgRZyeLWOo"、
          "跟踪实体"： "PQfMcpmX"PQfMcpmXeFE"、
          "关系"：[],
          "scheduledAt"："2023-03-10T00:00:00.000",
          "followUp": false、
          "deleted": false、
          "createdAt"："2017-03-06T05:49:28.353",
          "createdAtClient"："2016-03-06T05:49:28.353",
          "updatedAt"："2017-03-06T05:49:28.353",
          "attributeOptionCombo"："HllvX50cXC0"、
          "attributeCategoryOptions"："xYerKDKCefk"、
          "dataValues"：[],
          "备注"： [[]
        }
      ],
      "关系"：[],
      "属性"：[
        {
          "属性"： ["w75KJ2mc4zz"、
          "代码"："MMD_PER_NAM"、
          "displayName"（显示名称）："名字"、
          "创建时间"："2016-08-03T23:49:43.308",
          "updatedAt"："2016-08-03T23:49:43.308",
          "valueType"（值类型）： "TEXT"（文本"TEXT"、
          "值"："约翰"
        },
        {
          "属性"："zDhUuAYrxNC"、
          "显示名"："姓氏"、
          "创建时间"："2016-08-03T23:49:43.309",
          "updatedAt"："2016-08-03T23:49:43.309",
          "valueType"（值类型）： "TEXT"（文本"TEXT"、
          "值"："凯莉"
        },
        {
          "属性"："AuPLng5hLbE"、
          "代码"："国家标识符"、
          "displayName"（显示名称）："国家标识符"、
          "createdAt"："2016-08-03T23:49:43.301",
          "updatedAt"："2016-08-03T23:49:43.301",
          "valueType"（值类型）： "TEXT"（文本"TEXT"、
          "值"："245435245"
        },
        {
          "属性"："ruQQnf6rswq"、
          "显示名称"："结核病编号"、
          "创建时间"："2016-08-03T23:49:43.308",
          "updatedAt"（更新时间"2016-08-03T23:49:43.308",
          "valueType"（值类型）： "TEXT"（文本"TEXT"、
          "值"： "1z 1f2 a84"1Z 1F2 A84 59 4464 173 6"
        },
        {
          "属性"："cejWyOfXge6"、
          "显示名称"："性别"、
          "创建时间"："2016-08-03T23:49:43.307",
          "updatedAt"："2016-08-03T23:49:43.307",
          "valueType"（值类型）： "TEXT"（文本"TEXT"、
          "值"："男性"
        },
        {
          "属性"："VqEFza8wbwA"、
          "代码"："mmd_per_adr1"、
          "显示名称"："地址"、
          "创建时间"："2016-08-03T23:49:43.307",
          "updatedAt"（更新时间"2016-08-03T23:49:43.307",
          "valueType"（值类型）："TEXT"（文本"TEXT"、
          "值"："主要街道 2"
        }
      ],
      "备注"：[]
    }
  ],
  "programOwners"：[
    {
      "orgUnit"："DiszpKrYNg8"、
      "trackedEntity"："PQfMcpmXeFE"、
      "程序"："ur1Edk5Oe2n"
    },
    {
      "orgUnit"："DiszpKrYNg8"、
      "trackedEntity"："PQfMcpmXeFE"、
      "程序"："IpHINAT79UW" }
    }
  ]
}

###### 使用特定项目和组织单位查询所有事件: `uid` #### Return the tracked entity with specified `uid` 项目串 | 允许值 | Potential duplicate status | `order` | | --- | --- | --- | | `fields` | 具有以下要求: |Include specified sub-objects in the response | |`{ "periodFrom": -15, "periodTo": 15}`|JSON格式|``` GET /api/tracker/trackedEntities/PQfMcpmXeFE ``` | |iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|JSON格式|JSON格式 | | 数据值 | 具有以下要求: | CSV | ##### The response will be the same as the collection endpoint but referring to a single tracked entity, although it might have multiple rows for each attribute. Tracked entity attribute value change logs { #webapi_tracker_attribute_change_logs } ``json { "pager"：{ "page"：1, "pageSize"：10 }, "changeLogs"：[ { "createdBy"：{ "uid"："AIK2aQOJIbj"、 "username"："tracker"、 "firstName"："Tracker demo"、 "姓"："用户" }, "创建时间"："2024-06-20T14:51:16.433", "类型"： "UPDATE"UPDATE"、 "更改"：{ "attributeValue"：{ "attribute"："w75KJ2mc4zz"、 "previousValue"："John"、 "currentValue"："约翰尼" } } }, { "createdBy"：{ "uid"："AIK2aQOJIbj"、 "username"："tracker"、 "firstName"："Tracker demo"、 "姓"："用户" }, "创建时间"："2024-06-20T14:50:32.966", "类型"："CREATE"、 "更改"：{ "attributeValue"：{ "attribute"："w75KJ2mc4zz"、 "currentValue"："约翰" } } } ] }

This endpoint retrieves change logs for the attributes of a specific tracked entity. It returns a list of all tracked entity attributes that have changed over time for that entity.

Event data value change logs { #webapi_event_data_value_change_logs }

### 类型

Allowed values

path `/{uid}`

- 串
    - Tracked entity `UID`.
- 项目
    - `String`

#### 项目 `UID`(可选)。

根据筛选条件返回注册列表。

|允许值|Potential duplicate status|`order`|Parameter name|
|---|---|---|---|
|createdBy (Username of user)|具有以下要求:|See [Tracked Entities](#tracked-entities) and [Attributes](#attributes) for more field descriptions.|```json
{
  "pager": {
    "page": 1,
    "pageSize": 10
  },
  "changeLogs": [
    {
      "createdBy": {
        "uid": "AIK2aQOJIbj",
        "username": "tracker",
        "firstName": "Tracker demo",
        "surname": "User"
      },
      "createdAt": "2024-06-20T14:51:16.433",
      "type": "UPDATE",
      "change": {
        "dataValue": {
          "dataElement": "bx6fsa0t90x",
          "previousValue": "true",
          "currentValue": "false"
        }
      }
    },
    {
      "createdBy": {
        "uid": "AIK2aQOJIbj",
        "username": "tracker",
        "firstName": "Tracker demo",
        "surname": "User"
      },
      "createdAt": "2024-06-20T14:50:32.966",
      "type": "CREATE",
      "change": {
        "dataValue": {
          "dataElement": "ebaJjqltK5N",
          "currentValue": "0"
        }
      }
    }
  ]
}
```|
|orgUnitMode（见 [orgUnitModes](developer-manual.md#webapi_tracker_orgunit_scope)|具有以下要求:|Narrows response to events matching given filters. A filter is a colon separated property or data element UID with optional operator and value pairs. Example: `filter=fazCI2ygYkq:eq:PASSIVE` with operator starts with `eq` followed by a value. A filter like `filter=fazCI2ygYkq:!null` returns all events where the given data element has a value. Characters such as `:` or `,`, as part of the filter value, need to be escaped by `/`. Likewise, `/` needs to be escaped. Multiple operators for the same data element like `filter=qrur9Dvnyt5:gt:70:lt:80` are allowed. User needs access to the data element to filter on it.|选择组织单位的模式。默认为 "选择"。|
|`{ "periodFrom": -15, "periodTo": 15}`|具有以下要求:|```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//
```|`GET /api/tracker/enrollments/{id}`|
|retrieves an enrollment given the provided ID|具有以下要求:|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json`
or `events.csv` file.|Request parameter|
|用户友好型消息,说明操作是否成功。|具有以下要求:|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json`
or `events.csv` file.|Request parameter|
|Table: Program Stage Query Criteria|项目阶段| 跟踪器或事件项目的标识符。该参数为必填参数。 | orgUnitMode` see [orgUnitModes](developer-manual.md#webapi_tracker_orgunit_scope)|
|串|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | 项目|
|DateTime|[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.| 项目状态 **已过时,将在第 43 版中移除,使用 `status`** |
|串|Events CSV| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|  status|
|串|Events CSV| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.| 跟进|
|storeCopy|具有以下要求:|```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//
```| programStatus **deprecated for removal in version 43 use `enrollmentStatus`**|
|iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:|描述|updatedWithin|
|Duration|具有以下要求:|Only enrollments updated since given duration|enrolledAfter|
|> **注**
>
> 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。 
>
> 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo
>
> 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo|具有以下要求:|```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,//
```|根据给定的属性选项组合筛选注册信息。只返回匹配的注册信息。|
|串|*userDataStore* 由用户、命名空间、键和关联的
值。用户、命名空间和密钥的组合是唯一的。| |IdScheme used for category option references. Defaults to the `idScheme` parameter.|

enrolledBefore

##### Filter the result down to a limited set of IDs by using `event=id1,id2`.

[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)

Only enrollments older than this date

trackedEntity

串

At least one organisation unit must be specified using the `orgUnit`

Identifier of tracked entity

order

串

Comma-separated list of property name or attribute or UID and sort direction pairs in format `propName:sortDirection`.

Supported fields: `completedAt, createdAt, createdAtClient, enrolledAt, updatedAt, updatedAtClient`.

##### enrollments

串

Comma-separated list of enrollment `UID`s.

#### Filter the result down to a limited set of IDs by using `enrollments=id1,id2`.

includeDeleted

Boolean

##### ```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=occurredAt:desc&pageSize=10&page=1

查询不区分大小写。唯一的要求是必须提供项目参数。 | 允许值 | Potential duplicate status | `order` | Parameter name | | --- | --- | --- | --- | | storedByDataValue | 具有以下要求: | ``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ``` | To constrain the response to enrollments of a specific tracked entity you can include a tracked entity query parameter: | | 默认过滤器是`id,displayName` | 具有以下要求: | ``` GET /api/tracker/enrollments?orgUnitMode=ACCESSIBLE&trackedEntity=tphfdyIiVL6 ``` | ```json { "pager": { "page": 1, "pageSize": 1 }, "events": [ { "event": "A7rzcnZTe2T", "status": "ACTIVE", "program": "eBAyeGv0exc", "programStage": "Zj7UnCAulEk", "enrollment": "RiLEKhWHlxZ", "orgUnit": "DwpbWkiqjMy", "occurredAt": "2023-02-13T00:00:00.000", "scheduledAt": "2023-02-13T00:00:00.000", "followUp": false, "deleted": false, "createdAt": "2017-09-08T21:40:22.000", "createdAtClient": "2016-09-08T21:40:22.000", "updatedAt": "2017-09-08T21:40:22.000", "attributeOptionCombo": "HllvX50cXC0", "attributeCategoryOptions": "xYerKDKCefk", "geometry": { "type": "Point", "coordinates": [-11.468912037323042, 7.515913998868316] }, "dataValues": [ { "createdAt": "2016-12-06T18:22:34.438", "updatedAt": "2016-12-06T18:22:34.438", "storedBy": "bjorn", "providedElsewhere": false, "dataElement": "F3ogKBuviRA", "value": "[-11.4880220438585,7.50978830548003]" }, { "createdAt": "2013-12-30T14:23:57.423", "updatedAt": "2013-12-30T14:23:57.423", "storedBy": "lars", "providedElsewhere": false, "dataElement": "eMyVanycQSC", "value": "2018-02-07" }, { "createdAt": "2013-12-30T14:23:57.382", "updatedAt": "2013-12-30T14:23:57.382", "storedBy": "lars", "providedElsewhere": false, "dataElement": "oZg33kd9taw", "value": "Male" } ], "notes": [], "followup": false } ] } ``` | ##### Filter the result down to a limited set of IDs by using `event=id1,id2`.

{
  "pager": {
    "page": 1,
    "pageSize": 1
  },
  "enrollments": [
    {
      "enrollment": "TRE0GT7eh7Q",
      "createdAt": "2019-08-21T13:28:00.056",
      "createdAtClient": "2018-11-13T15:06:49.009",
      "updatedAt": "2019-08-21T13:29:44.942",
      "updatedAtClient": "2019-08-21T13:29:44.942",
      "trackedEntity": "s4NfKOuayqG",
      "program": "M3xtLkYBlKI",
      "status": "COMPLETED",
      "orgUnit": "DiszpKrYNg8",
      "enrolledAt": "2023-11-13T00:00:00.000",
      "occurredAt": "2023-11-13T00:00:00.000",
      "followUp": false,
      "deleted": false,
      "storedBy": "healthworker1",
      "notes": []
    }
  ]
}

Enrollments single object endpoint ##### enrollments The purpose of this endpoint is to retrieve an enrollment given its ID. ### Request syntax

GET /api/tracker/enrollment/{uid}

Request parameter 类型

GET /api/tracker/events/{id}

如果未另行指定，JSON 将是 `GET` 方法的默认响应。API 还还支持单个端点和集合端点的 CSV 导出。此外，它还支持压缩 JSON 和 CSV。 #### uid 串 | 指标组 | Potential duplicate status | | --- | --- | | The message text. | 串 | | 用户友好型消息,说明操作是否成功。 | 具有以下要求: | | `{ "periodFrom": -15, "periodTo": 15}` | Response format | | See an example payload below. | Response format | | 文本 | Response format | | `{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}` | Response format | | To retrieve an event with a specific ID:| Events CSV | | If not otherwise specified, JSON is the default response for the `GET` method. The API also supports CSV export for single and collection endpoints. Furthermore, it supports compressed JSON and CSV for the collection endpoint. | Events CSV | | In the case of CSV, the `fields` request parameter has no effect, and the response will always contain the following fields: | Property | | 类型 | event | | 用户标识 | status | | Table: Program Stage Query Criteria | 项目阶段 | | ID | 项目阶段 | | 类型 | Events CSV | | 身份证 | Events CSV | | String:Uid | Events CSV | | DateTime | Events CSV | | 日期时间 | updatedAtClient | | WKT, can be omitted it in case of a `Point` type and with `latitude` and `longitude` provided | Events CSV | | Latitude of a `Point` type of Geometry | updatedAtClient | | > **注** > > 以下属性可能使用了外部系统的引用,因此被特意排除在合并之外。如果这些字段出现问题,可能需要更新。 > > 指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo > > 项目指标: aggregateExportCategoryOptionCombo & aggregateExportAttributeOptionCombo | Response format | | boolean | Response format | | 布尔 | updatedAtClient | | 最小最大数据元素 | Response format | | 日期时间 | 具有以下要求: | | 日期时间 | updatedAtClient | | 日期时间 | 项目阶段 | | 用户名 | 具有以下要求: | | 创建的数据值 | Events CSV | | 用户名 | Events CSV | ID #### attributeCategoryOptions 响应是文件 `events.json.gz` 或 `events.csv.gz` ，其中包含 `events.json` 或 `events.csv` 文件。或 `events.csv` 文件。 #### assignedUser 响应文件是 `events.json.zip` 或 `events.csv.zip` 文件，其中包含 `events.json` 或 `events.csv` 文件。或 `events.csv` 文件。 #### dataElement ID |允许值|Potential duplicate status|`order`|Parameter name| |---|---|---|---| |`{ "periodFrom": -15, "periodTo": 15}`|具有以下要求:|storedByDataValue| 串| |See an example payload below.|具有以下要求:|storedByDataValue| 日期时间| |See [Events](developer-manual.md#webapi_tracker_objects_events) and [Data Values](developer-manual.md#webapi_tracker_data_values) for more field descriptions.|具有以下要求:|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json` or `events.csv` file.|scheduledBefore| |数据值|具有以下要求:|Returns a list of events based on the provided filters.|Request parameter| |类型|具有以下要求:|描述|项目 | |Table: Program Stage Query Criteria|项目阶段| 跟踪器或事件项目的标识符。该参数为必填参数。 | 项目阶段| |storeCopy|具有以下要求:|storedByDataValue|programStatus **deprecated for removal in version 43 use `enrollmentStatus`**| |`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`|具有以下要求:|storedByDataValue|filter| |串|具有以下要求:|Narrows response to events matching given filters. A filter is a colon separated property or data element UID with optional operator and value pairs. Example: `filter=fazCI2ygYkq:eq:PASSIVE` with operator starts with `eq` followed by a value. A filter like `filter=fazCI2ygYkq:!null` returns all events where the given data element has a value. Characters such as `:` or `,`, as part of the filter value, need to be escaped by `/`. Likewise, `/` needs to be escaped. Multiple operators for the same data element like `filter=qrur9Dvnyt5:gt:70:lt:80` are allowed. User needs access to the data element to filter on it.|filterAttributes| |用户友好型消息,说明操作是否成功。|具有以下要求:|Narrows response to tracked entities matching given filters. Example: `filterAttributes=H9IlTX2X6SL:eq:John`. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering) | 跟进| |boolean|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | trackedEntity| |串|Events CSV| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.| orgUnit| |串|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | orgUnitMode see [orgUnitModes](developer-manual.md#webapi_tracker_orgunit_scope)| |串|Events CSV| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.| status| |串|Events CSV| Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.| occurredAfter| |DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`. | occurredBefore| |DateTime|[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)| Filter for events which occurred up until this date.| scheduledAfter| |DateTime|具有以下要求:|The response is file `events.json.gz` or `events.csv.gzip` containing the `events.json` or `events.csv` file.|scheduledBefore| |DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|updatedAfter| |DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|updatedBefore| |DateTime|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|指定项目的注册开始日期| |Duration|Events CSV|Filter for events which were updated up until this date. Cannot be used together with `updatedWithin`.|指定项目的注册结束日期| |描述|DateTime|Enum|enrollmentEnrolledAfter| |DateTime|DateTime|Enum|enrollmentEnrolledBefore| |programStageIdScheme|DateTime|Enum|[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)| |Can either be `VALIDATE` which will report errors in the payload without making changes to the database or `COMMIT` (default) which will validate the payload and make changes to the database.|DateTime|Enum|方案| |IdScheme used for all metadata references unless overridden by a metadata specific parameter. Default is `UID`.|DateTime|Enum|`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`| |programIdScheme|DateTime|Enum|`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`| |`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`|DateTime|Enum|`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`| |iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:|Enum|`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`| |用于项目阶段引用的 IdScheme。默认为 `idScheme` 参数。|具有以下要求:|`UID`, `CODE`, `NAME`, `ATTRIBUTE:{uid}`|categoryOptionComboIdScheme| |Enum|具有以下要求:|IdScheme used for category option combo references. Defaults to the `idScheme` parameter.| |Enum|具有以下要求:|categoryOptionIdScheme| |串|*userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。| | IdScheme used for category option references. Defaults to the `idScheme` parameter.| |Enum|具有以下要求:| order| 串| |Property|具有以下要求:|events|串| > **注** > > 如果查询既不包含 `attributeCategoryCombo` 也不包含 `attributeCategoryOptions`、 > 服务器将返回用户具有读取权限的所有属性选项组合的事件。 ##### Filter the result down to a limited set of IDs by using `event=id1,id2`. attributeCategoryCombo (see note) 串 Attribute category combo identifier. Must be combined with `attributeCategoryOptions`. attributeCategoryOptions (see note) 串 Comma-separated attribute category option identifiers. Must be combined with `attributeCategoryCombo`. includeDeleted Boolean When true, soft deleted events will be included in your query result. assignedUserMode 串 `CURRENT`, `PROVIDED`, `NONE`, `ANY` Assigned user selection mode assignedUsers 串 Comma-separated list of user UIDs to filter based on events assigned to the users. Filter the result down to a limited set of tracked entities with events that are assigned to the given user IDs by using `assignedUser=id1,id2`.This parameter will only be considered if `assignedUserMode` is either `PROVIDED` or `null`. The API will error out, if for example, `assignedUserMode=CURRENT` and `assignedUser=someId`. > **Note** > > If the query contains neither `attributeCategoryOptions` nor `attributeCategoryOptions`, > the server returns events for all attribute option combos where the user has read access. ##### Example requests The query for all events with children of a particular organisation unit: ###### 数据存储 { #data-store } The query for all events with all descendants of a particular organisation unit, implying all organisation units in the sub-hierarchy:

GET /api/tracker/events?orgUnit=O6uvpzGd5pu&orgUnitMode=DESCENDANTS

###### 使用特定项目和组织单位查询所有事件:

GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc

Query for all events with a certain program and organisation unit, sorting by scheduled date ascending: #### ``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=scheduledAt

查询某一项目和组织单位中发生日期最新的 10 个事件 - 通过分页和按发生日期降序排序的方法
通过分页和按发生日期降序排序:

##### ```
GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=eBAyeGv0exc&order=occurredAt:desc&pageSize=10&page=1

Query for all events with a certain program and organisation unit for a specific tracked entity: |允许值|Potential duplicate status|`order`|Parameter name| |---|---|---|---| |``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ```|JSON格式|``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ```|Events response example| |The API supports CSV and JSON response for `GET /api/tracker/events`.|JSON格式| The JSON response can look like the following: |```json { "pager": { "page": 1, "pageSize": 1 }, "events": [ { "event": "A7rzcnZTe2T", "status": "ACTIVE", "program": "eBAyeGv0exc", "programStage": "Zj7UnCAulEk", "enrollment": "RiLEKhWHlxZ", "orgUnit": "DwpbWkiqjMy", "occurredAt": "2023-02-13T00:00:00.000", "scheduledAt": "2023-02-13T00:00:00.000", "followUp": false, "deleted": false, "createdAt": "2017-09-08T21:40:22.000", "createdAtClient": "2016-09-08T21:40:22.000", "updatedAt": "2017-09-08T21:40:22.000", "attributeOptionCombo": "HllvX50cXC0", "attributeCategoryOptions": "xYerKDKCefk", "geometry": { "type": "Point", "coordinates": [-11.468912037323042, 7.515913998868316] }, "dataValues": [ { "createdAt": "2016-12-06T18:22:34.438", "updatedAt": "2016-12-06T18:22:34.438", "storedBy": "bjorn", "providedElsewhere": false, "dataElement": "F3ogKBuviRA", "value": "[-11.4880220438585,7.50978830548003]" }, { "createdAt": "2013-12-30T14:23:57.423", "updatedAt": "2013-12-30T14:23:57.423", "storedBy": "lars", "providedElsewhere": false, "dataElement": "eMyVanycQSC", "value": "2018-02-07" }, { "createdAt": "2013-12-30T14:23:57.382", "updatedAt": "2013-12-30T14:23:57.382", "storedBy": "lars", "providedElsewhere": false, "dataElement": "oZg33kd9taw", "value": "Male" } ], "notes": [], "followup": false } ] } ```| ##### Filter the result down to a limited set of IDs by using `event=id1,id2`. The CSV response can look like the following:

event,status,program,programStage,enrollment,orgUnit,occurredAt,scheduledAt,geometry,latitude,longitude,followUp,deleted,createdAt,createdAtClient,updatedAt,updatedAtClient,completedBy,completedAt,updatedBy,attributeOptionCombo,attributeCategoryOptions,assignedUser,dataElement,value,storedBy,providedElsewhere,storedByDataValue,updatedAtDataValue,createdAtDataValue
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,F3ogKBuviRA,"[-11.4880220438585,7.50978830548003]",admin,false,,2016-12-06T17:22:34.438Z,2016-12-06T17:22:34.438Z
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,eMyVanycQSC,2018-02-07,admin,false,,2013-12-30T13:23:57.423Z,2013-12-30T13:23:57.423Z
A7rzcnZTe2T,ACTIVE,eBAyeGv0exc,Zj7UnCAulEk,RiLEKhWHlxZ,DwpbWkiqjMy,2023-02-12T23:00:00Z,2023-02-12T23:00:00Z,"POINT (-11.468912037323042 7.515913998868316)",7.515913998868316,-11.468912037323042,false,false,2017-09-08T19:40:22Z,,2017-09-08T19:40:22Z,,,,,HllvX50cXC0,xYerKDKCefk,,msodh3rEMJa,2018-02-13,admin,false,,2013-12-30T13:23:57.467Z,2013-12-30T13:23:57.467Z

##### Events single object endpoint `GET /api/tracker/events/{uid}` API 支持对 `GET /api/tracker/events/{uid}` 的 CSV 和 JSON 响应。 ###### 数据存储 { #data-store } `GET /api/tracker/events/{uid}?fields={fields}` ###### 使用特定项目和组织单位查询所有事件: 类型 #### Allowed values 描述 `uid` |允许值|Potential duplicate status|`order`| |---|---|---| |`fields`|具有以下要求:|Any valid field filter (default `*,!relationships`)| |iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:|A query for an Event: | |数据值|具有以下要求:|应用项目接口支持对 `GET /api/tracker/trackedEntities` 的 CSV 和 JSON 响应| ##### JSON格式

{
  "event": "rgWr86qs0sI",
  "status": "ACTIVE",
  "program": "kla3mAPgvCH",
  "programStage": "aNLq9ZYoy9W",
  "enrollment": "Lo3SHzCnMSm",
  "orgUnit": "DiszpKrYNg8",
  "occurredAt": "2024-10-12T00:00:00.000",
  "followUp": false,
  "deleted": false,
  "createdAt": "2018-10-20T12:09:19.492",
  "createdAtClient": "2017-10-20T12:09:19.492",
  "updatedAt": "2018-10-20T12:09:19.492",
  "attributeOptionCombo": "amw2rQP6r6M",
  "attributeCategoryOptions": "RkbOhHwiOgW",
  "dataValues": [
    {
      "createdAt": "2015-10-20T12:09:19.640",
      "updatedAt": "2015-10-20T12:09:19.640",
      "storedBy": "system",
      "providedElsewhere": false,
      "dataElement": "HyJL2Lt37jN",
      "value": "12"
    }
  ],
  "notes": [],
  "followup": false
}

CSV The response will be the same as the collection endpoint but referring to a single event, although it might have multiple rows for each data element value. Event data value change logs { #webapi_event_data_value_change_logs } ### `GET /api/tracker/events/{uid}/changeLogs` This endpoint retrieves change logs for the data values of a specific event. It returns a list of all event data values and event fields (`occurredAt`, `scheduledAt`, and `geometry`) that have changed over time for the specified event. Parameter 类型 Allowed values path `/{uid}` #### 串 |允许值|Potential duplicate status|`order`|Parameter name| |---|---|---|---| |storeCopy|具有以下要求:|``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ```|Event data value change logs response example| |文本|具有以下要求:|``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ```|More on change log configuration [here](../../sysadmin/reference/logging.md#changelog)| |The message text.|具有以下要求:|``` GET /api/tracker/events?orgUnit=DiszpKrYNg8&program=lxAQ7Zs9VYR&filter=DanTR5x0WDK:EQ:/:/,// ```|The purpose of this endpoint is to retrieve relationships between objects.| |默认过滤器是`id,displayName`|具有以下要求:|Request parameters |```json { "pager": { "page": 1, "pageSize": 1 }, "events": [ { "event": "A7rzcnZTe2T", "status": "ACTIVE", "program": "eBAyeGv0exc", "programStage": "Zj7UnCAulEk", "enrollment": "RiLEKhWHlxZ", "orgUnit": "DwpbWkiqjMy", "occurredAt": "2023-02-13T00:00:00.000", "scheduledAt": "2023-02-13T00:00:00.000", "followUp": false, "deleted": false, "createdAt": "2017-09-08T21:40:22.000", "createdAtClient": "2016-09-08T21:40:22.000", "updatedAt": "2017-09-08T21:40:22.000", "attributeOptionCombo": "HllvX50cXC0", "attributeCategoryOptions": "xYerKDKCefk", "geometry": { "type": "Point", "coordinates": [-11.468912037323042, 7.515913998868316] }, "dataValues": [ { "createdAt": "2016-12-06T18:22:34.438", "updatedAt": "2016-12-06T18:22:34.438", "storedBy": "bjorn", "providedElsewhere": false, "dataElement": "F3ogKBuviRA", "value": "[-11.4880220438585,7.50978830548003]" }, { "createdAt": "2013-12-30T14:23:57.423", "updatedAt": "2013-12-30T14:23:57.423", "storedBy": "lars", "providedElsewhere": false, "dataElement": "eMyVanycQSC", "value": "2018-02-07" }, { "createdAt": "2013-12-30T14:23:57.382", "updatedAt": "2013-12-30T14:23:57.382", "storedBy": "lars", "providedElsewhere": false, "dataElement": "oZg33kd9taw", "value": "Male" } ], "notes": [], "followup": false } ] } ```| |iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|具有以下要求:|描述|trackedEntity| |串|*userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。|跟踪器或事件项目的标识符。该参数为必填参数。| enrollment| 串 `uid` Identifier of an enrollment #### event 串 ## `uid` Identifier of an event ### fields 串 Any valid field filter (default `relationship,relationshipType,createdAtClient,from[trackedEntity[trackedEntity],enrollment[enrollment],event[event]],to[trackedEntity[trackedEntity],enrollment[enrollment],event[event]]`) Tracker 数据的一个关键点是需要采用整体方法。例如，用户只拥有数据元素的读取权限是无法查看数据元素值的。用户需要有数据读取权限，才能访问该数据元素所属的父计划阶段和计划。所属的父计划阶段和计划。这与类别选项组合的工作方式相同。在跟踪系统中，事件和注册与属性选项组合（AttributeOptionCombo）相关联，属性选项组合由多个类别选项组成。选项。要读取事件或注册信息，用户必须拥有对所有类别选项及其相应类别的数据读取权限。及其相应类别的数据读取权限。如果用户缺少对所需类别选项或类别之一的访问权限，则无法访问整个事件或注册信息。访问整个事件或注册。 order 串 Comma-separated list of property name or attribute or UID and sort direction pairs in format `propName:sortDirection`. ### Supported fields: `createdAt, createdAtClient`. includeDeleted Boolean `true`, `false` whether to include soft-deleted elements in your query result The following rules apply to the query parameters. | Only one parameter among `trackedEntity`, `enrollment`, `event` can be passed. | Parameter name | | --- | --- | | Example response | ```json { "pager": { "page": 1, "pageSize": 2 }, "relationships": [ { "relationship": "oGtgtJpp6fG", "relationshipType": "Mv8R4MPcNcX", "from": { "trackedEntity": { "trackedEntity": "neR4cmMY22o" } }, "to": { "trackedEntity": { "trackedEntity": "DsSlC54GNXy" } } }, { "relationship": "SSfIicJKbh5", "relationshipType": "Mv8R4MPcNcX", "from": { "trackedEntity": { "trackedEntity": "neR4cmMY22o" } }, "to": { "trackedEntity": { "trackedEntity": "rEYUGH97Ssd" } } } ] } ``` | | Tracker access control { #webapi_tracker_access_control } | Tracker has a few different concepts in regards to access control, like sharing, organisation unit scopes, ownership, and access levels. The following sections provide a short introduction to the different topics. | | Metadata sharing { #webapi_tracker_metadata_sharing } | Sharing setting is standard DHIS2 functionality that applies to both Tracker and Aggregate metadata/data as well as dashboards and visualization items. At the core of sharing is the ability to define who can see/do what. In general, there are five possible sharing configurations – no access, metadata read, metadata write, data read, and data write. These access configurations can be granted at user and/or user group level (for more flexibility). With a focus on Tracker, the following metadata and their sharing setting is of particular importance: Data Element, Category Option, Program, Program Stage, Tracked Entity Type, Tracked Entity Attribute as well as Tracker related Dashboards and Dashboard Items. | | Sharing settings are enforced during Tracker data import/export. Data read/write access is needed to read and write respectively. Similarly, if a user is expected to modify metadata, it is essential to grant metadata write access. | One critical point with Tracker data is the need to have a holistic approach. For example, a user won’t be able to see the Data Element value by having read access to just the Data Element. The user needs to have data read to access the parent Program Stage and Program where this Data Element belongs. It is the same with the category option combination. In Tracker, the Event is related to AttributeOptionCombo, which is made up of a combination of Category Options. Therefore, for a user to read data of an Event, he/she needs to have data read access to all Category Options and corresponding Categories that constitute the AttributeOptionCombo of the Event in question. If a user lacks access to just one Category Option or Category, then the user has no access to the entire Event. | | 在访问注册数据时,必须首先访问被跟踪实体。首先。通过共享设置项目、跟踪实体类型和跟踪实体属性,可以控制对跟踪实体的访问。类型和跟踪实体属性的共享设置来控制对跟踪实体的访问。一旦访问了注册,就有可能访问事件数据,这同样取决于项目阶段和数据元素共享设置。 | 另一个需要考虑的关键点是如何规划对不同项目阶段的访问。有时,我们可能需要向特定用户组(实验室技术人员)授予访问特定阶段的权限,如例如 "实验室结果")的访问权限。在这种情况下,我们可以为 "实验室结果 "阶段提供数据写入访问权限,可能为一个或多个阶段提供数据读取访问权限,以防我们希望实验室技术人员读取数据。如果我们希望实验室技术人员读取其他医疗结果,则可以提供数据写入访问权限;如果我们认为实验室技术人员没有必要查看数据,则可以不提供访问权限。如果我们认为实验室技术人员没有必要查看实验室相关数据以外的数据,则不提供访问权限。 | | In summary, DHIS2 has a fine-grained sharing setting that we can use to implement access control mechanisms both at the data and metadata level. These sharing settings can be applied directly at the user level or user group level. How exactly to apply a sharing setting depends on the use-case at hand. | Organisation unit scopes { #webapi_tracker_orgunit_scope } | Organisation units are one of the most fundamental objects in DHIS2. They define a universe under which a user is allowed to record and/or read data. There are three types of organisation units that can be assigned to a user. These are data capture, data view (not used in tracker), and tracker search. As the name implies, these organisation units define a scope under which a user is allowed to conduct the respective operations. A user can search for data in their search scope and capture scope organisation units. However, to further fine-tune the scope, DHIS2 Tracker introduces a concept that we call **OrganisationUnitSelectionMode**. Such a mode is often used at the time exporting tracker objects. For example, given that a user has a particular tracker search scope, does it mean that we have to use this scope every time a user tries to search for a tracker, Enrollment, or Event object? Or is the user interested in limiting the searching just to the selected org unit, or the entire capture org unit scope, and so on. Users can do the fine-tuning by passing a specific value of `orgUnitMode` in their API request:

/api/tracker/trackedEntities?orgUnit=UID&orgUnitMode=specific_organisation_unit_selection_mode

Currently, there are six selection modes available: *SELECTED, CHILDREN, DESCENDANTS, CAPTURE, ACCESSIBLE, and ALL*. Mode ### 描述 DHIS2 2.30 引入的 "跟踪所有权 "定义了一个组织单位关联，用于程序组合的组织单位关联。我们称其为计划背景下被跟踪实体的所有者（或拥有者）组织单位。我们称其为程序上下文中 TrackedEntity 的所有者（或拥有者）组织单元。所有者组织单元用于决定读写与程序相关的跟踪数据时的访问权限。这一点访问级别](#webapi_tracker_access_level) 配置一起，决定与程序相关数据（注册）的访问行为。行为。如果相应的所有者组织--用户--可以访问一个 TrackedEntity 的如果该 TrackedEntity-Program 组合对应的所有者组织单位（OrganisationUnit 在用户的组织单位范围内（搜索/捕获）。对于配置为的程序，其所有者组织单位必须在用户的搜索范围内。范围。对于访问级别为*PROTECTED*或*CLOSED*的程序，所有者组织单位必须在用户搜索范围内。组织单位必须在用户的捕获范围内，才能访问特定被跟踪实体的相应程序数据。的程序数据。无论程序访问级别如何，要访问无论程序访问级别如何，要访问跟踪器对象，所请求的组织单位必须始终在用户的搜索范围或捕获范围内。范围或捕获范围内。用户不能请求这两个范围之外的对象，除非他们使用组织单位模式 ALL 并拥有使用该模式的足够权限。 Specified organisation units. * CHILDREN Specified organisation unit including immediate children, i.e. organisation units at the immediate level below. * DESCENDANTS Specified organisation unit and all organisation units in the sub-hierarchy, i.e. at all organisation unit levels in the sub-hierarchy below the specified organisation units. #### CAPTURE The data capture organisation units associated with the current user and all organisation units in the sub-hierarchy. ACCESSIBLE 跟踪器会搜索与当前用户相关联的组织单位以及子层次结构中的所有组织单位。这包括用户可见的所有内容,包括搜索范围内的打开和已审核项目,以及用户捕获范围内受保护和已关闭项目中的数据。如果用户缺少搜索组织单元,系统会默认为捕获范围,确保用户始终可以访问至少一个范围。捕获范围是强制性的,是保证用户数据环境的基本要素。全部 All organisation units in the system. This mode is reserved for authorized users, specifically those with the authority ALL (super users). Users with the authority `F_TRACKED_ENTITY_INSTANCE_SEARCH_IN_ALL_ORGUNITS` can also search system-wide but need sharing access to the returned program, program stage, and/or tracked entity type. Non-authorized users are not permitted to search using this scope. #### The first three modes, *SELECTED*, *CHILDREN* and *DESCENDANTS*, expect an organisation unit to be supplied in the request, while the last three, *CAPTURE*, *ACCESSIBLE* and *ALL* do not. The organisation unit mode will be one of the ones listed above when it is explicitly provided in the API request. Since it is not a mandatory paramter, when not specified, the default value will be *SELECTED* if an organisation unit is present, and *ACCESSIBLE* if not. It makes little sense to pass these modes at the time of tracker import operations. Because when writing tracker data, each of the objects needs to have a specific organisation unit attached to them. The system will then ensure if each of the mentioned organisation units falls under the CAPTURE scope. If not, the system will simply reject the write operation. ### 请注意,与跟踪器对象相关的组织单位关联有四种类型。A 被跟踪实体有一个组织单位,通常称为注册组织单位。注册有一个与之相关的组织单位。事件也有一个关联。跟踪项目组合也有一个所有者组织单元。组合。 When fetching Tracker objects, depending on the context, the organisation unit scope is applied to one of the above four organisation unit associations. 例如,在没有项目上下文的情况下检索 "跟踪实体 "时,组织单位范围适用于被跟踪实体的注册组织单位。而当组织单位范围适用于所有者组织单位。组织单位范围适用于所有者组织单位。 #### Tracker Program Ownership { #webapi_tracker_ownership } A new concept called Tracker Ownership is introduced from 2.30. This introduces a new organisation unit association for a TrackedEntity - Program combination. We call this the Owner (or Owning) Organisation unit of a TrackedEntity in the context of a Program. The Owner organisation unit is used to decide access privileges when reading and writing tracker data related to a program. This, along with the Program's [Access Level](#webapi_tracker_access_level) configuration, decides the access behavior for Program-related data (Enrollments and Events). A user can access a TrackedEntity's Program data if the corresponding Owner OrganisationUnit for that TrackedEntity-Program combination falls under the user's organisation unit scope (Search/Capture). For Programs that are configured with access level *OPEN* or *AUDITED* , the Owner OrganisationUnit has to be in the user's search scope. For Programs that are configured with access level *PROTECTED* or *CLOSED* , the Owner OrganisationUnit has to be in the user's capture scope to be able to access the corresponding program data for the specific tracked entity. Irrespective of the program access level, to access Tracker objects, the requested organisation unit must always be within either the user's search scope or capture scope. A user cannot request objects outside these two scopes unless they are using the organisation unit mode ALL and have sufficient privileges to use that mode. #### 请求跟踪实体而不指定项目时,响应将只包括符合[元数据共享设置](developer-manual.md#webapi_tracker_metadata_sharing)和以下标准之一的被跟踪实体以下标准之一: 被跟踪的实体已加入用户可访问数据的至少一个项目,且用户 #### has access to the owner organisation unit. 被跟踪的实体没有加入用户有数据访问权的任何项目,但用户有 #### access to the tracked entity registering organisation unit. Tracker Ownership Override: Break the Glass { #webapi_tracker_ownership_override } ## It is possible to temporarily override the ownership privilege for a program that is configured with an access level of *PROTECTED*. Any user with the org unit owner within their search scope, can temporarily access the program-related data by providing a reason for accessing it. This act of temporarily gaining access is termed *breaking the glass*. Currently, temporary access is granted for 3 hours. DHIS2 audit breaking the glass along with the reason specified by the user. This information is also stored in the database, but only if the tracked entity type is configured to allow auditing, which is disabled by default. 无法临时访问已配置为*CLOSED*访问级别的项目。项目的临时访问权限。 To break the glass for a TrackedEntity-Program combination, the following POST request can be used: ### ``` /api/tracker/ownership/override?trackedEntity=DiszpKrYNg8&program=eBAyeGv0exc&reason=patient+showed+up+for+emergency+care

Tracker Ownership Transfer { #webapi_tracker_ownership_transfer }

It is possible to transfer the ownership of a TrackedEntity-Program from one organisation unit to
another. This will be useful in case of patient referrals or migrations. Only a user who has
Ownership access (or temporary access by breaking the glass) can transfer the ownership. To transfer
ownership of a TrackedEntity-Program to another organisation unit, the following PUT request can be
used:

#### A list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.

"assignedUsers":["DXyJmlo9rge"]

| 指标组 | Parameter name | 描述 |
| --- | --- | --- |
| displayColumnOrder | periodFrom | |
| dataFilters | Protected | |
| 这种访问级别的限制稍多一些。受保护项目中的数据只有在所有者组织单位属于用户捕获范围的情况下才能被用户访问。
只有当所有者组织单位属于用户的捕获范围时,用户才能访问受保护项目内的数据。但是,如果用户
用户可以通过 [打破玻璃](#webaptrl) 获得临时所有权。
玻璃](#webapi_tracker_ownership_override)获得临时所有权。用户必须说明为什么要访问手头的数据。
他们为什么要访问手头的数据。然后,系统会将理由和访问审核记录在案,并提供 3 个月的临时访问权限。
访问审计日志,并为用户提供 3 小时的临时访问权限。请注意,打破玻璃时
时,所有者组织单位保持不变,只有打碎玻璃的用户才能获得临时访问权。
获得临时访问权。 | Closed | |
| 这是最受限制的访问级别。在访问级别为
如果所有者组织单位不在用户的捕获范围内,则无法访问 "关闭 "项目下记录的数据。
范围。在这种配置下,也无法打破玻璃或获得临时所有权。
请注意,仍有可能将所有权转移到另一个组织单位。只有
才能将 TrackedEntity-Program 组合的所有权转移给另一个组织单位。
另一个组织单位。如果所有权被转移,所有者组织单位将被更新。
跟踪实体 | Working lists | 工作列表允许用户保存筛选器和排序偏好,从而有效地组织工作流程。
首选项。每种类型的工作列表
实体、注册和事件都有专门的应用项目接口进行管理。 |
| `{ "periodFrom": -15, "periodTo": 15}` | Query request parameters | Tracked entity working lists |
| Create, update and delete tracked entity working lists using |     /api/trackedEntityInstanceFilters | Payload |
| Table: Payload | Property | 描述 |

例

| 指标组 | Parameter name | 描述 |
| --- |---|---|
|A description of the working list.|sortOrder|The sort order of the working list.|
|DateTime|Object containing css style.||
|Table: Program Stage Query Criteria|项目||
|是否在 DHIS2 中存储一份项目信息副本。|`{ "id" : "uy2gU8kTjF"}`|entityQueryCriteria|
|`{"type":"RELATIVE","period":"TODAY"}`|See *Entity Query Criteria* definition table below.|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event scheduled date.|
|Enum|`[{"programStage": "eaDH9089uMp", "eventStatus": "OVERDUE", "eventCreatedPeriod": {"periodFrom": -15, "periodTo": 15}}]`|Table: Entity query criteria definition|
|Property|Object containing parameters for querying, sorting and filtering events.|例|
|`"enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"}`|Property|`"attributeValueFilters"=[{"attribute": "abcAttributeUid","le": "20","ge": "10","lt": "20","gt": "10","in": ["India", "Norway"],"like": "abc","sw": "abc","ew": "abc","dateFilter": {"startDate": "2014-05-01","endDate": "2019-03-20","startBuffer": -5,"endBuffer": 5,"period": "LAST_WEEK","type": "RELATIVE"}}]`|
|iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|The tracked entities enrollment status. Can be none(any enrollmentstatus) or ACTIVE, COMPLETED, CANCELLED|跟进|
|See an example payload below.|organisationUnit|To specify the uid of the organisation unit|
|`{"organisationUnit": "a3kGcGDCuk7"}`|ouMode|To specify the organisation unit selection mode. Options are `SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`|
|Absolute end date. Applicable only when `type` is ABSOLUTE|assignedUserMode|To specify the assigned user selection mode for events. Options are CURRENT,  PROVIDED,  NONE ,  ANY. See table below to understand what each value indicates. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be considered.|
|"assignedUserMode": "PROVIDED"|assignedUsers|To specify a list of assigned users for events. To be used along with PROVIDED assignedUserMode above.|
|`"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]`|displayColumnOrder|To specify the output ordering of columns|
|`"displayOrderColumns": ["enrollmentDate", "program"]`|例|名称|
|"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]|项目阶段|To specify a programStage uid to filter on. tracked entities will be filtered based on presence of enrollment in the specified program stage.|
|"order"="a3kGcGDCuk6:desc,eventDate:asc"|trackedEntityType|To specify a trackedEntityType filter tracked entities on.|

`{"trackedEntityType"="a3kGcGDCuk6"}`

| 指标组 | Parameter name | 描述 |
|---|---|---|
|See an example payload below.|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on enrollment created date.|`"enrollmentCreatedDate": {     "period": "LAST_WEEK",     "type": "RELATIVE"   }`|
|`"displayOrderColumns": ["enrollmentDate", "program"]`|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on enrollment incident date.|`"enrollmentIncidentDate": {     "startDate": "2014-05-01",     "endDate": "2019-03-20",     "startBuffer": -5,     "endBuffer": 5,     "period": "LAST_WEEK",     "type": "RELATIVE"   }`|
|eventStatus|The event status. Options are `ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED` and `VISITED`|`"status":"VISITED"`|
|Enum|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on event date.|`"eventDate": {"startBuffer": -5,"endBuffer": 5,     "type": "RELATIVE"   }`|
|Property|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on last updated date.|例|

Table: Event filters definition

| 指标组 | Parameter name | 描述 |
|---|---|---|
|项目阶段|被跟踪实体需要返回哪个项目阶段的事件。|-15|
|`"eaDH9089uMp"`|eventStatus|15|

#### The events status. Can be none(any event status) or ACTIVE, COMPLETED, SCHEDULE, OVERDUE

`ACTIVE`

| eventCreatedPeriod | Parameter name |
|---|---|
|`{ "periodFrom": -15, "periodTo": 15}`|assignedUserMode|

### To specify the assigned user selection mode for events. Options are `CURRENT` (events assigned to current user), `PROVIDED` (events assigned to users provided in "assignedUsers" list), `NONE` (events assigned to no one) ,  ANY (events assigned to anyone). If PROVIDED (or null), non-empty assignedUsers in the payload will be considered.

`"assignedUserMode": "PROVIDED"`

assignedUsers

#### A list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.

"assignedUsers":["DXyJmlo9rge"]

| Table: Period filter definition | Parameter name | 描述 |
| --- | --- | --- |
| displayColumnOrder | periodFrom | |
| dataFilters | Protected | |
| `{ "periodFrom": -15, "periodTo": 15}` | Query request parameters| Table: Tracked entity instance filters query parameters |
| See an example payload below. | 描述 | 项目 |
| 项目标识符。将筛选器限制在给定的项目中。 |     /api/trackedEntityInstanceFilters | Create, update and delete program stage working lists using |

/api/programStageWorkingLists

| Payload | Parameter name | 描述 |
|---|---|---|
|`"displayOrderColumns": ["enrollmentDate", "program"]`|例|名称|
|Name of the working list. Required.|描述|A description of the working list.|
|项目|eventCreatedAt|`{"id" : "uy2gU8kTjF"}`|
|项目阶段|包含项目阶段 ID 的对象。必须填写。|`{"id" : "uy2gU8kTjF"}`|
|DateTime|An object representing various possible filtering values.|See *Program Stage Query Criteria* definition table below.|
|Table: Program Stage Query Criteria|Criteria values|描述|
|例|eventStatus|The event status. Options are `ACTIVE`, `COMPLETED`, `VISITED`, `SCHEDULE`, `OVERDUE`, `SKIPPED` and `VISITED`|
|`"status":"VISITED"`|eventCreatedAt|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event creation date.|
|`{"type":"ABSOLUTE","startDate":"2020-03-01","endDate":"2022-12-30"}`|eventOccurredAt|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event occurred date.|
|`{"type":"RELATIVE","period":"TODAY"}`|eventScheduledAt|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event scheduled date.|
|Enum|enrollmentStatus|Any valid EnrollmentStatus. Options are `ACTIVE`, `COMPLETED` and `CANCELLED`.|
|Property|跟进|Indicates whether to filter enrollments marked for follow up or not|
|iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|enrolledAt|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event enrollment date.|
|`"enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"}`|enrollmentOccurredAt|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object filtering based on the event occurred date.|
|`{"type":"RELATIVE","period":"THIS_MONTH"}`|orgUnit|A valid organisation unit UID|
|A description of the working list.|ouMode|A valid OU selection mode|

`"ouMode": "SELECTED"`

assignedUserMode

### A valid user selection mode for events. Options are `CURRENT`, `PROVIDED`, `NONE`, `ANY` and `ALL`. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be expected.

"assignedUserMode":"PROVIDED"

assignedUsers

#### A list of assigned users for events. To be used along with `PROVIDED` assignedUserMode above.

"assignedUsers":["DXyJmlo9rge"]

| 指标组 | Parameter name | 描述 |
|---|---|---|
|displayColumnOrder|Output ordering of columns|"displayColumnOrder":["w75KJ2mc4zz","zDhUuAYrxNC"]|
|dataFilters|Protected|"dataFilters":[{"dataItem": "GXNUsigphqK","ge": "10","le": "20"}]|
|`{ "periodFrom": -15, "periodTo": 15}`|A list of attribute value filters. This is used to specify filters for attribute values when listing tracked entities|"attributeValueFilters":[{"attribute": "ruQQnf6rswq","eq": "15"}]|
|See an example payload below.|```json
{
  "name": "Test WL",
  "description": "Test WL definition",
  "program": {
    "id": "uy2gU8kT1jF"
  },
  "programStage": {
    "id": "oRySG82BKE6"
  },
  "programStageQueryCriteria": {
    "eventStatus": "VISITED",
    "eventCreatedAt": {
      "type": "ABSOLUTE",
      "startDate": "2020-03-01",
      "endDate": "2022-12-30"
    },
    "eventScheduledAt": {
      "type": "RELATIVE",
      "period": "TODAY"
    },
    "enrollmentStatus": "COMPLETED",
    "followUp": true,
    "enrolledAt": {
      "type": "RELATIVE",
      "period": "THIS_MONTH"
    },
    "enrollmentOccurredAt": {
      "type": "RELATIVE",
      "period": "THIS_MONTH"
    },
    "orgUnit": "Rp268JB6Ne4",
    "ouMode": "SELECTED",
    "assignedUserMode": "PROVIDED",
    "assignedUsers": [
      "DXyJmlo9rge"
    ],
    "order": "w75KJ2mc4zz:asc",
    "displayColumnOrder": [
      "w75KJ2mc4zz",
      "zDhUuAYrxNC"
    ],
    "dataFilters": [
      {
        "dataItem": "GXNUsigphqK",
        "ge": "10",
        "le": "20"
      }
    ],
    "attributeValueFilters": [
      {
        "attribute": "ruQQnf6rswq",
        "eq": "15"
      }
    ]
  }
}
```|Event working lists|
|Create, update and delete event working lists using the following endpoint.|```
/api/eventFilters
```|Payload|

Table: Payload

| 指标组 | Parameter name | 描述 |
|---|---|---|
|Table: Program Stage Query Criteria|Name of the working list.|"name":"My working list"|
|是否在 DHIS2 中存储一份项目信息副本。|`{ "id" : "uy2gU8kTjF"}`|"description":"for listing all events assigned to me".|
|`{"type":"RELATIVE","period":"TODAY"}`|项目的 uid。|"项目":"a3kGcGDCuk6"|
|Enum|项目阶段的 uid。|"项目阶段": "a3kGcGDCuk6"|
|Property|Object containing parameters for querying, sorting and filtering events.|"eventQueryCriteria": {     "organisationUnit":"a3kGcGDCuk6",     "status": "COMPLETED",     "createdDate": {       "from": "2014-05-01",       "to": "2019-03-20"     },     "dataElements": ["a3kGcGDCuk6:EQ:1", "a3kGcGDCuk6"],     "filters": ["a3kGcGDCuk6:EQ:1"],     "programStatus": "ACTIVE",     "ouMode": "SELECTED",     "assignedUserMode": "PROVIDED",     "assignedUsers" : ["a3kGcGDCuk7", "a3kGcGDCuk8"],     "followUp": false,     "events": ["a3kGcGDCuk7", "a3kGcGDCuk8"],     "fields": "eventDate,dueDate",     "order": "dueDate:asc,createdDate:desc"   }|
|`"enrolledAt": {"type":"RELATIVE","period":"THIS_MONTH"}` |Property|描述|
|iasc 和 idesc 是不区分大小写的排序。如果需要对多个属性进行排序,请使用逗号将它们分开。|跟进|Used to filter events based on enrollment followUp flag. Options are `true`, `false`.|
|`{"type":"RELATIVE","period":"THIS_MONTH"}`|organisationUnit|To specify the uid of the organisation unit|
|用户友好型消息,说明操作是否成功。|ouMode|To specify the OU selection mode. Options are `SELECTED`, `CHILDREN`, `DESCENDANTS`, `ACCESSIBLE`, `CAPTURE`, `ALL`|
|用于项目阶段引用的 IdScheme。默认为 `idScheme` 参数。|assignedUserMode|To specify the assigned user selection mode for events. Options are `CURRENT`, `PROVIDED`, `NONE`, `ANY`. See table below to understand what each value indicates. If `PROVIDED` (or null), non-empty assignedUsers in the payload will be considered.|
|"assignedUserMode": `PROVIDED`|assignedUsers|To specify a list of assigned users for events. To be used along with PROVIDED assignedUserMode above.|
|"assignedUsers": ["a3kGcGDCuk7", "a3kGcGDCuk8"]|项目阶段|To specify the output ordering of columns|
|"displayOrderColumns": ["eventDate", "dueDate", "program"]|order|To specify ordering/sorting of fields and its directions in comma separated values. A single item in order is of the form "dataItem:direction".|
|"order"="a3kGcGDCuk6:desc,eventDate:asc"|trackedEntityType|To specify filters to be applied when listing events|

`"ouMode": "SELECTED"`

status

### Any valid EventStatus

"eventStatus": "COMPLETED"

| 指标组 | Parameter name | 描述 |
|---|---|---|
|枚举(参见元数据和渲染类型表中的列表)|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on completed date.|"completedDate": {     "startDate": "2014-05-01",     "endDate": "2019-03-20",     "startBuffer": -5,     "endBuffer": 5,     "period": "LAST_WEEK",     "type": "RELATIVE"   }|
|eventDate|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on event date.|"eventDate": {     "startBuffer": -5,     "endBuffer": 5,     "type": "RELATIVE"   }|
|dueDate|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on due date.|"dueDate": {     "period": "LAST_WEEK",     "type": "RELATIVE"   }|
|lastUpdatedDate|[DateFilterPeriod](developer-manual.md#webapi_tracker_workinglists_common_objects) object date filtering based on last updated date.|"dueDate": {     "period": "LAST_WEEK",     "type": "RELATIVE"   }|
|See an example payload below.|```json
{
  "name": "event working list",
  "program": "VBqh0ynB2wv",
  "eventQueryCriteria": {
    "eventDate": {
      "period": "LAST_WEEK",
      "type": "RELATIVE"
    },
    "dataFilters": [
      {
        "ge": "35",
        "le": "70",
        "dataItem": "qrur9Dvnyt5"
      }
    ],
    "assignedUserMode": "PROVIDED",
    "assignedUsers": [
      "CotVI2NX0rI",
      "xE7jOejl9FI"
    ],
    "status": "ACTIVE",
    "order": "occurredAt:desc",
    "displayColumnOrder": [
      "occurredAt",
      "status",
      "assignedUser",
      "qrur9Dvnyt5",
      "oZg33kd9taw"
    ]
  }
}
```|Common objects { #webapi_tracker_workinglists_common_objects }|
|Table: DateFilterPeriod object definition|Property|描述|


## 例

type

Specify whether the date period type is `ABSOLUTE`, `RELATIVE`

`"type" : "RELATIVE"`

潜在重复的响应有效载荷如下所示。

Specify if a relative system defined period is to be used. Applicable only when `type` is RELATIVE. (see [Relative Periods](developer-manual.md#webapi_date_relative_period_values) for supported relative periods)

`"period" : "THIS_WEEK"`

| 允许值 | Parameter name | Potential duplicate status | `order` |
|---|---|---|---|
| Absolute end date. Applicable only when `type` is ABSOLUTE | `"startDate":"2014-05-01"` | startBuffer| Relative custom start date. Applicable only when `type` is RELATIVE |
| 用户友好型消息,说明操作是否成功。 | To inspect individual potential duplicate records, use the following endpoint: | 不区分大小写的字符串结尾匹配 | `"startDate":+10` |

Potential duplicates

Potential duplicates are records identified by the data deduplication feature as possibly being
duplicates. Due to the nature of this feature, the API endpoint has certain restrictions. A
potential duplicate represents a pair of records suspected to be duplicates.

To retrieve a list of potential duplicates, use the following endpoint:

GET /api/potentialDuplicates

The response payload for a potential duplicate looks like this.s

```json
{
  "created": "2024-06-04T10:11:29.110",
  "lastUpdated": "2024-06-04T10:11:29.110",
  "original": "<UID>",
  "duplicate": "<UID>",
  "status": "OPEN|INVALID|MERGED",
  "id": "<id>"
}

| ``` POST /api/potentialDuplicates ``` | Parameter name | --- | --- | | 400 | 描述 | 403 | 类型 | 404 | Allowed values | 409 | trackedEntities List of tracked entities List of string (separated by comma) | 允许值 | Parameter name | Potential duplicate status | `order` | | --- | --- | --- | --- | | 用户友好型消息,说明操作是否成功。 | To inspect individual potential duplicate records, use the following endpoint: | 不区分大小写的字符串结尾匹配 | To create a new potential duplicate, use this endpoint: | | ``` POST /api/potentialDuplicates ``` | Parameter name | --- | --- | | 400 | ```json { "original": "", "duplicate": "" }

| 400 | Status code

### 描述

Input original or duplicate is null or has invalid uid

User do not have access to read original or duplicate TEs

TE not found

| 允许值 | Parameter name | Potential duplicate status | `order` |
| --- | --- | --- | --- |
| 描述 | 类型 | 不区分大小写的字符串结尾匹配 | status |

Potential duplicate status

#### string

`OPEN`, `INVALID`

* Status code
* 描述
* You can't update a potential duplicate to MERGED as this is possible only by a merging request

You can't update a potential duplicate that is already in a MERGED status

Merging tracked entities

#### Tracked entities can be merged together if they are deemed viable. To initiate a merge, the first
step is to define two tracked entities as a Potential Duplicate. The merge endpoint moves data from
the duplicate tracked entity to the original tracked entity and deletes the remaining data of the
duplicate.

To merge a Potential Duplicate, i.e. the two tracked entities the Potential Duplicate represents,
use the following endpoint:

* ```
POST /api/potentialDuplicates/<id>/merge

Parameter name * 描述类型 Allowed values mergeStrategy Strategy to use for merging the potentialDuplicate string AUTO(default) or MANUAL #### The endpoint accepts a single parameter, `mergeStrategy`, which determines the strategy used when merging. For the `AUTO` strategy, the server will attempt to merge the two tracked entities automatically without user input. This strategy only allows merging tracked entities without conflicting data (see examples below). The `MANUAL` strategy requires the user to send in a payload describing how the merge should be done. For examples and rules for each strategy, see their respective sections below. Merge strategy AUTO The automatic merge evaluates the mergability of the two tracked entities and merges them if they are deemed mergeable. The mergability is based on whether the two tracked entities have any conflicts. Conflicts refer to data that cannot be merged automatically. Examples of possible conflicts include: ### The same attribute has different values in each tracked entity. Both tracked entities are enrolled in the same program. 程序通知模板中有几个配置参数对通知的正常运行至关重要。这些参数的说明如下表所示。下表对这些参数进行了说明。 If any conflict is encountered, an error message is returned to the user. When no conflicts are found, all data in the duplicate that is not already in the original will be moved to the original. This includes attribute values, enrollments (including events), and relationships. After the merge completes, the duplicate is deleted and the Potential Duplicate is marked as `MERGED`. When requesting an automatic merge, a payload is not required and will be ignored. #### Merge strategy MANUAL | The manual merge is suitable when there are resolvable conflicts or when not all the data needs to be moved during the merge. For example, if an attribute has different values in both tracked entities , the user can specify whether to keep the original value or move over the duplicate's value. Since the manual merge involves the user explicitly requesting to move data, there are some additional checks: | 检索和删除项目通知模板 | Parameter name | 译 | | --- | --- | --- | --- | | displayColumnOrder | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | When a manual merge is requested without a payload, we are telling the API to merge the two tracked entities without moving any data. In other words, we are just removing the duplicate and marking the potentialDuplicate MERGED. This might be valid in a lot of cases where the tracked entity was just created, but not enrolled for example. | Otherwise, if a manual merge is requested with a payload, the payload refers to what data should be moved from the duplicate to the original. The payload looks like this: | | ```json { "trackedEntityAttributes": ["B58KFJ45L9D"], "enrollments": ["F61SJ2DhINO"], "relationships": ["ETkkZVSNSVw"] } ``` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Additional information about merging | Currently it is not possible to merge tracked entities that are enrolled in the same program, due to the added complexity. A workaround is to manually remove the enrollments from one of the tracked entities before starting the merge. | | All merging is based on data already persisted in the database, which means the current merging service is not validating that data again. This means if data was already invalid, it will not be reported during the merge. The only validation done in the service relates to relationships, as mentioned in the previous section. | Program notification template | 项目通知模板允许您创建可根据不同类型事件发送的信息模板。消息和主题模板会被转换为实际值,并发送到配置的目的地。每个项目通知模板都会转化为 MessageConversation 对象或 ProgramMessage 对象,具体取决于收件人是外部还是内部。这些中间对象将只包含翻译后的信息和主题文本。 | 项目通知模板中有几个配置参数对通知的正常运行至关重要。这些参数的说明如下表所示。下表对这些参数进行了说明。 | | ``` POST /api/programNotificationTemplates ``` | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | 表:项目通知模板有效载荷 | 领域 | | 需要 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Values | 名称 | | 是的 | Program notification template | case-notification-alert | notificationTrigger | | 是的 | Program notification template | `ENROLLMENT` | subjectTemplate | 不 ## Subject template string Case notification V{org_unit_name} ### messageTemplate 是的 Message template string #### Case notification A{h5FuguPFF2j} notificationRecipient * 是的 * Who is going to receive notification. Options are `USER_GROUP`, `ORGANISATION_UNIT_CONTACT`, `TRACKED_ENTITY_INSTANCE`, `USERS_AT_ORGANISATION_UNIT`, `DATA_ELEMENT`, `PROGRAM_ATTRIBUTE`, `WEB_HOOK` #### USER_GROUP deliveryChannels * 不 * Which channel should be used for this notification. It can be either `SMS`, `EMAIL`, or `HTTP` * `SMS` * sendRepeatable 不 Whether notification should be sent multiple times #### 假 | The manual merge is suitable when there are resolvable conflicts or when not all the data needs to be moved during the merge. For example, if an attribute has different values in both tracked entities , the user can specify whether to keep the original value or move over the duplicate's value. Since the manual merge involves the user explicitly requesting to move data, there are some additional checks: | 检索和删除项目通知模板 | Parameter name | 译 | |---|---|---|---| | The program message feature enables you to send messages to tracked entities, contact addresses associated with organisation units, phone numbers, and email addresses. Messages can be sent using the `messages` resource. | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | 发送项目信息 | 项目消息可以使用两个传递渠道发送: | | 文本 | Program notification template | Recipients | 项目消息可以发送给各种收件人: | | The message text. | Program notification template | List of phone numbers: The system will use the explicitly defined phone numbers. | List of email addresses: The system will use the explicitly defined email addresses. | | 是的 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | 表格项目报文有效载荷 | 领域 | | 需要 | Program notification template | Values | enrollment | | 是的 | Program notification template | Can be trackedEntity, organisationUnit, an array of phoneNumbers or an array of emailAddresses. | enrollment | | 不 | ```json { "name": "Case notification", "notificationTrigger": "ENROLLMENT", "subjectTemplate": "Case notification V{org_unit_name}", "displaySubjectTemplate": "Case notification V{org_unit_name}", "notifyUsersInHierarchyOnly": false, "sendRepeatable": false, "notificationRecipient": "ORGANISATION_UNIT_CONTACT", "notifyParentOrganisationUnitOnly": false, "displayMessageTemplate": "Case notification A{h5FuguPFF2j}", "messageTemplate": "Case notification A{h5FuguPFF2j}", "deliveryChannels": [ "EMAIL" ] } ``` | Enrollment ID. | enrollment | | 不 | Program notification template | Event ID. | deliveryChannels | ### 是的 Array of delivery channels. `SMS`, `EMAIL` notificationTemplate 不 ProgramNotificationTemplate UID 用于交叉检查哪个项目消息属于哪个通知模板。 Text. 程序消息 API 支持使用特定请求参数查询消息。您可以根据过滤信息。所有请求都应使用 GET HTTP verb 来检索信息。不 | 默认值 | Text. | | --- | --- | | 文本 | 是的 | | The message text. | Text. | | storeCopy | 不 | | 是否在 DHIS2 中存储一份项目信息副本。 | `false`, `true` | | 查询项目信息 | 项目消息 API 支持使用特定请求参数查询消息。 | ### ``` GET /api/messages

To retrieve a specific message.

GET /api/messages/{uid}

GET /api/programNotificationInstances

表格查询程序通知实例 API

| 类型         | Potential duplicate status              | 检索和删除项目通知模板 | Parameter name                                                                                                                  |
|-------------|-------------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| 计划日期 | 日期"（ISO-8601） | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 返回计划在给定日期发送的通知实例。Example: `scheduledAt=2025-01-01`.                   |
| `true`&#124;`false`      | Field Presets { #field-presets }          | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 启用或禁用分页。默认为 `true`。使用 `paging=false` 可返回不带分页的所有匹配实例。  |
| comma separated list of fields or presets to include        | 整数         | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 启用分页时返回的页码。                                                                           |
| 默认    | 整数         | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 启用分页时每页的条目数。                                                                        |
| 事件       | Narrows response to tracked entities matching given filters. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering)             | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 该活动附有计划通知实例。                                                                      |
| 注册  | Narrows response to tracked entities matching given filters. More on filters [here](developer-manual.md#tracked_entity_attribute_filtering)             | [Enrollment Aggregate data dimensions](developer-manual.md#webapi_enrollment_aggregate_analytics_dimension) `/analytics/enrollments/aggregate/dimensions`       | 该注册附有计划通知实例。                                                                 |

## 性能{ #webapi_tracker_performance }

本节包括一般性能原则，然后是针对特定端点的
跟踪器导出端点的具体指导。进一步的性能优化需要了解真实世界的访问
模式和数据分布。如果你的实施能共享这些信息，将有助于
确定改进的优先次序。

### 进口

#### 通知

通知在导入后以异步方式发送，但会与并发请求争夺
数据库连接、CPU 和内存的并发请求。如果有很多实体和通知模板，这可能会增加延迟。
增加延迟。对于不需要通知的批量导入，请跳过通知：

    POST /api/tracker?skipSideEffects=true

#### 计划规则

在导入过程中，规则引擎会同步运行捆绑包中的每个注册和事件、
这会大大增加批量导入的延迟。只有当程序中没有
必须在导入时执行的带有验证或分配的规则时才跳过：

    POST /api/tracker?skipRuleEngine=true

### 出口

#### 一般原则

导出端点的响应时间通常由数据库查询的执行时间决定。下面的
下面的建议主要是减少数据库的工作量。

##### 正确的查询

跟踪器数据模型有三个层次：跟踪实体、注册人数和事件。始终在
满足需求的最低级别。使用 `GET /api/tracker/events` 而不是 `GET
/api/tracker/trackedEntities?fields=enrollments[events]`。通过父端点查询会增加
查询复杂性或查询次数。

##### 使用明确的 "字段

默认情况下，所有端点都不包括嵌套集合，如 "注册"、"事件 "和 "关系"。
关系"。每个额外的集合都会增加资源利用率和响应时间。只
请求所需的 "字段"，避免使用 "字段=*"。

##### 选择性

查询性能取决于数据库在返回结果前必须处理多少条记录。
需要扫描、排序和重复的记录越少，响应速度就越快。这就是**选择性**：
符合查询条件的记录占总记录数的比例。

选择性有几个来源，但都是复合的：请求参数（如
程序"、"过滤器"、日期范围）、用户范围和 "orgUnitMode"。

###### 过滤器

在排序和分页之前，过滤器会缩小结果集的范围。当有
数据库索引支持时最有效。宽泛的筛选器（例如，"filter=w75KJ2mc4zz:like:J"）可能会匹配大部分数据集，但几乎不提供选择性。
数据集，选择性很小。窄筛选器（例如，`filter=w75KJ2mc4zz:eq:Jerald` 或严格的日期范围
严格的日期范围）会大大减少工作集。跟踪实体属性的 `like` 过滤器
可受益于 [trigram 索引]（#scheduling_tracker_index_maintenance）。

程序和跟踪实体类型上的 "搜索所需的最少属性数 "设置
在用户捕获范围外进行搜索时，需要最少数量的属性筛选器。

###### IndicatorGroup

指定 `program` 可实现基于所有权的访问控制。如果没有 `program`，系统必须
动态评估被跟踪实体注册的所有程序的访问规则。总是
在查询特定程序数据时包含 `program`。

请注意，即使指定了 "程序"，选择性也取决于该程序存在多少数据。
程序的数据量。一个包含了大多数被跟踪实体的程序的选择性不会很高。

##### 组织单位模式{ #webapi_tracker_perf_organisation_unit_mode }

[`orgUnitMode`](developer-manual.md#webapi_tracker_orgunit_scope)和用户的组织单位范围会直接影响
数据库处理的记录数量。性能取决于所包含的组织单位
拥有多少数据。只对单个设备有作用域的用户只能查询一小部分记录；而拥有根级
访问权限的用户可能会扫描整个程序。**选择 "是最有效的**，因为数据库可以
直接查询指定组织单位拥有的记录。

**当儿童不拥有数据时，**`CHILDREN`速度较慢。
(最低级别）。在较高层次（如地区）使用 `CHILDREN`，会返回没有事件的行政组织单位。
单位，迫使数据库扫描程序中的所有事件以确认这一点。
当子机构是实际捕获数据的组织单位时，"CHILDREN "速度很快。

**`ALL`** 不包括地域限制。**ACCESSIBLE`**取决于用户的搜索范围、
对于有广泛访问权限的用户，搜索范围可涵盖程序的大部分数据。结合选择性
过滤器相结合，以保持工作集的可管理性。

##### 订购

order "参数会极大地影响查询性能。顺序字段可分为性能
层：

* **快速（索引）**：数据库按顺序运行索引，并在填满所请求的索引后停止运行。
  页。成本随页面大小和偏移量而变化，不随数据集大小而变化。假设查询条件为
  允许数据库使用索引，这取决于筛选器和 `orgUnitMode`.
* **慢（无索引）**：数据库必须对所有匹配记录进行扫描和排序，然后才能返回
  页。成本主要取决于匹配记录的总数。
* **非常慢（跨资源）**：排序值来自相关资源（例如，排序跟踪的资源
  或属性值）。数据库必须为每个
  匹配记录，然后再进行排序。

**选择性比顺序字段选择更重要、
即使排序速度慢的字段也能快速排序，因为数据库只对一小部分字段进行排序。请注意
仍会降低排序成本，但不会降低扫描成本。

请参阅下面针对端点的章节，了解哪些订单字段属于哪个层级。

##### 分页

DHIS2 使用[基于偏移量的分页](https://use-the-index-luke.com/no-offset)。页码越高，速度越慢，因为数据库必须计算并丢弃前面的所有行。
行。这是偏移分页法的基本特性，并非 DHIS2 所特有。

建议：
* 保持合理的页面大小（默认值为 50）
* 避免浏览到很高的页码
* 除非必要，否则避免使用 `totalPages=true` ，因为它会运行一个额外的计数查询，必须处理所有页数。
  无论页面大小，都能匹配记录
* 避免使用 `paging=false` ，因为它会在单个响应中返回所有匹配记录

配置 [收集限制](#tracked-entities-collection-limits) 以限制结果集大小，保护数据库和服务器资源。
保护数据库和服务器资源。

#### `/api/tracker/trackedEntities`.

##### 过滤器

程序 "或 "trackedEntityType "都是必需的。程序 "更可取，因为它可以实现基于所有权的直接
基于所有权的访问控制。

##### 订购

| 层 | 订单字段 | 费用 |
|------|-------------|------|
| 快速 | 被跟踪实体"、"创建时间 | 与 `page` (偏移量) + `pageSize` 成比例 |
| 慢 | `updatedAt`, `createdAtClient`, `updatedAtClient`, `inactive`. | 与匹配跟踪实体总数的比例 |
| 非常慢 | enrolledAt"，跟踪的实体属性 UID | 与匹配跟踪实体总数的比例 + 相关表格中每条记录的查找量 |

enrolledAt "还要求在一个被跟踪实体有多个注册同一计划时进行重复数据删除。
同一计划。配置为 "只注册一次 "的计划可避免重复数据删除成本。

#### `/api/tracker/enrollments`.

##### 订购

| 层 | 订单字段 | 费用 |
|------|-------------|------|
| 慢 | 已注册用户"、"已创建用户"、"已完成用户"、"已更新用户"、"已创建客户"、"已更新客户 | 与对等入学总人数的比例 |

目前，所有注册顺序字段都缺少综合索引。数据库必须对所有
匹配的注册信息，然后再返回所请求的页面。

#### `/api/tracker/events`（跟踪程序）

##### 过滤器

program "是必填项，可与 "programStage "结合使用，将范围缩小到单个阶段。

##### 所有权

每个跟踪器事件查询都必须遍历注册和所有权记录，以执行访问控制。
在一个有成千上万注册用户的程序中，广泛的查询（如不带过滤器的 `orgUnitMode=ALL
不带过滤器）必须先处理所有所有权记录，然后才能开始任何事件级工作。索引
因为所有权检查是在不同的表上进行的。

降低成本的最有效方法是缩小 org 单位范围。一个用户对
单个设施的用户会产生一个小的所有权集，从而使查询的其余部分快速完成，而无需考虑其他参数。
参数。

注册级筛选器（"enrollmentStatus"、"followUp"、注册日期范围）不受
索引支持。它们仍然可以减少结果集，但不会减少数据库
扫描。

##### 订购

| 层 | 订单字段 | 费用 |
|------|-------------|------|
| 慢 | 发生时间"、"计划时间"、"创建时间"、"更新时间"、"完成时间"、"客户创建时间"、"客户更新时间"、"注册时间"、数据元素 UID | 与匹配事件总数成比例（加入所有权后） |
| 非常慢 | 跟踪的实体属性 UID | 按匹配事件总数比例 + 按事件跨资源查找 |

所有跟踪器事件顺序字段都缺少程序级的复合索引。数据库必须
必须遍历注册和所有权记录，收集所有匹配事件，对其进行排序，并返回所请求的页
请求的页面。成本与匹配事件总数而非页面大小成正比。

指定 `programStage` 并不能提高排序性能，因为瓶颈是所有权连接，而不是事件级扫描。
所有权连接，而不是事件级扫描。

enrolledAt` 来自注册表，而注册表已经是所有权连接的一部分，因此不需要额外的查找。
不需要额外查找。属性 UID 要求对每个匹配事件的被跟踪实体进行跨资源查找。
实体的跨资源查询。

#### `/api/tracker/events`（事件程序）

活动计划（无注册的计划）没有注册或所有权方面的开销。数据库
直接从事件转到其 org 单元，使这些查询在结构上比跟踪程序查询更快。
程序查询更快。

##### 过滤器

程序 "是强制性的。

##### 组织单位模式

在默认的 "occurredAt "顺序下，数据库会执行排序索引，并按
org 单位过滤每个事件。当匹配事件出现在索引的早期时，这种方法速度很快。对于 `SELECTED`、`DESCENDANTS`、
和 `ACCESSIBLE` 的性能取决于匹配的组织单位事件在排序顺序中的分布情况。
排序顺序。如果匹配事件很少或集中在索引末尾，数据库
必须先扫描许多非匹配事件。在拥有数百万个事件的程序阶段，用户的
org单元只覆盖一小部分的情况下，这可能会导致在扫描索引的大部分内容后才填满单页。
填满一个页面。添加 `occurredAfter` 和/或 `occurredBefore` 可以将扫描限制在一个有边界的窗口内，建议用于大容量扫描。
窗口，建议用于大容量程序阶段。

`ALL` 完全避免了 org 单元过滤，使用默认顺序时速度很快。CHILDREN`速度较慢，原因与
一般原则](#webapi_tracker_perf_organisation_unit_mode) 中所述的相同原因。

如果没有默认的 "occurredAt "顺序，所有模式都需要对所有匹配事件进行扫描和排序。

##### 订购

默认顺序是 `occurredAt desc`。这是事件程序最有效的顺序。

| 层 | 订单字段 | 费用 |
|------|-------------|------|
| 快速（索引） | 发生时间 | 与 `page` (偏移量) + `pageSize` 成比例。当组织单位过滤激活但匹配稀少时会降低--参见上文[组织单位模式](#organisation-unit-mode)。 |
| 慢速（无索引） | 创建于客户"、"更新于客户"、"完成于客户"、"创建于客户"、"更新于客户"。 | 占计划阶段活动总数的比例 |
| 缓慢（JSON 提取） | 数据元素 UID | 需要提取每个匹配事件的 JSON 值并对其进行排序 |


# ```
/ api / userLookup

## 电子邮件 { #webapi_email } Web API 具有用于发送电子邮件的资源。对于电子邮件发送需要已正确设置 SMTP 配置并且 DHIS2 实例的系统通知电子邮件地址具有被定义。您可以从电子邮件设置屏幕设置 SMTP 设置和来自常规设置屏幕的系统通知电子邮件地址在 DHIS2 中。 / api / 33 /电子邮件 ### 系统通知 { #webapi_email_system_notification } *notification* 资源可让您发送系统电子邮件通知使用 JSON 或 XML 格式的给定主题和文本。电子邮件将发送至 DHIS2 通用系统中定义的通知电子邮件地址设置：

{
  "subject": "Integrity check summary",
  "text": "All checks ran successfully"
}

DELETE /api/messages/{uid}

项目消息 API 支持使用特定请求参数查询消息。您可以根据过滤信息。所有请求都应使用 GET HTTP verb 来检索信息。 ### 外发电子邮件 Parameter 网址 enrollment /api/messages?enrollment=6yWDMa0LP7 event /api/messages?event=SllsjpfLH2 ### trackedEntity /api/messages?trackedEntity=xdfejpfLH2 organisationUnit # 数据存储 ## processedDate /api/messages?processedDate=2016-02-01 Program Notification Instance /api/programNotificationInstances exposes program notification instances, i.e. concrete scheduled or sent notifications created from program notification templates. ### Returns program notification instances, optionally filtered and paginated.

GET /api/programNotificationInstances

Table: Query program notification instance API

| Name         | Type              | Required | Description                                                                                                                   |
|-------------|-------------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `scheduledAt` | `date` (ISO-8601) | no       | Returns notification instances scheduled to be sent on the given date. Example: `scheduledAt=2025-01-01`.                    |
| `paging`      | `boolean`         | no       | Enables or disables pagination. Default is `true`. Use `paging=false` to return all matching instances without pagination.   |
| `page`        | `integer`         | no       | Page number to return when pagination is enabled.                                                                            |
| `pageSize`    | `integer`         | no       | Number of items per page when pagination is enabled.                                                                         |
| `event`       | `UID`             | no       | Program notification instances attached to this enrollment.                                                                   |
| `enrollment`  | `UID`             | no       | Program notification instances attached to this event.                                                                   |



# Email { #email } 

## Email { #webapi_email } 

The Web API features a resource for sending emails. For emails to be
sent it is required that the SMTP configuration has been properly set up
and that a system notification email address for the DHIS2 instance has
been defined. You can set SMTP settings from the email settings screen
and system notification email address from the general settings screen
in DHIS2.

    /api/33/email

### System notification { #webapi_email_system_notification } 

The *notification* resource lets you send system email notifications
with a given subject and text in JSON or XML. The email will be sent to
the notification email address as defined in the DHIS2 general system
settings:

```json
{
  "subject": "Integrity check summary",
  "text": "All checks ran successfully"
}

您可以通过发布到通知来发送系统电子邮件通知像这样的资源: | 响应示例: | Parameter name | 您还可以通过发布到通知资源如下所述。 `F_SEND_EMAIL` 或 `ALL` 权限必须在系统中才能使用这个 api。主题参数是可选的。 “DHIS 2”字符串将作为默认主题发送如果 url 中没有提供。应该对 URL 进行编码才能使用它应用项目接口。 | |---|---|---| | ```bash curl "localhost/api/33/email/notification?recipients=xyz%40abc.com&message=sample%20email&subject=Test%20Email" -X POST -u admin:district ``` | The previous example is convenient for short messages. However, since the message is passed as a query string, it can quickly hit the URL length limit of the server. For longer messages, it is better to send the data in the POST request body. The following example shows how to send an email with a longer message in the request body: | 具有以下要求: | | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | ```bash curl -u admin:district -X POST 'localhost/api/33/email/notification' \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'recipients=recipient1@example.com,recipient2@example.com' \ --data-urlencode 'subject=System Maintenance Schedule' \ --data-urlencode 'message=

System Maintenance

Dear user,

We are writing to inform you about scheduled system maintenance. The following table shows the maintenance schedule for the upcoming week:

Day	Time
Monday	10 PM - 11 PM
Wednesday	10 PM - 11 PM

We apologize for any inconvenience this may cause. Please plan your work accordingly.

Best regards,
The DHIS2 Team

' ``` | 具有以下要求: | | ```json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } ``` | ```bash curl "localhost/api/33/email/test" -X POST -H "Content-Type:application/json" -u admin:district ``` | 数据存储 { #data-store } | | / api / 33 / userDataStore | 使用 *dataStore* 资源,开发人员可以存储任意数据他们的应用项目。对数据存储密钥的访问基于其共享设置。默认情况下,所有创建的密钥都可以公开访问(读取和写入)。此外,对数据存储命名空间的访问仅限于用户的访问相应的应用项目,如果应用项目保留了命名空间。例如,有权访问“sampleApp”应用项目的用户也将能够使用数据存储中的 sampleApp 命名空间。如果一个命名空间没有保留,使用它不需要特定的访问权限。 | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | ### Note that there are reserved namespaces used by the system that require special authority to be able to read or write entries. For example the namespace for the android settings app `ANDROID_SETTINGS_APP` will require the `M_androidsettingsapp` authority. 数据存储结构 { #webapi_data_store_structure } 数据存储条目由命名空间、键和值组成。这命名空间和键的组合是唯一的。值数据类型为 JSON。 Table: Data store structure 项目 Indicates whether the value of the given key should be encrypted 数据类型命名空间 Namespace for organization of entries. Table: Data store structure 键 Indicates whether the value of the given key should be encrypted 串值 Value holding the information for the entry. JSON格式 Encrypted Indicates whether the value of the given key should be encrypted Boolean 获取键和名称空间 { #webapi_data_store_get_keys_and_namespaces } 有关所有现有名称空间的列表: JSON格式清单示例curl请求: Indicates whether the value of the given key should be encrypted 响应示例: ### 查询 API 有关命名空间中所有键的列表: GET /api/33/dataStore/ 清单示例curl请求: * ```bash curl "play.dhis2.org/demo/api/33/dataStore/foo" -u admin:district

* 响应示例:
* ```json
[
  "key_1",
  "key_2"
]

要从名称空间检索现有键的值: GET /api/33/dataStore// 卷曲请求检索示例: #### 分页响应示例:

{
  "foo":"bar"
}

要从名称空间检索现有键的元数据: GET /api/33/dataStore///metaData 卷曲请求检索示例:

curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1/metaData" -u admin:district

#### 价值提取

{
  "id": "dsKeyUid001", 
  "created": "...",
  "user": {...},
  "namespace": "foo",
  "key": "key_1"
}

查询应用项目接口{ #query-api } The query API is allows you to query and filter values over all keys in a namespace. The `fields` parameter is used to specify the query. This is useful for retrieving specific values of keys across a namespace in a single request. GET /api/dataStore/?fields= The list of `fields` can be: empty: returns just the entry keys `.`: return the root value as stored comma separated list of paths: `[,]`; each `` can be a simple property name (like `age`) or a nested path (like `person.age`) Furthermore, entries can be filtered using one or more `filter` parameters and sorted using the `order` parameter. Multiple filters can be combined using `rootJunction=OR` (default) or `rootJunction=AND`. All details on the `fields`, `filter` and `order` parameters are given in the following sections. Paging { #paging } By default, results use paging. Use `pageSize` and `page` to adjust size and offset. The parameter `paging=false` can be used to opt-out and always return all matches. This should be used with caution as there could be many entries in a namespace. The default page size is 50. GET /api/dataStore/?fields=.&page=2&pageSize=10 When paging is turned off, entries are returned as plain result array as the root JSON structure. The same effect can be achieved while having paged results by using `headless=true`.

{
  "pager": { ... },
  "entries": [...]
}

vs.

[...]

Value extraction { #value-extraction } The data store allows extracting entire simple or complex values as well as the extraction of parts of complex JSON values. > **Note** > > For clarity of the examples the responses shown mostly omit the outermost object with the `pager` information > and the `entries` array that the examples show. To filter a certain set of fields add a `fields` parameter to the namespace query: GET /api/dataStore/?fields=name,description This returns a list of all entries having a non-null `name` and/or a `description` field like in the following example:

[
  {"key": "key1", "name": "name1", "description": "description1"},
  {"key": "key2", "name": "name2", "description": "description2"}
]

If for some reason we even want entries where none of the extracted fields is non-null contained in the result list the `includeAll` parameter can be added: GET /api/dataStore/?fields=name,description&includeAll=true The response now might look like this:

[
  {"key": "key1", "name": "name1", "description": "description1"},
  {"key": "key2", "name": "name2", "description": "description2"},
  {"key": "key3", "name": null, "description": null},
  {"key": "key4", "name": null, "description": null}
]

### 结果排序 GET /api/dataStore/?fields=name,root[child1,child2] GET /api/dataStore/?fields=name,root(child1,child2) The example response could look like this:

[
  { "key": "key1", "name": "name1", "root": {"child1": 1, "child2": []}},
  { "key": "key2", "name": "name2", "root": {"child1": 2, "child2": []}}
]

The same syntax works for nested members: GET /api/dataStore/?fields=root[level1[level2[level3]]] GET /api/dataStore/?fields=root(level1(level2(level3))) Example response here:

[
  { "key": "key1", "root": {"level1": {"level2": {"level3": 42}}}},
  { "key": "key1", "root": {"level1": {"level2": {"level3": 13}}}}
]

When such deeply nested values are extracted we might not want to keep the structure but extract the leaf member to a top level member in the response. Aliases can be used to make this happen. An alias can be placed anywhere after a member name using `~hoist` followed by the alias in round brackets like so: * GET /api/dataStore/?fields=root[level1[level2[level3~hoist(my-prop)]]] * The response now would look like this: * ```json [ { "key": "key1", "my-prop": 42}, { "key": "key2", "my-prop": 13} ]

* If the full path should be kept while giving an alias to a nested member the 
parent path needs to be repeated using dot-syntax to indicate the nesting.
This can also be used to restructure a response in a new different structure 
like so:

    GET /api/dataStore/<namespace>?fields=root[level1[level2[level3~hoist(my-root.my-prop)]]]

### 过滤条目
```json
[
  { "key": "key1", "my-root": {"my-prop": 42}},
  { "key": "key2", "my-root": {"my-prop": 13}}
]

OBS! An alias cannot be used to rename an intermediate level. However, an alias could be used to resolve a name collision with the `key` member. * GET /api/dataStore/?fields=id,key~hoist(value-key) * ```json [ { "key": "key1", "id": 1, "value-key": "my-key1"}, { "key": "key2", "id": 2, "value-key": "my-key2"} ]

* Sorting results { #sorting-results } 

Results can be sored by a single property using the `order=<path>[:direction]` parameter.
This can be any valid value `<path>` or the entry key (use `_` as path).

| 所需值 | Parameter name |
| -------- | ----------- |
|     GET /api/dataStore/<namespace>?fields=name&order=name   | To switch to descending order use `:desc`: |
|     GET /api/dataStore/<namespace>?fields=name&order=name:desc  | Sometimes the property sorted by is numeric so alphanumeric interpretation would be confusing.
In such cases special ordering types `:nasc` and `:ndesc` can be used. |
| In summary, order can be one of the following:  | `asc`: alphanumeric ascending order |
| `desc:`: alphanumeric descending order | `nasc`: numeric ascending order |

`ndesc`: numeric descending order

| 所需值 | Parameter name |
| -------- | ----------- |
| To filter entries within the query API context add one or more `filter` parameters
while also using the `fields` parameter.     | Each `filter` parameter has the following form: |
| unary operators: `<path>:<operator>` | binary operators: `<path>:<operator>:<value>` |
| set operators: `<path>:<operator>:[<value>,<value>,...]`     | Unary operators are: |
| Operator     | 描述 |
| `null`     | value is JSON `null` |
| `!null`     | value is defined but different to JSON `null` |

`empty`

| 所需值 | `!empty` |  Parameter name |
| -------- | ---------------- | ----------- |
| Binary operators are:   | Operator          | 描述 |
| `eq`  | value is equal to the given boolean, number or string         | `!eq`, `ne`, `neq` |
| value is not equal to the given boolean, number or string  | `lt`   | value is numerically or alphabetically less than the given number or string |
| `le` | value is numerically or alphabetically less than or equal to the given number or string | `gt` |
| value is numerically or alphabetically greater than the given number or string  | `ge`     | value is numerically or alphabetically greater than or equal to the given number or string |
| Text pattern matching binary operators are: | Operator   | Case Insensitive |

描述

`like`

`ilike`

| 所需值 | Parameter name |
| -------- | ----------- |
| `!ilike`     | value does not match the text pattern given |
| `$like`    | `$ilike`, `startswith` |

value starts with the text pattern given

* `!$like`
* `!$ilike`, `!startswith`
* value does not start with the text pattern given
* `like$`

`ilike$`, `endswith`

value ends with the text pattern given

`!like$`

`!ilike$`, `!endswith`

value does not end with the text pattern given

For operators that work for multiple JSON node types the semantic is determined from the provided value.
If the value is `true` or `false` the filter matches boolean JSON values.
If the value is a number the filter matches number JSON values.
Otherwise, the value matches string JSON values or mixed types of values.

> **Tip**
>
> To force text comparison for a value that is numeric quote the value in single quotes.
> For example, the value `'13'` is the text 13 while `13` is the number 13.  

Set operators are:

Operator

描述

`in`

entry value is textually equal to one of the given values (is in set)

`!in`

entry value is not textually equal to any of the given values (is not in set)

### The `<path>` can be:

`_`: the entry key is

`.`: the entry root value is

`<member>`: the member of the root value is

`<member>.<member>`: the member at the path is (up to 5 levels deep)

Indicates whether the value of the given key should be encrypted

Some example queries are found below.

Name (of root object) is "Luke":

    GET /api/dataStore/<namespace>?fields=.&filter=name:eq:Luke

### Age (of root object) is greater than 42 (numeric):

    GET /api/dataStore/<namespace>?fields=.&filter=age:gt:42

Root value is a number greater than 42 (numeric matching inferred from the value):

    GET /api/dataStore/<namespace>?fields=.&filter=.:gt:42

Enabled (of root object) is true (boolean matching inferred from the value):

Indicates whether the value of the given key should be encrypted

Root object has name containing "Pet" and has an age greater than 20:

###     GET /api/dataStore/<namespace>?fields=.&filter=name:like:Pet&filter=age:gt:20

Root object is either flagged as minor or has an age less than 18:

    GET /api/dataStore/<namespace>?fields=.&filter=minor:eq:true&filter=age:lt:18&rootJunction=or

创造价值 { #webapi_data_store_create_values } 

为命名空间创建新的键和值:

Indicates whether the value of the given key should be encrypted

假设有效的JSON有效负载,创建示例的curl请求:

```bash
curl "https://play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X POST
  -H "Content-Type: application/json" -d "{\"foo\":\"bar\"}" -u admin:district

响应示例: 创造价值 { #webapi_data_store_create_values } 如果您需要加密存储的数据(例如用户凭据或类似的),您可以像这样将查询附加到 url: Indicates whether the value of the given key should be encrypted 更新值 { #webapi_data_store_update_values } ### 更新命名空间中存在的密钥: PUT /api/33/dataStore// 假设有效的JSON有效负载,示例curl请求更新:

curl "https://play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X PUT -d "[1, 2, 3]"
  -H "Content-Type: application/json" -u admin:district

响应示例: 有关所有现有名称空间的列表: 删除键 { #webapi_data_store_delete_keys } 要从名称空间中删除现有键: 删除/ api / 33 / dataStore / / 删除示例curl请求:

curl "play.dhis2.org/demo/api/33/dataStore/foo/key_1" -X DELETE -u admin:district

## 响应示例:

{
  "httpStatus": "OK",
  "httpStatusCode": 200,
  "status": "OK",
  "message": "Key 'key_1' deleted from namespace 'foo'."
}

要删除名称空间中的所有键: ### 删除/ api / 33 / dataStore / 删除示例curl请求:

curl "play.dhis2.org/demo/api/33/dataStore/foo" -X DELETE -u admin:district

| 响应示例: | Parameter name | Sharing data store keys { #webapi_data_store_sharing } | |---|---|---| | Sharing of data store keys follows the same principle as for other metadata sharing (see [Sharing](developer-manual.md#webapi_sharing)). | To get sharing settings for a specific data store key: | 具有以下要求: | | ```bash curl "localhost/api/33/email/notification?recipients=xyz%40abc.com&message=sample%20email&subject=Test%20Email" -X POST -u admin:district ``` | GET /api/33/dataStore///metaData | 具有以下要求: | | To send an email with an HTML body, you can simply provide the HTML content in the `message` parameter. The email client should interpret the HTML and render it accordingly. Note that the `Content-Type` header in the `curl` command should be `application/x-www-form-urlencoded`, as the data is sent as URL-encoded form data. The following example shows how to send an email with a simple HTML table: | POST / api / 33 / sharing?type = dataStore&id = | 具有以下要求: | | ```json { "object": { "publicAccess": "rw------", "externalAccess": false, "user": {}, "userAccesses": [], "userGroupAccesses": [ { "id": "hj0nnsVsPLU", "access": "rw------" }, { "id": "qMjBflJMOfB", "access": "r-------" } ] } } ``` | 用户数据存储 { #webapi_user_data_store } | 数据存储 { #data-store } | | / api / 33 / userDataStore | 用户数据存储结构 { #webapi_user_data_store_structure } | *userDataStore* 由用户、命名空间、键和关联的值。用户、命名空间和密钥的组合是唯一的。 | ### Table: User data store structure 项目描述 Data Type 用户数据类型 ### 串命名空间 The namespace the key belongs to

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

键串 ### 串值 The value stored

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

Encrypted Indicates whether the value should be encrypted ### Boolean 获取名称空间 { #webapi_user_data_store_get_namespaces } 返回所有现有名称空间的数组

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

请求示例:

curl -H "Content-Type: application/json" -u admin:district "play.dhis2.org/api/33/userDataStore"

[
  "foo",
  "bar"
]

取得金钥 { #webapi_user_data_store_get_keys } ### 返回给定名称空间中所有现有键的数组 GET /api/userDataStore/ 请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

[
  "key_1",
  "key_2"
]

获取价值 { #webapi_user_data_store_get_values } ### 返回给定名称空间和键的值 GET /api/33/userDataStore// 请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "some": "value"
}

创造价值 { #webapi_user_data_store_create_values } ### 向给定名称空间中的给定键添加新值。 POST / api / 33 / userDataStore / / 请求示例:

curl -X POST -H "Content-Type: application/json" -u admin:district -d "['some value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "message": "Key 'bar' in namespace 'foo' created."
}

如果您需要加密该值(例如用户凭据等等)您可以像这样将查询附加到网址: ### 其他用户数据存储的管理访问权限更新值 { #webapi_user_data_store_update_values } 更新现有值 PUT /api/33/userDataStore// ## 部分更新（试验性）

curl -X PUT -H "Content-Type: application/json" -u admin:district -d "['new value']"
  "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus":"Created",
  "httpStatusCode":201,
  "status":"OK",
  "message":"Key 'bar' in namespace 'foo' updated."
}

删除键 { #webapi_user_data_store_delete_key } 删除金钥 ### 更新根目录（整个条目）请求示例:

curl -X DELETE -u admin:district "play.dhis2.org/api/33/userDataStore/foo/bar"

{
  "httpStatus":"OK",
  "httpStatusCode":200,
  "status":"OK",
  "message":"Key 'bar' deleted from the namespace 'foo."
}

### 更新特定路径删除给定名称空间中的所有键删除/ api / 33 / userDataStore / 请求示例:

curl -X DELETE -u admin:district "play.dhis2.org/api/33/userDataStore/foo"

{
  "httpStatus":"OK",
  "httpStatusCode":200,
  "status":"OK",
  "message":"All keys from namespace 'foo' deleted."
}

Admin Access to another User's Datastore { #admin-access-to-another-users-datastore } ### 益处 - For example, to add a value to `Peter`'s datastore an admin uses: - POST /api/userDataStore//?username=Peter ## 滚动（实验性） Both the datastore and user datastore allow partial updating of entry values. We can perform many update operations on this entry. The following examples use `{store}` in the API calls, please substitute with `dataStore` or `userDataStore` for your use case.

{
  "name": "wisker",
  "favFood": [
    "fish", "rabbit"
  ]
}

We can perform many update operations on this entry. The following examples use `{store}` in the API calls, please substitute with `dataStore` or `userDataStore` for your use case. Update root (entire entry) { #update-root-entire-entry } We can update the entry at the root by not supplying the `path` request param or leaving it empty `path=`. `PUT` `/api/{store}/pets/whiskers` with body `"whiskers"` updates the entry to be the supplied body. So a `GET` request to `/api/{store}/pets/whiskers` would now show:

"whiskers"

Update at specific path { #update-at-specific-path } We can update the entry at a specific path by supplying the `path` request param and the property to update. `PUT` `/api/{store}/pets/whiskers?path=name` with body `"whiskers"` updates the entry at the `name` property only. So a `GET` request to `/api/{store}/pets/whiskers` would now show the updated `name`: ### 益处 - We can update an array element at a specific path. # `PUT` `/api/{store}/pets/whiskers?path=favFood.[0]` with body `"carrot"` updates the first element in the `favFood` array only. So a `GET` request to `/api/{store}/pets/whiskers` would now show the updated `favFood`:

{
    "name": "wisker",
    "favFood": [
        "carrot",
        "rabbit"
    ]
}

Benefits { #benefits } smaller payloads required for small changes less error-prone (no copy-pasting large entries to change 1 property) - Roll (Experimental) { #roll-experimental } - The `roll` request param enables the user to have a 'rolling' number of elements in an array. In our example we have the `favFood` array. If we wanted to update this array previously, we'd have to supply the whole payload like so: `PUT` `/api/{store}/pets/whiskers` with body - ```json { "name": "wisker", "favFood": [ "fish", "rabbit", "carrot" ] }

- Now we can use the `roll` request param (with the `path` functionality) to state that we want the rolling functionality for _n_ number of elements.
In this example we state that we want the array to have a rolling value of 3, passing in an extra element in the call.  
`PUT` `/api/{store}/pets/whiskers?roll=3&path=favFood` with body `"carrot"` would result in the following state.
- ```json
{
    "name": "wisker",
    "favFood": [
        "fish",
        "rabbit",
        "carrot"
    ]
}

- Since we passed the rolling value of `3`, this indicates that we only want the last 3 elements passed into the array. So if we now make another call and add a new element to the array, we would expect the first element (`fish`) to be dropped from the array. `PUT` `/api/{store}/pets/whiskers?roll=3&path=favFood` with body `"bird"` would result in the following state: ## 创建组织单位简介 > **Note** > > Once a rolling value has been set (e.g. `role=3`), it can only be increased (e.g. `roll=5`) and cannot be decreased (e.g. `roll=2`) Dot notation does allow for nested calls. Let's say we have this current entry value:

{
  "name": "wisker",
  "favFood": [
    "fish", "rabbit"
  ],
  "type": {
    "breed": ["shorthair"]
  }
}

If we wanted to add another breed using a rolling array we could make the call: `PUT` `/api/{store}/pets/whiskers?roll=3&path=type.breed` with body `"small"` which would result in the following state:

{
  "name": "wisker",
  "favFood": [
    "fish", "rabbit"
  ],
  "type": {
    "breed": ["shorthair, small"]
  }
}

## 获取组织单位简介 Only interested in keeping track of _n_ values which may change over time Organisation unit profile { #org_unit_profile } The organisation unit profile resource allows you to define and retrieve an information profile for organisation units in DHIS 2. ## 获取组织单位概况数据 A single organisation unit profile can be created and applies to all organisation units. The information part of the organisation unit profile includes: Name, short name, description, parent organisation unit, level, opening date, closed date, URL. * Contact person, address, email, phone number (if exists). * Location (longitude/latitude). Metadata attributes (configurable). * Organisation unit group sets and groups (configurable). * Aggregate data for data elements, indicators, reporting rates, program indicators (configurable). * Create organisation unit profile { #create-organisation-unit-profile } * 要定义组织单位配置文件,可以使用`POST`请求:

POST /api/organisationUnitProfile

JSON 格式的有效载荷如下所示,其中`attributes `指元数据属性,`groupSets `指组织单位组集,`dataItems `指数据元素、指标、数据集和计划指标:

{
  "attributes": [
    "xqWyz9jNCA5",
    "n2xYlNbsfko"
  ],
  "groupSets": [
    "Bpx0589u8y0",
    "J5jldMd8OHv"
  ],
  "dataItems": [
    "WUg3MYWQ7pt",
    "vg6pdjObxsm",
    "DTVRnCGamkV",
    "Uvn6LCg7dVU",
    "eTDtyyaSA7f"
  ]
}

The `F_ORG_UNIT_PROFILE_ADD` authority is required to define the profile. Get organisation unit profile { #get-organisation-unit-profile } ## 为组织单位上传图片

GET /api/organisationUnitProfile

The response will be in JSON format. Get organisation unit profile data { #get-organisation-unit-profile-data } To retrieve the organisation unit profile data you can use a `GET` request:

GET /api/organisationUnitProfile/{org-unit-id}/data?period={iso-period}

The organisation unit profile data endpoint will combine the profile definition with the associated information/data values. `org-unit-id `路径变量为必填项,指要提供汇总数据的组织单位的 ID。查询参数 `iso-period `是可选参数,指的是为数据项提供汇总数据的 ISO 期间 ID。如果没有指定,则将使用 _this year_ 相对期间作为后备。 The response will include the following sections: `info`: Fixed information about the organisation unit. `属性`:元数据属性及相应的属性值。 `组集`:组织单位组集,包含该组织单位所属的相应组织单位组。 `数据项`带有相应汇总数据值的数据项。 ## 获取组织单位的图像请求示例如下所示:

GET /api/organisationUnitProfile/DiszpKrYNg8/data?period=2021

The profile data response payload in JSON format will look like this, where the `id` and `label` fields refer to the metadata item, and the `value` field refers to the associated value:

{
  "info": {
    "id": "DiszpKrYNg8",
    "code": "OU_559",
    "name": "Ngelehun CHC",
    "shortName": "Ngelehun CHC",
    "parentName": "Badjia",
    "level": 4,
    "levelName": "Facility",
    "openingDate": "1970-01-01T00:00:00.000",
    "longitude": -11.4197,
    "latitude": 8.1039
  },
  "attributes": [
    {
      "id": "n2xYlNbsfko",
      "label": "NGO ID",
      "value": "GHE51"
    },
    {
      "id": "xqWyz9jNCA5",
      "label": "TZ code",
      "value": "NGE54"
    }
  ],
  "groupSets": [
    {
      "id": "Bpx0589u8y0",
      "label": "Facility Ownership",
      "value": "Public facilities"
    },
    {
      "id": "J5jldMd8OHv",
      "label": "Facility Type",
      "value": "CHC"
    }
  ],
  "dataItems": [
    {
      "id": "WUg3MYWQ7pt",
      "label": "Total Population",
      "value": 3503
    },
    {
      "id": "DTVRnCGamkV",
      "label": "Total population < 1 year",
      "value": 140
    },
    {
      "id": "vg6pdjObxsm",
      "label": "Population of women of child bearing age (WRA)",
      "value": 716
    },
    {
      "id": "Uvn6LCg7dVU",
      "label": "ANC 1 Coverage",
      "value": 368.2
    },
    {
      "id": "eTDtyyaSA7f",
      "label": "FIC <1y",
      "value": 291.4
    }
  ]
}

Upload image for organisation unit { #upload-image-for-organisation-unit } 要为组织单位上传图片,可以使用 `fileResources` 端点。 # 应用 ## `文件资源`端点接受原始文件作为请求体。组织单位图像支持 `JPG`、`JPEG` 和 `PNG` 格式。组织单位图像的域为 `ORG_UNIT`。 Please consult *File resources* in the *Metadata* section for details about the `fileResources` endpoint. 要上传图片,可以发送一个以 `ORG_UNIT` 作为域查询参数的 `POST` 请求,并将图片作为请求有效载荷。 `Content-Type` 头应与上传的文件类型相匹配。

POST /api/fileResources?domain=ORG_UNIT

### JSON 响应中的 `response` > `fileResource` 对象的 `id ` 属性将包含对文件资源标识符的引用。组织单位实体有一个 `image` 属性,指向文件资源图像。要在组织单位上设置文件资源引用,可以向组织单位发送带有 JSON 有效负载的`PATCH`请求:

PATCH /api/organisationUnits/{id}

{ 
  "image": "{file-resource-id}" 
}

Alternatively, you can use a `PUT` request with the full organisation unit payload (fields omitted for brevity):

PUT /api/organisationUnits/{id}

{
  "id": "Rp268JB6Ne4",
  "name": "Adonkia CHP",
  "image": {
    "id":  "{file-resource-iid}"
  }
}

Get image for organisation unit { #get-image-for-organisation-unit } The organisation unit entity has an `image` object which refers to a file resource by identifier. You can get the organisation unit information from the `organisationUnits` endpoint. If set, the JSON format looks like this: ### ``` GET /api/organisationUnits/{id}

```json
{
  "id": "Rp268JB6Ne4",
  "name": "Adonkia CHP",
  "image": {
    "id":  "{file-resource-id}"
  }
}

The image file resource identifier can be used to make a request to the `fileResources` endpoint to retrieve the file content: ### ``` GET /api/fileResources/{id}/data

`Content-Type`(内容类型)标头将反映正在检索的文件类型。

应用 { #apps } 

### 应用 { #webapi_apps } 

`/api/apps` 端点可用于安装、删除和
列出应用项目。应用项目密钥基于应用项目名称,但与所有
删除了非字母数字字符,并用破折号替换了空格。
*My app!* 将返回密钥 *My-app*。

> **注意**
>
> 在 2.28 之前,应用密钥是从 ZIP 的名称派生的
> 存档,不包括文件扩展名。使用旧格式的 URL
> 仍应在 api 中返回正确的应用项目。

###     / api / 33 / apps

获取应用 { #webapi_get_apps } 

> **注意**
>
> 2.28之前的app属性folderName指的是实际
> 已安装应用项目的路径。能够在云上存储应用项目
> 服务,folderName 的用途已更改,现在将引用应用项目
> 键。

## 您可以通过列出应用项目中的所有应用项目来读取应用项目的密钥
资源并查找 *key* 属性。列出所有已安装的应用项目
JSON:

```bash
curl -u user:pass -H "Accept: application/json" "http://server.com/api/33/apps"

您也可以简单地将Web浏览器指向资源URL: ### http://server.com/api/33/apps 应用列表也可以按应用类型和名称过滤,通过附加 URL 的一个或多个 *filter* 参数: http://server.com/api/33/apps?filter=appType:eq:DASHBOARD_APP&filter=name:ilike:youtube 应用项目名称支持 *eq* 和 *ilike* 过滤器运算符,而 *appType* 仅支持 *eq*。安装应用 { #webapi_install_app } ### 要安装应用项目,可以发出以下命令:

curl -X POST -u user:pass -F file=@app.zip "http://server.com/api/33/apps"

删除应用 { #webapi_delete_app } # OpenAPI

curl -X DELETE -u user:pass "http://server.com/api/33/apps/<app-key>"

重新加载应用 { #webapi_reload_apps } 要强制重新加载当前安装的应用项目,您可以发出以下命令。如果您直接手动添加文件,这很有用到文件系统,而不是通过 DHIS2 用户上传界面。

curl -X PUT -u user:pass "http://server.com/api/33/apps"

在实例之间共享应用 { #webapi_share_apps_between_instances } 如果 DHIS2 实例已配置为使用云存储,应用项目现在将安装并存储在云服务上。这将启用多个实例在已安装的应用项目上共享相同的版本,而不是在每个单独的实例上安装相同的应用项目。 > **注意** > > 在 2.28 之前,安装的应用项目只会存储在实例的 > 本地文件系统。 2.28 之前安装的应用项目仍可在 > 实例已安装,但不会与其他人共享 > 实例,因为它仍然位于实例本地文件系统上。应用商店 { #webapi_app_store } 网络应用项目接口将 DHIS2 应用项目商店的内容以 JSON 表示,可在 `/api/appHub`资源中找到。 /api/33/appHub * 获取应用 { #webapi_get_app_store_apps } * 您可以使用GET请求检索应用项目: * GET /api/33/appHub * JSON响应示例如下所述。 * ```json { [ { "name": "Tabular Tracker Capture", "description": "Tabular Tracker Capture is an app that makes you more effective.", "sourceUrl": "https://github.com/dhis2/App-repository", "appType": "DASHBOARD_WIDGET", "status": "PENDING", "id": "NSD06BVoV21", "developer": { "name": "DHIS", "organisation": "Uio", "address": "Oslo", "email": "dhis@abc.com", }, "versions": [ { "id": "upAPqrVgwK6", "version": "1.2", "minDhisVersion": "2.17", "maxDhisVersion": "2.20", "downloadUrl": "https://dhis2.org/download/appstore/tabular-capture-12.zip", "demoUrl": "http://play.dhis2.org/demo" } ], "images": [ { "id": "upAPqrVgwK6", "logo": "true", "imageUrl": "https://dhis2.org/download/appstore/tabular-capture-12.png", "description": "added feature snapshot", "caption": "dialog", } ] } ] } ``` * 安装应用 { #webapi_install_app_store_apps } * 您可以在 DHIS2 实例上安装应用项目,前提是您拥有适当的权限。使用 `id` 属性引用应用项目应用项目的相关版本。使用 POST 安装应用项目使用版本 ID 请求以下资源: * POST /api/33/appHub/{app-version-id} * OpenAPI { #openapi } * DHIS2 服务器可为其应用项目接口提供 OpenAPI 文档。该文档是根据对实际应用项目接口的分析即时创建的。这意味着该文件是完整的,但由于分析的局限性,可能会丢失或误报细节。由于分析的局限性。 * Both JSON and YAML format are supported by all OpenAPI endpoints. YAML should be requested with `Accept` header of `application/x-yaml`. * To fetch a single document containing all endpoints of the server use: GET /api/openapi.json GET /api/openapi.yaml ### 名称冲突失败通过在端点根路径上附加 `openapi.json` 或 `openapi.yaml` 到端点根路径即可访问特定端点的文档。例如,要为 `/users` 端点生成文档,请使用 GET /api/users/openapi.json GET /api/users/openapi.yaml ### 不一致失败 GET /api/openapi/openapi.json?path=/users&path=/dataElements GET /api/openapi/openapi.yaml?tag=system&tag=metadata 可用的标签有

toc.title

总览

介绍

个人访问令牌 (PAT)

大多数网络开发环境都支持基本

个人访问令牌 (PAT) 是使用 API 时对 DHIS2 进行身份验证的密码替代方法。

HTTP 基本身份验证被认为是不安全的,原因包括

创建令牌

B. 通过 API 创建令牌。

"该类型用于不会被浏览器访问的集成和脚本"。

2. 浏览器上下文

配置令牌

重要:如果您打算在非安全和/或公共环境中使用 PAT 令牌,强烈建议您创建一个单独的专用用户,该用户只能拥有您希望令牌拥有的角色/权限,

允许的 HTTP 方法

这是一个以逗号分隔的 IP 地址列表,用于限制令牌请求的来源。

HTTP 方法

HTTP 引用来源是添加到请求中的一个标头,当您点击链接时,它会显示您点击链接时所在的网站/页面。

重要:这不是一项安全功能。Referer 标头很容易被欺骗。

重要:生成的秘密令牌密钥只会显示一次,因此请务必

注意:记住请求体中的空 JSON 主体 ({})!

```bash

例如:

OAuth2

创建客户端

可用以下命令发送有效负载:

这将给您类似的响应:

响应与获得令牌开始时的响应完全相同。

```bash

在这里,我们可以看到用户试图访问一个

例如,如果要表达 2014 年 3 月 20 日,必须使用

名称

本节将解释标识符方案的概念。

下面列出了可用的全套标识符方案对象类型,

表:查询参数

表格翻译选项

在用户语言环境中过滤了转换数组的数据元素示例:

/api/42/dataElements

请参阅 "模式"部分,了解哪些属性可用。

示例:正常过滤,其中 id 和 code 必须匹配才能具有

示例:过滤所有包含 2nd 的数据元素

include/exclude 的格式允许无限递归。要过滤可以在"根"级只使用字段的名称,

/api/dataElements/ID?fields=idrename(i),namerename(n)

获取集合的大小:

/ api /

表:可用的查询过滤器

http:// /api/schemas/constant.json

```bash

POST / api / categories / IDA / categoryOptions

您还可以手动验证您的有效负载,方法是将其发送到适当的

下面是几个与 DHIS2 相关的示例。请注意,对有效载荷的任何更新都应视为 HTTP PUT 操作,即任何突变都必须产生有效的 PUT 元数据有效载荷。

```

```json

```json

```json

```json

对于支持CSV的端点(如/api/dataElements /api/organisationUnits等我们的元数据端点),您可以使用Accept头部和值text/csv,或者您可以使用扩展名.csv。请注意,不支持复杂对象,我们仅支持id-object集合(因此将返回一个UID列表)。

```

/ api /元数据

对于批量导入,需要一个带有特征集合的 GeoJSON 文件。

名称

DELETE /api/organisationUnits/geometry

POST /api/organisationUnits/{id}/geometry

DELETE /api/organisationUnits/{id}/geometry

要获取XML中所有可用的模式:

默认图标:预装在应用项目中,无法修改或删除。

GET /api/icons?type=CUSTOM

类型

类型

key,keywords,description,fileResourceUid,createdByUserUid,href

当前有两种不同的renderingTypes可用:

表格样式属性

删除源

成功响应示例如下

```json

CategoryOptionCombos are unique in that they are auto-generated by the system, most of the time (imports are allowed with specific expectations, mentioned below). They are generated based on their category model:

CategoryOption

CC1 有 2 个类别 CC1=[C1, C2]

> 注

请求{ #request }

/api/33/programs/orgUnits?programs={programIdA} 、{programIdB}

重要:这不是一项安全功能。`Referer` 标头很容易被欺骗。

注意:记住请求体中的空 JSON 主体 (`{}`)!

示例:过滤所有包含 2^nd 的数据元素

/api/dataElements/ID?fields=id_{rename(i),name}rename(n)

对于支持CSV的端点(如`/api/dataElements` `/api/organisationUnits`等我们的元数据端点),您可以使用`Accept`头部和值`text/csv`,或者您可以使用扩展名`.csv`。请注意,不支持复杂对象,我们仅支持id-object集合(因此将返回一个UID列表)。

`key,keywords,description,fileResourceUid,createdByUserUid,href`

`CategoryOptionCombo`s are unique in that they are auto-generated by the system, most of the time (imports are allowed with specific expectations, mentioned below). They are generated based on their category model:

`CategoryOption`

`ORGANISATION_UNIT_CONTACT` for external messages

项目指示符可在其 `categoryMappingIds` 字段中选择要使用的项目映射。