1 需求场景

场景1：点击飞书应用图标，从飞书单点登录Smartbi首页。

场景2：同步飞书用户组、用户至Smartbi。

场景3：从Smartbi推送报表链接给指定的飞书群。

场景4：定时推送消息至飞书，包含：普通应用消息、群消息。

2 使用说明

2.1 加载扩展包

扩展包：飞书集成Smartbi

扩展包部署详情请看文档：部署扩展包

注意：上传该扩展包时需进行系统升级。请勿在系统忙碌期间部署该扩展包。

2.2. 集成说明

2.2.1. 步骤1 配置飞书应用

2.2.1.1. 登录飞书开发者后台

通过以下网站，登录开发者后台

https://open.feishu.cn/app?lang=zh-CN

2.2.1.2. 创建应用（假如是基于已有应用进行开发，可以跳过这一步）

1、点击创建企业自建应用，填写必填项

2、创建后，可点击进入对应应用配置页

2.2.1.3. 完善应用凭证与基础信息

配置应用图标（此步骤必须完成，否则应用后续发布会有异常。）

若对应用国际化名称有特殊要求，也请修改底下国际化配置。

2.2.1.4. 记录应用信息(后续需要配置到smartbi内)

记录应用的App ID和App Secret

2.2.1.5. 配置应用功能-网页

单点集成时需要用到应用的网页功能，即点击应用图标后跳转的页面。

当前扩展包交付时，内置有一个feishuIndex.jsp接口，供飞书应用集成使用。

配置时，根据当前部署smartbi外网的域名和地址进行构造填写。

如以下示例:

当前smartbi部署在http://10.10.27.105:8095上。

则配置的地址为http://10.10.27.105:8095/smartbi/vision/feishuIndex.jsp

注：移动端和桌面端主页都配置feishuIndex.jsp 即可，后续单点成功后，移动端会跳转到移动端首页。

添加网页应用能力：

配置网页应用的主页：

2.2.1.6. 配置应用功能-机器人

要完成飞书推送功能，需要开启飞书应用的机器人权限。

2.2.1.7. 配置安全设置

当前扩展包内，在跟飞书交互时，会用到Oauth2登陆认证，飞书接受到登录请求后，会重定向回Smartbi，并携带相关code信息。

此处需要将Smartbi解析code并登录的地址配置到重定向URL内。

如2.2.1.5示例，Smartbi部署在http://10.10.27.105:8095上

则此处需要新增的回调地址是

http://10.10.27.105:8095/smartbi/vision/FeiShuOauthLogin

2.2.1.8. 应用权限开通说明

需要给到应用配置以下权限：

权限名称	权限说明	使用场景
contact:contact:readonly_as_app	以应用身份读取通讯录	用户同步，单点登录
contact:department.organize:readonly	获取部门组织架构信息	用户同步，单点登录
contact:user.base:readonly	获取用户基本信息	用户同步，单点登录
contact:user.employee_id:readonly	获取用户user ID	用户同步，单点登录
contact:user.phone:readonly	获取用户手机号	用户同步，单点登录
im:message	获取与发送单聊、群组信息	推送消息
im:message:send_multi_depts	给一个或多个部门成员批量法消息	推送消息
im:message:send_multi_users	给多个用户批量发消息	推送消息
im:resource	获取与上传图片或文件资源	推送消息
contact:department.base:readonly	获取部门基础信息	用户同步（部门信息），单点登录
contact:user.employee:readonly	获取用户受雇信息	用户同步(用户状态)
contact:user.department:readonly	获取用户所属部门的 ID	用户同步
contact:user.email:readonly	获取用户邮箱信息	用户同步（email邮箱扩展属性）

2.2.1.9. 版本与管理

每一次修改应用信息，都要创建版本并发布后才能生效。

2.2.2. 步骤2 配置Smartbi系统选项

2.2.2.1. 正常部署扩展包

正常部署扩展包，部署成功后，可以在系统选项内看到飞书相关配置入口。

2.2.2.2. 配置飞书相关信息

根据2.2.1.4 内获取的app_id和app_sercret,配置进smartbi系统选项内

其中Smartbi外网访问地址需要配置Smartbi外网可访问的IP或域名地址。

用户同步可以指定同步时的用户名，使用的飞书属性key以及同步到Smartbi的默认密码；

Ps：name属性在飞书中是可重复的，手机号、邮箱、工号是非必填属性，现场可根据实际情况设置，如不需使用自带的用户同步，可忽略；

2.3. 应用单点说明

2.3.1.配置应用管理

