1. 安装禅道
1.1  选择适合您的安装方法
1.2  使用云禅道在线项目管理服务!
1.3  (推荐)windows用一键安装包安装
1.4  (推荐)linux用一键安装包
1.5  linux下用lampp集成包安装
1.6  使用源码包安装(MAC系统)
1.7  MAC下用XAMPP安装禅道
1.8  MAC下用XAMPP-VM安装禅道
1.9  禅道一键安装包里安装蝉知和ZDOO
1.10  使用源码包安装(各系统通用)
1.11  宝塔面板安装禅道
1.12  华芸NAS在线安装
1.13  Centos7.4系统下安装httpd,mariadb,php7.2环境运行禅道
1.14  Centos8系统下安装httpd,mariadb,php7.2环境运行禅道
1.15  安装ioncube扩展
1.16  Docker方式部署禅道
2. 禅道介绍
2.1  关于禅道项目管理软件
2.2  禅道介绍PPT下载
2.3  如何获得支持
2.4  关注我们
3. 升级禅道
3.1  选择和自己环境对应的升级方式
3.2  通过源代码方式升级(通用)
3.3  windows一键安装包的升级
3.4  linux一键安装包升级
4. 创建分组和用户
4.1  建立部门结构
4.2  添加一个用户帐号
4.3  批量维护帐号
4.4  设置分组,建立权限体系
5. 最简使用
5.1  使用禅道来进行项目任务管理
5.2  只使用禅道来做bug管理
5.3  只使用禅道来进行产品管理
5.4  个人使用禅道来做事务跟踪管理
6. 基本使用
6.1  禅道使用的基本流程和产品、研发、测试之间的三权分立
6.2  敏捷开发及scrum简介
6.3  禅道和scrum的对应关系
6.4  禅道的新手教程
6.5  创建第一个产品
6.6  添加第一个需求
6.7  开始第一个项目
6.8  确定项目要完成的需求列表
6.9  为需求分解任务
6.10  提交bug
6.11  视频教程:第一个演示项目
6.12  维护联系人
6.13  禅道的自定义功能
6.14  导入excel、csv参考文档
6.15  文档管理
6.16  工作方式的切换
6.17  操作获取积分功能
6.18  自定义必填项功能
6.19  如何排查产品、项目是否有访问权限
6.20  年度总结,工作内容统计一览表说明
7. 进阶使用
7.1. 使用流程
7.1.1  禅道使用流程图解
7.2. 个人管理
7.2.1  使用待办进行个人事务管理
7.2.2  关注需要自己处理的任务、需求、bug
7.2.3  通过我的档案查看或者修改个人信息
7.2.4  视频教程:禅道使用之个人篇
7.3. 产品经理篇
7.3.1  维护产品
7.3.2  维护产品线
7.3.3  创建和评审需求
7.3.4  变更和评审需求
7.3.5  需求的状态和研发阶段
7.3.6  需求的注意事项
7.3.7  维护产品模块
7.3.8  建立发布计划
7.3.9  建立发布
7.3.10  路线图
7.3.11  文档管理
7.3.12  主持产品会议
7.3.13  参与项目管理、演示和总结
7.3.14  需求的基本统计报表
7.3.15  视频教程:禅道使用之产品经理篇
7.4. 项目经理篇
7.4.1  建立项目
7.4.2  组建项目团队
7.4.3  确定项目要完成的需求列表
7.4.4  组织进行任务分解
7.4.5  召开每天的站立会议
7.4.6  通过燃尽图了解项目的进展
7.4.7  通过各种列表的各种功能了解项目进展
7.4.8  召开演示会议和总结会议
7.4.9  项目任务基本的报表统计
7.4.10  视频教程:禅道使用之项目经理篇
7.5. 开发团队篇
7.5.1  参加项目计划会议,分解任务
7.5.2  领取任务,并每天更新任务
7.5.3  通过看板和树状图查看任务
7.5.4  创建版本
7.5.5  申请测试
7.5.6  解决bug
7.5.7  文档管理
7.5.8  确认bug
7.5.9  视频教程:禅道使用之开发团队篇
7.6. 测试团队篇
7.6.1  维护bug视图模块
7.6.2  提交bug
7.6.3  验证bug,关闭
7.6.4  激活bug
7.6.5  找到自己需要的bug
7.6.6  维护测试用例视图
7.6.7  创建测试用例
7.6.8  测试套件、报告和公共用例库的维护
7.6.9  管理测试版本
7.6.10  执行用例,提交Bug
7.6.11  查看报表统计
7.6.12  视频教程:禅道使用之测试团队篇
8. 维护配置
8.1. 维护禅道
8.1.1  初始化管理脚本
8.1.2  备份禅道
8.1.3  恢复删除的资源
8.1.4  如何更新燃尽图
8.1.5  一键安装包如何实现mysql异机连接
8.2. 配置禅道
8.2.1  设置是否允许匿名访问
8.2.2  如何配置email发信
8.2.3  禅道云发信
8.2.4  如何成为超级管理员
8.2.5  配置禅道系统为静态访问
8.2.6  去掉禅道访问地址中的zentao
8.2.7  集成禅道和svn
8.2.8  集成禅道和git
8.2.9  在第三方应用中集成禅道
8.2.10  第三方应用配置免密登录禅道
8.2.11  第三方应用集成禅道客户端进行消息通知
8.2.12  集成webhook
8.2.13  集成ZDOO
8.2.14  客户端集成
8.2.15  禅道的翻译功能
8.2.16  浏览器通知的设置
8.2.17  集成钉钉工作消息通知
8.2.18  企业微信群机器人
8.2.19  集成企业微信应用消息通知
8.2.20  集成版本库、集成Jenkins,并进行构建
9. 定制开发
9.1  二次开发机制
9.2  禅道的目录结构
9.3  找到要修改的文件
9.4  禅道的数据库结构
9.5  公用模块--common
9.6  如何登记菜单
9.7  如何登记权限
9.8  示例:如何修改禅道的语言提示?
9.9  示例:创建bug时可以设置优先级字段
9.10  使用在线扩展编辑器
9.11  二次开发编辑器和翻译功能限制使用说明
9.12  禅道项目管理软件打包规范1.1版本
10. 其他相关
10.1  禅道所使用到的第三方代码
10.2  禅道FAQ
10.3  如何帮助禅道项目
10.4  禅道商业服务
10.5  禅道项目的贡献者
10.6  历史修改记录

