飞书集成

1.1 版本

1.2 功能简介

管理员安装插件并配置，可实现飞书集成，并进行消息推送。

1.3 注意事项

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

设计器插件安装方法请参见：设计器插件管理

服务器安装插件方法请参见：服务器插件管理

3.1 新建应用

1）管理员登录飞书管理后台，打开「工作台>应用管理」，点击「创建应用」。

2）进入「飞书开放平台」后，点击「企业自建应用」右侧的「创建企业自建应用」按钮，创建应用。

3）在创建界面选择「企业自建应用」，输入信息后，点击「确定创建」。如下图所示：

3.2 设置应用权限

2）所需要开放的权限名称如下表所示：

3）对应权限说明可点击「权限名称」查看，如下图所示：

注：在应用发布前，还有一些配置，需要先在报表服务器中配置好才能继续，需进入报表工程配置并获取信息。

3.3 获取应用参数

获取在报表服务器中需要使用的三个参数：

1）在「飞书开放平台」创建的应用下，打开「凭证与基础信息>应用凭证」获取「App ID」、「App Secret」 。如下图所示：

2）进入「飞书管理后台」，在「企业设置>企业信息」中，获取「企业编号」。如下图所示：

4.2 飞书

以管理员身份进入数据决策系统，点击「管理系统>飞书管理>应用快捷配置」。

「应用快捷配置」分为「飞书代理跳转」、「生成飞书链接」、「飞书群」三部分。

5.1 飞书代理跳转

1）若服务器配置在外网环境中，则 不需要 设置代理服务器地址。

2）若服务器是配置在内网环境中：

• 客户服务器可以访问飞书服务器，网络正常，则 不需要 设置代理服务器地址。

• 客户服务器访问不到飞书服务器，网络不通，则 需要 设置代理服务器地址。

注1：判断服务器是否可以访问飞书服务器的方法，详情参见：报表服务器访问微信/钉钉/飞书服务器 。

注2：设置代理服务器的方法，详情参见：网络不通情况下飞书服务器正向代理 。

3）点击「应用快捷配置>代理服务器地址」，输入地址后点击「测试连接并保存」。如下图所示：

5.2 生成飞书链接

各设置项说明如下表所示：

注：使用 V11.0.74 版本插件生成的链接，若回退插件，需使用老版本插件重新生成链接，重新挂载飞书主页链接和 飞书RedirectURL 重定向链接。

5.2.1 生成访问决策平台的飞书链接

1）选择飞书应用名称后，链接页面下拉选择「决策平台」。

2）点击「生成链接」后，生成 飞书链接 和 飞书RedirectURL 。

3）点击「复制」按钮即可复制。如下图所示：

5.2.2 生成访问单个模板的飞书链接

1）选择飞书应用名称，链接页面下拉选择「单个模板」，然后选择一张模板。

2）如需设置参数，请点击「设置参数默认值」进行设置，设置了参数后可以根据实际需要选择是否勾选「解析参数值」。

3）点击「生成链接」后，生成 飞书链接 和 飞书RedirectURL 。

4）点击「复制」按钮即可复制。如下图所示：

• 设置参数默认值

点击「设置参数默认值」后，如果模板本身有参数，则会显示在下方，用户可以设置参数的默认值，也可以点击右上角「添加」参数，如下图所示：

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

• 解析参数值

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

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

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

注：仅「模板消息推送」的消息链接可选择不勾选解析参数值，从而实现推送的公式计算；其他模板单点链接必须勾选「解析参数值」，否则将导致参数丢失。

5.3 飞书群

在第 6 节应用发布后，才能够成功建群。点击「新建飞书群」，可实现推送消息到群，群成员除群主外还要至少两人。如下图所示：

返回飞书开放平台，进入 3.1 节新建的飞书应用，对应用进行进一步配置，并发布应用。

6.1 安全设置

1）将本文 5.2 节生成的「飞书RedirectURL」链接，填入应用的「安全设置>重定向URL」处。

2）配置 IP 白名单。如下图所示：

注：如没有配置白名单则无法访问集成应用。

3）飞书集成下若使用扫码控件、文件控件， 则要求单点登录、且必须经过可信域名校验。如下图所示：

6.2 设置应用首页

6.3 启用机器人

为了保证飞书推送消息成功，需要在「添加应用能力」中配置机器人。否则会导致消息推送失败。

消息推送参见文档：飞书定时推送消息 。

6.4 发布应用

1）点击「应用管理>版本管理与发布>创建版本」，如下图所示：

2）「应用版本号」和「更新说明」用户在飞书合理范围内填写即可，默认能力选择「网页应用」。