配置应用管理信息，将应用放到工作台上。

飞书应用管理页面地址如下：

https://ghupecklnh.feishu.cn/admin/appCenter/manage

调整应用分类

配置应用可见范围

配置完成后，即可在桌面版的飞书内看到该应用入口了。

正常完成用户信息同步后，点击即可进入到smartbi首页了。

移动端进入时，会进入到移动端首页。

2.4. 用户组织同步

在完成集成配置后，可通过系统功能，新建任务进行信息同步。

2.4.1. 配置同步用户组任务

如下步骤，新建任务，并将定制提供的脚本粘贴到代码编辑区。

保存后即可测试运行进行用户组同步。

任务代码如下：

connector.remoteInvoke("FeiShuCommonModule","syncFeiShuGroup",[]);

2.4.2. 配置同步用户任务

在Smartbi中创建定制任务

宏代码如下

connector.remoteInvoke("FeiShuCommonModule","syncFeiShuUser",[true]);

2.4.3. 执行同步用户组和用户

执行顺序：先执行用户组同步，然后再执行用户，因为在Smartbi中，用户是挂靠在用户组下的，如果先执行同步用户，可能该用户的用户组在Smartbi中不存在，导致同步异常；

手动执行：任务创建完成后，可手动操作上述两个任务的【测试运行】功能即可手动触发数据同步；

自动执行：如需系统定时自动执行，可创建计划绑定上述两个任务，任务顺序按用户组优先；

配置计划绑定任务：

2.4.4.手动同步

可以手工配置用户编辑页面的飞书用户ID保存，保存后该用户即可从飞书单点登录到Smartbi；

2.5. 消息推送

2.5.1. 手动推送

配置完飞书权限后，可进到smartbi内，右键要分享的资源（仅支持电子表格，web电子表格，url链接，页面，office分析报告，自主仪表盘资源）；可看到【推送到飞书应用】的操作入口。

点击后会弹出推送到飞书应用的提示框

点击【推送人员】后面的操作按钮，会弹窗供选择接收信息的角色，用户组或者用户

标题内容为消息首行加粗的文本信息，必填默认为当前推送报表资源的名称。

描述为推送信息内的文字信息，可为空。

点击图片后的【选择文件】按钮，可选择推送时带上的图片信息。

链接地址，自动生成，不允许修改，正常是读取当前访问Smartbi的域名，拼接出带/vision/feishu/openresource.jsp的链接，并带上当前操作的resid

点击推送时，会弹出推送确认。

点击是时，将会进行推送（推送可能存在延迟），并返回推送结果。

推送成功后，将会在飞书内收到对应的信息。

如应用单点登陆部署正常，推送的链接也是单点登陆的域名，则点击查看详情时，将会免密打开对应的报表。

2.5.2. 定时推送普通应用消息

通过任务脚本，定时推送普通的应用消息（带标题、消息内容、报表访问链接）到被推送用户的飞书上；

2.5.2.1. 操作步骤

如下步骤，新建任务，并将定制提供的脚本粘贴到代码编辑区。

保存后即可测试运行推送报表到飞书。

2.5.2.2. 任务脚本

// 推送资源报表到飞书，目前仅支持电子表格，web电子表格，url链接，页面，office分析报告，自主仪表盘资源

importPackage(Packages.smartbi.sdk.service.systemconfig);

/****************** 配置 - 开始******************/

// 必须配置：报表资源ID

var reportId = 'I8a8a8d2a018584b084b0fae2018584fde1d200a0';

// 必须配置：推送标题

var title = "消息标题";

// 可选配置：推送消息内容

var desc = "这是一段消息内容";

// 必须配置：接收者在Smartbi的用户，用户组或者角色id；

// 若配置的是用户，则type设置为"USER"；若配置的是用户组，则type设置为"GROUP"；若配置的是角色，则type设置为"ROLE"；

// id需要配置对应的用户id，用户组id或者角色id

var sendUser = [

{type: "USER", id: "用户ID1"},

{type: "USER", id: "用户ID2"},

{type: "GROUP", id: "用户组ID"},

{type: "ROLE", id: "角色ID"}

];

/****************** 配置 - 结束******************/

var sendUrl = "";

var systemConfigService = new SystemConfigService(connector);

var urlConfig = systemConfigService.getSystemConfig("INTEGRATED_APPLICATION_ADDRESS");

