YonBIPV3.0(R6_2407_1)旗舰版云平台-三方集成资产-BIP和企微集成资产实施指南用友网络科技股份有限公司2024年9月用户手册1/95版权©2024用友集团版权所有。未经用友集团的书面许可，本用户手册任何整体或部分的内容不得被复制、复印、翻译或缩减以用于任何目的。本用户手册的内容在未经通知的情形下可能会发生改变，敬请留意。请注意：本用户手册的内容并不代表用友网络所做的承诺。用户手册2/95目录第一章概述.............................................................................................................................................................61.1业务场景...................................................................................................................................................61.1.1正向基础数据同步（YonBIP→企业微信）......................................................................71.1.2待办消息同步（YonBIP→企业微信）................................................................................71.2关键词.......................................................................................................................................................8第二章前期准备...................................................................................................................................................92.1开通租户事件订阅白名单（待办消息同步公有云需要）........................................................92.2确认具有集成应用导入权限..............................................................................................................9第三章企微应用设置........................................................................................................................................113.1初始化企业微信内部应用.................................................................................................................113.2企微可信域名设置...............................................................................................................................123.3企微可信ip配置..................................................................................................................................133.4服务器外网ip查看.............................................................................................................................15第四章私有云仓库初始化................................................................................................................................164.1下载仓库文件........................................................................................................................................164.2初始化仓库............................................................................................................................................164.3连接器导入............................................................................................................................................16第五章集成资产包导入与配置......................................................................................................................181.集成应用导入................................................................................................................................182.事件订阅脚本执行.......................................................................................................................18用户手册3/953.混合云网关配置...........................................................................................................................194.Api调用创建.................................................................................................................................225.企微连接器连接配置创建.........................................................................................................246.BIP旗舰版连接器配置...............................................................................................................286.1.复杂人力........................................................................................................................................286.2简版人力........................................................................................................................................297.集成应用连接配置绑定..............................................................................................................308.配置事件订阅（待办消息同步需要）..................................................................................318.1添加待办事件订阅......................................................................................................................318.2添加撤销待办事件订阅............................................................................................................338.3添加工作通知事件订阅............................................................................................................358.4添加预警通知事件订阅............................................................................................................369.配置API路由................................................................................................................................389.1添加待办API路由......................................................................................................................389.2添加撤销待办API路由.............................................................................................................409.3添加工作通知API路由.............................................................................................................419.4添加预警通知API路由.............................................................................................................43第六章集成方案配置说明...............................................................................................................................466.1行政业务单元........................................................................................................................................466.1.1BIP行政业务单元同步企微部门.........................................................................................466.1.2BIP业务单元同步删除企微部门.........................................................................................48用户手册4/956.2部门..........................................................................................................................................................506.2.1BIP部门同步企微部门...........................................................................................................506.2.2BIP部门同步删除企微部门..................................................................................................536.3员工..........................................................................................................................................................556.3.1BIP人力云人员同步企微成员.............................................................................................556.3.2BIP人力云人员同步删除企微成员....................................................................................616.3.3BIP简版人员同步企微成员..................................................................................................636.3.4BIP简版人员同步删除企微成员.........................................................................................696.4待办、工作通知、预警同步（YonBIP->企微）.......................................................................706.4.1用户关系绑定...........................................................................................................................706.4.2BIP待办同步企微应用消息..................................................................................................736.4.3BIP撤销待办消息同步撤回企微消息...............................................................................756.4.4BIP工作通知同步发送企微消息.........................................................................................766.4.5BIP添加预警消息实时同步新增企微应用消息.............................................................78第七章数据同步任务执行................................................................................................................................807.1立即执行.................................................................................................................................................807.2定时执行.................................................................................................................................................807.3停止..........................................................................................................................................................82第八章混合云网关配置（非必须）..............................................................................................................848.1新建网关.................................................................................................................................................848.2下载网关客户端...................................................................................................................................84用户手册5/958.3下载网关密钥........................................................................................................................................858.4启动本地网关客户端..........................................................................................................................868.5验证网关是否启动成功.....................................................................................................................868.6使用混合云网关...................................................................................................................................87第九章注意事项..................................................................................................................................................889.1关于常量、默认值、直接映射使用说明......................................................................................889.2数据同步任务执行频率.....................................................................................................................889.3其它..........................................................................................................................................................88第十章实施过程常见问题................................................................................................................................8910.1发送待办失败.....................................................................................................................................8910.2事件查询界面无事件........................................................................................................................8910.3数据库表字段长度不足...................................................................................................................8910.4网关离线..............................................................................................................................................9010.5API未被授权.......................................................................................................................................91用户手册6/95第一章概述1.1业务场景本文档描述了企业微信和YonBIP集成场景，包括基础数据同步（YonBIP→企业微信）及待办消息（YonBIP→企业微信）。通过企微和YonBIP集成资产包的实施可以快速实现YonBIP与企业微信系统之间的基础数据和待办消息的集成，帮助项目快速完成项目交付，降低和企业微信系统的集成难度、成本。YonBIP和企业微信的集成场景如下图所示：1.基础数据集成：YonBIP的行政业务单元、部门、人员同步到企业微信部门和成员数据。2.单点登录集成：YonBIP工作台或单独功能点集成到三方OA系统的桌面端和移动端，在三方OA系统的桌面端和移动端可以单点打开YonBIP的PC和移动端工作台或单独功能点页面。用户手册7/953.待办消息集成：YonBIP的待办实时推送到三方OA系统，用户通过三方OA系统收到YonBIP待办消息，并可以在三方OA系统的桌面端和移动端可以单点打开YonBIP的PC和移动端待办审批页面进行审批；三方OA系统中YonBIP待办审批状态要保持和YonBIP一致。4.工作通知/预警通知集成：YonBIP的工作通知和预警通知实时推送到三方OA系统，用户可以在三方OA系统PC和移动端收到YonBIP的工作通知和预警通知的消息提醒；三方OA系统中YonBIP工作通知和预警通知的已读状态要和YonBIP保持一致。1.1.1正向基础数据同步（YonBIP→企业微信）数据集成说明行政业务单元定时将BIP的行政业务单元同步新增或更新企微部门数据定时将BIP停用行政业务单元同步删除企微的部门数据部门定时将BIP部门同步新增或更新企微部门数据定时将BIP停用部门同步删除企微的部门数据员工定时将BIP的员工同步新增或更新企微的成员数据定时将BIP停用的员工同步删除企微的成员数据1.1.2待办消息同步（YonBIP→企业微信）数据集成说明备注用户主键绑定关系定时将BIP和企业微信的用户主键关系进行绑定待办集成需要将BIP用户主键转换为企业微信用户ID待办消息集成监听BIP添加待办消息事件，同步发送企业微信的应用消息支持根据根据来源字段过滤监听BIP开放平台撤回待办消息事件，同步撤回企业微信应用消息工作通知监听BIP开放平台的工作通知事件，同步发送企业微信应用消息支持根据单据类型过滤预警通知监听BIP开放平台的预警通知事件，同步发送企业微信应用消息用户手册8/951.2关键词组织、部门、员工、待办、工作通知、预警消息用户手册9/95第二章前期准备2.1开通租户事件订阅白名单（待办消息同步公有云需要）注意:公有云订阅事件待办事件，需要发送邮件给消息与打印开发部胡连平（hulp@yonyou.com）进行开通，同时抄送宗腾飞（zongtf3@yonyou.com）和肖萌（xiaomenga@yonyou.com），需要包含信息如下：1.项目2.开通原因3.租户id和数据中心；参考模板如下：你好，请帮忙开通事件订阅中创建待办和更新待办事件，具体信息如下：1.项目：****项目2.开通原因：三方系统集成YonBIP待办3.租户id:oxv*****i，数据中心:公有云核心2租户ID的查询方法如下：菜单目录：数字化建模>我的企业>企业设置>企业信息下的企业账号ID;2.2确认具有集成应用导入权限打开连接集成服务>数据集成>集成方案设计页面，确认页面右上角有导入按钮，如没有集成方案设计页面的需要联系商务进行开通。用户手册10/95用户手册11/95第三章企微应用设置3.1初始化企业微信内部应用访问企业微信开放平台（网址：https://work.weixin.qq.com/wework_admin/frame#apps），创建企业微信自建应用；(1)点击创建应用，填写应用信息；用户手册12/953.2企微可信域名设置进入到应用的详情页面，在调用企微接口时，企微需要添加ip白名单，但是添加ip白名单之前企微需要先设置可信域名。点击下图箭头指向位置，按页面指引配置可信域名即可。添加页面如下图所示，需要完成域名归属认证，如配置域名为：huang9527.cn，则需要保证访问http://huang9527.cn/WW_verify_R3aiTZ603qLZR795.txt链接时能够下载WW_verify_R3aiTZ603qLZR795.txt文件。用户手册13/953.3企微可信ip配置用户手册14/95使用企微的部门、员工同步方案时，需将混合云网关所在服务器的外网ip配置到企微管理后台白名单，配置位置为下图中的secret下方企业可信ip；使用企微的待办同步方案时，在配置通讯录同步的可信IP的基础上，同时需将混合云网关及单点服务所在服务器的外网ip配置到企微管理后台白名单，配置位置为应用管理——>自建应用——>企业可信IP，如下图所示；注：如添加ip白名单时，遇到提示为：一下ip属于第三方服务商，则需要运维更改服务器出口ip，同一个ip配置在多个企微应用也可能出现此提示，该提示为企微限制。用户手册15/953.4服务器外网ip查看无论winServer或linux服务器，均可执行如下命令查询外网ip。curlcip.cc用户手册16/95第四章私有云仓库初始化4.1下载仓库文件使用用友云盘下载最新的仓库文件：https://pan.yonyou.com/s/yOpbN2jWRSw4.2初始化仓库在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击右上角“更新仓库”按钮选择从云盘下载的repository.tar.gz仓库文件进行上传，文件导入较慢，需要等待一段时间。4.3连接器导入在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击右上角“导入”按钮选择具体的业务连接器zip文件进行上传，文件导入较慢，需要等用户手册17/95待一段时间。用户手册18/95第五章集成资产包导入与配置5.1集成应用导入在用友YonBIP系统中的云平台>连接集成服务>数据集成>集成设计>集成方案设计界面，左上角点击“导入”功能，完成集成应用的导入新建工作。5.2事件订阅脚本执行专属化项目需联系项目运维人员，执行提供的集成资产包中的私有云事件订阅脚本，数据库为：iuap_ipaas；依次解压并执行下图压缩包内的sql。用户手册19/955.3混合云网关配置企微连接配置需要先创建混合云网关，操作步骤如下：创建完成后，混合云网关需要下载安装，操作步骤如下：第一步：下载网关客户端1.找一台7x24小时都能访问您企业内部系统，且能访问互联网的机器，安装网关客户端。2.下载完成后解压，需保证解压后的文件目录不存在中文字符。用户手册20/95供4种主流操作系统版本。即：Windowsx64、Windowsx86、Linuxx64、Linuxx86集群部署：支持下载多个客户端安装至同一/多个服务器第二步：下载密钥请将下载的密钥解压至网关客户端解压目录的config文件夹下集群部署：请使用同一网关内的密钥文件用户手册21/95第三步：启动网关客户端（本地）在网关客户端解压目录的bin文件夹，运行startup.bat用户手册22/95Linux环境：在网关客户端解压目录的bin文件夹，运行startup.sh集群部署：请先添加客户端所在服务器IP，再启动网关客户端第四步：测试连接集群部署需提前安装nginx（由nginx负责路由转发网关客户端）步骤如下：1、下载和解压nginx到服务器，请根据nginx安装服务器选择下载linux版或windows版。下载地址:http://nginx.org/en/download.html2、在【网关详情页】维护网关客户端实例，并下载nginx配置文件3、将nginx配置文件覆盖到nginx服务器上（nginx安装目录/conf）4、启动nginx5.4API调用创建进入api调用节点，点击添加用户手册23/95输入授权key描述，点击确定点击api授权点击新增api，选择原厂开放api用户手册24/95购买复杂人力服务的需要授权【业务单元列表数据同步_集成】、【部门列表数据同步_集成】、【员工信息列表查询MDD】、【获取员工详细信息MDD】接口。购买简版人力服务的需要授权【业务单元列表数据同步_集成】、【部门列表数据同步_集成】、【员工列表查询】、【员工详情查询】接口。5.5企微连接器连接配置创建集成应用导入成功之后，需要进行连接配置后才能使用，操作步骤如下：在用友YonBIP系统中的云平台>连接集成服务>集成总线>连接配置界面，点击新建连接按钮>选择对应的连接器>填写基本配置信息>确认>测试连接，提示连接测试成功即可。用户手册25/95填写企业微信域名、应用ID、企业ID、密钥，均由客户提供，以下均为测试数据配置名称配置编码配置参数企业微信域名hosthttps://qyapi.weixin.qq.com应用IDagentid1000002企业IDcorpidwwdc50dab7d879eb9e通讯录企业密钥connectCorpsecretoOcGtl4m8vQnNTg8TdA1eRM1eY33pNafPFPq9P08Uv8应用企业密钥appCorpsecretichM6bDkPRwz89BaFAYUXJGDScYXO06S7icnBZ8aquI企微单点hostauthHosthttps://open.weixin.qq.com单点接口地址authInterfacehttp://huang9527.cn/authhttp超时时间httpTimeOut30000用户手册26/95企微链接配置参数获取方式如下图：进入企微管理后台：https://work.weixin.qq.com/wework_admin/frame#profile下图所示即为企业ID选择应用管理，创建应用根据下图箭头所示，分别获取应用ID以及应用企业密钥用户手册27/95根据如下箭头所示，访问通讯录同步功能，获取通讯录企业密钥用户手册28/95企业微信域名以及企微单点host在项目无特殊网络要求情况下使用默认配置参数即可；单点接口地址在使用待办功能时配置，配合待办单点访问BIP；http超时时间为http请求发送后响应超时时间，单位毫秒；5.6BIP旗舰版连接器配置5.6.1复杂人力填写host、client_id、client_secret信息，需通过第五章第4小节api调用创建获取，以下均为测试信息租户：生态连接器复杂人力Host:https://bip-new15.yyuap.comappKey:a418aa5b36e04b05b2abbb025af0b7c3appSecret：7ccf51cfcb218a5ff898c804adb96d6354e93f25用户手册29/95注意：来源系统连接器和目标系统连接器的连接配置都需要创建。5.6.2简版人力填写host、client_id、client_secret信息，需通过第五章第4小节api调用创建节点进行注册，以下均为测试信息Host:https://bip-new15.yyuap.comappKey:a418aa5b36e04b05b2abbb025af0b7c3appSecret：7ccf51cfcb218a5ff898c804adb96d6354e93f25用户手册30/955.7集成应用连接配置绑定来源系统和目标系统连接配置创建完成之后，点击集成应用的编辑按钮，将刚创建的连接配置选择上，进行保存即可用户手册31/955.8配置事件订阅（待办消息同步需要）菜单路径：云平台>连接集成服务>API管理>事件订阅。5.8.1添加待办事件订阅配置步骤：1.进入事件订阅节点，创建企微新增待办授权KEY【名称可自定义】，确定保存。用户手册32/952.点击事件订阅按钮3.点击下图中的新增订阅，按事件编码【TODO_CENTER_ADD_TODO】添加订阅事件后点击保存，返回下图页面后，在回调地址中添加如下链接【注：需要将${BIP域名}提前进行替换】之后点击测试按钮，测试成功后，点击保存。用户手册33/95https://${BIP域名}/iuap-api-gateway/yonbip/uspace/event/todocenter/addTodo5.8.2添加撤销待办事件订阅配置步骤：1.进入事件订阅节点，创建企微更新待办授权KEY【名称可自定义】，确定保存。用户手册34/952.点击事件订阅按钮3.点击下图中的新增订阅，按事件编码【TODO_CENTER_UPDATE_TODO】添加订阅事件后点击保存，返回下图页面后，在回调地址中添加如下链接【注：需要将${BIP域名}提前进行替换】之后点击测试按钮，测试成功后，点击保存。https://${BIP域名}/iuap-api-gateway/yonbip/uspace/event/todocenter/updateTodo用户手册35/955.8.3添加工作通知事件订阅配置步骤：1.进入事件订阅节点，创建企微发送工作通知授权KEY【名称可自定义】，确定保存。用户手册36/952.点击事件订阅按钮3.点击下图中的新增订阅，按事件编码【WORK_NOTIFY_WORK_NOTIFY】添加订阅事件后点击保存，返回下图页面后，在回调地址中添加如下链接【注：需要将${BIP域名}提前进行替换】之后点击测试按钮，测试成功后，点击保存。https://${BIP域名}/iuap-api-gateway/yonbip/uspace/event/worknotify/addWorkNotify5.8.4添加预警通知事件订阅配置步骤：1.进入事件订阅节点，创建企微发送预警通知授权KEY【名称可自定义】，确定保存。用户手册37/952.点击事件订阅按钮用户手册38/953.点击下图中的新增订阅，按事件编码【WORK_NOTIFY_ALARM_NOTIFY】添加订阅事件后点击保存，返回下图页面后，在回调地址中添加如下链接【注：需要将${BIP域名}提前进行替换】之后点击测试按钮，测试成功后，点击保存。https://${BIP域名}/iuap-api-gateway/yonbip/uspace/event/worknotify/addAlarmNotify5.9配置API路由5.9.1添加待办API路由1.进入api路由节点，点击新增2.选择api，在预置页面，输入待办，勾选监听监听BIP添加待办事件推送三方系统，点击确定。用户手册39/953.确认保存api路由后，点击下图中的设计按钮，并新增规则。4.规则内容为：actionKey(Body)等于ucenter,集成方案选择BIP添加待办消息同步发送企微消息，确认保存。用户手册40/955.9.2添加撤销待办API路由1.进入api路由节点，点击新增2.选择api，在预置页面，输入待办，勾选监听监听BIP添加待办事件推送三方系统，点击确定。用户手册41/953.确认保存api路由后，点击下图中的设计按钮，并新增规则。4.规则内容为：actionKey(Body)等于revocation::ucenter,集成方案选择BIP撤销待办消息同步撤回企微消息，确认保存。5.9.3添加工作通知API路由1.进入api路由节点，点击新增用户手册42/952.选择api，在预置页面，输入工作通知，勾选监听BIP工作通知事件推送三方系统，点击确定。3.确认保存api路由后，点击下图中的设计按钮，并新增规则。4.规则内容为：actionKey(Body)等于UCenterAppIdShareNotify,集成方案选择BIP工作通知同步发送企微消息，确认保存。用户手册43/955.9.4添加预警通知API路由1.进入api路由节点，点击新增2.选择api，在预置页面，输入工作通知，勾选监听BIP预警通知事件推送三方系统，点击确定。用户手册44/953.确认保存api路由后，点击下图中的设计按钮，并新增规则。4.规则内容为：actionKey(Body)等于UCenterAppIdShareNotify,集成方案选择BIP添加预警消息实时同步新增企微应用消息，确认保存。用户手册45/95用户手册46/95第六章集成方案配置说明6.1行政业务单元6.1.1BIP行政业务单元同步企微部门方案编码：bip_wecom_Org_sync定时任务主动拉取BIP行政组织用户手册47/95注：BIP新建业务单元如有上级，需要勾选如图所示位置的上级行政组织，否则同步组织不会按树形同步。企微管理后台地址：（需要扫码登录，联系客户企微管理人员扫码登录后台）{"funcTypeCode":"adminorg","orgDept":"org",用户手册48/95https://work.weixin.qq.com/wework_admin/frame#contacts6.1.2BIP业务单元同步删除企微部门方案编码：bip_wecom_org_del定时任务主动拉取不可用状态的行政组织同步删除企微部门用户手册49/95{"funcTypeCode":"adminorg","orgDept":"org","enable":"2"用户手册50/956.2部门6.2.1BIP部门同步企微部门方案编码：bip_wecom_dept_sync定时任务主动拉取BIP部门用户手册51/95此映射字段可配置公式编辑器，通过公式自行处理该部门是否同步用户手册52/95示例为根据部门code进行筛选，示例公式中的code的部门将不会被同步到企微iif(contains(code,"123")||contains(code,"234"),false,true){"enable":"1"}用户手册53/956.2.2BIP部门同步删除企微部门方案编码：bip_wecom_dept_del定时任务主动拉取不可用状态的部门同步删除企微部门用户手册54/95{"enable":"2"}用户手册55/956.3员工BIP员工根据项目是否购买人力云分为2种情况，一个是简版人员，即未购买人力云，在BIP的数字化建模里的【员工】节点维护员工信息；一个是人力云员工，即购买人力云，在BIP的人力云的【员工信息】节点维护盐工信息。由于这2种情况BIP的员工接口是不同的，所以简版人员和人力云员工各做了一套数据同步方案。注：项目组需要根据是否购买人力云，选择使用其中一套集成方案。6.3.1BIP人力云人员同步企微成员方案编码：bip_wecom_staffMDD_sync定时任务主动拉取可用状态的员工同步到企微人员企微人员同步方案同步筛选字段syncFlag配置，如下图【必须有对应来源字段，且来源字段为必填值，如手机号，否则不会执行公式造成默认同步该成员】：用户手册56/95此映射字段可配置公式编辑器，通过公式自行按照实际需求处理哪些员工是否同步，syncFlag为true时表示需要同步，为false时表示不需要同步。示例为根据手机号进行筛选，示例公式中的手机号的员工将不会被同步到企微用户手册57/95此映射字段可配置公式编辑器，通过公式自行处理该员工的任职信息是否被同步iif(contains(mobile,"13363227182")||contains(mobile,"13363227183"),false,true)用户手册58/95示例为根据任职信息的备注进行筛选，备注内容包含“不同步”字符串的任职将不会被同步到企微用户手册59/95企微人员同步方案自定义字段以及成员对外属性配置，如下图：自定义字段映射配置：其中企微自定义字段需要先在WEB管理端添加，见扩展属性添加方法（按ctrl点击查看配置方法），否则忽略未知属性的赋值。企微可配置文本、网页、小程序三种自定义字段；传输文本时：字段配置为extattrObj.textMap.自定义字段名称（企微限制四个汉字最多）.value【该字段需传输文本属性内容，长度限制64个UTF8字符】传输网页时：字段配置为extattrObj.webMap.自定义字段名称.title【该字段需传输网页的展示标题,长度限制12个UTF8字符】；以及字段配置为extattrObj.webMap.自定义字段名称.url【该字段需传输网页的url,必须包含http或者https头】传输小程序时：字段配置为extattrObj.miniprogramMap.自定义字段名称.appid【该字段需传输小程序的appid】；iif(contains(jobList.memo,"不同步"),false,true)用户手册60/95以及字段配置为extattrObj.miniprogramMap.自定义字段名称.pagepath【该字段需传输小程序访问页面路径，示例：/index】；以及字段配置为extattrObj.miniprogramMap.自定义字段名称.title【该字段需传输小程序的标题】成员对外属性映射配置：企微成员对外属性，字段详情见对外属性（按ctrl点击查看配置方法）；成员对外属性与自定义字段同样有三种类型，分别为文本、网页、小程序，配置方式与上方自定义字段基本一致，只需修改为extattrObj为externalProfileAttrObj即可，以文本为示例：传输文本时：字段配置为externalProfileAttrObj.textMap.自定义字段名称（企微限制四个汉字最多）.value【该字段需传输文本属性内容，长度限制64个UTF8字符】是否需要合并主职、兼职数据:true是否需要详情数据:true状态:1用户手册61/956.3.2BIP人力云人员同步删除企微成员方案编码：bip_wecom_staffMDD_del定时任务主动拉取不可用状态的员工同步删除企微员工用户手册62/95状态:2用户手册63/956.3.3BIP简版人员同步企微成员方案编码：bip_wecom_staff_sync定时任务主动拉取可用状态的员工同步到企微员工企微人员同步方案同步筛选字段配置，如下图【必须有对应来源字段，且来源字段为必填值，如手机号，否则不会执行公式造成默认同步该成员】：此映射字段可配置公式编辑器，通过公式自行处理该员工是否同步用户手册64/95示例为根据手机号进行筛选，示例公式中的手机号的员工将不会被同步到企微iif(contains(mobile,"13363227182")||contains(mobile,"13363227183"),false,true)用户手册65/95此映射字段可配置公式编辑器，通过公式自行处理该员工的任职信息是否被同步示例为根据任职信息的备注进行筛选，备注内容包含“不同步”字符串的任职将不会被同步到企微用户手册66/95企微人员同步方案自定义字段以及成员对外属性配置，如下图：自定义字段映射配置：其中企微自定义字段需要先在WEB管理端添加，见扩展属性添加方法（按ctrl点击查看...