第三方应用集成禅道客户端进行消息通知

2018-12-20 16:34:29
先知
9782
最后编辑:王怡栋 于 2020-06-18 16:15:38
分享链接

禅道开源版11.0版本集成了禅道客户端功能。

禅道里的消息通知可以发送到禅道客户端, 同时增加了消息通知接口。

与禅道集成的第三方应用,也可以通过该消息通知接口,将第三方应用的消息发送到禅道客户端里。

本文将详细介绍第三方应用如何集成禅道客户端进行消息通知。

一、设置应用集成 

第三方应用要与禅道做集成,具体请参考: http://www.zentao.net/book/zentaopmshelp/integration-287.html

二、签名机制

第三方应用在请求喧喧数据时所调用的 API 的请求地址格式为:

/x.php?m=$moduleName&f=$methodName$params&code=$code&token=$token

以上请求地址格式中的变量定义如下:

  • $moduleName :要调用的 API 所属模块名称(通常为 “im”),必须提供;

  • $methodName :要调用的 API 所属模块内的方法名称,如果缺省则为 index ;

  • $params :要调用的 API 方法参数,如果没有参数可以留空,如果所调用的 API 方法有参数则将参数名和参数值通过通用网址查询字符串的形式插入到 $params 所在位置,例如 gid=XXX ;

  • $code :应用代号,必须提供;

  • $token :调用 API 时的数字签名。

例如获取讨论组 gid 为 64da14c3-c07a-45af-9c61-4e638de4af26 中的用户数据请求地址为:


/x.php?m=im&f=getChatUsers&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8


签名算法

API 请求地址中的数字签名 $token 应该在每次调用时根据应用集成密匙生成,具体算法为:

$token = md5(md5($query) + $key)

以上公式包含的变量定义如下:

  • $query :请求地址中查询字符串(? 之后的部分)不包含 &token=$token 的部分;

  • $key :应用密匙(必须为小写形式)。

例如:

// 查询参数
var $query = 'm=chat&f=getChatUsers&code=myAppCode';
// 应用密匙
var $key   = '3cd0914d656e90ab181f1d52ff352cfe';
// 计算签名字符串
var $token = md5(md5('m=im&f=getChatUsers&code=myAppCode') + '3cd0914d656e90ab181f1d52ff352cfe');
// 这样 $token 的计算值为 'f5633c34c0c551a16c1d63bceb38d6a8'

下面将详细说明第三方应用在完成和禅道的集成后如何通过禅道客户端进行消息通知。

三、通过禅道客户端进行消息通知

下面列出目前第三方应用可以使用的 API。

im/getChatGroups

