1. 概述
1.1 版本
| 报表服务器版本 | 飞书管理插件版本 | 功能变动 |
|---|---|---|
| 11.0.2 | V11.0.54 | - |
| V11.0.62 | 「成员管理」支持同步多个企业的数据 | |
| V11.0.72 | 「成员管理」支持同步根部门下的用户，需要开放“获取企业信息”权限 | |
| 11.0.9 | V11.0.74 | 优化单点登录性能 |
| 11.0.10 | V11.0.75 | 支持将飞书用户同步到「用户管理」，详情见本文 2.6.3 节 |
1.2 功能简介
管理员安装插件并配置，可实现飞书集成，并进行消息推送。
1.3 注意事项
飞书成员ID不要设置成中文和特殊字符，不然会导致单点失败，成员ID不可修改，只能删除成员重新添加。
2. 操作步骤
2.1 安装插件
点击下载插件：飞书管理插件、HTML5 移动端展现插件
设计器插件安装方法请参见：设计器插件管理
服务器安装插件方法请参见：服务器插件管理
2.2 飞书后台创建应用
2.2.1 新建应用
1）管理员登录飞书管理后台，打开「工作台>应用管理」，点击「创建应用」。
2）进入「飞书开放平台」后，点击「企业自建应用」右侧的「创建企业自建应用」按钮，创建应用。
3）在创建界面选择「企业自建应用」，输入信息后，点击「确定创建」。
2.2.2 设置应用权限
1）创建应用后在「权限管理」中开通所需权限。
所需要开放的权限名称如下表所示：
| 权限名称 |
|---|
| 获取应用信息 |
| 获取部门组织架构信息 |
| 获取用户组织架构信息 |
| 获取与更新群组信息 |
| 获取与发送单聊、群组消息 |
| 获取单聊、群组消息 |
| 获取与上传图片或文件资源 |
| 管理应用可见范围 |
| 获取用户组信息 |
| 获取用户 user ID |
| 读取群信息 |
| 获取群组中所有消息 |
以应用的身份发消息 |
| 获取企业信息 |
| 获取通讯录基本信息 |
| 获取角色权限 |
| 获取用户手机号 |
| 更新应用所创建群的群信息 |
| 更新应用创建群聊的信息 |
| 给一个或多个部门的成员批量发消息 |
| 获取部门基础信息 |
| 获取用户基本信息 |
| 搜索用户 |
| 获取群组信息 |
| 获取用户发给机器人的单聊消息 |
| 给多个用户批量发消息 |
| 获取用户邮箱信息 |
对应权限说明可点击「权限名称」查看，如下图所示：
注：在应用发布前，还有一些配置，需要先在报表服务器中配置好才能继续，需进入报表工程配置并获取信息。
2.2.3 获取应用参数
先获取在报表服务器中需要使用的三个参数：
| 参数 |
|---|
| App ID |
| App Secret |
| 企业编号 |
1）在「飞书开放平台」创建的应用下，打开「凭证与基础信息>应用凭证」获取「App ID」、「App Secret」 。如下图所示：
2）进入「飞书管理后台」，在「企业设置>企业信息」中，获取「企业编号」。如下图所示：
2.3 报表服务器添加应用
以管理员身份进入数据决策系统，点击「管理系统>飞书管理>应用管理」。
2.3.1 服务器地址
点击「管理系统>飞书管理>应用管理」，输入「服务器地址」并「保存」。
示例：http://域名:端口号/webroot/decision
注：请使用二级或二级以上域名，且需通过 ICP 备案。
2.3.2 新建飞书应用
点击「新建飞书应用」，设置飞书应用的名称，并根据文档 2.2.3 节获取的应用参数，填入 App_Id、租户ID（即企业编号）、App_Secret
2.4 应用快捷配置
2.4.1 飞书代理跳转
点击「应用快捷配置>代理服务器地址」，输入地址后点击「测试连接并保存」。
注：和微信的代理服务器地址配置逻辑相同，服务器需要可以与外网互通，配置正向代理后，在此处填写对应代理地址。代理配置方案参考：微信钉钉集成环境准备第 4.2 节
飞书代理跳转说明：
1）判断是否需要填写代理服务器地址
若服务器是配置在外网环境中，则不需要设置代理服务器地址。
若服务器是配置在内网环境中，且客户服务器可以访问外网，网络正常，则不需要填写服务器地址。
若服务器是配置在内网环境中，且客户服务器访问不到飞书服务器，访问不到外网时，需要配置代理服务器地址。
2）判断内网环境是否可访问到外网
① 先判断报表服务器上，ping open.feishu.cn，能 ping 通，代理服务器配置这边不用填写。
② ping不通，找一个代理服务器配置nginx正向代理，代理配置如下：
server {
listen 8116; # 飞书代理服务器端口
server_name 192.168.5.137; # 飞书代理服务器IP
location / {
proxy_redirect off;
proxy_pass https://open.feishu.cn; #飞书服务器域名
}
location = /favicon.ico {
log_not_found off;
}
}
2.4.2 生成飞书链接
设置项说明如下表所示：
| 设置项 | 说明 |
|---|---|
| 飞书应用名称 | 必填项 |
| 链接页面 | 选择不同的「链接页面」，可生成两种链接：访问决策平台的链接、访问单个模板的链接。详情参见该表下文 |
| 飞书链接 | 此处生成的飞书链接作用有两点： 1）挂载在飞书后台创建的应用「网页>启用网页>移动端主页」，详情见本文 2.5.2 节 2）用于推送的自定义链接处，详情见：定时调度任务详细设置步骤 |
| 飞书RedirectURL | 获取后填入飞书后台创建的应用，「安全设置>重定向URL」处，否则不能调用 JSAPI 。详情见本文 2.5.1 节 |
注：使用 V11.0.74 版本插件生成的链接，若回退插件，需使用老版本插件重新生成链接，重新挂载飞书主页链接和 飞书RedirectURL 重定向链接。
1）生成访问决策平台的飞书链接
选择飞书应用名称后，链接页面下拉选择「决策平台」，点击生成链接后，生成「飞书链接」和「飞书RedirectURL」。点击复制按钮即可复制，如下图所示：
2）生成访问单个模板的飞书链接
选择飞书应用名称，链接页面下拉选择「单个模板」，然后选择一张模板。如需设置参数，请点击「设置参数默认值」进行设置，设置了参数后可以根据实际需要选择是否勾选「解析参数值」，最后点击生成链接，点击复制按钮即可复制。如下图所示：
设置参数默认值
点击「设置参数默认值」后，如果模板本身有参数，那么会显示在下方，用户可以设置参数的默认值，也可以点击右上角「添加」参数，如下图所示：
注：如果想删除参数，可以鼠标悬浮在参数列表的右边，会出现删除按钮。
解析参数值
假如一张模板 a.cpt 设置了一个参数 date，其值为公式 ${today}。
如果勾选了「解析参数值」，那么点击「生成链接」后，链接中会自动解析出当天的日期，例如：a.cpt&date=2020-11-03。
如果不想链接中直接解析参数，想要保留这个公式，可以取消勾选「解析参数值」，点击「生成链接」后，公式保留，例如：a.cpt&date=${today}。
注：仅「模板消息推送」的消息链接可选择不勾选解析参数值，从而实现推送的公式计算；其他模板单点链接必须勾选「解析参数值」，否则将导致参数丢失。
2.4.3 新建飞书群
在 2.5 节应用发布后，才能够成功建群。点击「新建飞书群」，可实现推送消息到群，群成员除群主外还要至少两人。
2.5 飞书后台发布应用
返回飞书开放平台，进入 2.2 节新建的飞书应用，对应用进行进一步配置，并发布应用。
2.5.1 安全设置
将本文 2.4.2 节生成的「飞书RedirectURL」链接，填入应用的「安全设置>重定向URL」处。
注：飞书集成下若使用扫码控件、文件控件， 则要求单点登录、且必须经过可信域名校验。
2.5.2 设置应用首页
先点击「应用功能>网页」，打开「启用网页」按钮。将本文2.4.2节生成的「飞书链接」，填入「网页配置>移动端主页」中，并点击「保存」。
如果要桌面端登录，需配置桌面端主页链接。
2.5.3 启用机器人
为了保证飞书推送消息成功，需要在「添加应用能力>机器人」。否则会导致消息推送失败。
消息推送参见文档：飞书定时推送消息 。
2.5.4 发布应用
注：每次配置、修改完成飞书应用后都要发布才生效。
1）点击「应用管理>版本管理与发布>创建版本」，如下图所示：
2）「应用版本号」和「更新说明」用户在飞书合理范围内填写即可，默认能力选择「网页应用」。可用范围可选择全部成员或按部门选择部分成员，完成后点击「保存」。
注 1：V11.0.65.1 版本之前的飞书集成插件，飞书应用可用范围需选择「所有员工」。
注 2：如果想要跳转到平台，需将「默认能力」设置为网页应用。
3）保存后点击「申请线上发布」。
4）管理员审核通过发布。
2.5.5 效果预览
企业用户登录「工作台」在应用中可找到创建的应用。
2.6 成员管理
飞书应用发布后，在数据决策系统「管理系统>飞书管理>成员管理」中，可通过用户匹配获取飞书通讯录的数据。
2.6.1 用户匹配方式
可根据实际情况选择一种用户匹配方式。
用户匹配方式包括：飞书账号匹配、手机号匹配、手动匹配、自定义匹配。「成员管理」页面如下图所示：
注：飞书成员ID 不要设置成中文和特殊字符，不然会导致单点失败。成员ID 不支持修改，只能删除成员重新添加信息。
注：不管集成几个飞书应用，用户均统一进行管理。
1）飞书账号/手机号匹配
「飞书账号匹配」和「手机号匹配」展示列相同。
飞书账号匹配：飞书成员ID 对应报表用户名，若一个 成员ID 对应多个报表用户名，则遍历取第一个报表用户进行匹配。
手机号匹配：飞书成员手机号对应报表用户手机号，若一个成员手机号可对应多个报表用户名，则遍历取第一个报表用户进行匹配。
选择这两个匹配方式时，飞书通讯录信息展示：姓名、飞书成员ID、部门手机号，如下图所示：
2）手动匹配
手动设置飞书用户匹配具体报表用户。当匹配方式为「手动匹配」时，成员列表中多出「用户名」一列信息，点击出现下拉框，选择相应的用户名，进行手动匹配。
注1：手动匹配时，用户名支持选择「不选」选项。
注2：手动匹配方式是用户可以自由选择与飞书用户匹配的报表用户，可实现多个飞书用户匹配同一个报表用户。
如下图所示：
3）自定义匹配
选择对应服务器数据集，选择对应列，实现飞书成员 ID 匹配对应报表成员用户名。
即通过设置的「服务器数据集」，将对应数据列的飞书用户和报表用户相匹配。若出现一个飞书用户对应了多个报表用户的情况，默认匹配第一个报表用户。选择自定义匹配时，下方多出「匹配设置」项，选择「数据集」、「飞书成员ID」及「用户名」，进行匹配。如下图所示：
2.6.2 飞书通讯录
点击「立即更新」按钮，立即更新通讯录内容。
点击「设置自动更新」按钮，可设置自动定时更新，和更新周期。如下图所示：
注1：用户匹配方式为「飞书账号匹配」或「手机号匹配」时，如果用户增删改报表用户或者在后台增删改飞书用户，需要手动同步通讯录更新。
注2：用户匹配方式为「手动匹配」或「自定义匹配」时，如果用户增删改报表用户或者在后台增删改飞书用户，无需更新同步。
2.6.3 用户同步
设计器 V11.0.10 版本，飞书管理插件 V11.0.75 版本及之后，支持将飞书通讯录的用户信息同步到「用户管理」界面中，保存到平台。
用户同步配置详情请参见：同步用户 。
1）同步配置
在「用户管理」中进行「同步用户」，用户来源选择「从飞书同步」，选中对应的飞书应用，即可根据飞书通讯录实现同步效果。
注：「飞书管理>成员管理」的通讯录手动更新和自动更新、「用户管理>同步用户」都能实现平台用户信息的更新。
2）同步成功后，用户信息同步到平台。
注：因为飞书接口限制，所有无法同步密码，报表用户初始密码随机生成。如果用户在 APP 或 PC 端想通过账号密码登录，需点击 忘记密码 ，重置后才能登录。
同步出现问题请参见：同步/导入用户常见问题 。
3）同步触发方式
| 同步类别 | 同步设置方式 | 详情 |
|---|---|---|
| 手动同步 | 用户管理>同步用户>从飞书同步 | 第一次同步飞书用户信息 |
| 用户管理>同步用户管理>立即同步 | 对用户信息再次进行同步 | |
| 飞书管理>成员管理>立即更新 | 更新通讯录，并同步「用户管理」中的用户信息 | |
| 自动同步 | 飞书管理>成员管理>自动更新 | 根据飞书管理中设置的「自动更新」时间，自动更新通讯录，并同步「用户管理」中的用户信息 |
注意事项：不满足以下两点，同步飞书用户到平台会失败
飞书通讯录添加的用户，要保证姓名、飞书成员ID、部门、手机号不为空。
使用飞书同步前，平台同步功能是打开的，且不能清空过同步数据。
4）飞书和平台同步字段的映射关系
将飞书中的成员信息，同步到「用户管理」中时，每条字段的映射关系如下表所示：
| 平台字段 | 飞书字段 |
|---|---|
| 用户ID | UserID |
| 用户名 | 飞书ID |
| 姓名 | 姓名 |
| 密码 | 因为飞书接口限制，无法同步密码，所以初始密码随机生成； 如果用户希望通过 APP 或 PC 端登录，需要 重置密码 |
| 手机 | 手机 |
| 邮箱 | 邮箱 |
| 部门id | departmentid |
| 部门名称 | 部门 |
| 无职务 | 无职务 |
| 角色id | roleid（目前接口尚未适配同步角色） |
| 角色名称 | 角色（目前接口尚未适配同步角色） |
3. 注意事项
3.1 修改已发布的飞书应用
用户已发布应用中需要修改配置后重新发布，需要再飞书开放后台进入应用，修改配置。
3.2 飞书集成支持可用范围为部门
V11.0.65.1 及之后版本的飞书集成插件，飞书应用可用性范围支持设置为部门，如下图所示：
注意：飞书集成插件一直都不支持可见范围设置为某个单独用户。
3.3 报错代码10010002
配置飞书时弹窗报错：发生错误，错误码为：10010002
这是由于飞书插件未授权导致的，购买插件获得授权后可解决该问题。