if (urlConfig !== null && urlConfig.getLongValue() !== null && urlConfig.getLongValue() !== "") {

sendUrl = urlConfig.getLongValue();

if(!sendUrl.endsWith('/')){

sendUrl = sendUrl+'/';

}

sendUrl += "vision/feishu/openresource.jsp?feishu=true&sh=false&refresh=true&showtoolbar=false&showPath=false&iPad=true&sendTarget=auto&resid=" + reportId;

}

var sendSetting = {

reportId: reportId,

title: title,

sendUrl: sendUrl,

desc: desc,

sendUser: sendUser

};

connector.remoteInvoke("FeiShuCommonModule","sendInfoToFeiShu",[JSON.stringify(sendSetting)]);

2.5.2.3. 配置项说明

1、报表资源ID：配置需要推送的报表资源的id，配置之后，点击推送消息的“查看详情”可以直接跳转Smartbi，打开对应资源。

获取报表资源id的方式如下，右键点击需要推送的报表资源，点击属性，便可以看到节点id，节点id就是报表资源id：

2、推送标题：配置推送此消息时，显示的标题，如截图所示红框部分：

3、推送消息内容：配置推送此消息时，显示的消息内容，如截图所示红框部分：

4、推送消息接收者，在Smartbi中对应的用户id、用户组id或者角色id：配置消息的接收者，若配置的是用户，则type设置为"USER"；若配置的是用户组，则type设置为"GROUP"；若配置的是角色，则type设置为"ROLE"，id需要配置对应的用户id，用户组id或者角色id，id可通过查询t_user（用户表）、t_group（用户组表）和t_role（角色表）获取。

2.5.2.4. 配置相关计划定时推送

打开计划-新建计划，绑定刚刚创建的任务设置定时时间即可；

2.5.3. 定时推送电子表格带图的应用消息

通过任务脚本，定时推送带图的应用消息（标题、消息内容、报表导出图片、报表访问链接）到被推送用户的飞书上；

说明：导出的图片按任务任务的执行账号对报表执行导出，如果推送的报表资源对不同用户有不同数据权限，请使用2.5.2的普通应用消息进行推送。

2.5.3.1. 操作步骤

如下步骤，新建任务，并将定制提供的脚本粘贴到代码编辑区。

保存后即可测试运行把资源报表导出图片，然后推送图片到飞书。

2.5.3.2. 任务脚本

// 把资源报表导出图片，然后推送图片到飞书，目前仅支持电子表格、web电子表格

importPackage(Packages.smartbi.sdk.service.systemconfig);

/****************** 配置 - 开始******************/

// 必须配置：电子表格ID

var reportId = 'I8a8a8d2a018584b084b0fae2018584fde1d200a0';

// 必须配置：可配置推送标题

var title = "测试电子表格";

// 可选配置：推送消息内容

var desc = "这是一段消息内容";

// 必须配置：接收者在Smartbi的用户，用户组或者角色id。

// 若配置的是用户，则type设置为"USER"；若配置的是用户组，则type设置为"GROUP"；若配置的是角色，则type设置为"ROLE"

// id需要配置对应的用户id，用户组id或者角色id

var sendUser = [

{type: "USER", id: "用户ID1"},

{type: "USER", id: "用户ID2"},

{type: "GROUP", id: "用户组ID"},

{type: "ROLE", id: "角色ID"}

];

// 可选配置：导出电子表格的参数信息---------------------------------------------

// 设置格式：{id:"OutputParameter.数据集ID.参数名称",value:参数真实值,displayValue:参数显示值}，参数值可

// 以设置为固定值，变量，或者默认值，默认值写法："$默认值$"，例如如：{id:"OutputParameter.I2c9019810158fc12fc1224c00158fc2e21c50069.测试",value:"$默认值$",displayValue:"$默认值$"}

var reportParamSetting = [

//{id:"OutputParameter.I8a8a9be9018671b671b6e610018671d0e80500e8.用户",value:"SCHEDULEADMIN",displayValue:"计划管理员"}//多个参数之间以逗号分隔

];

/****************** 配置 - 结束******************/

// 以下内容无需配置

var sendUrl = "";

var systemConfigService = new SystemConfigService(connector);

var urlConfig = systemConfigService.getSystemConfig("INTEGRATED_APPLICATION_ADDRESS");

if (urlConfig !== null && urlConfig.getLongValue() !== null && urlConfig.getLongValue() !== "") {

sendUrl = urlConfig.getLongValue();

if(!sendUrl.endsWith('/')){

sendUrl = sendUrl+'/';

}

sendUrl += "vision/feishu/openresource.jsp?feishu=true&sh=false&refresh=true&showtoolbar=false&showPath=false&iPad=true&sendTarget=auto&resid=" + reportId;

}