3）可用范围可选择全部成员或按部门选择部分成员，完成后点击「保存」。如下图所示：

注1：V11.0.65.1 版本之前的飞书集成插件，飞书应用可用范围需选择「所有员工」。

注2：如果想要跳转到平台，需将「默认能力」设置为网页应用。

4）保存后点击「申请线上发布」。如下图所示：

5）管理员审核通过发布。如下图所示：

6.5 效果预览

企业用户登录「工作台」在应用中可找到创建的应用。如下图所示：

设计器 V11.0.10 版本，飞书管理插件 V11.0.75 版本及之后，支持将飞书通讯录的用户信息同步到「用户管理」界面中，保存到平台。

注：请注意区分本文的用户同步和用户匹配。用户同步是指将飞书通讯录中的用户信息同步到决策平台的「用户管理」界面中，确保 FineReport 平台中的用户信息与飞书通讯录中的信息保持一致。用户匹配是指在决策平台中，通过不同的匹配方式将飞书通讯录中的用户与 FineReport 中的用户进行关联，确保两者能够正确对应。

用户同步配置详情请参见：同步用户 。

1）同步配置

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

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

2）同步成功后，用户信息同步到平台。

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

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

3）同步触发方式

注1：飞书通讯录添加的用户，要保证姓名、飞书成员ID、部门、手机号不为空，不满足此条件则同步飞书用户到平台会失败。

注2：使用飞书同步前，平台同步功能是打开的，且不能清空过同步数据，不满足此条件则同步飞书用户到平台会失败。

4）飞书和平台同步字段的映射关系

将飞书中的成员信息，同步到「用户管理」中时，每条字段的映射关系如下表所示：

8.1 用户匹配方式

飞书应用发布后，在数据决策系统「管理系统>飞书管理>成员管理」中，可通过用户匹配关联飞书通讯录中的用户。

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

用户匹配方式包括：飞书账号匹配、手机号匹配、手动匹配、自定义匹配。「成员管理」页面如下图所示：

注1：飞书成员ID 不要设置成中文和特殊字符，不然会导致单点失败。成员ID 不支持修改，只能删除成员重新添加信息。

注2：请注意区分本文的用户同步和用户匹配。用户同步是指将飞书通讯录中的用户信息同步到决策平台的「用户管理」界面中，确保 FineReport 平台中的用户信息与飞书通讯录中的信息保持一致。用户匹配是指在决策平台中，通过不同的匹配方式将飞书通讯录中的用户与 FineReport 中的用户进行关联，确保两者能够正确对应。

注：不管集成几个飞书应用，用户均统一进行管理。

1）飞书账号/手机号匹配

• 飞书账号匹配：飞书成员ID 对应报表用户名，若一个 成员ID 对应多个报表用户名，则遍历取第一个报表用户进行匹配。

• 手机号匹配：飞书成员手机号对应报表用户手机号，若一个成员手机号可对应多个报表用户名，则遍历取第一个报表用户进行匹配。

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

2）手动匹配

手动设置飞书用户匹配具体报表用户。当匹配方式为「手动匹配」时，成员列表中多出「用户名」一列信息，点击出现下拉框，选择相应的用户名，进行手动匹配。

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

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

如下图所示：

3）自定义匹配

自定义匹配可在飞书成员id和报表用户名，字段值不一致的情况下使用。

选择对应服务器数据集，选择对应列，实现飞书成员 ID 匹配对应报表成员用户名。

即通过设置的「服务器数据集」，将对应数据列的飞书用户和报表用户相匹配。若出现一个飞书用户对应了多个报表用户的情况，默认匹配第一个报表用户。选择自定义匹配时，下方多出「匹配设置」项，选择「数据集」、「飞书成员ID」及「用户名」，进行匹配。如下图所示：

8.2 飞书通讯录

点击「立即更新」按钮，立即更新通讯录内容。

点击「设置自动更新」按钮，可设置自动定时更新，和更新周期。如下图所示：

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

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

9.1 修改已发布的飞书应用

用户已发布应用中需要修改配置后重新发布，需要再飞书开放后台进入应用，修改配置。

9.2 飞书集成支持可用范围为部门

V11.0.65.1 及之后版本的飞书集成插件，飞书应用可用性范围支持设置为部门，如下图所示：

注意：飞书集成插件一直都不支持可见范围设置为某个单独用户。

9.3 报错代码10010002

配置飞书时弹窗报错：发生错误，错误码为：10010002

这是由于飞书插件未授权导致的，购买插件获得授权后可解决该问题。