此接口用于获取系统中的讨论组会话列表。

  • 请求方式:GET;
  • 模块名称:im;
  • 方法名称:getChatGroups;
  • 参数:无;
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称 类型 说明
result 字符串 如果为'success'则操作成功,如果为其他值则表示操作失败
message 字符串 如果操作失败,则使用此属性返回失败原因提示文本
data 对象 该对象定义了系统中的讨论组清单,对象属性名为讨论组的全局唯一 标识字符串(GID),属性对应的值为讨论组名称

下面为一个示例请求地址:

      https://myxxb.com/x.php?m=im&f=getChatGroups&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

正常情况下返回值如下:

      {
    "result": "success",
    "data": {
        "30683aea-7a1f-4ec8-a6d6-834e0310fd7d": "第四期项目讨论",
        "81c6ba89-00ab-4431-8e47-063556ae4886": "研发部",
        "64da14c3-c07a-45af-9c61-4e638de4af26": "公司总群"
    }
} 

im/getChatUsers

此接口用于获取指定讨论组中的成员信息或者获取系统中全部成员信息。

  • 请求方式:GET;

  • 模块名称:im;

  • 方法名称:getChatUsers;

  • 参数:

    • gid:设置为要获取用户成员信息的讨论组的全局唯一 标识字符串(GID),如果留空,则请求会返回系统所有成员信息。
  • 返回值:JSON 对象,该对象属性定义如下:

属性名称 类型 说明
result 字符串 如果为'success'则操作成功,如果为其他值则表示操作失败
message 字符串 如果操作失败,则使用此属性返回失败原因提示文本
data 对象 该对象定义了成员清单,对象属性名为成员 ID,属性对应的值为成员显示名称

下面为获取 GID 为'30683aea-7a1f-4ec8-a6d6-834e0310fd7d'的讨论组成员信息的示例请求地址:

https://myxxb.com/x.php?m=im&f=getChatUsers&gid=30683aea-7a1f-4ec8-a6d6-834e0310fd7d&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

正常情况下返回值如下:

{
    "result": "success",
    "data": {
        "1": "管理员",
        "3": "张三",
        "4": "李四"
    }
} 

im/sendNotification

此接口用于向通知中心(小喧喧)推送通知消息。

  • 请求方式:POST;
  • 模块名称:im;
  • 方法名称:sendNotification;
  • 参数:无;
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称 类型 说明
result 字符串 如果为'success'则操作成功,如果为其他值则表示操作失败
message 字符串 如果操作失败,则使用此属性返回失败原因提示文本

将要推送的通知消息对象转换为 JSON 字符串形式,然后通过 POST 请求发送到服务器。

一个通知消息对象拥有如下属性:

属性名称 类型 可选性 说明
users 数组 特定条件必须 使用一个用户 ID 数组指定通知发送给哪些用户,例如[1, 4],也可以指定一个用户账号组成的数组,例如['admin', 'zhangsan', 'lisi']
title 字符串 必须 通知消息的标题
subtitle 字符串 可选 通知消息的副标题
content 字符串 可选 通知消息的内容文本
contentType 字符串 必须 可选值包括:'plain'表示纯文本,'text'表示 Markdown 格式的文本
url 字符串 可选 该通知消息所指向的网页链接
actions 对象数组 可选 使用 操作对象数组表示该通知支持的操作
sender 对象 可选 通知的 发送方信息对象

通知的 操作对象包含如下属性:

属性名称 类型 可选性 说明
label 字符串 必须 操作按钮上显示的文本
icon 字符串 可选 操作按钮上显示的图标
url 字符串 必须 点击此操作按钮时要打开的页面链接
type 字符串 可选 操作按钮类型,影响操作按钮外观,可选值包括'primary'、'success'、'danger'、'warning'、'info'、'important'、'special'

发送方信息对象包容如下属性:

属性名称 类型 可选性 说明
id 字符串或数字 必须 标识发送方唯一身份的字符串或数字
name 字符串 可选 发送方在界面上显示的名称
avatar 字符串 必须 发送方头像图片链接地址

下面为一个发送通知消息的示例 POST 请求地址:

https://myxxb.com/x.php?m=im&f=sendNotification&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

下面为使用 JavaScript Fetch API 发起请求示例代码:

