反馈已提交

网络繁忙

钉钉集成

  • 文档创建者:ukae
  • 历史版本:76
  • 最近更新:YukiCheng 于 2024-03-26
  • 1. 概述

    1.1 版本

    报表服务器版本钉钉管理插件版本功能变动
    11.0.2V11.0.54钉钉管理支持将钉钉用户同步到「用户管理」,详情见本文 2.10.3 节
    11.0.3V11.0.62
    • 「应用快捷配置>生成钉钉链接」支持生成自定义链接,详情参见本文 2.7.2 

    • 「成员管理」支持同步多个企业的数据

    11.0.9
    V11.0.74优化单点登录性能
    V11.0.84

    可以通过修改fine_conf_entity参数DingTalkConfig.requestConfigEnable的值为true,开启「高级请求配置」功能进行自定义请求配置。详情见本文2.7节

    1.2 应用场景

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

    1.3 功能简介

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

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

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

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

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

    注2:「钉钉管理」支持 集群

    2. 示例

    2.1 环境准备

    2.1.1 安装插件

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

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

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

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

    2.1.2 配置网络环境

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

    2.2 新建应用

    1)管理员登录钉钉企业号,进入开放平台后打开「应用开发>钉钉应用」界面,点击「创建应用」如下图所示:

    2024-01-18_16-14-43.png

    填写创建应用的相关信息。如下图所示:

    2024-01-18_16-14-07.png

    2.3 配置H5微应用

    配置应用能力。点击「添加应用能力>网页应用」进入配置界面。

    2024-01-18_16-37-59.png

    填写应用首页地址(可以先填数据决策系统的地址,具体的地址需要在后续步骤生成后,将生成的链接再粘贴过来)。点击「保存」完成配置。如下图所示:

    2024-01-18_16-38-35.png

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

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

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

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

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

    1587985281312087.png

    2.4 发布H5微应用

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

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

    2024-01-18_17-01-20.png

    2.5 获取应用参数值

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

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

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

    2024-01-18_17-03-46.png

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

    2024-01-18_17-04-38.png

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

    2.6 平台中添加钉钉应用

    以管理员身份进入数据决策系统,点击「管理系统」>「钉钉管理」。

    2.6.1 保存报表服务器地址

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

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

    2024-01-18_17-05-52.png

    2.6.2 新建钉钉应用

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

    2021-08-02_15-15-26.png

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

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

    16.png

    2.7 应用快捷配置

    2.7.1 钉钉代理跳转

    内网环境:

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

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

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

    外网环境:

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

    私有化部署环境下可能需要在高级请求配置参数,用于认证等,操作详情见「其他配置」的 2.7.4.2 节。

    2.7.2 生成钉钉链接

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

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

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

    2021-11-19_11-23-51.png

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

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

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

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

    2021-11-19_11-26-04.png

    下面介绍下如何配置参数。

    • 设置参数默认值

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

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

    2021-11-19_11-27-51.png

    • 解析参数值

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

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

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

    2021-11-19_11-28-41.png

    3)生成自定义链接

    生成在钉钉能够访问的轻应用链接。

    首先,选择「企业应用名称」,生成「自定义链接」并填入「移动端轻应用」中生成的链接。然后点击「生成链接」并复制即可。如下图所示:

    2022-04-15_15-49-02.jpg

    2.7.4 其他设置

    2.7.4.1 PC端在浏览器打开链接

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

    2023-08-02_14-46-13.png


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

    1637291434565714.png

    2.7.4.2 (非必须项)高级请求配置

    需要请求头自定义的用户可进行配置,没有需求可跳过此步骤。

    FineReport版本
    钉钉管理插件版本 fine_conf_entity可视化配置插件版本
    11.0.9V11.0.84
    V1.9.19

    高级请求配置可设置请求头参数,用于认证等。

    通过修改 fine_conf_entity可视化配置参数DingTalkConfig.requestConfigEnable的值为true,打开「钉钉管理」的高级请求配置功能页面,进行自定义请求配置。

    参数名
    参数描述参数值
    DingTalkConfig.requestConfigEnable开启或关闭钉钉插件高级请求配置

    参数值需为布尔型,默认为false

    false:关闭钉钉插件高级请求配置

    true:开启钉钉插件高级请求配置

    2023-08-02_11-04-24.png

    完成后返回「钉钉管理>应用快捷配置」中,查看到「其他配置」项中出现了「高级请求配置」。可添加请求头配对的「键」和「值」。可添加多个。完成后点击「保存」。如下图所示:

    2023-08-02_14-38-51.png


    2.7.5 新建钉钉群

    给钉钉应用新建钉钉群,支持通过定时调度推送群消息到钉钉群。建群方法如下:

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

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

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

    企业微信截图_16136357871830.png

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

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

    1611286974790342.png

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

    1611295457611078.png

    2.8 (可选)修改首页地址链接

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

    2.8.1 修改应用首页地址

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

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

    2024-01-18_17-08-27.png

    2.9 开启权限

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

    2024-01-18_17-16-46.png

    开通的权限为以下4项:

    • 企业员工手机号信息

    • 通讯录部门信息读权限

    • 成员信息读权限

    • 通讯录部门成员读权限

    2024-01-18_17-13-59.png

    若要实现群消息推送,需要在钉钉开放平台里新增一个权限:钉钉群基础信息管理权限。

    企业微信截图_17096226682260.png

    2.10 成员管理

    2.10.1 用户匹配方式

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

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

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

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

    2024-01-18_17-17-43.png

    钉钉工号匹配:

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

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

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

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

    2024-01-18_17-19-14.png

    手动匹配:

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

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

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

    2024-01-18_17-22-25.png

    自定义匹配:

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

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

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

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

    2024-01-18_17-18-42.png

    2.10.2 通讯录更新

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

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

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

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

    2024-01-18_17-24-21.png

    2.10.3 用户同步

    报表版本 V11.0.2 ,钉钉管理插件版本 V11.0.54 之后,支持将钉钉通讯录的用户信息同步到「用户管理」界面中,保存到平台。

    用户同步配置详情请参见:同步用户

    1)同步配置

    在「用户管理」中进行「同步用户」,用户来源选择「从钉钉同步」,选中对应的钉钉应用,即可根据钉钉通讯录实现同步效果。

    注:「钉钉管理>成员管理」的通讯录手动更新和自动更新;「用户管理>同步用户」都能实现平台用户信息的更新。

    2022-01-21_15-19-28.png

    2)同步成功后,用户信息同步到平台。

    注:因为钉钉接口限制,所有无法同步密码,报表用户初始密码随机生成。如果用户在 APP 或 PC 端想通过账号密码登录,需点击 忘记密码  ,重置后才能登录。

    同步出现问题请参见:同步/导入用户常见问题

    2022-01-21_16-34-44.png

    同步出现问题请参见:同步/导入用户常见问题


    3)同步触发方式

    同步类别同步设置方式详情
    手动同步用户管理>同步用户>从钉钉同步
    第一次同步钉钉用户信息
    用户管理>同步用户管理>立即同步对用户信息再次进行同步
    钉钉管理>成员管理>立即更新更新通讯录,并同步「用户管理」中的用户信息
    自动同步
    钉钉管理>成员管理>自动更新
    根据钉钉管理中设置的「自动更新」时间,自动更新通讯录,并同步「用户管理」中的用户信息

    注意事项:

    1)钉钉通讯录添加的用户,要保证姓名、钉钉工号、钉钉部门和手机号不为空;

    2)使用钉钉同步前,平台同步功能是打开的,且不能清空过同步数据;

    不满足以上两点,同步钉钉用户到平台会失败。


    4)钉钉和平台同步字段的映射关系

    将钉钉中的成员信息,同步到「用户管理」中时,每条字段的映射关系。

    平台字段钉钉字段
    用户ID
    UserID
    用户名工号(job_number)
    姓名姓名
    密码

    因为钉钉接口限制,无法同步密码,所以初始密码随机生成;

    如果用户希望通过 APP 或 PC 端登录,需要 重置密码

    手机手机
    邮箱邮箱
    部门iddepartmentid
    部门名称部门
    无职务无职务
    角色id
    roleid(目前接口尚未适配同步角色)
    角色名称角色(目前接口尚未适配同步角色)

    2.11 效果查看

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

    1587987383350158.jpg

    3. 注意事项

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

    问题描述:

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

    13.png

    原因分析:

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

    解决方案:

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

    14.png

    3.2 内网开放白名单

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

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

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

    1616401707983392.png

    3.4 苹果用户钉钉 PC 端强制打开模板

    如果苹果(Mac)电脑用户,想让模板链接强制使用钉钉内部浏览器打开,可以在模板 url 后添加上 ?ddtab=true 在钉钉内部浏览器打开以保证与钉钉登录用户匹配。


    3.5 23001网络异常

    钉钉部署代理服务器时,插件日志出现 error 级别的日志报错,报错码为「23001」则是网络异常的问题。

    可以参考文档解决异常:代理服务器连接外网 3.1节。

    3.6 添加服务器出口IP

    调用钉钉服务端API时的合法IP列表,多个IP请以“,”隔开,支持带一个*号通配符的IP格式


    附件列表


    主题: 移动端应用
    • 有帮助
    • 没帮助
    • 只是浏览
    中文(简体)

    鼠标选中内容,快速反馈问题

    鼠标选中存在疑惑的内容,即可快速反馈问题,我们将会跟进处理。

    不再提示

    10s后关闭

    联系我们
    在线支持
    获取专业技术支持,快速帮助您解决问题
    工作日9:00-12:00,13:30-17:30在线
    页面反馈
    针对当前网页的建议、问题反馈
    售前咨询
    采购需求/获取报价/预约演示
    或拨打: 400-811-8890 转1
    qr
    热线电话
    咨询/故障救援热线:400-811-8890转2
    总裁办24H投诉:17312781526
    提交页面反馈
    仅适用于当前网页的意见收集,帆软产品问题请在 问答板块提问前往服务平台 获取技术支持