历史版本37 :钉钉集成 返回文档
编辑时间: 内容长度:图片数:目录数: 修改原因:

目录:

1. 概述编辑

1.1 版本

报表服务器版本JAR 包版本钉钉管理插件版本功能变动
10.0 2019-05-2010.2.34-
2020-08-0310.4.97支持是否解析参数值
10.4.976新增配置钉钉群入口,支持群消息推送

注1:报表服务器必须是能够访问外网的, http 协议访问端口号推荐使用 80;https 协议访问端口号推荐使用 443 。

注2:钉钉管理插件支持代理服务器配置,若有些用户报表服务器是配置在内网,则需要配置代理服务器地址,来进行钉钉的访问,配置方法参见 代理服务器配置

1.2 应用场景

用户如果将钉钉作为移动端办公平台,可以通过安装此插件直接将报表集成到钉钉中,以钉钉为统一入口进行报表的查看。

1.3 功能简介

  • 安装钉钉管理插件,就可以实现钉钉集成。

  • 在钉钉管理中配置钉钉平台的基本参数,就可以读取到钉钉平台通讯录,将报表用户与钉钉用户绑定,就可以实现单点登录。

  • 在定时调度的输出设置中,可以配置并推送钉钉消息。

  • 支持集成多个企业应用,进行钉钉升级时请注意进行兼容设置。

注1:钉钉集成下若使用「扫码控件」, 要求 单点登录

注2:JAR 包为 2020-04-26 及之后、「钉钉管理」插件版本为 V10.4.69 及之后时,钉钉集成支持 集群

2. 示例编辑

2.1 安装插件

点击下载插件:钉钉管理HTML5 移动端展现插件

设计器插件安装方法参照 设计器插件管理

服务器安装插件方法参照 服务器插件管理

注:微信/钉钉集成过程中,必须确保各版本相对应,请参见:微信、钉钉、H5、服务器、JAR 之间的依赖关系

2.2 新建 H5 微应用

1)管理员登录钉钉企业号,在「工作台」Tab 页下点击自建应用,如下图所示:

7.png

2)在左侧 Tab 中点击H5微应用,点击创建应用,如下图所示:

8.png

2.3 配置 H5 微应用

1)填写应用名称,上传应用 Logo,填写应用简介,开发方式选择企业内部自主开发,点击下一步。如下图所示:

9.png

2)开发模式选择开发应用,开发应用类型选择微应用,应用首页地址可以先填数据决策系统的地址,具体的地址需要在后续步骤生成后,将生成的链接再粘贴过来,设置服务器出口 IP,点击创建。如下图所示:

20.png

服务器出口 IP 获取方法本文提供 4 种,如下所示:

  • 百度浏览器输入 IP 获取地址

  • 点击右边链接获取:获取服务器出口IP

  • Linux 系统中,输入curl ifconfig.me 获取

  • 打开 cmd 命令窗口,输入如下指令:ping 域名(内网映射到外网的域名)如下图所示:

1587985281312087.png

2.4 应用发布

在 应用发布 Tab 页下点击确认发布,选择可使用范围后,点击保存修改。如下图所示:

注:可使用范围应以部门为主,不能选择到个人。

21.png

2.5 获取参数值

1)需获取的四个参数及说明如下表所示:

  参数 说明
AgentID在创建应用时,系统会自动生成一个 AgentID,可用于发送企业会话消息等场景
AppKey在创建应用时,系统会自动分配一对 AppKey 和 AppSecret,该 AppKey 是应用开发过程中的唯一性标识
AppSecret AppSecret 和上面 AppKey 一同生成,使用 AppKey 和 AppSecret 来换取 access_token
CorpID企业 ID

2)在新创建的应用中点击查看详情,即可查看 AgentID、AppKey、AppSecret 这三个参数的值。如下图所示:

12.png

3)首页查看企业的 CorpID,如下图所示:

13.png

2.6 平台中添加钉钉应用

以管理员身份进入数据决策系统,点击管理系统>钉钉管理,如下图所示:

11.png

2.6.1 保存报表服务器地址

必须设置报表服务器地址并保存,如果不设置,推送的时候可能会有问题,例如:http://secure.finedevelop.com:65081/webroot/decision