var sendPictureSetting = {

reportId: reportId,

title: title,

desc: desc,

sendUrl: sendUrl,

sendUser: sendUser,

reportParamSetting: reportParamSetting

};

connector.remoteInvoke("FeiShuCommonModule","sendPictureToFeishu",[JSON.stringify(sendPictureSetting)]);

2.5.3.3. 配置项说明

参考2.3.1，此处仅补充一处2.3.1没有的配置项：

可选配置，导出电子表格的参数信息，这项配置项可以用于配置以什么参数来导出电子表格。参数id的获取方式参考下方说明：

右键点击目标电子表格，点击“血统分析”，打开数据集：

按以下操作，即可获取参数id：

而参数的真实值和显示值，可以通过“系统运维-全局资源定义-参数定义-打开参数-预览备选值”来获取：

2.5.3.4. 配置相关计划定时推送

请参考2.5.2.4

2.5.4. 定时推送自定义机器人消息（群消息）

通过计划任务定时向飞书推送群消息。

2.5.4.1. 操作步骤

（1）飞书自定义机器人配置

打开群设置：

进入群机器人：

添加自定义机器人：

配置webhook：

其中webhook地址需要在Smartbi中使用；

如果需要设置签名，签名秘钥需复制到Smartbi中使用；

（2）新建任务，并将定制提供的脚本粘贴到代码编辑区。

保存后即可测试运行推送报表到飞书。

2.5.4.2. 任务脚本

importPackage(Packages.java.io);

importPackage(Packages.java.net);

importPackage(Packages.java.lang);

importPackage(Packages.smartbi.net.sf.json);

importPackage(Packages.smartbi.ext.feishu.common)

/****************************** 配置开始 ******************************/

//机器人webhook

var webhook = "https://open.feishu.cn/open-apis/bot/v2/hook/c2538dae-218f-41a8-abaf-6435a828258b";

//签名校验，如果不需要可以置空

var secret="NWswmBHaiQjHoDaIZ2dnbg";

//消息标题

var title="消息标题";

//消息内容

var content ="测试消息内容";

//按钮显示内容

var btnStr="打开报表"

//按钮打开的报表链接

var btnUrl="http://10.10.13.170:8080/smartbi/vision/feishu/openresource.jsp?feishu=true&sh=false&refresh=true&showtoolbar=false&showPath=false&iPad=true&resid=I297e289f017ccb5fcb5fe29e017ccb6a9ae50099";

/****************************** 配置结束 ******************************/

var rtn = httpRequest(webhook, "POST",secret,title, content,btnStr,btnUrl);

logger.info("返回结果为：" + rtn);

//发送消息

function httpRequest(requestUrl, requestMethod,secret, title, content, btnStr, btnUrl) {

var httpUrlConn = null;

var url = new URL(requestUrl);

httpUrlConn = url.openConnection();

httpUrlConn.setDoOutput(true);

httpUrlConn.setDoInput(true);

httpUrlConn.setUseCaches(false);

// 设置请求方式（GET/POST）

httpUrlConn.setRequestMethod(requestMethod);

httpUrlConn.setRequestProperty("Content-Type", "application/json");

httpUrlConn.setRequestProperty("Charset", "UTF-8");

/****************** 拼接发送内容（包括签名） - 开始 *****************/

var dataStr='{"msg_type": "interactive",'

+'"card": {'+'"header": {"title": {"tag": "plain_text","content": "'+title+'"}},'

+'"elements": ['

+'{"tag": "div","text": {"tag": "lark_md","content": "'+content+'"}}';

if(btnStr!=null && btnStr!=''){

dataStr=dataStr+',{"actions": [{"tag": "button","text": {"tag": "lark_md","content":"'+btnStr+'"},"url": "'+btnUrl+'","type": "default"}],"tag": "action"}';

}

dataStr=dataStr+']}}';

var jsonObj = JSONObject.fromString(dataStr);

//如果秘钥不为空则视为需要签名

if(secret!=null && secret!=''){

var timestamp = parseInt(System.currentTimeMillis()/1000);

var sign = FeiShuCommonModule.getInstance().GenSign(secret,timestamp);

jsonObj.put("timestamp",""+timestamp);

jsonObj.put("sign",sign);

}

logger.info("发送请求参数：" + jsonObj.toString());

/******************拼接发送内容（包括签名） - 结束 *****************/

httpUrlConn.connect();

var writer = new OutputStreamWriter(httpUrlConn.getOutputStream());

// 发送参数

writer.write(jsonObj.toString());

// 清理当前编辑器的左右缓冲区，并使缓冲区数据写入基础流

writer.flush();

// 将返回的输入流转换成字符串

var inputStream = httpUrlConn.getInputStream();

var inputStreamReader = new InputStreamReader(inputStream, "UTF-8");

var bufferedReader = new BufferedReader(inputStreamReader);

var str = null;

var buffer = "";

while ((str = bufferedReader.readLine()) !== null) {

buffer += str;

}

bufferedReader.close();

inputStreamReader.close();

// 释放资源

inputStream.close();

httpUrlConn.disconnect();

var jsonObject = buffer.toString();

return jsonObject;

}

