钉钉管理插件

1.1 版本

1.2 应用场景

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

1.3 功能简介

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

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

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

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

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

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

2.1 环境准备

2.1.1 安装插件

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

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

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

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

2.1.2 配置网络环境

在钉钉集成之前，必须先完成网络环境配置，参考文档：微信钉钉集成环境准备

2.2 新建H5微应用

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

2）打开「应用开发>企业内部开发」界面，点击「创建应用」，如下图所示：

3）填写创建应用的相关信息：①应用类型选择「H5微应用」；②填写对应的应用信息；③开发方式选择「企业内部自主开发」。填写完成点击「确认创建」。本文示例的应用名称为「文档测试」，如下图所示：

2.3 配置H5微应用

配置「文档测试」应用的开发管理信息。点击「开发管理>修改」进入配置界面。

具体如下：①开发模式选择「开发应用」；②设置服务器出口 IP；③填写应用首页地址（可以先填数据决策系统的地址，具体的地址需要在后续步骤生成后，将生成的链接再粘贴过来）。点击「保存」完成配置。如下图所示：

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

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

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

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

• 打开 cmd 命令窗口，输入如下指令：ping 域名（内网映射到外网的域名）如下图所示：

2.4 发布H5微应用

在「文档测试」应用中点击「版本管理与发布>确认发布」。发布后，设置应用的可使用范围，并点击「保存」。如下图所示：

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

2.5 获取应用参数值

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

2）在「文档测试」应用中点击「基础信息」，在「应用凭证」下即可查看 AgentID、AppKey、AppSecret 这三个参数的值。如下图所示：

3）「首页」查看企业的 CorpID，如下图所示：

完成 H5 微应用发布并获取应用参数值后，进入 Finereport 进行后续配置。

2.6 平台中添加钉钉应用

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

2.6.1 保存报表服务器地址

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

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

2.6.2 新建钉钉应用

点击「新建钉钉应用」，输入钉钉应用名称，并将本文 2.5 节已确认的 AgentID、CorpID、AppKey、AppSecret 分别填到钉钉应用 ID、CropID、AppKey、AppSecret 中，点击「确定」。如下图所示：

注：请填写合乎规范的信息，钉钉应用名称、钉钉应用 ID（AgentId）、CropID、AppKey、AppSecret 均不可为空，且钉钉应用名称不可重复。

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

2.7 应用快捷配置

2.7.1 钉钉代理跳转

内网环境：

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

注：当客户需要配置正向代理时，可将对应代理服务器的地址填写在快捷配置这里，具体正向代理的配置可以参考：微信钉钉集成环境准备第 4 节

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

外网环境：

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

2.7.2 生成钉钉链接

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

1）生成访问决策平台的钉钉链接

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

2）生成访问某个模板的钉钉链接

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

注 1：若生成的链接想用于定时调度自定义链接推送、直接访问、挂载到钉钉后台的时候，必须勾选「解析参数值」，否则将导致参数丢失。

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

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

• 设置参数默认值

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

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

• 解析参数值

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

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

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

2.7.3 其他设置

若用户希望 PC 端点击消息推送的链接，能够在外部浏览器下打开内容。则打开按钮「PC端在浏览器打开链接」。

在 PC 端点击推送消息后，钉钉内置浏览器提示「链接将在外部浏览器打开」。

2.7.4 新建钉钉群

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

1）在钉钉开放平台里新增一个权限：chat相关接口的管理权限。步骤详情请参见钉钉帮助文档：企业群消息---概述

否则会出现报错，如下图所示：

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

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

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

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

2.8 修改首页地址链接

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

2.8.1 修改应用首页地址

进入本文 2.3 节中已创建的H5微应用，点击「开发管理>修改」，将 2.7.2 节 生成的链接粘贴到「应用首页地址」，点击「保存」。如下图所示：

2.8.2 填写PC端首页地址

1）版本适配

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

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

2）具体步骤

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

2.9 开启权限

点击「权限管理>通讯录管理」，开启权限。如下图所示：

开通的权限为以下4项：

• 企业员工手机号信息

• 通讯录部门信息读权限

• 成员信息读权限

• 通讯录部门成员读权限

若要实现群消息推送，需要在钉钉开放平台里新增一个权限：chat相关接口的管理权限。

2.10 成员管理

2.10.1 用户匹配方式

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

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

注1：不管集成几个钉钉应用，用户统一进行管理。

注2：切换了匹配方式后，都需要同步一下用户。

钉钉工号匹配：

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

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

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

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

手动匹配：

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

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

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

自定义匹配：

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

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

注 1：自定义匹配时，钉钉用户列填写的是钉钉成员 ID 。

注 2：数据集是用户自己写的做匹配的服务器数据集，钉钉成员ID、用户名选择表内对应的字段。

2.10.2 通讯录更新

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

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

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

注3：时间点设置不要为 00:00，可能会概率导致通讯录同步失败，因为钉钉管理平台那边有接口频率调用限制，限制600次/秒，而大部分企业的时间可能都会使用00:00这个时间点，导致同步失败，通讯录获取的用户信息缺失。

2.11 效果查看

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

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

问题描述：

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

原因分析：

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

解决方案：

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

3.2 内网开放白名单

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

3.3 插件不支持内外网同时配置

若同时配置会出现报错 redirect_uri，以及部分用户登陆有问题。如下图所示：