输入「报表服务器地址」,如下图所示:

14.png

2.6.2 新建钉钉应用

点击新建钉钉应用按钮,将本文 2.4 节已确认的 AgentID、CorpID、AppKey、AppSecret 分别填到钉钉应用 IDCropIDAppKeyAppSecret 中,点击确定。如下图所示:

15.png

注:请填写合乎规范的信息,钉钉应用名称、钉钉应用 ID(AgentId)、CropID、AppKey、AppSecret 均不可为空,且钉钉应用名称不可重复。

新建钉钉应用成功后,可对信息进行修改和删除,支持集成多个钉钉应用。如下图所示:

16.png

2.7 应用快捷配置

2.7.1 钉钉代理跳转

内网环境:

若报表服务器是配置在内网,则需要配置代理服务器地址,来进行钉钉的访问。如下图所示:
1611285946332074.png

注:钉钉集成既需要设置正向代理,也需要设置反向代理,配置方法参考 代理服务器配置

文本框中输入正确的代理服务器地址,点击测试连接,连接成功后,会提示信息:连接成功

外网环境:

外网环境不需要设置代理服务器地址。

2.7.2 生成钉钉链接

该功能可以生成访问决策平台或某个模板的链接,通过 模板消息事件插件 可以将该链接推送给移动端用户,用户点开后即可访问链接对应的内容。

1)生成访问决策平台的微信链接

首先要选择企业应用名称,链接页面下拉选择决策平台,点击生成链接后,点击复制按钮即可,如下图所示:

1611286073292883.png

2)生成访问某个模板的微信链接

首先要选择企业应用名称,链接页面下拉选择单个模板,然后选择一张模板,如果需要设置参数,可以点击设置参数默认值进行设置,设置了参数后可以根据自己的需要选择是否解析参数值,最后点击生成链接,点击复制按钮即可,如下图所示:

1611286261594710.png

下面介绍下如何配置参数,如果想要使用设置参数默认值功能需要将插件更新到 10.4.76 版本,如果想要使用解析参数值功能需要更新到 10.4.97 版本。

  • 设置参数默认值

点击设置参数默认值后,如果模板本身有参数,那么会显示在下方,用户可以设置参数的默认值,当然也可以点击右上角新增参数,如下图所示:

注:如果想删除参数,可以鼠标悬浮在参数列表的右边,会出现删除按钮。

1611286407519158.png

  • 解析参数值

假如一张模板a.cpt设置了一个参数date,其值为公式${today}

如果勾选了解析参数值,那么点击生成链接后,链接中会自动解析出今天的日期,也就是变成了:a.cpt&date=2020-11-03

如果不想链接中直接解析参数,想要保留这个公式,可以取消勾选解析参数值,点击生成链接后,公式保留:a.cpt&date=${today}

1611286451987782.png

注1:微信/钉钉集成链接必须勾选解析参数值,否则将导致参数丢失。

注2:模板消息推送的消息链接可选择不解析参数值,从而实现推送的公式计算。

2.7.3 新建钉钉群

10.4.976 版本新增的功能,可以给钉钉应用新建钉钉群,支持通过定时调度推送群消息到钉钉群。建群方法如下:

1)在钉钉开放平台里新增一个权限:企业会话。步骤详情请参见钉钉帮助文档:企业群消息---概述

否则会出现报错,如下图所示:

钉钉返回失败信息为:{'errcode':60011,'errmsg':'没有调用该接口的权限,接口权限申请参考:https://ding-doc.dingtalk.com/doc#/serverapi2/rnomdt'}

企业微信截图_16136357871830.png

2)开启企业会话权限后,点击「新建钉钉群」,选择「钉钉应用」,填写「钉钉群名称」,选择「群主」和「群成员」,如下图所示:

注:所有设置项均不允许为空。

1611286974790342.png

10.4.976 版本支持推送钉钉群消息,详细介绍参见文档:钉钉定时推送消息

1611295457611078.png

2.8 修改首页地址链接

用户若需要设置 PC 端单点登录,参考本文 2.8.2 节内容;若不需要设置 PC 端单点登录,请忽略本文 2.8.2 节内容。

