1. 概述
1.1 版本
| FineBI 版本 | 飞书管理插件版本 | 功能变动 |
|---|---|---|
| 6.0 | V11.0.68 | - |
| 6.0.3 | V11.0.72 | 「成员管理」支持同步根部门下的用户，需要开放“获取企业信息”权限 |
| 6.0.4 | V11.0.74 | 优化单点登录性能 |
| 6.0.5 | V11.0.75 | 支持将飞书用户同步到「用户管理」，详情见本文第 7 节 |
1.2 功能简介
管理员安装插件并配置，可实现飞书集成，并进行消息推送。
1.3 注意事项
1）飞书成员ID不要设置成中文和特殊字符，不然会导致单点失败，成员ID不可修改，只能删除成员重新添加。
2）飞书管理和lark管理，这两个插件不能同时安装使用。
2. 安装插件
3. 飞书后台创建应用
3.1 新建应用
1）管理员登录飞书管理后台，打开「工作台>应用管理」，点击「创建应用」。
2）进入「飞书开放平台」后，点击「企业自建应用」右侧的「创建企业自建应用」按钮，创建应用。
3）在创建界面选择「企业自建应用」，输入信息后，点击「确定创建」。如下图所示：
3.2 设置应用权限
1）创建应用后，进入应用配置界面。在「权限管理」中开通所需权限，如下图所示：
2）所需要开放的权限名称如下表所示：
| 权限名称 |
|---|
| 获取应用信息 |
| 获取通讯录组织架构信息 |
| 获取用户组织架构信息 |
| 获取与更新群组信息 |
| 获取与发送单聊、群组消息 |
| 获取单聊、群组消息 |
| 获取与上传图片或文件资源 |
| 管理应用可见范围 |
| 获取用户组信息 |
| 获取用户 user ID |
| 读取群信息 |
| 获取群组中所有消息 |
以应用的身份发消息 |
| 获取企业信息 |
| 获取通讯录基本信息 |
| 获取角色权限 |
| 获取用户手机号 |
| 更新应用所创建群的群信息 |
| 更新应用创建群聊的信息 |
| 给一个或多个部门的成员批量发消息 |
| 获取部门基础信息 |
| 获取用户基本信息 |
| 搜索用户 |
| 获取群组信息 |
| 获取用户发给机器人的单聊消息 |
| 给多个用户批量发消息 |
3）对应权限说明可点击「权限名称」查看，如下图所示：
注：在应用发布前，还有一些配置，需要先在报表服务器中配置好才能继续，需进入报表工程配置并获取信息。
3.3 获取应用参数
先获取在报表服务器中需要使用的三个参数：
| 参数 |
|---|
| App ID |
| App Secret |
| 企业编号 |
1）在「飞书开放平台」创建的应用下，打开「凭证与基础信息>应用凭证」获取「App ID」、「App Secret」 。如下图所示：
2）进入「飞书管理后台」，在「企业设置>企业信息」中，获取「企业编号」。如下图所示：
4. 应用管理
以管理员身份进入FineBI，点击「管理系统>飞书管理>应用管理」。
4.1 服务器
点击「管理系统>飞书管理>应用管理」，输入「服务器地址」并「保存」。
示例：http://域名:端口号/webroot/decision
注：请使用二级或二级以上域名，且需通过 ICP 备案。
4.2 飞书
点击「新建飞书应用」，设置飞书应用的名称，并根据文档 3.3 节获取的应用参数，填入 App_Id、租户ID（即企业编号）、App_Secret
5. 应用快捷配置
以管理员身份进入数据决策系统，点击「管理系统>飞书管理>应用快捷配置」。
「应用快捷配置」分为「飞书代理跳转」、「生成飞书链接」、「飞书群」三部分。
5.1 飞书代理跳转
1）若服务器配置在外网环境中，则 不需要 设置代理服务器地址。
2）若服务器是配置在内网环境中：
客户服务器可以访问飞书服务器，网络正常，则 不需要 设置代理服务器地址。
客户服务器访问不到飞书服务器，网络不通，则 需要 设置代理服务器地址。
注1：判断服务器是否可以访问飞书服务器的方法，详情参见：报表服务器访问微信/钉钉/飞书服务器 。
注2：设置代理服务器的方法，详情参见：网络不通情况下飞书服务器正向代理 。
3）点击「应用快捷配置>代理服务器地址」，输入地址后点击「测试连接并保存」。
5.2 生成飞书链接
设置项说明如下表所示：
| 设置项 | 说明 |
|---|---|
| 飞书应用名称 | 必填项 |
| 链接页面 | 选择不同的「链接页面」，可生成两种链接：访问决策平台的链接、访问单个模板的链接。详情参见该表下文 |
| 飞书链接 | 此处生成的飞书链接作用有两点： 1）挂载在飞书后台创建的应用「网页>启用网页>移动端主页」，详情见本文 6.2 节 2）用于推送的自定义链接处，详情见：定时调度任务详细设置步骤 |
| 飞书RedirectURL | 获取后填入飞书后台创建的应用，「安全设置>重定向URL」处，否则不能调用 JSAPI 。详情见本文 6.1 节 |
注：使用 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 节应用发布后，才能够成功建群。点击「新建飞书群」，可实现推送消息到群，群成员除群主外还要至少两人。
6. 飞书后台发布应用
返回飞书开放平台，进入 3.1 节新建的飞书应用，对应用进行进一步配置，并发布应用。
6.1 安全设置
1）将本文 2.4.2 节生成的「飞书RedirectURL」链接，填入应用的「安全设置>重定向URL」处.
2）配置 IP 白名单。如下图所示：
注：如没有配置白名单则无法访问集成应用。
3）飞书集成下若使用扫码控件、文件控件， 则要求单点登录、且必须经过可信域名校验。如下图所示：
6.2 设置应用首页
1）点击「网页应用」，编辑「网页应用配置」。
2）将本文 5.2 节生成的「飞书链接」，填入「移动端主页」中，并点击「保存」。如下图所示：
注：如果要桌面端登录，需配置桌面端主页链接。6.3 启用机器人
为了保证飞书推送消息成功，需要在「添加应用能力>机器人」。否则会导致消息推送失败。
消息推送参见文档：飞书定时推送消息 。
6.4 发布应用
注：每次配置、修改完成飞书应用后都要发布才生效。
1）点击「应用管理>版本管理与发布>创建版本」，如下图所示：
2）「应用版本号」和「更新说明」用户在飞书合理范围内填写即可，可用范围可选择全部成员或按部门选择部分成员，完成后点击「保存」。
注：V11.0.65.1 版本之前的飞书集成插件，飞书应用可用范围需选择「所有员工」。
3）保存后点击「申请线上发布」。
4）管理员审核通过发布。
6.5 效果预览
企业用户登录「工作台」在应用中可找到创建的应用。
7. 用户同步
设计器 V11.0.10 版本，飞书管理插件 V11.0.75 版本及之后，支持将飞书通讯录的用户信息同步到「用户管理」界面中，保存到平台。
注：请注意区分本文的用户同步和用户匹配。用户同步是指将飞书通讯录中的用户信息同步到决策平台的「用户管理」界面中，确保 FineReport 平台中的用户信息与飞书通讯录中的信息保持一致。用户匹配是指在决策平台中，通过不同的匹配方式将飞书通讯录中的用户与 FineReport 中的用户进行关联，确保两者能够正确对应。
用户同步配置详情请参见：同步用户 。
1）同步配置
在「用户管理」中进行「同步用户」，用户来源选择「从飞书同步」，选中对应的飞书应用，即可根据飞书通讯录实现同步效果。
注：「飞书管理>成员管理」的通讯录手动更新和自动更新、「用户管理>同步用户」都能实现平台用户信息的更新。
2）同步成功后，用户信息同步到平台。
注：因为飞书接口限制，所有无法同步密码，报表用户初始密码随机生成。如果用户在 APP 或 PC 端想通过账号密码登录，需点击 忘记密码 ，重置后才能登录。
同步出现问题请参见：同步/导入用户常见问题 。
3）同步触发方式
| 同步类别 | 同步设置方式 | 详情 |
|---|---|---|
| 手动同步 | 用户管理>同步用户>从飞书同步 | 第一次同步飞书用户信息 |
| 用户管理>同步用户管理>立即同步 | 对用户信息再次进行同步 | |
| 飞书管理>成员管理>立即更新 | 更新通讯录，并同步「用户管理」中的用户信息 | |
| 自动同步 | 飞书管理>成员管理>自动更新 | 根据飞书管理中设置的「自动更新」时间，自动更新通讯录，并同步「用户管理」中的用户信息 |
注1：飞书通讯录添加的用户，要保证姓名、飞书成员ID、部门、手机号不为空，不满足此条件则同步飞书用户到平台会失败。
注2：使用飞书同步前，平台同步功能是打开的，且不能清空过同步数据，不满足此条件则同步飞书用户到平台会失败。
4）飞书和平台同步字段的映射关系
将飞书中的成员信息，同步到「用户管理」中时，每条字段的映射关系如下表所示：
| 平台字段 | 飞书字段 |
|---|---|
| 用户ID | UserID |
| 用户名 | 飞书ID |
| 姓名 | 姓名 |
| 密码 | 因为飞书接口限制，无法同步密码，所以初始密码随机生成； 如果用户希望通过 APP 或 PC 端登录，需要 重置密码 |
| 手机 | 手机 |
| 邮箱 | 邮箱 |
| 部门id | departmentid |
| 部门名称 | 部门 |
| 无职务 | 无职务 |
| 角色id | roleid（目前接口尚未适配同步角色） |
| 角色名称 | 角色（目前接口尚未适配同步角色） |
8. 成员管理
飞书应用发布后，在数据决策系统「管理系统>飞书管理>成员管理」中，可通过用户匹配获取飞书通讯录的数据。
8.1 用户匹配方式
可根据实际情况选择一种用户匹配方式。
用户匹配方式包括：飞书账号匹配、手机号匹配、手动匹配、自定义匹配。「成员管理」页面如下图所示：
注：飞书成员ID 不要设置成中文和特殊字符，不然会导致单点失败。成员ID 不支持修改，只能删除成员重新添加信息。
注：不管集成几个飞书应用，用户均统一进行管理。
1）飞书账号/手机号匹配
「飞书账号匹配」和「手机号匹配」展示列相同。
飞书账号匹配：飞书成员ID 对应报表用户名，若一个 成员ID 对应多个报表用户名，则遍历取第一个报表用户进行匹配。
手机号匹配：飞书成员手机号对应报表用户手机号，若一个成员手机号可对应多个报表用户名，则遍历取第一个报表用户进行匹配。
选择这两个匹配方式时，飞书通讯录信息展示：姓名、飞书成员ID、部门手机号，如下图所示：
2）手动匹配
手动设置飞书用户匹配具体报表用户。当匹配方式为「手动匹配」时，成员列表中多出「用户名」一列信息，点击出现下拉框，选择相应的用户名，进行手动匹配。
注1：手动匹配时，用户名支持选择「不选」选项。
注2：手动匹配方式是用户可以自由选择与飞书用户匹配的报表用户，可实现多个飞书用户匹配同一个报表用户。
如下图所示：
3）自定义匹配
选择对应服务器数据集，选择对应列，实现飞书成员 ID 匹配对应报表成员用户名。
即通过设置的「服务器数据集」，将对应数据列的飞书用户和报表用户相匹配。若出现一个飞书用户对应了多个报表用户的情况，默认匹配第一个报表用户。选择自定义匹配时，下方多出「匹配设置」项，选择「数据集」、「飞书成员ID」及「用户名」，进行匹配。如下图所示：
8.2 飞书通讯录
点击「立即更新」按钮，立即更新通讯录内容。
点击「设置自动更新」按钮，可设置自动定时更新，和更新周期。如下图所示：
注1：用户匹配方式为「飞书账号匹配」或「手机号匹配」时，如果用户增删改报表用户或者在后台增删改飞书用户，需要手动同步通讯录更新。
注2：用户匹配方式为「手动匹配」或「自定义匹配」时，如果用户增删改报表用户或者在后台增删改飞书用户，无需更新同步。
9. 注意事项
9.1 修改已发布的飞书应用
用户已发布应用中需要修改配置后重新发布，需要再飞书开放后台进入应用，修改配置。
9.2 飞书集成支持可用范围为部门
V11.0.65.1 及之后版本的飞书集成插件，飞书应用可用性范围支持设置为部门，不支持设置为某个用户。如下图所示：
9.3 报错代码10010002
配置飞书时弹窗报错：发生错误，错误码为：10010002
这是由于飞书插件未授权导致的，购买插件获得授权后可解决该问题。
