# 飞书审批泛微 E9 Connector 部署方案 本文档介绍如何使用泛微 E9 Connector 集成泛微审批到飞书审批中心。 **注意事项**：飞书文档可参考：[飞书审批泛微 E9 Connector 部署方案](https://bytedance.larkoffice.com/docs/doccnUs8IzdmUO1xDszh3N0Wfsd)。 ## 集成效果演示 ## 准备信息检查表 本小节提供部署之前需准备的环境、信息的检查表。你可复制该表，将已准备的信息直接粘贴进去。 所属模块 | 准备信息 | 对应账号、地址等信息 ---|---|--- 部署Connector的服务器 | 外网地址、端口号 |   外网域名 |   飞书自建应用 | App ID和App Secret |   应用权限确认已开通 |   重定向URL、IP白名单确定已配置 |   泛微统一认证中心配置 | Token认证服务确认已启用（启用后需要重启OA） |   认证应用的应用标识 |   IP白名单已配置 |   映射关系配置正确 |   OA服务 | 内网地址 |   外网地址 |   确认Webservic服务已开通 |   OA数据库信息 | 数据库地址、端口号 |   database |   数据库账号、密码 |   ## 服务器要求 本小节介绍部署的硬件和网络要求。 本方案支持云上部署，建议提供云服务器，Connector 占用资源不多，需要的规格不高、花费不多，且云服务器方便调试与维护。 ### 硬件要求 - 服务器：Linux，Windows - 规格：>= 2核8G - 磁盘 ：>= 20G ### 外网域名映射要求 由于以下原因，需做外网域名映射。 - 避免安全策略拦截 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2b63d77590f14f3f0646df2b334dadcc_i6q9HHhQ3z.png?height=461&lazyload=true&maxWidth=442&width=742) - 避免更换部署服务器导致历史同步到飞书的单据无法打开 - 原因：OA单据同步到飞书，会在飞书服务端保存跳转地址，地址格式示例“Connector地址/sso/login?redirectUrl=OA地址+requestid” - 如果Connector地址变化，会导致历史同步的单据无法打开 ### 网络要求 - 从服务器可以访问泛微应用 - 从服务器可以访问泛微系统数据库 - 从服务器可以访问外网域名：[https://open.feishu.cn](https://open.feishu.cn/), [https://www.feishu.cn](https://www.feishu.cn/) - 将部署服务器开放 1117 端口（默认这个，其他端口也可以）warning 连接器开放到外网的时候，请不要将所有接口地址都开放到外网上，由于管理后台暴露到公网上，后台账号密码泄漏后会有安全风险，只需要开启有限的接口地址（不开启外网访问的话，内网环境可以免登，但是不能使用快捷审批） - 用户获取免登 token - /sso/login - /sso/feishuCallback - 飞书审批回调 - /callback/approval/operate ## 步骤一：创建飞书团队 创建您企业所在的飞书团队，参考： [1分钟快速创建团队](https://www.feishu.cn/hc/zh-CN/articles/360049067641#referrer=hcFeedback&source=landing_suggestion)。 ## 步骤二：创建飞书审批泛微 Connector 企业应用 1. 管理员身份打开 [开发者后台](http://open.feishu.cn/app)，点击“创建企业自建应用”，应用名称填写“飞书审批泛微Connector”，应用描述填写“飞书审批泛微 Connector”。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ae3f094d5a760d164231c1a9c2bcf61e_vAMZ18yOMu.png?height=1570&lazyload=true&width=2624) 2. 创建好应用后，获取到相应的 App ID 和 App Secret，会在后续步骤步骤中使用到。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b98b9e3dfd4902601f1b880ce878653f_H3oOVQGuV8.png?height=894&lazyload=true&width=2772) 3. 开启机器人能力 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d05afd098dfb853b5b7022c9d356a790_9Vv5xCuDBS.png?height=990&lazyload=true&width=2734) 4. 授予应用权限：点击左侧“权限管理”，然后在右侧“选择所需的权限”处，选择 **“通讯录”，“云文档”** ， **“消息与群组”** ， **“审批”** 下的部分权限： - 通讯录（只需要 读取类权限，不需要新建、更新权限） - 获取用户 user ID - 通过手机号或邮箱获取用户 ID - 获取通讯录基本信息 - 以应用身份读取通讯录 - 获取部门基础信息 - 获取通讯录部门组织架构信息 - 获取用户基本信息 - 获取用户组织架构信息 - 获取用户邮箱信息 - 获取用户手机号 - 审批（需要读取类权限、新建、更新类权限） - 查看、创建、更新、删除审批应用相关信息 - 查询审批列表 - 访问审批应用 - 查看、创建、更新、删除三方审批实例相关信息 - 消息与群组（需要读取类权限、新建、更新类权限） - 获取与更新群组信息 - 读取群信息 - 更新应用所创建群的群信息 - 获取群组信息 - 获取与发送单聊、群组消息 - 更新应用创建群聊的信息 - 以应用的身份发消息 - 云文档（需要读取类权限、新建、更新类权限） - 查看、评论、编辑和管理电子表格 **注意**：“通讯录”、“消息与群组”要翻页，这两目录下的权限有多页，需要翻页后再次全部勾选。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/12a4f9b3646f92890b5a3b591f019fbe_vgS53XT6Ve.png?height=1350&lazyload=true&width=2772) 5. 点击安全设置，添加“重定向URL”和“IP白名单”： ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/fcb26023db6b2f8661613b40acc47088_t7skLdDFfl.png?height=968&lazyload=true&width=2786) - 重定向 URL，用于在飞书端免登 OA。将重定向 URL 填写为 **（建议用域名）** ： `http://{替换为您部署飞书审批泛微Connector的``外网地址``}/sso/feishuCallback` > 示例：计划将飞书审批泛微Connector部署在内网服务器：10.227.78.75:1117 上， > 公网访问地址： 112.10.12.41:1117 \ > 重定向URL： （1117 端口是示例，如果部署的时候修改了端口，填写实际打开的端口号） - IP 白名单：填写准备部署 Connector 服务器的出口 IP **注意**： - IP白名单不要填写成内网地址，错误率非常高。不清楚可以先不填写，之后再写。 - 未填写的情况，请先妥善保管好你的 app_id，app_secret。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8a23d8eead6f1998664786a990bed8ee_cnCXXEmyd2.png?height=1310&lazyload=true&width=2798) 6. 给应用添加一个图标，可使用下方提供的图标： 图标可以自行选择，如果没有合适的，可以先使用下方我提供的 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/fb5cacb3ca6654d07306739f7a6347e5_Aegp72iUkD.jpeg?height=1036&lazyload=true&maxWidth=342&width=1036)![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2c4b998433312fb31fd2bcf46f9714d3_W6CPPuNWQf.png?height=1198&lazyload=true&width=2770) 7. 创建版本：点击左侧“版本管理与发布”，再在右侧点击“创建版本”。或者直接点击上方的提示栏的“点击创建” ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2ff2e88158d2821e03f7fe470eaf83a0_QDjMW2sUaA.png?height=1220&lazyload=true&width=2788) 8. 填写版本详情。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d1306c509fa54e73f0cf39920c8afc5b_vAT0srDRyF.png?height=1138&lazyload=true&width=2756) 9. 可用性状态编辑：此处选择全部员工（后续仍可以通过连接器后台灰度控制）。 > 还在发布版本的页面里，往下滚动 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7362f548407e88a16eda8d45e8f80fe6_81SUnYwVA3.png?height=1188&lazyload=true&width=2800) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/c2d6d653448279bb4dac05a60d7d14c1_PlGhxQR2ap.png?height=1242&lazyload=true&width=2798) 10. 点击“申请发布”。请务必发布，否则上述修改不生效。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7e1c94cfcd6da69a18b9287d69645937_pn2zWPDlyR.png?height=1352&lazyload=true&width=2796) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/93806d48e718f84afcd2466ebee77713_dRUMjrEbXR.png?height=1162&lazyload=true&width=2784) 11. 管理员会收到飞书提醒，点击“去审核”通过即可。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/c42b65c2ae707026ec50d7b46bff961d_Dua7POMc2h.png?height=206&lazyload=true&maxWidth=542&width=738) ## 步骤三：泛微后台配置统一认证 1. 进入泛微管理员后台，进入“集成中心”，“统一认证中心"。启用泛微 Token 认证。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/99c9eddce50ffb5c6624de8051b0c88d_dYDPxgUkme.png?height=742&lazyload=true&maxWidth=542&width=2370) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/983fab8f679e12eeaf8a8ecae619a1c0_VjrTxupRYg.png?height=898&lazyload=true&maxWidth=542&width=1500) 会有信息确认，需要重启，点击确认即可，重启一般很快（1分钟内），不放心可在下班时间操作。 2. 注册认证应用。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/9a440daba153cef40d8dc3366228f72a_YlBTxhF9hJ.png?height=1596&lazyload=true&maxWidth=542&width=2542) 点击 ④ 生成，然后将应用标识复制保存下来，在【功能验证启用配置并检查“运行监控”】启用配置时会用到。 IP 白名单填写为部署飞书泛微 Connector 机器的地址，填写`127.0.0.1,${connector部署服务器内网IP}` ，需要使用英文标点符号。 **注意**： - 账号映射规则：目前支持“手机号码”和“邮箱”，需要泛微的与飞书的一致。 - 飞书的邮箱是通讯录成员的联系邮箱（管理员后台可以操作编辑），不是用于飞书登录的邮箱地址。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/93a2002f710530c4278014ee48f1bbe5_QC9YjjzQcr.png?height=1412&lazyload=true&maxWidth=542&width=2048) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/9ff1c7e8b7e1939da8ffac68c27456c4_DSr8yMr2aq.png?height=968&lazyload=true&maxWidth=542&width=2656) 3. 准备数据库账号信息：地址，database，账号密码。建议新增账号，并开通以下表的读权限。 - 不开通托管需要的表权限如下： ``` workflow_nodeform（工作流节点字段表） workflow_nodebase（工作流节点基本信息表） workflow_currentoperator（工作流请求节点操作人信息表） workflow_requestbase（工作流请求基本信息表) workflow_base（工作流基本信息表) workflow_flownode（流程流转节点表 ） workflow_freenode（流程自由节点表） workflow_urgerdetail（流程督办表） workflow_requestdeletelog（流程请求删除log表） workflow_requestoperatelog（流程操作log表） workflow_requestlog（工作流请求签字日志表） ecology_message_info_read（消息发送记录表) ecology_biz_ec (三方信息注册表） hrmresource（人员信息表） hrmdepartment（人员部门表） workflow_nodelink(工作流节点出口信息表) hrm_transfer_log(人力资源权限转移表) hrm_transfer_log_detail(人力资源权限转移详细信息表) workflow_type(工作流种类表) workflow_otheroperator(工作流暂停、撤销、启用操作信息表) hrmsubcompany（人员部门表） workflow_agent（代理设置信息表） ecology_message_config（消息配置表） ecology_message_config_detail（消息详细配置表） ``` - 如果要开通托管，除了上述 24 张表以外，还需要额外开通以下权限： ``` workflow_nodehtmllayout workflow_communicationcontent workflow_communicationbase workflow_communicationreply hrm_transfer_log_detail hrm_transfer_log workflow_groupdetail imagefile workflow_formfield_group workflow_billfield workflow_viewattrlinkage workflow_systemfield_group ``` ## 步骤四：部署 Connector ### 1. 获取 Connector 和 JDK 根据对应的 OA 版本和部署服务器的系统将文件上传到机器上（任意位置）的相同目录下 目前飞书审批泛微E9 Connector方案为付费方案：[方案咨询预约：三方审批与飞书审批待办集成](https://bytedance.larkoffice.com/share/base/form/shrcnXQcYnmExCz2Vj67VDqxmu5) - Windows 直接解压两个 zip 文件（将 JDK 文件夹和 approval-connector-service 移动到同一个文件夹，如下展示： **提示**：JDK 放在目录下不会影响别的应用。你也可以添加环境变量 JAVA_HOME 指向已有 JDK 的目录。 ``` ├── JDK └── approval-connector-service ``` ### 2. 将 Connector 部署服务器的 1117 端口暴露到外网 连接器开放到外网的时候，请不要将所有接口地址都开放到外网上，由于管理后台暴露到公网上，后台账号密码泄漏后会有安全风险，只需要开启有限的接口地址（不开启快捷审批功能的话可以不开启外网访问）warning - 用户获取免登 token - /sso/login - /sso/feishuCallback - 飞书审批回调 - /callback/approval/operate - 开启托管需增加以下接口 - /trusteeship/operate - /trusteeship/button - /trusteeship/node - /trusteeship/detail - /trusteeship/download 端口不是固定的可以自行做映射能联通即可 需要暴露到外网的原因： 1. 用于快捷审批，飞书回调使用（如果是内网环境，飞书的回调请求无法进来） 1. 非办公网下使用飞书审批 Connector ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/bc4f402178e4f16bf8f6d7b48ddb08b1_bcqMWFIwTl.png?height=1412&lazyload=true&maxWidth=542&width=2048) 需要外网能够访问部署的 connector 机器 > 示例：计划将 connector 部署在您的内网 ip: 192.168.122.225 机器 (端口使用默认配置 1117)，您公司的外网地址是58.6.125.161，可以做如下映射 58.6.125.161:1117 -> 192.168.122.225:1117 \ > 端口不是固定的，您可以自己决定使用哪个端口，下面的配置文件中可以修改 常见问题：能否限制端口的入流量 IP？ 答：不行，有一个从连接器获取OA 免登 token 的接口，入流量是用户客户端地址，无法限制来源。 ### 3. 开启 WebService WebServices 提示错误的，请按照下图处理： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/84ce1bd341de94908186cbbd6d59b6c7_6wtEqrv7nt.png?height=302&lazyload=true&maxWidth=542&width=1784) 后台运行详情页 Webservices 接口开启失败的再按此操作，可以先跳过。 没有成功的按以下操作步骤开启： 1. 下载文件： [weaver_security_custom_rules_ws_20210818.xml](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/5266ca3f8ad7d007405d63261321dc23_XQBhsbqdZ7.xml) 2. 在 ``下面添加一个``的替换下即可，这个是 ip 白名单 2. 将修改好的文件（文件名可以自定义，只要保证后缀是.xml即可）放到`/ecology/WEB-INF/securityXML/`目录下，用 sysadmin 登录，访问 `http://oa域名或ip/updateRules.jsp`即可生效(如果是集群环境，需要每个节点都访问下该地址），无需重启OA服务。（重启服务也可以生效）。 2. 然后在 connector 服务器 ip 执行请求查看下请求是否能成功，不是 404 的就是成功了（没有成功的可稍后重试） - Linux 服务器请执行以下命令： ``` $ curl http://oa服务器内网IP/services/WorkflowService?wsdl ``` - Windows 服务器，请直接在浏览器打开这个地址 http://oa服务器内网/services/WorkflowService?wsdl 提示
如果您的OA可以在外网访问，并且通过外网该地址能够请求成功的话如下图所示的结果，将存在安全性风险。请参考以下步骤处理。如果不清楚或者没有成功，请联系 OA 的实施。 `将文件中的 ` 填写上限定访问的IP，然后重启OA服务器。
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0e29b4fa45a5e0b2308510eeb0e63836_dAZfXwhbyR.png?height=1072&lazyload=true&maxWidth=542&width=2112) ### 4. 修改部署端口后台密码等配置 请务必修改密码。 Connector 的配置文件为 `application-custom.``properties` 在 `application-connector-service/conf` 目录下，部署服务的端口号可以在这里面修改。 ``` # 服务启动端口 server.port=1117 # 快捷审批回调 token, 修改成任意值 fanwei.callback-token=20211117 ``` 密码可以在 /conf/admin.setting 中进行设置： **注意**：服务首次启动后生成此文件，也可在启动前手动创建。 ``` [] user = connector password = 2021 ``` ### 5. 启动与关闭 Connector - Windows 用户右键“以管理员身份运行” 依次执行脚本： - approval-connector-service/bin/nssm-install.cmd - approval-connector-service/bin/nssm-start.cmd **注意**：杀毒软件会拦截nssm-install.cmd 脚本注册windows服务，执行脚本前请关闭360等杀毒软件。 - **Linux** **执行以下命令**： ``` $ cd approval-connector-service/bin/ $ ./startup.sh ``` 如果启动成功的话会输出`connector startup success!`： ``` /usr/weaver/jdk1.8.0_151/bin/java -server -Xms2g -Xmx2g -Xmn1g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m -XX:-OmitStackTraceInFastThrow -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/root/approval-connector-service/logs/java_heapdump.hprof -XX:-UseLargePages -Djava.ext.dirs=/usr/weaver/jdk1.8.0_151/jre/lib/ext:/usr/weaver/jdk1.8.0_151/lib/ext -Xloggc:/root/approval-connector-service/logs/gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=100M -jar /root/approval-connector-service/target/approval-connector-service.jar --spring.config.additional-location=file:/root/approval-connector-service/conf/ --spring.application.profiles.active=custom --logging.config=/root/approval-connector-service/conf/logback-spring.xml --server.max-http-header-size=524288 connector is starting，you can check the /root/approval-connector-service/logs/start.out ================================================================================ ================================================================================ waiting for connector to response.... waiting for connector to response.... waiting for connector to response.... waiting for connector to response.... connector startup success! ``` 若启动失败，请根据提示去目录下查看启动日志： ``` /usr/weaver/jdk1.8.0_151/bin/java -server -Xms2g -Xmx2g -Xmn1g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m -XX:-OmitStackTraceInFastThrow -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/root/approval-connector-service/logs/java_heapdump.hprof -XX:-UseLargePages -Djava.ext.dirs=/usr/weaver/jdk1.8.0_151/jre/lib/ext:/usr/weaver/jdk1.8.0_151/lib/ext -Xloggc:/root/approval-connector-service/logs/gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=100M -jar /root/approval-connector-service/target/approval-connector-service.jar --spring.config.additional-location=file:/root/approval-connector-service/conf/ --spring.application.profiles.active=custom --logging.config=/root/approval-connector-service/conf/logback-spring.xml --server.max-http-header-size=524288 connector is starting，you can check the /root/approval-connector-service/logs/start.out ================================================================================ ================================================================================ waiting for connector to response.... waiting for connector to response.... waiting for connector to response.... waiting for connector to response.... waiting for connector to response.... connector startup failed, please check the /approval-connector-service/target/approval-connector-service/logs/start.out for detail! ``` **关闭 Connector** 如果要关闭 Connector ，执行 stop.sh 即可。 **注意**：请不要用 kill pid 方式关闭 Connector，有守护脚本会在 Connector 异常退出时自动重新启动。 ``` $ cd approval-connector-service/bin/ $ ./stop.sh ``` 执行命令后输出如下： ``` The connector(9214) is running... Send shutdown request to connector(9214) OK The watchdog(8649) is running... Send shutdown request to watchdog(8649) OK ``` ### 6. 功能验证 **登录到后台** 浏览器打开部署的地址，输入在【步骤四.修改部署端口后台密码等配置】中设置的账号密码，登录进去进入到“灰度设置”，“启用配置”按页面上提示完成配置即可。 - 地址：部署 Connector 的服务器地址+端口号（例如：www.feishuConnector.com:1117) - 账号密码：工程目录下 /conf/admin.setting 中 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/abfec78a79af26f1abb5f87df72c1141_ubNvXuFCMq.png?height=1690&lazyload=true&maxWidth=542&width=2530) **启用配置并检查“运行监控”** 在“启用配置”页面，将前置准备的信息补充到配置页面： 页数 | 菜单项 | 需填写内容 | 来源系统 ---|---|---|--- 第一页 | App ID | 飞书自建应用的AppID | 飞书开发者后台-企业自建应用 App Secret | 飞书自建应用的App Secret 认证应用-应用标识 | 泛微认证应用的应用标识 | 泛微OA-统一认证中心-认证应用 账号映射规则（认证应用） | OA 和飞书有 1：1 匹配的规则，需要和OA侧配置的一致，支持3种方式：
1. OA手机号--飞书手机号
2. OA邮箱--飞书邮箱
3. OA工号--飞书 userid 第二页 | OA系统内网地址 | OA内网地址，需要带http或者https | OA系统，用于通过这个地址请求OA接口 OA系统外网地址（PC, 不要填写移动管理平台地址） | OA外网地址，需要带http或者https | OA系统，用于打开审批单据的地址；
如果OA没有开放外网访问，可以填内网地址。--在飞书打开OA单据，也只支持在内网环境 OA系统外网地址（移动, 不要填写, 特殊场景下填写） | OA移动端的外网地址，一般不需要填写 | OA系统，用户打开单据移动端页面的地址；
这里95%的场景不需要填写，仅在OA只能在PC访问时，移动端是通过云桥访问的场景下填写 数据库信息 | OA数据库信息 | OA系统
特殊场景：如果说Oracle，有多租户，需要选oracle2 第三页 | Connector 外网地址 | 部署Connector的服务器的外网地址， | 部署Connector的服务器。
建议用域名（避免后续更换服务器导致的历史单据无法打开；或者因为飞书安全策略，导致IP地址打开报错） 连接器管理员飞书账号（手机号、邮箱或者工号） | Connector服务的运维人员 | 接收Connector相关告警，比如：
磁盘空间、CPU告警；人员不匹配的告警 其他配置（无特殊需求无需修改, 修改后仅对新发送的审批消息和新同步的流程生效） | OA发起申请和详情页的后缀地址，一般不需要填写 | OA系统 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/92ef5e1d039445097e4bd765cf89de81_IiLhn6swIo.png?height=1616&lazyload=true&maxWidth=542&width=3280) 然后点击左侧菜单的“运行监控”查看是否有检查失败的配置项。帮助信息请搜索查看本文档“启用配置帮助：如何获取数据库配置”一节。 都通过后，点击下图中框出来的两个按钮，飞书审批会收到一条信息，按照按钮上的提示验证下功能即可。 **修改灰度范围** 灰度范围指在范围内的用户会收到审批的通知和提醒，关闭灰度范围意味着所有用户都可以使用审批。 当前版本为了减少初次部署对客户的影响，默认开启灰度并设置所有用户不可用，部署的时候如果没有进行过配置，请按照文档操作。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/88a7e4021d527bbc6b993a7726e80b21_50qZHDGpzJ.png?height=1404&lazyload=true&maxWidth=542&width=2716) **验证功能** ![img_v3_02dq_0120aa37-a072-4187-96d8-b649daebdfbg.jpg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/22f627dd551a0e2d2c4d696a59811584_Lv1KM3JYvW.jpg?height=1470&lazyload=true&width=2766) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/1983b70b3ad4dd9f33f2651924dd03e7_PO3BRhNb02.png?height=498&lazyload=true&maxWidth=342&width=714) 发起流程后会收到消息提醒，发起一条审批人都是自己的流程验证以下功能： 1. 审批 Bot 消息能收到提醒 1. 点击消息卡片的详情能展示泛微流程单据 1. 快捷审批功能能够使用 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/bc4f402178e4f16bf8f6d7b48ddb08b1_0psMpnjpnf.png?height=1412&lazyload=true&maxWidth=542&width=2048) 审批列表页能查看到发起的审批流程。 4. 点击 [飞书审批应用中心](https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9cb844403dbb9108&width=1136&height=750&path=pc%2Fpages%2Frequested%2Findex) 就可以看到已发起的流程。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8075220554ab9d93e26e8443532b11fc_UqphkUtZEy.png?height=1412&lazyload=true&maxWidth=542&width=2048) **（可选）OA 发起页流程同步到飞书审批** 同步后，会将OA中的审批定义入口同步到飞书审批的审批管理后台、以及“发起审批”页面。 **注意**：请勿在飞书审批管理后台删除同步的审批定义，删除后再次同步也无法恢复。 ![img_v3_02dq_5715a5af-5110-4dbc-a596-ff580808e4eg.jpg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7f3effc6a14eab3a3032018bb0867c2a_nXTE1U6z4f.jpg?height=1426&lazyload=true&width=2748) “谁可以发起这个审批”无法同步，默认为“所有人不可见”，需要手动调整可见范围。配置地址：[审批 (feishu.cn)](https://www.feishu.cn/approval/admin/approvalList)。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a514fc0eb3c88ffd23df131cdeaad69f_ox2qUa6ZR4.png?height=1282&lazyload=true&maxWidth=542&width=2542) ## 步骤五：添加数据库索引 该功能从 0.2.2 版本2021年11月29日开始支持。说明见：[连接器需要的索引](https://bytedance.feishu.cn/docx/doxcnnJ9UDAFDS7pQKNgCPl1hnc#doxcnmOsoCuoEqKSKmehy1hGfDh)。 连接器是采取定时轮询 OA 数据库数据，将数据同步到飞书审批的。OA 数据库已有的索引在流程数据量大时不能满足连接器的使用。 对于接入的数据量不大的可以直接在连接器后台点击“创建索引”按钮（需要数据库读写权限），已有数据量比较大的建议手动执行变更语句。 ``` # 同步最近操作过的流程 create index CONNECTOR_OPERATEDATETIME on WORKFLOW_CURRENTOPERATOR (OPERATEDATE, OPERATETIME); # 同步最近操作过的流程 create index CONNECTOR_RECEIVEDATETIME on WORKFLOW_CURRENTOPERATOR (RECEIVEDATE, RECEIVETIME); # 同步强制回收的流程 create index CONNECTOR_INVALIDDATETIME on WORKFLOW_REQUESTOPERATELOG (INVALIDDATE, INVALIDTIME); # 同步最近删除的流程 create index CONNECTOR_OPERATEDATETIME on WORKFLOW_REQUESTDELETELOG (OPERATE_DATE, OPERATE_TIME); # 发送督办提醒 create index CONNECTOR_CREATEDATETIME on WORKFLOW_REQUESTBASE (CREATEDATE, CREATETIME); ``` ![img_v3_02dq_9b42d052-bb0d-4fc2-be66-563216c3b04g.jpg](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/52a28945451d9f553038f0451480cab4_BgnugRKxwk.jpg?height=1462&lazyload=true&width=2736) ## （可选）升级连接器 ### 更新记录 | 日期 | 版本号 | 更新内容 | 备注 | | ---- | ----- | -------------------------------------------------------- |----- | | 2024-08-01 | 2.1.01 | 1. 修复同步评论oracle问题
2. 增加数据库类型oracle多租户选项 || | 2024-05-08 | 2.0.36 | 1. 用户待办同步错误（需剔除供应商门户租户任务）
2. 因分组导致全局变量被清空，托管无法正常显示的问题 | | | 2024-03-27 | 2.0.35 | 1. 修复因增加前缀无法对账的问题 | | | 2024-03-27 | 2.0.34 | 1. 升级spring security版本5.6.12至5.7.12 | | | 2024-03-21 | 2.0.33 | 1. 升级snakeyaml版本1.29至2.0
2. 修复审批意见换行问题 | | | 2024-02-23 | 2.0.32 | 1. 升级spring security版本5.6.10至5.6.12 | | | 2024-01-16 | 2.0.31 | 1. 适配管理后台的权限调整功能（批量转移/批量复制）
2. 托管流程支持黑名单模式
3. 托管退回非托管，重新同步1个月内待办
4. 修复字段配置隐藏规则后联动属性失效的问题
5. 增加oracle2，用于支持使用server name连接oracle的场景 | | | 2023-12-07 | 2.0.30 | 1. 修复自定义审批 bot 展示字段不生效问题
2. 兼容意见征询回复等因为task和log表时间延迟不匹配，导致无法发出bot的问题 | | | 2023-11-09 | 2.0.29 | 1. 支持自定义审批 bot 展示字段
2. 兼容流程定义v1版本被删除，查不到流程问题 | 自定义审批 bot 展示字段，Connector 后台需要打开配置项
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/cb38beced606972da33f8da9eb4b6354_bYk0PrM7wo.png?height=817&lazyload=true&maxWidth=242&width=960) | | 2023-10-27 | 2.0.28 | 1. 支持同步流程黑白名单
2. 抄送任务不触发20s对账
3. 免登账号缓存时间配置化 | [免登账号缓存时间配置化说明](https://bytedance.feishu.cn/docx/PRe7dTfqyoJ3LAxkKSSceC9Tn2f) | | 2023-10-16 | 2.0.27 | 1. 优化托管表单适配控件
2. 审批节点文案支持国际化 | | | 2023-09-26 | 2.0.26 | 1. springboot版本更新到2.6.15（修复tomcat和Spring Framework的安全漏洞）
2. 兼容低版本h2数据库中user表无name和work_code字段的情况
3. 代理问题优化（支持被代理的在途单据回收） | | | 2023-09-07 | 2.0.25 | 1. 托管审批定义自动合并版本 | | | 2023-08-31 | 2.0.24 | 1. 代理问题优化（代理期过后，待办任务需移交）
2. 后台增加自动同步审批定义开关 | | | 2023-08-24 | 2.0.23 | 1. 托管适配泛微表单控件（文档/多文档/日期时间）
2. JS 节点支持配置托管模式
3. 转办问题优化 | | | 2023-08-17 | 2.0.22 | 1. 主次账号路径参数位置调整 | | | 2023-08-10 | 2.0.21 | 1. 增加主次账号路径参数和映射规则
2. 增加托管详情页本地用户不存在时，实时用户查询 3. TokenKeeper 循环时间提取到配置文件 | [主次账号映射规则说明](https://bytedance.feishu.cn/docx/XB0jdzkNgo93Kqx4zgucj8GvnSg) | | 2023-07-20 | 2.0.20 | 1. 增加https的支持 | [泛微connector开启https说明](https://bytedance.feishu.cn/docx/GYZbdsVUEoJ7gExwmbdcoQ2Tnhc) | | 2023-07-06 | 2.0.19 | 1. 流程退回归档节点后显示为拒绝，增加开关
2. 修复连接器版本获取失败case
3. 修复oa审批定义code获取失败case | | | 2023-06-30 | 2.0.18 | 1. 支持发送督办 bot 消息 | | | 2023-06-21 | 2.0.17 | 1. 新增发起节点bot发送开关
2. 托管金额组件展示问题优化
3. 托管关联审批展示优化 | | | 2023-05-19 | 2.0.16 | 1. 新增全天对账流程，每日推送对账结果
2. 修复组合字段展示问题
3. 飞书审批 Bot 推送消息关联泛微个人消息配置 | [全天对账功能依赖说明](https://bytedance.feishu.cn/docx/T6awdPZfNoksvlx6QFdcikcCnoe)
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b25132c0ec4a77fc6f68f33fead7b94b_xdAdI6fr2J.png?height=446&lazyload=true&maxWidth=242&width=1246)
需要保证连接器应用内对应的 **“云文档”** ， **“消息与群组” 下全部接口权限开通并重新发布应用。否则会影响该功能的正常使用**
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ddc3a245991ce7b0520b65d11758f708_9tL9wEsS5z.png?height=1124&lazyload=true&maxWidth=242&width=3260) | | 2023-04-20 | 2.0.15 | 1. 完善监控
2. 增加日志埋点 | | | 2023-03-31 | 2.0.14 | 1. bot列表标题适配优化
2. 评论双向回传问题修复 | | | 2023-03-24 | 2.0.13 | 1. 审批流程可视化-历史数据回刷&单据id
2. 显隐问题优化
2. 表单分组问题修复 | | | 2023-03-15 | 2.0.12 | 1. 审批流程可视化适配
2. 托管退回非托管在途单据回刷
2. 修复人员组件多用户展示问题 | | | 2023-02-28 | 2.0.11 | 1. 增加单据同步黑名单功能
2. 优化内存使用问题 | | | 2023-02-16 | 2.0.10 | 1. 托管双向评论同步
2. 表单js代码不托管
3. 强制收回适配优化 | [飞书审批-全文评论 vs. 泛微 OA-相关交流 双向回传功能说明文档](https://bytedance.larkoffice.com/docx/A0F0dyChYoWaYrxcN3vc1lCbnhf) | | 2023-01-13 | 2.0.8 | 1. 修复e7表单不兼容的问题 | | | 2023-01-12 | 2.0.7 | 1. 免登兼容+86手机号
2. 支持按表单必填项是否有值托管
3. 修复“审批信息”中英文显示错误 | | | 2023-01-05 | 2.0.6 | 1. 修改了免登失败的错误提示信息
2. 添加了一个清理后台审批定义的接口 | | | 2022-12-30 | 2.0.5 | 1. 修复托管关联审批字段展示失败
2. 修复托管表单行内排序错误
3. 修复部分托管表单值不展示
4. 新增托管表单分组功能 | | | 2022年12月21日 | 2.0.4 | 1. 抄送需提交转待办功能支持
2. 托管支持按节点是否编辑开启托管 | | | 2022年12月14日 | 2.0.3 | 1. 超时提醒发起人文案优化
2. 表单多选匹配不上导致托管无法打开兼容
3. 托管表单支持组合字段功能 | | | 2022年12月08日 | 2.0.2 | 1. Spring boot 升级到2.6.14 修复 spring security 安全漏洞
2. 支持日文适配 | | | 2022年11月30日 | 2.0.1 | 1. html模板明细表格支持 | | | 2022年11月23日 | 2.0.0 | 1. 「OA审批」同步失败阻塞启动
2. 表单预加载可配置化
3. 托管分支合并 | | | 2022年11月16日 | 0.4.9 | 1. 用户同步优化
2. 对账SQL优化 | | | 2022年11月09日 | 0.4.8 | 1. 线程池调度优化
2. 新增线程池状态接口
3. sql init脚本优化
4. Rpc IO超时优化 | | | 2022年10月08日 | 0.4.7 | 1. 修复启动失败问题
2. 优化日志打印 | | | 2022年09月27日 | 0.4.6 | 1. 增加兼岗开关
2. 修复一些消息不发送问题
3. 增加超时前消息发送
4. 退回后的任务在用户待办中显示 | | | 2022年08月15日 | 0.4.5 | 1. 修复语言切换失败 | | | 2022年07月29日 | 0.4.4 | 1. 扫库方式修改，加快同步速度
2. 提供修改定时任务扫描间隔配置
3. mybatis版本升级，修复潜在安全漏洞 | | | 2022年06月29日 | 0.4.3 | 1. 升级 springboot 修复相关安全漏洞 | | | 2022年05月24日 | 0.4.2 | 1. 修复转交消息发送失败
2. 增加发起人保存按钮是否提交 | | | 2022年04月26日 | 0.4.1 | 1. 支持“OA审批”定义可隐藏
2. 离职用户不发送通知报警消息 | | | 2022年04月12日 | 0.4.0 | 1. 支持批量转发
2. 支持名称审批定义名称自定义 | | | 2022年03月31日 | 0.3.9 | 1. 增加“用户管理”页面，该页面展示OA用户与飞书关联的情况，并可以进行同步更新 | | | 2022年03月15日 | 0.3.8 | 1. 同步审批定义到飞书不会出现多个版本同时出现了
2. 修复了部分数据 RequestNameNew 自定义标题为空的场景
3. 兼容OA消息必填数据错误的问题| | | 2022年03月08日 | 0.3.7 | 1. 略微提高连接器同步的性能(对账过滤掉没有飞书账号的任务)
2. 现在 | | | 2022年02月23日 | 0.3.6 | 1. 关闭了后台 h2-console 本地数据库访问页面
2. 现在第一次运行会随机生成后台账号密码
3. 关闭了 spring-boot-actuator 访问的 http 接口 | 账号密码在 `application-connector-service/conf/admin.setting` 文件中，删除文件后会重新生成 | | 2022年02月22日 | 0.3.5 | 1. 支持非标“撤销”功能
2. 删除的流程不在“已发起”中显示
3. 修复了OA数据写入慢时先进行了同步再对账，导致消息漏发的问题 | | | 2022年02月09日 | 0.3.4 | 1. 修复抄送id和流程id一致时同步失败的问题
2. 添加显示oa流程id的开关 | | | 2022年01月21日 | 0.3.3 | 1. 支持退回到“归档”节点出口 | | | 2022年01月19日 | 0.3.2 | 1. 修复了开启灰度时，删除流程操作人不在灰度范围内导致，流程删除后仍停留在飞书审批列表里的问题| | | 2022年01月17日 | 0.3.1 | 1. 修复了中文手机端打开了英文端OA的问题 | | | 2022年01月11日 | 0.3.0 | 1. 支持OA用户海外手机号
2. 飞书免登授权添加了重试提高网络等异常情况下的成功率
3. 去除了登录名重复提醒 | | | 2022年01月05日 | 0.2.9 | 1. 添加了日志查看功能
2. 用户免登失败时提示信息更加明确
3. 处理了小概率漏发消息的问题
4. 修复对账消息多发的问题 | | | 2021年12月20日 | 0.2.8 | 1. 任务数过多的流程会被过滤（>200)
2. 链接打开支持国际化
3. 修改了一些提示信息
4. 关闭了自动创建审批定义
5. 修复了对账时部分消息没有重新发送 | | | 2021年12月08日 | 0.2.5 | 1. 飞书用户查询不到报警提示添加了用户姓名信息
2. 修改了“启用配置”的提示信息，快捷审批失败的提示信息
3. 修复了 0.2.4 引入的，无法同步删除流程的 bug | | | 2021年12月03日 | 0.2.4 | 1. 修复了链接打开方式选用“侧边栏”时，PC发起页使用了移动端的问题
2. 修复了开启了灰度范围时，当前节点信息显示不正确的
3. 修复了采用工号关联飞书账号的时候，卡片消息通知上没有显示用户部门信息 | ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/27fd8eddf84fef32b3132c368b6c6cf3_njKh1aaSnf.png?height=520&lazyload=true&maxWidth=242&width=1280)
修复连接错误，“同步流程到飞书审批”按钮重新点击 | | 2021年12月01日 | 0.2.3 | 1. 修复填写了移动端地址的时候发起连接地址错误的问题
2. 对用户误删定义的场景了兼容 | | | 2021年11月29日 | 0.2.2 | 1. 添加了自动同步流程类型功能
2. 添加了创建索引功能 | | | 2021年11月18日 | 0.2.0 | 1. [OA超时消息提醒功能](https://bytedance.feishu.cn/docx/doxcnYQwFMZLqwWHzGutAFlh76d)
2. 支持请求 feishu.cn open.feishu.cn 时返回 301 的情况 | | | 2021年11月17日 | 0.1.9 | 1. 略微提高了快捷审批的成功率
2. 简化了 windows 部署脚本 | | | 2021年11月10日 | 0.1.8 | 1. 添加了自助验证功能 | | | 2021年11月03日 | 0.1.7 | 1. 移动端支持快捷审批功能
2. 审批消息链接支持跳转到审批应用中心
3. 审批消息“备注区”支持选择 | | |/ | / | 1. 审批卡片支持显示用户信息（老版本升级的用户飞书企业应用需要添加需新添加权限）![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6d14a75ac4a6afe379191a4a9154af05_4nSPNpg6VZ.png?height=424&lazyload=true&maxWidth=242&width=1274)
2. 消息卡片内容支持自定义
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3936680f353c03afe0d423a79cfaf3cc_wuXgVQ190e.png?height=542&lazyload=true&maxWidth=242&width=666) ｜ ### 升级操作步骤 **注意**：请尽量选在低峰期进行升级。 1. 获取升级 jar 包：本章步骤四：部署 Connector 处有下载链接 2. 进入连接器部署目录，找不到目录的 Linux 可以执行 `ps aux | grep approval` 命令查找进程 3. 备份老版本 jar 包。可备份在专门的文件夹里面，方便回滚和回档追溯，文件名建议包含备份日期 `approval-connector-service-20221109.jar`。 4. 替换新的 jar 包。将 `approval-connector-service/target` 下的 jar 文件进行替换。注意新包名称必须是 `approval-connector-service.jar`。 5. 停止程序。执行命令`./bin/stop.sh`（Windows右键以管理员身份执行 bin 下的 nssm-stop.cmd）停止程序。 **注意**：确保停止程序前，业务处于低峰期。 6. 停止命令执行后，执行命令`ps aux | grep approval` 确保进程已经真正停止。也可以执行查看日志命令， 判断日志是否停止刷新来确认： `tail -f logs/stdout.log` 7. 启动程序。确保程序已经停止后，执行命令`./bin/start``up``.sh`（Windows右键管理员身份执行 nssm-start.cmd）启动程序。 8. 执行命令 `tail -f logs/stdout.log` 查看日志观察是否存在错误。 9. 打开 飞书审批，确认单据可正常打开/操作/流转。 7. 检查是否升级成功： 1. 登陆连接器管理台，确认版本已升级： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/c015735addfda580ac26c44eb2d8f0be_dAF5T474Mc.png?height=482&lazyload=true&maxWidth=542&width=2430) 2. 检查运行日志，确认「创建审批定义」事件，状态为成功： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/f660887fd5d5f7d8fe9c4711bfb93249_ebegMkI4kt.png?height=900&lazyload=true&maxWidth=542&width=3418) ## 了解更多 ### 迁移服务器指南 请保证迁移前后，连接器服务映射到外网的地址一致，比如域名或者直接公网IP。否则历史单据会打不开。 #### 步骤一：迁移系统或文件 - 若使用云服务器，请直接使用镜像迁移功能，可以咨询对应的云服务供应商 - 若使用自建机房，将用户空间下的 ~/bytedance 目录和 approval-connector-serverice 迁移到新服务器即可，位置不需要改变 #### 步骤二 迁移后，重新启动连接器（可搜索并参考本文档 **启动 Connector** 一节），然后进入详情页面查看检测是否通过。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ad97ab504fc730ba47da273082e457b2_fweUcvJzFk.png?height=1124&lazyload=true&maxWidth=542&width=3574) 如果修改了连接器外网地址，还需要更改对应的外网地址配置： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6b8e3dd7cf90182e21848e00489d0330_N0C3IPDC1l.png?height=1292&lazyload=true&maxWidth=542&width=3578) #### 步骤三：验证连接器功能 在 OA 发起流程，然后点击连接器日志管理页面，查看是否正常。若运行都正常，将旧服务器停掉。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/431212efe8a3c4ecf617c481a18356fd_Lw625zXeSD.png?height=1040&lazyload=true&maxWidth=542&width=3566) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/252216dcfad184b71b54321f66274376_yz8fsp0XGD.png?height=446&lazyload=true&maxWidth=542&width=940) 成功的返回如图所示： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/44f728c7d0d5ebc829b9a4174500eb18_BSZCjUF0vl.png?height=1324&lazyload=true&maxWidth=542&width=2046) ### 多个OA部署集成到同一个飞书租户中操作步骤 1. 单独准备服务器分开部署连接器，部署步骤可参考之前的部署步骤。 2. 然后在 `/approval-connector-service/conf/application-custom.properties` 加入下列配置，再启动连接器。多个服务器的话，把下面配置中的 a，换成 b，c，d 就可以，已经部署的机器不需要修改。 ``` connector.idPrefix.instanceId=a connector.idPrefix.taskId=at connector.idPrefix.ccId=ac fanwei.approval-code=a-052D-49E9-B570-C29C836CDF8E ``` 注意： - 请不要使用同步审批类型到飞书中的功能，当前使用可能会存在问题。 - 请确保配置加入后再启动连接器。 ### 连接器对账机制说明 对账机制指将 OA 最近一段时间的流程数据通过接口调用方式去和飞书审批侧已经推送过了的数据进行比对（如比对时间戳等），如果返回了不一致，连接器就会对该条流程重新进行推送。 例如，最近 30 分钟流程 ID=91110 的流程在 11:00 发生变更过，连接器会请求飞书审批侧最新版本的数据是 11:00 的，否则，连接器重新推送该流程。 对账间隔是指在设定的时间间隔内，将当前时间与间隔时间之间发生的流程变更进行对账比对。对账的周期本身并不重要，因为如果网络未恢复，缩短对账间隔和增加频率的效果有限。最终能否成功对账，取决于异常情况何时恢复。只要网络未恢复，就无法完成同步，用户审批列表中的状态也无法更新正确。 对账过程中可能会失败，因为对账操作需要通过网络发起HTTP请求。当请求失败时，系统会立即进行三次重试。如果在对账时网络环境出现故障，对账将失败，并只能等待下次的对账操作。如果所有对账尝试均失败，系统将不再继续处理。 - 24小时（自然日）对账特别说明： - 对账范围：T-1 0点～23点59分59秒 - 对账时间：凌晨3点 - 对账结果发送时间：9点 ## 故障排查 ### 1. 收不到消息 #### 原因一：不在灰度范围内，请参考本文**修改灰度范围**一节修改。 灰度范围指在范围内的用户会收到审批的通知和提醒，关闭灰度范围意味着所有用户都可以使用审批。当前版本为了减少初次部署对客户的影响，默认开启灰度并设置所有用户不可用，部署的时候如果没有进行过配置，请按照文档操作。若添加了部门，注意部门下的所有子部门都要添加进去。 #### 原因二：灰度设置问题 开启了“过滤发起人”，会导致发起人不在灰度范围内的时候，后续节点的操作人也收不到审批消息，审批中心也不见，关闭即可。 #### 原因三：用户飞书和 OA 关联信息不一致无法查找到 可以访问 `http://${连接器地址}/api/t/user?id=${userId} ，（用OA的userId）`。例如：`http://10.128.114.221:1117/api/t/user?id=1112`。 该接口返回的信息中存在一种特殊情况，即在 "larkUser" 后的数据段中，虽然中括号内没有内容，但 "larkUserId" 后仍然有值。这种情况通常是由于用户在飞书平台的信息发生变动，导致飞书ID发生变化（例如，用户离职后再次入职）。然而，连接器中的“缓存”数据库仍然保留了先前的飞书ID，因此本次请求中使用的是旧的飞书ID。 遇到这种情况，可以手动调用 `/api/t/cleanUsers` 接口清空缓存，或者在连接器后台的“用户管理页面”中点击“用户全量同步”以更新缓存，问题应可得到解决。 #### 原因四：开启了“聚合推送审批消息” 当启用了“聚合推送审批消息”功能后，用户可能会暂时收不到待办等实时消息。这些审批实例仍然会显示在审批实例列表中，但相应的消息通知可能会延迟到次日才推送。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2c87b91deb6a95b3cdd6403d13375e7a_2TAxQSyx1m.jpeg?height=1452&lazyload=true&maxWidth=542&width=2156) #### 其他原因排查 进入连接器管理后台后，选择“时间区间”，事件选择“发送审批消息”，并在参数中输入对应的流程ID。如下图所示，可以查看是否有消息发送记录及其状态。如果发现消息已发送但发送失败，可以通过备注中的 `userId`（即OA的用户ID）确认消息发送的目标用户。 如果消息已成功发送但用户未收到通知，请联系飞书并提供此处响应中的相关数据以协助排查问题。 如果没有发送记录，请检查其他可能的原因，并提供对应时间的日志给飞书以便进一步调查。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/830eec58ccff2fbde7e01ff9fc97e1b7_0WCTlqEDcF.png?height=1276&lazyload=true&maxWidth=542&width=3816) ### 2. 页面无法打开 当遇到无法打开页面的情况时，首先需要判断是哪个地址无法打开，然后再进行问题排查。以下是具体操作步骤： 1. **Feishu**：检查飞书平台的链接。 2. **OA域名**：检查与OA相关的链接（客户通常能识别这些域名）。 3. **连接器**：检查与连接器相关的链接，尤其是 `/sso/feishuCallback` 路径。 对于手机端用户，建议先点击“更多”，然后点击“复制链接”来获取当前页面的地址，以便进一步分析和解决问题。 若提示登录超时且在浏览器地址栏中出现 `ssoToken`，说明OA服务器的免登设置可能存在配置问题。 请根据[泛微OA的文档](https://www.e-cology.com.cn/sp/ebdcus/ktree/help/freepass?pathKey=aW50ZWdyYXRpb24vdG9rZW4=&lang=7)，自行检查OA服务器的相关配置（如果是集群部署，则需逐一检查每台服务器）。确保所有配置项均正确无误，并根据需要进行调整或修改。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e9498a0791ac7d5285c24501f7ebf78f_QoPF1LcnUP.png?height=1404&lazyload=true&maxWidth=542&width=2690) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2b3c556268b70b684c0ef3bba253b738_5uN7mm2s0t.png?height=318&lazyload=true&maxWidth=542&width=750) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b07e876cc3020acb4b2b402c002c6458_ZGmyq7LhM3.png?height=352&lazyload=true&maxWidth=542&width=721) #### 链接超时（ERR_CONNECTION_TIMED_OUT） 如果确认请求地址无误但问题仍然存在，请联系公司内部的网络团队进行进一步排查。网络运维人员可以帮助检查是否存在网络配置或连接问题导致的访问故障。 #### 域名解析失败（ERR_NAME_NOT_RESOLVED） 如果确认请求地址无误，且问题依旧存在，请检查以下几个方面： 1. **DNS域名设置**：确保DNS配置正确，避免因域名解析错误导致的访问问题。 2. **VPN设置**：检查是否开启了VPN，可能会影响访问。 3. **网络拦截**：确认公司网络内部是否存在拦截或限制。 在这些方面进行检查后，如果问题仍未解决，请联系公司网络团队进行进一步的诊断和解决。 #### 链接拒绝（ERR_CONNECTION_REFUSED） 请检查以下几点： 1. **服务状态**：确认相关服务是否正常运行，有无挂掉的情况。 2. **域名绑定**：检查域名是否绑定了多台服务器，可能某一台服务器挂掉或无法访问。 如果发现服务或服务器存在问题，请进行修复或联系相关技术支持进行处理。 #### 提示“请求非法，请联系应用开发者” 如果遇到以下错误，请检查并更新“飞书企业应用-安全设置-重定向地址”中的设置： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d04a54058ac8ebf74a9e8d151dde12d2_raI8LoqZRq.png?height=802&lazyload=true&maxWidth=542&width=1978) **重定向 URL** 应填写为：`http://{替换为您部署飞书审批泛微Connector的外网地址}/sso/feishuCallback` 例如，如果飞书审批泛微Connector部署在内网服务器 `10.227.78.75:1117` 上，公网访问地址为 `112.10.12.41:1117`，则重定向 URL 应设置为：`http://112.10.12.41:1117/sso/feishuCallback`。请根据实际部署情况修改端口号和外网地址。 ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/19ff5bc6cbed43a149cb78a9e6ff8843_F65lb2JW9O.png?height=1156&lazyload=true&width=2782) #### 免登失败，链接地址中已经有 ssoToken 地址 无法免登进入 OA 页面。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/30bfb4664539de455c1809cbe9f36365_ZGteWyMUfl.png?height=704&lazyload=true&maxWidth=542&width=1280) 检查方式 1：免登功能检测 1. **执行命令** 复制以下命令到连接器部署的机器的命令行并回车执行： ```bash curl --location --request POST 'http://{替换泛微内网地址}/ssologin/getToken' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'appid={替换泛微统一认证中心的appid}' --data-urlencode 'loginid={替换无法获取token人员的手机号或者邮箱}' ``` 2. **处理命令执行结果** - **如果 SSO 服务正常**：会返回一串 `token`。将该 `token` 追加到访问 OA 的 URL 后面，并使用**无痕模式**打开，确保当前没有登录 OA。示例 URL 格式如下： ```text http://#{OA地址}/spa/workflow/xxxx?ssoToken=#{token} ``` 如果添加 `ssoToken` 后可以免登 OA，则免登功能正常；如果不能免登，则说明 OA 侧的免登功能存在问题，需要联系 OA 支持解决。 - **如果 SSO 服务异常**：会提示相应的错误信息。此时需要联系 OA 的技术支持确认问题原因。 检查方法2：泛微数据库字段丢失导致token免登失败的，然后页面打不开了 在泛微的 /usr/weaver/Resin4/log/stdout.log 下有错误日志，如下图所示的错误，遇到这个问题请联系泛微的老师处理（异常现象就说是“token免登方式失败，有错误日志”） 检查方法 2：泛微数据库字段丢失导致 token 免登失败 1. **检查日志文件** 在泛微的服务器上，检查 `/usr/weaver/Resin4/log/stdout.log` 文件中的错误日志。如果出现如下所示的错误，这可能是由于数据库字段丢失导致 token 免登失败，进而影响页面的访问。请联系泛微技术支持处理。异常现象可以描述为：“token 免登方式失败，日志中出现错误。” ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ed0097bd15efdf692a9e60f0c6e86ed7_dEW1cJvX2u.png?height=933&lazyload=true&maxWidth=542&width=1280) 检查方法 3：泛微 ssologin/getToken 功能没有启用 1. **检查 404 错误** 在浏览器中打开以下 URL（例如 `http://10.10.11.11/ssologin/getToken`），查看是否出现 404 错误提示。如果页面返回 404 错误，说明该路径无法访问。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/dff54b55a96e2dcb356c062f753167b5_PupNyMKTNE.png?height=586&lazyload=true&maxWidth=542&width=1902) 2. **处理步骤** 如果出现 404 错误，请进行以下操作： - **调整配置** 在 `ecology/WEB-INF/weaver_security_config.xml` 文件中，将 `is-login-check` 属性设置为 `false`。 - **替换配置文件** 下载文档中提供的 `web.xml` 文件，并将其替换 `ecology/WEB-INF/web.xml` 文件。 修改前后对比图如下，右边绿色部分是新增的内容： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/9b628ee510d53edd1c5ce7f112a753de_FspvdcVjUv.png?height=683&lazyload=true&maxWidth=542&width=1280) - **重启 OA 应用** 修改配置后，重启 OA 应用以使更改生效。 #### 提示 500 错误（oauth2GetUserInfo 接口获取用户信息失败） 在泛微与企业微信集成的场景下，可能会出现一个 bug。具体解决方法如下： 1. **判断 User-Agent** 在请求到 OA 的时候，检查请求头中的 `User-Agent` 是否包含 "Lark"。如果包含，将 `User-Agent` 替换为标准浏览器的 `User-Agent`。例如： ```text Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36 ``` 2. **示例配置（以 Nginx 为例）** 如果使用 Nginx 作为反向代理，可以在 `nginx.conf` 中的 `location` 规则中添加请求头处理： ```nginx location / { set $ua "$http_user_agent"; # 如果 ua 包含飞书 lark，替换请求头中的 ua if ($ua ~* lark) { set $ua "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.109 Safari/537.36"; } # 修改 ua 请求头 proxy_set_header User-Agent $ua; proxy_pass http://localhost:7777; } ``` 3. **其他注意事项** - 如果使用其他网关或 SLB（Server Load Balancer）进行域名请求转换或请求传递，需根据实际情况进行相应的请求头处理。 - 对于云桥样式的问题，请客户自行检查或联系 OA 支持。 #### 手机 4G 网络下无法打开流程详情 **问题描述**：当泛微OA仅在内网环境下使用时，用户可能在手机端飞书收到审批 Bot 消息，但在4G手机网络环境下无法查看 OA 流程详情，仅在公司WiFi环境下能够访问。 **解决方法**：为了让用户在4G手机网络下也能访问泛微OA的流程详情，需要将泛微OA在外网暴露出来，并做好相应的安全防护。 **注意事项**： - 连接器本身仅是一个 HTTP 后端应用，不具备处理或优化外网访问能力，因此无法解决此类网络访问问题。 - 确保外网暴露后的安全防护措施到位，以防止潜在的安全风险。 #### 免登失败（获取 Token 失败：has no account） 1. **检查用户记录** - 确认OA系统中是否存在与该手机号关联的多条记录。可能出现离职用户仍在系统中的情况。 - **解决方案**：删除或合并离职用户记录，以确保手机号唯一并与现有用户匹配。 2. **检查手机号区号** - 确认手机号是否包含区号（如 +86）。缺失区号可能导致匹配问题。 - **解决方案**：如果手机号带有区号，建议升级到最新版连接器，该版本已兼容处理区号问题。 - #### 页面提示 jem.js 加载失败 泛微OA主页与泛微云桥http，https 协议不一致，换成同样的协议即可。 已经提示协议不一致：在手机端提示协议不一致的原因可能是由于使用了 HTTP 地址登录，而请求的 Ecology 地址使用了 HTTPS，从而导致协议不一致。建议直接更换为 HTTPS 地址进行登录。 如果必须使用 HTTP 地址，则需要在 Ecology 集成中进行映射配置，将 HTTP 的 EM 地址映射到 HTTP 的 EC 地址。 请检查 EM7 后台基础设置，确保 EM 外网地址和 EC 外网地址（移动端）在协议上保持一致，否则可能会导致 jem.js 加载失败的问题。 #### 先显示登录失败，再显示请求非法 请检查复制出来的链接中的 `app_id`，确认该 `app_id` 是否为连接器创建的飞书企业应用。如果不是，请按照以下步骤进行操作： 1. 将应用的可用范围修改为“所有人”。 2. 按照泛微提供的集成文档配置企业应用的重定向地址。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d1b7b93d390c61ba2ee75001c55acc7c_5i3hsIAfP0.png?height=842&lazyload=true&maxWidth=542&width=3094) 3. 将该飞书企业应用删除 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/96bc03d51e0e287d71a8ee22a1b62cac_KXjeSc9mDu.png?height=318&lazyload=true&maxWidth=542&width=3398) #### 页面提示“你没有权限使用该应用” 查看连接器应用的可用范围。 #### 免登功能时好时坏 **现象**：点击流程时会跳转到登录页面，第二次点击则正常，过一段时间后再次点击又会跳转到登录页面。 ![现象示例](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/d7841644b9b337852998af1d684efe83_M3fcW3cuQU.png?height=609&lazyload=true&maxWidth=542&width=1147) 对于此类问题，首先需要确认用户是否启用了 CAS 认证。如果启用了 CAS 认证，则需要根据 UA 进行排查。 ![CAS 认证配置](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0c8552c7c0955946f379f4d46cfc1701_eds7jGIpYh.jpeg?height=293&lazyload=true&maxWidth=542&width=1146) #### 点击“浏览器打开”，外跳浏览器后无法免登 在浏览器中打开链接时，无法实现免登录功能，因为免登录是一次性的，仅在飞书客户端内有效。跳转到浏览器后，访问链接时不会携带免登录所需的 Token 信息，因此无法实现免登录。对此问题目前没有解决办法。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/fcc473df90763b9ecaa91e99b051582f_Ct9q5gnmrx.png?height=570&lazyload=true&maxWidth=542&width=1920) ### 3. 流程同步记录不对，状态排查 连接器版本 0.4.6 和 0.4.7 存在 Bug，请升级到最新版本的连接器。在升级后，可能会遇到遗留的状态不一致问题，请关注单据在提单时是否发生在升级之前。 1. 确认同步时间是否匹配，确保信息没有错误。如有疑问，请进一步核实。 2. 请首先检查运行日志，确认是否有同步记录以及同步是否成功。 3. 对于同步记录失败的情况，请获取具体的错误原因，例如 TimeoutException、UnknownHostException 或 socketTimeout。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/8a6f9ae31a37fea4c007b954fc9a0cdf_Pf2ijYGhmy.jpeg?height=624&lazyload=true&maxWidth=542&width=1173) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/c35716b53e6e11da806fefdad62fcc12_PRhvhQB6yF.png?height=1308&lazyload=true&maxWidth=542&width=3580) 4. 请复制最新一次同步记录的参数。 获取用户的飞书 `userId`，可以在“用户管理”页面中找到。然后，检查该用户在 `taskList` 下的任务状态是否正确。 例如：`"user_id": "62559b3f"` 表示该任务属于用户 “62559b3f”，其状态为 `pending`。 ```json { "approvalInstanceDTO": { "approval_code": "3B7F5EAB-B9FB-44C9-BDF0-EF4358CD84D3", "user_name": "@i18n@username", "end_time": 0, "title": "@i18n@title", "start_time": 1672105509000, "update_time": 1672105509000, "instance_id": "29121", "trusteeship_user_id_type": "user_id", "form": [ { "name": "@i18n@form_7", "value": "@i18n@form_8" }, { "name": "@i18n@form_4", "value": "@i18n@form_2" }, { "name": "@i18n@form_5", "value": "@i18n@form_6" } ], "update_mode": "REPLACED", "display_method": "TRUSTEESHIP", "trusteeship_url_token": "F19DDDAD1002F9B3339D1D5598BEA5E8", "links": { "pc_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4form%2Findex.html%23%2Fmain%2Fworkflow%2Freq%3Frequestid%3D29121", "mobile_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4mobileform%2Findex.html%23%2Freq%3Frequestid%3D29121" }, "cc_list": [], "task_list": [ { "action_context": "65@29121@13054", "create_time": 1672105509000, "end_time": 0, "action_configs": [ { "action_type": "APPROVE", "next_status": "APPROVED", "is_need_attachment": false, "is_need_reason": false, "is_reason_required": false }, { "action_type": "REJECT", "next_status": "REJECTED", "is_need_attachment": false, "is_need_reason": true, "is_reason_required": false } ], "task_id": "t13054", "update_time": 1672105509000, "user_id": "62559b3f", "display_method": "TRUSTEESHIP", "links": { "pc_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4form%2Findex.html%23%2Fmain%2Fworkflow%2Freq%3Frequestid%3D29121", "mobile_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4mobileform%2Findex.html%23%2Freq%3Frequestid%3D29121" }, "status": "PENDING" }, { "action_context": "66@29121@13055", "create_time": 1672105509000, "end_time": 0, "action_configs": [ { "action_type": "APPROVE", "next_status": "APPROVED", "is_need_attachment": false, "is_need_reason": false, "is_reason_required": false }, { "action_type": "REJECT", "next_status": "REJECTED", "is_need_attachment": false, "is_need_reason": true, "is_reason_required": false } ], "task_id": "t13055", "update_time": 1672105509000, "user_id": "527284g2", "display_method": "TRUSTEESHIP", "links": { "pc_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4form%2Findex.html%23%2Fmain%2Fworkflow%2Freq%3Frequestid%3D29121", "mobile_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4mobileform%2Findex.html%23%2Freq%3Frequestid%3D29121" }, "status": "PENDING" }, { "create_time": 1672105509000, "end_time": 0, "action_configs": [], "task_id": "t13057", "update_time": 1672105509000, "user_id": "a9ed3bd4", "display_method": "TRUSTEESHIP", "links": { "pc_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4form%2Findex.html%23%2Fmain%2Fworkflow%2Freq%3Frequestid%3D29121", "mobile_link": "http://10.248.136.16:1117/sso/login?redirectUrl=http%3A%2F%2F10.248.136.16%3A8080%2Fspa%2Fworkflow%2Fstatic4mobileform%2Findex.html%23%2Freq%3Frequestid%3D29121" }, "status": "PENDING" } ], "i18n_resources": [ { "locale": "zh-CN", "is_default": true, "texts": { "@i18n@title": "谢阳阳测试流程(29121)", "@i18n@form_6": "处理2", "@i18n@form_5": "当前节点", "@i18n@form_8": "谢阳阳测试流程-系统管理员-2022-12-27", "@i18n@form_7": "流程标题", "@i18n@username": "系统管理员", "@i18n@form_2": "2022-12-27 09:45:09", "@i18n@form_4": "提单时间" } }, { "locale": "en-US", "is_default": false, "texts": { "@i18n@title": "谢阳阳测试流程(29121)", "@i18n@form_6": "处理2", "@i18n@form_5": "Current Step", "@i18n@form_8": "谢阳阳测试流程-系统管理员-2022-12-27", "@i18n@form_7": "Workflow Title", "@i18n@username": "Sysadmin", "@i18n@form_2": "2022-12-27 09:45:09", "@i18n@form_4": "Start time" } }, { "locale": "ja-JP", "is_default": false, "texts": { "@i18n@title": "谢阳阳测试流程(29121)", "@i18n@form_6": "处理2", "@i18n@form_5": "Current Step", "@i18n@form_8": "谢阳阳测试流程-系统管理员-2022-12-27", "@i18n@form_7": "Workflow Title", "@i18n@username": "Sysadmin", "@i18n@form_2": "2022-12-27 09:45:09", "@i18n@form_4": "Start time" } } ], "status": "PENDING", "trusteeship_urls": { "action_callback_url": "http://10.248.136.16:1117/trusteeship/operate", "form_detail_url": "http://10.248.136.16:1117/trusteeship/detail", "approval_node_url": "http://10.248.136.16:1117/trusteeship/node", "action_definition_url": "http://10.248.136.16:1117/trusteeship/button" } } } ``` 5. 若task 中没有该用户，查看用户 oa 与飞书关联关系。 ### 4. 用户关联不上的相关问题 请首先检查 OA 系统与飞书中的用户关联信息是否一致，例如手机号。确保手机号完全相同，包括是否带有国际区号（如 +46）。 确认一致后，请提供相关截图。 1. 确认该用户是否在连接器飞书应用的可用范围内。 2. 在用户管理页面重新同步该用户，并检查同步后页面上是否能找到相关用户。 ![用户管理页面示例](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3de2f0a346a77829aeb7396643b6d633_ffQRLO3mcr.png?height=1368&lazyload=true&maxWidth=542&width=3536) 3. 如果同步仍未成功，请访问 `连接器地址/api/t/user?id=[OA用户id]` 以确认关联信息是否匹配。 ### 5. 快捷审批功能失败 1. 如果所有快捷审批操作都失败了，请检查以下几个方面： - 确认连接器的外网是否已开通。 - 确保域名证书没有问题。 使用以下命令检查请求的响应： ```bash curl --location --request POST 'http://{}/callback/approval/operate' ``` 可能返回如下错误信息： ```json { "timestamp": "2023-01-31T07:59:28.123+00:00", "status": 400, "error": "Bad Request", "path": "/callback/approval/operate" } ``` 如果泛微（Weaver）接口返回异常，请稍后重试或直接在 OA 系统中操作，错误详情如下： ![日志示例](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/930ff8d9d295563454b4f445cb75cdf5_DuSQR8e3Tv.jpeg?height=836&lazyload=true&maxWidth=542&width=1364) ## 常见问题 ### 1. 安全性问题 1. **暴露外网端口是否存在安全隐患** 存在一定的安全隐患，但这些隐患是可控的。连接器仅暴露几个简单的 HTTP 接口，并且可以选择将连接器单独部署，以减少潜在的影响范围。 在将连接器开放到外网时，请避免将所有接口地址暴露到外网。特别是管理后台若暴露在公网后，后台的账号和密码可能会面临泄露的风险。建议仅开放必要的接口地址。例如： - **用户获取免登录 Token**: - `/sso/login` - `/sso/feishuCallback` - **飞书审批回调**: - `/callback/approval/operate` 如果不需要快捷审批功能，可以选择不开放外网访问。 2. **提供数据库信息时，Connector 会修改泛微的数据吗？** Connector 在首次启动时，会插入一条注册泛微 API 接口的数据。之后，Connector 仅使用“只读”数据库账号。 如果提供了读写账号，Connector 会自动插入所需数据。对于只读账号，需要手动在泛微的数据库中执行以下 SQL 语句： ```sql INSERT INTO ecology.ecology_biz_ec (ID, APPID, NAME) VALUES ('20210602', UUID(), 'connector'); ``` ### 2. 表单没有快捷审批功能（没有“同意”，“拒绝”） 如果当前流程节点的表单存在必填项，则快捷审批功能将无法使用。请在泛微流程中检查表单是否包含必填项，操作方法如下： 另外，也可以通过直接在数据库中查询节点的 ID，查看哪些字段为必填项。执行以下 SQL 语句： ```sql SELECT * FROM workflow_nodeform WHERE nodeid = ? AND ismandatory = '1'; ``` ### 3. PC 端审批中心不支持快捷审批 审批中心处，目前只有移动端支持快捷审批。 ### 4. 退回能否指定退回到某个节点？ 可以，流程节点配置“出口”即可。 ### 5. 能否去除掉“来自OA” 可以的，可以在连接器后台进行设置 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a4a2ba240495d875a688ee073e39f779_Dggjzqs3mF.png?height=502&lazyload=true&maxWidth=542&width=1280) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/f4b900c152d993b4e696e5c272c66b65_5rLsoO83BD.png?height=826&lazyload=true&maxWidth=542&width=1280) ### 6. 审批消息卡片内容如何自定义 可参考[Connector 同步飞书审批 Bot 通知配置说明](https://bytedance.feishu.cn/docs/doccnjVGnC34jLfAoJratGJuGDb)。 1. 每个字段拆不同行展示 1. connect管理后台配置： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/dbe93ca7fdf3f121cc0c7743eebff7d8_T8PXirbEj3.jpeg?height=1206&lazyload=true&maxWidth=542&width=1674) 2. OA侧标题配置 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/95caf91cc38011ee53ef81d0a3f0adc4_w5FLb6Y1Ra.jpeg?height=1104&lazyload=true&maxWidth=542&width=2740) ### 7. 同一条流程出现了两条记录在了飞书审批中心的“已办”里 当前版本对同一个审批节点的同一操作人多条任务进行了过滤，不同审批节点的同一操作人，审批中心“已办”还是会有多条记录。 ### 8. 发起流程入口只有点击到“审批”中才有 建议：在工作台增加一个新建审批入口，且与“审批”中的“发起申请”界面显示内容一致，减少路径； ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a391d3f570b4092a7e8498f36c8695d1_nXZtycPnxM.png?height=978&lazyload=true&maxWidth=542&width=970) 请将下列文本表达得更加正式： --- **操作步骤如下：** 1. 打开自建的飞书企业应用，并启用网页功能。 在网页配置处填写以下内容（直接拷贝即可，无需其他修改）： - **桌面端主页**: ```plaintext https://applink.feishu.cn/client/mini_program/open?mode=appCenter&appId=cli_9cb844403dbb9108&width=1136&height=750&path=pc%2Fpages%2Fcreate%2Findex ``` - **移动端主页**: ```plaintext https://applink.feishu.cn/client/mini_program/open?appId=cli_9cb844403dbb9108&path=pages%2Fcreate-list%2Findex ``` 然后点击“保存”。 ![保存配置](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/17f659f504f0dec8a5295546cf1f943c_MM9lh87jwA.png?height=1290&lazyload=true&maxWidth=542&width=2206) 添加后，可以在飞书管理后台按需调整应用的顺序。 ![调整顺序](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/700ad47b7486a3c69d45368fe9509128_H7lPNyzbnM.png?height=1178&lazyload=true&maxWidth=542&width=2658) 2. 发布修改后的企业应用。 选择“移动端默认的应用功能”和“PC客户端默认的应用功能”为“网页”，然后发布应用即可。 ![发布应用](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e8d2dd27c9c5530bf70f2f965e1fad67_eS9wqo8Ogm.png?height=1854&lazyload=true&maxWidth=542&width=3212) 3. 发布后，点击工作台中的自建应用，即可跳转到审批发起中心。 ### 9. 快捷审批如何关闭（删除卡片上的“同意”，“拒绝”） 在连接器后台快捷审批设置中进行操作，可以指定流程不开启。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/467b5df36e3d6991b250eda361187979_7b7UKVIaFb.png?height=1044&lazyload=true&maxWidth=542&width=1664) ### 10. 增加批量审批功能和快捷按钮（同意、拒绝、撤销） ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a746682c8dc3b356364155a738b79247_TWWrpTSFwd.png?height=1622&lazyload=true&maxWidth=542&width=3000) 目前仅支持批量同意。需将三方审批定义开启批量处理，且需要开启流程的快捷审批。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3924bc544617699021c3d10fdff51828_c9ISTuzJby.png?height=716&lazyload=true&maxWidth=542&width=2892) ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/f08c75392c1bfd2fc423d117f7b2249d_IdcdPSFwow.png?height=573&lazyload=true&maxWidth=542&width=957) ### 11. OA 的流程中任务的状态关系和飞书审批中是怎么关联的 | **飞书任务状态** | 待办 | 抄送 | 已办 | 已发起 | | --------------- | -------------------------------- | ------ | ------------------- | --- | | **OA** **任务状态** | 待办转办意见征询流程退回后（退回节点操作人会有一条待办）流程保存 | 传阅抄送转发 | 回复了意见征询处理了待办处理了转办归档 | 已发起 | ### 12. 流程发起人没有飞书账号影响使用吗 Connector可以使用，但是在消息卡片将不展示发起人信息；在审批中心发起人无法点击打开飞书名片。 ### 13. 快捷审批拒绝怎么退回给了申请人 节点有设置出口的话，会先退回到“出口”，没有的话才会退回到“发起人”。 ### 14. 保存流程时飞书审批中怎么添加一条待办 与OA一致，OA保存流程的时候也是会添加一条待办的，该流程后续继续“提交”或者“删除”都能够继续。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/08c87a33f3eceb36df73d5c3c01e0c56_2Ntma7i14Q.png?height=1560&lazyload=true&maxWidth=542&width=2834) ### 15. Bot 提示流程任务数过多 飞书审批 API 有最大 200 的任务数限制，流程任务数超过的话，会在飞书审批里做删除操作（查询不到该流程），不影响oa里的操作。 ### 16. 快捷审批失败 **日志及响应处理：** - 对于以下错误，请联系 Oncall 处理： - **回调 token 错误** - **操作类型错误** - **连接器错误 xxx** - 对于以下日志和响应，请按照以下步骤排查和处理： 1. **“任务已经被 xxx”** 可能是任务的已办状态未及时更新。找到 `requestId`，然后调用 `/api/t/sync?requestId=xxx`，待办任务应会消失。 2. **“回调失败, 退回节点未查询到 xxx”** 和 **“OA 流程异常, 申请人节点未查询到 xxx”** 泛微的拒绝操作接口需要指定退回节点，目前仅支持退回到发起人节点；如果在拒绝时找不到退回节点，则无法调用泛微接口。用户可以通过以下 SQL 语句在泛微数据库中查找相关信息： ```sql SELECT nodeid FROM workflow_currentoperator WHERE requestid = ? AND showorder = -1; ``` 3. **“回调失败: xxx”** 和 **“泛微（Weaver）接口返回异常，请稍后重试或进入 OA 操作，错误详情为: xxx”** - 含有“调用 ECOLOGY 系统接口进行注册失败” 的错误：可能由于网络波动或泛微 `/api/ec/dev/auth/regist` 接口故障导致。 - 含有“获取 Token 失败”、“Token 为空” 的错误：可能由于网络波动或泛微 `/api/ec/dev/auth/applytoken` 接口故障导致。 - 注意：某些版本的泛微系统可能会出现注册后 secret 失效的问题，此时调用 `applytoken` 接口前需要先进行注册。 - 其他错误可能由网络波动或泛微 `/api/workflow/paService/submitRequest` 或 `/api/workflow/paService/rejectRequest` 接口故障引起。 - 如果突然出现泛微接口故障： 1. 询问泛微是否最近进行了升级，并请泛微同事协助排查。 2. 检查是否在连接器和泛微之间的环境中对泛微的接口路径进行了拦截，或是否在中间逻辑中出现错误。 4. **获取 Token 失败（stdout 日志有报错：“secret 解密失败”）** ### 17. 测试流程被同步到了飞书审批 找到对应的流程单据 ID，将以下 SQL 语句中的流程 ID 替换为实际的流程 ID，查询 OA 数据库。如果查询结果有数据，说明该流程不是测试流程，请联系 OA 支持团队咨询原因。 ``` select * from workflow_requestbase t1 join workflow_base t2 on t1.workflowid = t2.id join workflow_requestlog t3 on t1.requestid = t3.requestid where (t2.isvalid='1' or t2.isvalid='3') and t1.requestid = '流程ID'; ``` ### 18. startlog日志文件过大 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a3620f390b16089b2fc69fc9bfce3d76_on2ZZcLD4B.jpeg?height=339&lazyload=true&maxWidth=542&width=1161) 遇到这种情况的原因是连接器在升级过程中，相关脚本没有进行同步更新。解决这个问题可以通过以下步骤： 1. **检查连接器部署目录：** 找到 `bin` 目录下的 `start.sh` 脚本。 2. **更新 `start.sh` 脚本：** 在 `connector startup success` 之后，添加以下命令： ```bash rm -rf "${BASE_DIR}/logs/start.log" ``` 如果不想手动修改脚本，可以下载最新版本的脚本并进行替换。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ccf6e9ac8161a96b4e075c91edd073f1_YIRWvmjaPN.png?height=378&lazyload=true&maxWidth=542&width=1606) ### 19. 单据同步延迟 请检查下配置OA库是否是从库，如果是请改成主库。 ### 20. 审批定义类型同步失败 在连接器管理后台点击同步流程类型到飞书审批后，审批管理后台未展示同步的审批定义，并且连接器管理后台日志中出现创建审批定义失败的情况，可以尝试以下解决方法： 1. **修改审批定义名称：** 在审批管理后台，找到同步失败的审批定义，将其名称进行修改。此操作有助于重新激活同步过程。 2. **重新同步：** 在连接器管理后台，点击同步按钮，再次尝试同步流程类型。 3. **验证结果：** 返回审批管理后台，检查修改后的审批定义是否成功展示。 ### 21. 审批列表中心批量审批按钮不存在 1. 参考 **FAQ 2. 表单快捷方式的没有快捷审批功能** 检查表单是否有必填项。有必填项的情况下不会有快捷审批功能。 1. 没有必填项，再查看下审批定义是否开启了快捷审批，开启下即可。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/fa9416e7c1babf9a636adddf21ad82f0_Ml7uaveLYL.png?height=874&lazyload=true&maxWidth=542&width=2320) ### 22. 提示 socketTimeout、或者 UnknownHost, TimeoutException ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/cf0ef48cade502ad4391dea32e6590a5_eyUfgcoykP.png?height=1610&lazyload=true&maxWidth=542&width=3128) 到服务器上执行下命令，查看下能否成功。若失败，请检查是否有网络防火墙等限制。 ``` curl "https://www.feishu.cn" -v curl "https://open.feishu.cn" -v ping www.feishu.cn ping open.feishu.cn ``` ### 23. 将飞书审批中的一个流程删除，不停留在飞书审批中 使用 `/api/t/delete?requestId={requestId}&approvalCode={approvalCode}`。approvalCode 可以在审批管理后台获取到。 ### 24. Oracle DB 连接报错 TNS:listener does not currently know of SID given in connect descriptor ``` // 执行以下sql，获取db名称 select INSTANCE_NAME from v$instance; ``` ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/5325d07649bda059801ed5a62b02c58a_QYvEbYyYRm.png?height=182&lazyload=true&maxWidth=542&width=538) ### 25. 支持 https 如果需要使用https访问服务，可以参考如下文档：[ 泛微connector开启https说明](https://bytedance.feishu.cn/docx/GYZbdsVUEoJ7gExwmbdcoQ2Tnhc) ### 26. 修改默认审批定义【OA审批】的发起页地址 在配置文件 application-custom.properties 中加如下行，然后重启： ``` fanwei.oa-mobile-create-link={新的发起页地址} ``` ### 27. 拼接 OA 其他页面地址并免登 - PC端使用以下格式的地址： ``` https://applink.feishu.cn/client/web_url/open?mode=window&url=Connector地址/sso/login?redirectUrl=OA主页地址 ``` 请确保 `url=` 后的内容经过 URL 编码（encode）。 - 移动端使用以下格式的地址： ``` Connector地址/sso/login?redirectUrl=OA主页地址 ``` 请确保 `redirectUrl=` 后的内容经过 URL 编码（encode）。 详细操作手册：[如何通过泛微Connector配置工作台应用免登](https://bytedance.larkoffice.com/wiki/SwUJw7B5Iio0NWk8PB0cD6L9nuW) ### 28. 泛微单据详情预览附件异常跳登录 E9 跨域问题，参考该[文档](https://e-cloudstore.com/doc.html?appId=2b01acef55c34a428f041f9789b8599a#E9%20%E8%B7%A8%E5%9F%9F%E9%97%AE%E9%A2%98)。 泛微ecode常见问题，参考该[文档](https://e-cloudstore.com/doc.html?appId=25fb364617c44ca3aa007581db3e4269#ecode%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98%E5%8F%8A%E8%A7%A3%E5%86%B3%E6%96%B9%E6%B3%95)。 ### 29. 连接器使用到的泛微oa接口列表 ``` http: /api/workflow/reqform/loadForm /api/workflow/reqform/remarkOperate /api/workflow/paService/submitRequest /api/workflow/paService/rejectRequest /api/workflow/paService/getDoingWorkflowRequestCount /api/workflow/paService/forwardRequest /api/workflow/communication/getContentList /api/workflow/communication/doSaveContent /api/workflow/communication/doDelete /api/workflow/communication/doEditContent /api/workflow/communication/doSaveReply /api/doc/upload/uploadFile /api/cowork/base/uploadOperate?secId=1 /api/public/browser/destData/formField?isFromWfcustitle=1&systemFieldType=wfcustitle /ssologin/checkToken webservice: urn:weaver.workflow.webservices.WorkflowService.submitWorkflowRequest urn:weaver.workflow.webservices.WorkflowService.getWorkflowRequestLogs urn:weaver.workflow.webservices.WorkflowService.getWorkflowRequest urn:weaver.workflow.webservices.WorkflowService.forwardWorkflowRequest ``` ### 30. 运行监测-检查项报错“快捷审批接口-Error request, response status: 500” ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/87f6b033d340ff7501424a9b023c5d3f_k9QatOWXDf.png?height=1302&lazyload=true&maxWidth=542&width=2592) 解决方案如下：请在飞书上进行测试，验证在执行“bot机器人卡片的同意”或“拒绝”操作后，单据状态是否能够正常同步到OA系统。如果同步正常，则可以忽略此问题（请注意，E9的某些小版本可能会出现校验错误，但实际功能可用）。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/f3992b92f95b2223a63ffdc7353854c0_PokVQQMi6T.png?height=1350&lazyload=true&maxWidth=542&width=2400) ### 31. Oracle 数据库查询失败 **报错信息**：`table or view does not exist` **问题原因**：在Oracle数据库中，子账号查询数据时，需要表头才能完成查询。因此，需要设置数据库的同义词。 **解决办法**：请设置数据库的同义词。具体操作如下： ```sql CREATE PUBLIC SYNONYM {tablename} FOR ecology.{tablename}; ``` 例如： ```sql CREATE PUBLIC SYNONYM hrmresource FOR ecology.hrmresource; ``` ### 32. 同步间隔、同步周期是多久 **轮询读取数据库的同步间隔默认设置为7秒**。根据需要，可以调整此间隔，但调整后必须重启Connector。 请注意，缩短轮询间隔会增加数据库扫描的频率，从而对数据库性能及Connector所在服务器的存储空间提出更高的要求。建议根据实际需求谨慎调整。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e800bfd56651e70e5f27ec5e7e49e545_rUz3sCoF61.jpeg?height=1306&lazyload=true&maxWidth=542&width=1582) ### 33. OA没有待办，飞书审批中心有，如何快速清理 1. **OA中有这条单据，但与飞书审批中心状态不一致** 1. 在浏览器中登录Connector管理后台。 2. 访问以下URL以同步单据状态： ``` http://替换连接器地址/api/t/sync?requestId=替换requestid ``` 例如： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3a8d5a890dcb350fb3e01e8342ea1f91_YVLbJofLml.png?height=440&lazyload=true&maxWidth=542&width=1289) 3. 如果返回`success`，则同步成功。 2. **OA中已经删除了这条单据** 1. 在浏览器中登录Connector管理后台。 2. 访问以下URL以删除单据： ``` http://替换连接器地址/api/t/delete?requestId=替换requestid&approvalCode=替换definition_code ``` 例如： ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/f08a22b6fba0e902f9e8fde45e66ce2e_kstl2vQdbi.png?height=246&lazyload=true&maxWidth=542&width=1116) 3. 如果返回`success`，则删除成功。 ### 34. 启用配置帮助：如何获取数据库配置？ 请按照以下步骤查找数据库配置： 1. 登录到 OA 部署的服务器。 2. 找到 `ecology` 目录。你可通过执行命令 `ps aux | grep weaver` 来查找 `weaver` 的目录，从而定位到 `ecology` 目录。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/aeaa8c07a5b4ddd9cda9cc901fe84732_YpMpsA3jaQ.png?height=612&lazyload=true&maxWidth=542&width=1624) 3. 打开 `ecology` 目录下的 `WEB-INF/prop/weaver.properties` 文件。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/4bf9066635a15301b30f8ed32fe381d5_mmnaqM36nU.png?height=740&lazyload=true&maxWidth=542&width=1628) 在 `weaver.properties` 文件中，你将能够找到数据库相关的信息。 ### 35. 启用配置帮助：如何获取 OA 地址？ 泛微的地址可以在移动管理平台中获取。请从平台中复制该地址，并直接使用。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ec8bd1da7b62cf9d271e66abe9d646ae_J0dmxfvFK7.png?height=1518&lazyload=true&maxWidth=542&width=2564) 登录后点击「系统检测」查看相关信息。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/14a9e4855428d78ced2b4d5a755f807f_qfZbOT61Bq.png?height=1876&lazyload=true&maxWidth=542&width=2366) ### 36. 如何修改 Bot 详情页打开方式 在附件查看外部浏览器跳转会导致免登录失败，请将跳转设置修改为直接跳转到审批中心。参考[泛微 OA Connector 页面打开方式配置](https://bytedance.feishu.cn/docx/doxcn0la0HybcA7txF89UQsAntg)。