2.8.1 应用首页地址

1)进入本文 2.3 节中已创建的H5微应用,点击查看详情>修改,如下图所示:

12.png

2)将生成的链接粘贴到应用首页地址,点击提交,如下图所示:

19.png

2.8.2 PC 端首页地址

1)版本适配

JAR 为 2019-12-05 及之后,钉钉管理插件为 V10.4.69 及之后,HTML5 移动端展现插件版本为 V10.4.45 及之后时,钉钉集成支持 PC 端单点登录 。

注:若用户版本不满足该条件,升级 JAR 包和插件后,重新生成钉钉链接。用户清理 PC 端钉钉登录的缓存,即可单点登录。

2)具体步骤

用户若需要设置 PC 端单点登录 ,需填写「PC端首页地址」,该地址与「应用首页链接」地址一致。如下图所示:

1608630426119160.png

2.9 开启权限

点击接口权限,开启通讯录只读权限手机号码信息权限。如下图所示:

20.png

2.10 成员管理

2.10.1 用户匹配方式

可根据实际情况选择一种用户匹配方式。

用户匹配方式:钉钉工号匹配手机号匹配手动匹配自定义匹配,默认为钉钉工号匹配。「成员管理」页面如下图所示:

注:不管集成几个钉钉应用,用户统一进行管理。

4.png

钉钉工号匹配:

钉钉工号匹配手机号匹配展示列相同。

钉钉工号匹配,则是钉钉工号与报表里的用户名匹配,为一对一匹配。

手机号匹配,钉钉用户的手机号是唯一的,但是报表用户可以设置多个用户有同一个手机号,此时的匹配逻辑为哪个报表用户先创建则匹配哪个

选择这两个匹配方式时,钉钉通讯录信息展示:姓名钉钉工号钉钉成员ID钉钉部门钉钉成员手机号,如下图所示:

24.png

手动匹配:

当匹配方式为手动匹配时,钉钉成员列表中多出「报表用户名」一列信息,点击出现下拉框,选择相应的报表用户名,进行手动匹配。如下图所示:

注1:手动匹配时,报表用户名支持选择「不选」选项。

注2:手动匹配方式是用户可以自由选择与钉钉用户匹配的报表用户,可实现多个钉钉用户匹配同一个报表用户。

1589945982516853.png

自定义匹配:

即通过设置的服务器数据集,将对应数据列的钉钉用户和报表用户相匹配。若出现一个钉钉用户对应了多个报表用户的情况,默认匹配第一个报表用户

选择自定义匹配时,下方多出「匹配设置」项,选择数据集钉钉成员ID以及报表用户名,进行匹配。如下图所示:

注:自定义匹配时,钉钉用户列填写的是钉钉成员 ID 。

26.png

2.10.2 通讯录更新

点击左侧立即更新按钮,立即更新通讯录内容。也可设置定时更新,点击自动更新按钮,弹出设置框,设置更新频率。如下图所示:

注1:用户匹配方式为「钉钉工号匹配」或「手机号匹配」时,如果用户增删改报表用户或者在后台增删改钉钉用户,需要手动同步通讯录更新。

注2:用户匹配方式为「手动匹配」或「自定义匹配」时,如果用户增删改报表用户或者在后台增删改钉钉用户,无需更新同步。

27.png

2.11 效果查看

登录钉钉,点击工作台>文档测试,该用户会看到自己权限内可以查看的目录,如下图所示:

1587987383350158.jpg

3. 注意事项编辑

3.1 推送到钉钉的模板报表块展示异常

问题描述:

设置定时调度任务推送包含报表块的决策报表给钉钉,其中「文件处理」步骤客户端通知中,「链接」选择定时结果链接,报表块展示异常。如下图所示:

13.png

原因分析:

模板受到 PC 端自适应属性 的影响。

解决方案:

「文件处理」步骤客户端通知中,「链接」选择自定义链接。如下图所示:

14.png

3.2 内网开放白名单

在做钉钉集成时,有的客户为内网环境,不允许所有网页都能访问,但要确保能访问钉钉的域名:https://oapi.dingtalk.com/