更新内容:

  1. 私有部署支持开启插件系统;
  2. 支持添加、管理、配置、启用监听器(webhook模式)

使用指南:(功能介绍/使用场景/操作指引) #

在某些情况下除了 ONES 系统通知方式以外,用户对于外部事件的通知,支持通过 Webhook 的方式,用户在提供了钩子地址进行配置后,即可在第三方获取 ONES 的系统消息。例如:应用想要获取新增的工作或状态变更,可以通过 Webhook 接收通知消息。

一、使用方法 #

进入 团队配置中心 > 外部通知 - 监听器 ,即可配置监听器名称、发送模式、URL、设置监听事件和范围,测试成功并保存后,即可在第三方进行监听。

仅限已开启插件系统的私有部署版本,未启用 Webhook 的用户可联系我们服务人员进行升级。

二、Webhook 响应机制 #

ONES 将系统事件的参数,通过 HTTP 协议以 POST 方式通知指定的 URL。在接收到 ONES 的 Webhook 请求后,若因为网络不佳等情况 5 秒内未返回消息 ID 的状态码,系统会认为通知失败,启用重传机制

重传机制: 每条消息至多重发 3 次,当系统 30分钟未检测到任何应答(期间系统每 5 分钟发送一次心跳消息),则判定对端的 Web 服务已失效,将停用 Webhook,用户可在配置界面手动重启。

三、Webhook 消息字段说明 #

消息交互方式分为两种:①系统通知;②心跳信息 #

  • 用户无论是收到的系统通知,还是心跳消息,都需要返回其 ID。如果未收到返回消息,则判定当前消息发送失败。
  • 接收通知消息的服务可以按照需要继续处理,心跳消息可以直接应答后抛弃。通知消息和心跳消息都是 json 标准的字符串。
  • 我们在消息中提供了部分描述信息,以便于用户的使用。根据这些描述信息,用户可以直接得到一个可读性高的消息(与我们在微信或者 ONES 网页右上角收到的通知一样),而不需要根据某些 ID 去查询其对应的值。
{
"id": "hhqS4Wa3UQYJeHZv"
}
{
"id": "SWzhDqzxDDzgsJPB",
"messages": [
{
"from_user": {
"uuid": "6ZpgEzkk",
"name": "贝加庞克"
},
"to_users": [],
"title": "[onePiece]双方各被污染",
"desc": "贝加庞克 将属性「状态」修改为「已计划」",
"url": "https://xxxxxxx/#/team/BDfDqJU7/project/6ZpgEzkkmkvOVIU6/issue_type/GwNxpqQh/task/6ZpgEzkkUmmWMLeg",
"task_uuid": "6ZpgEzkkUmmWMLeg",
"issue_type_uuid": "GwNxpqQh",
"issue_type_name": "需求",
"event_type": "update_task_status",
"event_name": "更新任务状态",
"raw_message": {
"uuid": "P6KGV72t",
"team_uuid": "BDfDqJU7",
"ref_type": "project",
"ref_id": "6ZpgEzkkmkvOVIU6",
"type": "system",
"from": "BOT",
"to": "6ZpgEzkkmkvOVIU6",
"send_time": 1583152234311552,
"subject_type": "user",
"subject_id": "6ZpgEzkk",
"action": "update",
"object_type": "task",
"object_id": "6ZpgEzkkUmmWMLeg",
"object_name": "双方各被污染",
"object_attr": "field",
"old_value": "SriNNDVw",
"new_value": "FXapje9B",
"ext": {
"field_name": "状态",
"field_type": 12,
"field_uuid": "field005",
"new_option": {
"name": "已计划",
"uuid": "FXapje9B"
},
"new_value": "",
"old_option": {
"name": "进行中",
"uuid": "SriNNDVw"
},
"old_value": "",
"parent_message_uuid": "FBRsgsj3"
    },
"is_can_show_richtext_diff": false
}
}
]
}

直接以字符串写入应答的消息体

hhqS4Wa3UQYJeHZv
事件字段名类型说明
消息类型idstring消息体唯一标识 16位
消息类型messages[]message消息体数组(目前消息推送只支持推送单条消息)
Messagefrom_useruser消息来源
Messageto_users[]userONES 体统内的配置的消息通知列表
Messagetitlestring消息标题:格式 [团队名称]工作项名称
Messagedescstring消息描述 格式:who [do_what]
Messageurlstring工作项 url 地址
Messagetask_uuidstring工作项UUID
Messageissue_type_uuidstring工作项类型UUID
Messageissue_type_namestring作项类型名称
Messageevent_typestring事件类型
Messageevent_namestring事件名称
Messageraw_messagerawONES 系统中消息体
Useruuidstring用户UUID
Usernamestring用户名称
Rawuuidstringmessage uuid
Rawteam_uuidstring团队uuid
Rawref_typestring消息引用类型: task:工作项 project:项目
Rawref_idstring消息引用类型的uuid: 如果"ref_type"是"task"的话,那么"ref_id"的值就是工作项uuid 如果"ref_type"是"project"的话,那么"ref_id"的值就是项目uuid
Rawtypestring消息类型: discussion:评论类型动态 system:系统类型动态
Rawfromstring谁发送的消息: BOT:代表系统
Rawtostring操作的实体:某个工作项或者某个项目
Rawsend_timeint64发送时间
Rawtextstring当"type"为"discussion"才有,评论的内容
Rawis_can_show_richtext_diffbool是否能查看工作项描述的diff
Rawsubject_typestring一般值为"user”
Rawsubject_idstring操作人uuid
Rawactionstring操作类型: add:新增 update:更新 delete:删除 move:移动 copy:复制
Rawobject_typestring消息实体uuid
Rawobject_namestring消息实体名称
Rawobject_attrstring消息实体属性
Rawnew_valuestring更新后的值
Rawextext修改数据说明
Extfield_uuidstring属性UUID
Extfield_namestring属性名称,omitempty
Extfield_typeint属性类型
Extold_valuestring属性旧值
Extnew_valuestring属性新值
Extold_optiondesc旧属性项,omitempty
Extnew_optiondesc新属性项,omitempty
Extnew_multi_option[]desc旧属性项列表,omitempty
Extold_multi_option[]desc新属性项列表,omitempty
Extbatch_actionstring批处理动作
Extparent_message_uuidstring主消息UUID
Exttrigger_task_uuidstring触发工作项UUID
Exttrigger_task_titlestring触发工作项标题
DescuuidstringUUID
Descnamestring名称