const notifycationData = {
    users: [1, 3],
    title: '测试通知消息',
    subtitle: '测试通知消息副标题',
    content: '**测试消息**内容',
    contentType: 'text',
    url: 'http://xuan.im',
    actions: [
        {
            type: 'danger',
            label: '更新日志',
            url: 'https://xuan.im/page/changelogs.html'
        }, {
            type: 'normal',
            label: '下载地址',
            url: 'http://xuan.im/page/download.html'
        }
    ],
    sender: {
        avatar: 'https://avatars2.githubusercontent.com/u/472425?s=460&v=4',
        name: 'Catouse',
        id: 'catouse'
    }
};
const postUrl = 'https://myxxb.com/x.php?m=im&f=sendNotification&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8';
fetch(postUrl, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(data)
}).then(r => {
    return r.json();
}).then(response => {
    if (response && response.result === 'success') {
        console.log('操作成功');
    }
}); 

正常情况下返回值如下:

{ "result": "success" }

im/sendChatMessage

此接口用于向指定的讨论组推送通知消息。

  • 请求方式:POST;
  • 模块名称:im;
  • 方法名称:sendChatMessage;
  • 参数:无;
  • 返回值:JSON 对象,该对象属性定义如下:
属性名称 类型 说明
result 字符串 如果为'success'则操作成功,如果为其他值则表示操作失败
message 字符串 如果操作失败,则使用此属性返回失败原因提示文本

将要推送的通知消息对象转换为 JSON 字符串形式,然后通过 POST 请求发送到服务器。

一个通知消息对象拥有如下属性:

属性名称 类型 可选性 说明
gid 字符串 特定条件必须 为讨论组的全局唯一字符串,指定通知发送到的讨论组,当向讨论组发送通知时必须(即receiver为'group')
title 字符串 必须 通知消息的标题
subtitle 字符串 可选 通知消息的副标题
content 字符串 可选 通知消息的内容文本
contentType 字符串 必须 可选值包括:'plain'表示纯文本,'text'表示 Markdown 格式的文本
url 字符串 可选 该通知消息所指向的网页链接
actions 对象数组 可选 使用 操作对象数组表示该通知支持的操作
sender 对象 可选 通知的 发送方信息对象

通知的 操作对象包含如下属性:

属性名称 类型 可选性 说明
label 字符串 必须 操作按钮上显示的文本
icon 字符串 可选 操作按钮上显示的图标
url 字符串 必须 点击此操作按钮时要打开的页面链接
type 字符串 可选 操作按钮类型,影响操作按钮外观,可选值包括'primary'、'success'、'danger'、'warning'、'info'、'important'、'special'

发送方信息对象包容如下属性:

属性名称 类型 可选性 说明
id 字符串或数字 必须 标识发送方唯一身份的字符串或数字
name 字符串 可选 发送方在界面上显示的名称
avatar 字符串 必须 发送方头像图片链接地址

下面为一个发送通知消息的示例 POST 请求地址:

https://myxxb.com/x.php?m=im&f=sendChatMessage&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8

下面为使用 JavaScript Fetch API 发起请求示例代码:

const notifycationData = {
    gid: 'f3de9ff9-dcb4-49de-915b-377ee9143418',
    title: '测试通知消息',
    subtitle: '测试通知消息副标题',
    content: '**测试消息**内容',
    contentType: 'text',
    url: 'http://xuan.im',
    actions: [
        {
            type: 'danger',
            label: '更新日志',
            url: 'https://xuan.im/page/changelogs.html'
        }, {
            type: 'normal',
            label: '下载地址',
            url: 'http://xuan.im/page/download.html'
        }
    ],
    sender: {
        avatar: 'https://avatars2.githubusercontent.com/u/472425?s=460&v=4',
        name: 'Catouse',
        id: 'catouse'
    }
};
const postUrl = 'https://myxxb.com/x.php?m=im&f=sendChatMessage&code=myAppCode&token=f5633c34c0c551a16c1d63bceb38d6a8';
fetch(postUrl, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(data)
}).then(r => {
    return r.json();
}).then(response => {
    if (response && response.result === 'success') {
        console.log('操作成功');
    }
}); 

正常情况下返回值如下:

{ "result": "success" }
评论列表
程先生 2020-05-18 17:36:47
请求的数据为:{users:[75],content:'124679',contentType:'text',gid:'',receiver:'users',subtitle:'待办任务',title:'服务治理平台消息通知',url:'www.baidu.com',userList:[75]} ,响应的数据为:{"result":false,"message":"没有设置接收者类型,只能是用户或者是某个讨论组。"},请问是什么问题,是按照API文档进行的上送
石洋洋 2020-05-18 17:51:08
这个文档中的接口新版客户端已经更新了,可以先参考:https://www.xuanim.com/book/dev/141.html
1/1
发表评论
评论通过审核后显示。