2.5.4.3. 配置项说明

webhook：机器人webhook，可在群设置中的机器人配置中找到（如下图）；

Secret：签名秘钥，可在群设置中的机器人配置中找到（如下图），如果没设置签名校验，可设置空；

title：消息标题;

content：消息内容;

btnStr：按钮显示内容；

btnUrl：按钮打开的报表链接；

2.5.4.4. 配置相关计划定时推送

请参考2.5.2.4

2.5.5. 定时推送电子表格导出文件或图片到用户或群

导出电子表格文件或图片推送给用户或者推送给应用机器人有权限的群；

2.5.5.1. 操作步骤

如果要推送到群，需要按如下步骤配置：

1、飞书后台管理配置应用机器人，参考 2.2.1.6

2、在群里添加smartbi应用对应的机器人：

3、新建任务，并将定制提供的脚本粘贴到代码编辑区，根据实际情况调整脚本配置内容：

2.5.5.2. 任务脚本

2.5.5.3. 配置项说明

脚本的配置项说明具体可参考脚本中的注释

导出报表文件或图片发送给用户或群任务脚本.txt

2.5.5.4. 使用效果

1、推送pdf文件消息到群的效果（脚本配置项uploadType = "file"）：

2、推送png带图片的富文本消息到群的效果（图片可预览，脚本配置项uploadType = "img"）：

3、推送png文件消息到群的效果（图片当做文件发送，脚本配置项uploadType = "file"）：

3. 常见问题

3.1. 配置飞书系统选项报错

问题：配置系统选项-飞书集成时，如果提示无法获取token

解决方案：如果报错为【UnknownHostException: open.feishu.cn】，如下图，请检查服务器是否做了网络访问限制，导致服务器无法正常访问飞书的接口，开放飞书网络访问限制即可；

关注我们

服务支持

页面树结构

飞书集成Smartbi

1 需求场景

2 使用说明

2.1 加载扩展包

2.2. 集成说明

2.2.1. 步骤1 配置飞书应用

2.2.1.1. 登录飞书开发者后台

2.2.1.2. 创建应用（假如是基于已有应用进行开发，可以跳过这一步）

2.2.1.3. 完善应用凭证与基础信息

2.2.1.4. 记录应用信息(后续需要配置到smartbi内)

2.2.1.5. 配置应用功能-网页

2.2.1.6. 配置应用功能-机器人

2.2.1.7. 配置安全设置

2.2.1.8. 应用权限开通说明

2.2.1.9. 版本与管理

2.2.2. 步骤2 配置Smartbi系统选项

2.2.2.1. 正常部署扩展包

2.2.2.2. 配置飞书相关信息

2.3. 应用单点说明

2.3.1.配置应用管理

2.4. 用户组织同步

2.4.1. 配置同步用户组任务

2.4.2. 配置同步用户任务

2.4.3. 执行同步用户组和用户

2.4.4.手动同步

2.5. 消息推送

2.5.1. 手动推送

2.5.2. 定时推送普通应用消息

2.5.2.1. 操作步骤

2.5.2.2. 任务脚本

2.5.2.3. 配置项说明

2.5.2.4. 配置相关计划定时推送

2.5.3. 定时推送电子表格带图的应用消息

2.5.3.1. 操作步骤

2.5.3.2. 任务脚本

2.5.3.3. 配置项说明

2.5.3.4. 配置相关计划定时推送

2.5.4. 定时推送自定义机器人消息（群消息）

2.5.4.1. 操作步骤

2.5.4.2. 任务脚本

2.5.4.3. 配置项说明

2.5.4.4. 配置相关计划定时推送

2.5.5. 定时推送电子表格导出文件或图片到用户或群

2.5.5.1. 操作步骤

2.5.5.2. 任务脚本

2.5.5.3. 配置项说明

2.5.5.4. 使用效果

3. 常见问题

3.1. 配置飞书系统选项报错