For the complete DHIS2 documentation index, see llms.txt.

讯息传递¶

讯息对话¶

DHIS2 具有发送消息的机制，例如用户反馈、通知和给用户的一般信息。留言被分组到对话中。与消息对话交互您可以向 messageConversations 发送 POST 和 GET 请求资源。

/ api / 33 / messageConversations

消息会传送到 DHIS2 消息收件箱，但也可以发送以短信形式发送到用户的电子邮件地址和手机。在这个例子中，我们将看到如何利用 Web API 来发送、读取和管理消息。我们将伪装成*DHIS2管理员*用户并发送给*移动*用户的消息。然后我们会假装是手机用户并阅读我们的新消息。在此之后，我们将管理管理员用户收件箱通过标记和删除邮件。

撰写和阅读邮件¶

我们在发送和阅读消息时需要交互的资源是 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>

为了发送给连接到一个或多个组织单位的所有用户，我们可以使用：

<message xmlns="http://dhis2.org/schema/dxf/2.0">
  <subject>This is the subject</subject>
  <text>This is the text</text>
  <organisationUnits>
    <organisationUnit id="ou1ID" />
    <organisationUnit id="ou2ID" />
    <organisationUnit id="ou3ID" />
  </organisationUnits>
</message>

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:

<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，但是其他运算符可以在查询中定义。

管理讯息¶

随着用户接收和发送消息，对话将开始堆积在他们的收件箱中，最终变得难以跟踪。我们现在将看看通过删除和标记来管理用户的消息收件箱通过 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"
    }
  ]
}

邮件附件¶

创建带附件的消息分两步完成：上传文件添加到 attachments 资源，然后包括一个或几个创建新邮件时的附件 ID。

对 attachments 资源的 POST 请求会将文件上传到服务器。

curl -F file=@attachment.png“ https://play.dhis2.org/demo/api/messageConversations/attachments”
  -u管理员：区

该请求返回一个表示附件的对象。的标识创建消息时必须使用此对象以链接邮件附件。

{
  "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 将上传的文件链接到正在创建的消息。

{
  "subject": "Hey",
  "text": "How are you?",
  "users": [
    {
      "id": "OYLGMiazHtW"
    },
    {
      "id": "N3PZBUlN8vq"
    }
  ],
  "userGroups": [
    {
      "id": "ZoHNWQajIoe"
    }
  ],
  "organisationUnits": [
    {
      "id": "DiszpKrYNg8"
    }
  ],
  "attachments": [
    "fTpI4GOmujz",
    "h2ZsOxMFMfq"
  ]
}

回复消息时，可以将 id 作为请求传递范围。

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 / <uid> / priority

在 2.29 中，验证分析生成的消息现在也用于状态和优先级属性。默认情况下，消息由验证分析将继承验证规则的优先级问题，或者如果消息包含多个最重要的规则。

在 2.30 中，可以将验证规则分配给任何用户，同时工单仍然需要分配给系统反馈接收者中的一个用户团体。

表：有效状态和优先级值的列表

状态	优先事项
打开	低的
待办的	中等的
无效的	高的
解决了

也可以给工单添加内部消息，只能看到拥有“管理票证”权限的用户。创建一个内部回复，包括“内部”参数，并将其设置为

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