YonBIPV3.0(R6_2407_1)旗舰版云平台-三方集成资产-BIP和蓝凌集成资产实施指南用友网络科技股份有限公司2024年9月用户手册1/52版权©2024用友集团版权所有。未经用友集团的书面许可，本用户手册任何整体或部分的内容不得被复制、复印、翻译或缩减以用于任何目的。本用户手册的内容在未经通知的情形下可能会发生改变，敬请留意。请注意：本用户手册的内容并不代表用友网络所做的承诺。用户手册2/52目录第一章概述.............................................................................................................................................................51.1业务场景...................................................................................................................................................51.1.1正向基础数据同步（YonBIP→蓝凌）................................................................................61.1.2待办消息同步（YonBIP→蓝凌）.........................................................................................61.2关键词.......................................................................................................................................................6第二章前期准备....................................................................................................................................................72.1开通租户事件订阅白名单（待办消息同步公有云需要）........................................................72.2确认具有集成应用导入权限..............................................................................................................82.3访问蓝凌接口访问鉴权.......................................................................................................................8第三章集成资产包导入与配置.........................................................................................................................93.1集成应用导入..........................................................................................................................................93.2YonBIP的API授权..............................................................................................................................113.3YonBIP连接器连接配置....................................................................................................................123.4蓝凌连接器连接配置..........................................................................................................................143.5集成应用连接配置绑定.....................................................................................................................163.6配置事件订阅(待办消息同步需要).................................................................................................163.6.1添加待办事件订阅..................................................................................................................163.6.2更新待办事件订阅..................................................................................................................183.7配置API路由（待办消息同步需要）.........................................................................................193.7.1添加待办API路由配置.........................................................................................................19用户手册3/523.7.2更新待办API路由配置.........................................................................................................21第四章集成方案配置说明................................................................................................................................224.1正向基础数据同步（BIP同步到蓝凌）.......................................................................................224.1.1行政业务单元...........................................................................................................................224.1.2部门.............................................................................................................................................234.1.3岗位.............................................................................................................................................254.1.4职级.............................................................................................................................................264.1.5职务.............................................................................................................................................284.1.6员工.............................................................................................................................................294.2待办消息同步（BIP同步到蓝凌）................................................................................................314.2.1BIP和蓝凌用户主键关系定时同步绑定_简版员工.......................................................314.2.2BIP添加待办消息实时同步新增蓝凌待办消息.............................................................324.2.3BIP更新待办消息实时同步更新或删除蓝凌待办消息................................................35第五章数据同步任务配置说明.......................................................................................................................365.1立即执行.................................................................................................................................................365.2定时执行.................................................................................................................................................375.3停止..........................................................................................................................................................39第六章混合云网关配置....................................................................................................................................406.1新建网关.................................................................................................................................................406.2下载网关客户端...................................................................................................................................406.3下载网关密钥........................................................................................................................................41用户手册4/526.4启动本地网关客户端.........................................................................................................................426.5验证网关是否启动成功....................................................................................................................426.6使用混合云网关..................................................................................................................................43第七章注意事项..................................................................................................................................................447.1关于常量、默认值、直接映射使用说明......................................................................................447.2数据同步任务执行频率.....................................................................................................................447.3其它..........................................................................................................................................................44第八章常见问题..................................................................................................................................................448.1问题1：API未被授权........................................................................................................................448.2问题2：方案中没有来源主键为**的数据映射关系.................................................................478.3问题3：新建连接配置找不到连接器怎么办？.........................................................................498.4问题4：执行同步任务报编码已存在，如何处理？................................................................508.5问题5：执行同步任务报字段长度太长，如何处理？...........................................................508.6问题6：执行同步任务报没检索到可执行函数，如何处理？..............................................50用户手册5/52第一章概述1.1业务场景本文档描述了蓝凌和YonBIP集成场景，包括正向基础数据同步（YonBIP→蓝凌）及待办消息（YonBIP→蓝凌）。通过蓝凌和YonBIP集成资产包的实施可以快速实现YonBIP与蓝凌系统之间的基础数据和待办消息的集成，帮助项目快速完成项目交付，降低和蓝凌系统的集成难度、成本。YonBIP和蓝凌的集成场景如下图所示：1.基础数据集成：YonBIP的行政业务单元、部门、岗位、职级、职务、人员和蓝凌组织机构、组织部门、组织岗位、组织职级、组织职务和组织人员数据的同步。用户手册6/522.单点登录集成：YonBIP工作台或单独功能点集成到三方OA系统的桌面端和移动端，在三方OA系统的桌面端和移动端可以单点打开YonBIP的PC和移动端工作台或单独功能点页面。3.待办消息集成：YonBIP的待办实时推送到三方OA系统，用户通过三方OA系统收到YonBIP待办消息，并可以在三方OA系统的桌面端和移动端可以单点打开YonBIP的PC和移动端待办审批页面进行审批；三方OA系统中YonBIP待办审批状态要保持和YonBIP一致。1.1.1正向基础数据同步（YonBIP→蓝凌）数据集成说明行政业务单元定时将BIP的行政业务单元同步新增或更新蓝凌行政组织机构数据，需要根据启停用状态调用启用或停用接口，未启用的数据不同步，要支持扩展属性部门定时拉取BIP部门信息同步到蓝凌的行政组织部门，需要根据启停用状态调用启用或停用接口，未启用的数据不同步，要支持扩展属性岗位定时拉取BIP岗位信息同步到蓝凌的行政组织岗位，需要根据启停用状态调用启用或停用接口，未启用的数据不同步职级定时拉取BIP职级信息同步到蓝凌的行政组织职级，需要根据启停用状态调用启用或停用接口，未启用的数据不同步职务定时拉取BIP职务信息同步到蓝凌的行政组织职务，需要根据启停用状态调用启用或停用接口，未启用的数据不同步人员定时拉取BIP人员信息同步到蓝凌的行政组织人员，需要根据启停用状态调用启用或停用接口，未启用的数据不同步1.1.2待办消息同步（YonBIP→蓝凌）数据集成说明用户主键绑定关系定时将BIP和蓝凌的用户主键关系进行绑定待办消息集成监听BIP开放平台的【添加待办消息】事件，同步新增蓝凌待办监听BIP开放平台的【更新待办消息】事件，同步更新或删除蓝凌待办1.2关键词单点待办、蓝凌、蓝凌连接器、蓝凌集成资产包、事件订阅、API路由。用户手册7/52第二章前期准备2.1开通租户事件订阅白名单（待办消息同步公有云需要）注意:公有云订阅事件待办事件，需要发送邮件给消息与打印开发部胡连平（hulp@yonyou.com）进行开通，同时抄送宗腾飞（zongtf3@yonyou.com）和肖萌（xiaomenga@yonyou.com），需要包含信息如下：1.项目2.开通原因3.租户id和数据中心；参考模板如下：你好，请帮忙开通事件订阅中创建待办和更新待办事件，具体信息如下：1.项目：****项目2.开通原因：三方系统集成YonBIP待办3.租户id:oxv*****i，数据中心:公有云核心2租户ID的查询方法如下：菜单目录：数字化建模>我的企业>企业设置>企业信息用户手册8/522.2确认具有集成应用导入权限打开连接集成服务>数据集成>集成方案设计页面，确认页面右上角有导入按钮，如没有集成方案设计页面的需要联系商务进行开通。2.3访问蓝凌接口访问鉴权我们采用的是蓝凌的OAuth2认证方式，OAuth2的认证方式的特征，是在调用实际的业务接口之前需要获取token，然后实际调用业务接口时，需要传递这个token作为身份认证的标识集成平台获取token的请求路径为：/authapi/getToken调用/authapi/getToken需要传递appKey和appSecret，可以通过body来传递，也可以通过URL参数来传递获取token的调用样例如下：用户手册9/52蓝凌的appKey以及appSecret配置在连接配置里第三章集成资产包导入与配置3.1集成应用导入在用友YonBIP系统中的云平台>连接集成服务>数据集成>集成设计>集成方案设计界面，点击左上角“导入”按钮，按照页面提示，完成集成应用的导入工作。用户手册10/52导入后效果如下：用户手册11/523.2YonBIP的API授权进入“API调用”节点，点击“添加”按钮创建授权配置，点击确定点击“API授权”用户手册12/521.正向基础数据同步（BIP→蓝凌）授权接口：接口名称接口地址业务单元列表数据同步_集成/yonbip/digitalModel/integrationApi/org/orgUnitDataSync部门列表数据同步_集成/yonbip/digitalModel/integrationApi/dept/deptDataSync岗位列表查询/yonbip/digitalModel/position/list员工列表查询/yonbip/digitalModel/staff/list员工详情查询/yonbip/digitalModel/staff/detail员工信息列表查询MDD/yonbip/hrcloud/staff/listmdd获取员工详细信息MDD/yonbip/hrcloud/HRCloud/getStaffDetail2.消息集成（BIP→蓝凌）授权接口：集成认证中心获取登录临时code/yonbip/yht/getThirdLoginCode员工列表查询（简版）/yonbip/digitalModel/staff/list3.3YonBIP连接器连接配置集成应用导入成功之后，需要进行连接配置后才能使用，操作步骤如下：1、在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击新建连接按钮>选择对应的连接器>填写基本配置信息>确认>测试连接，提示连接测试成功即可。用户手册13/522、填写host、appkey、appsecret（用上面创建授权配置获取的appkey、appsecret）host:域名，根据部署环境填写（例如：https://bip-new18.yyuap.com）3、填写完毕后点击测试连接用户手册14/523.4蓝凌连接器连接配置在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击新建连接按钮>选择对应的连接器>填写基本配置信息>确认>测试连接，提示连接测试成功即可。具体创建步骤可参照BIP连接配置创建。用户手册15/52具体属性说明：属性说明服务地址蓝凌服务地址，http或https开头appKey访问蓝凌鉴权的方式，默认选择IP方式，需要蓝凌那边通过配置ip白名单;当鉴权方式选择rsa非对称鉴权的方式时，可以通过获取token的方式来进行鉴权appSecret网关代理如果bip和致远都是私有云，网络是连通的则不需要开启；如果bip是公有云，致远是私有云，网络没有连通则需要将混合云网关部署至本地内网中，用于打通云上云下的内外网穿透网关信息如果网关代理打开，需要选择对应的混合云网关，创建网关具体请请参考第四章系统编码对接系统编码，蓝凌系统配置的异构系统编码单点跳转服务单点三方服务地址，如http://abc.com?code=%s&redirectUrl=%s用户手册16/523.5集成应用连接配置绑定来源系统和目标系统连接配置创建完成之后，点击集成应用(BIP和蓝凌)的编辑按钮，将刚创建的连接配置选择上，进行保存即可。3.6配置事件订阅(待办消息同步需要)菜单路径：云平台>连接集成服务>API管理>事件订阅。3.6.1添加待办事件订阅新增应用【蓝凌新增待办】，名字可以自定义，鼠标悬停在【蓝凌新增待办】应用条目，点击【事件订阅】按钮，配置添加待办事件订阅回调地址。1.查询“监听BIP添加待办事件推送三方系统”API地址，API文档菜单目录：云平台>连接集成服务>API管理>调用API>API文档；用户手册17/522.配置事件订阅回调地址事件订阅回调地址格式：https://YonBIP业务中台统一域名/iuap-api-gateway/yonbip/uspace/event/todocenter/addTodo。回调地址示例：https://bip-pre.yonyoucloud.com/iuap-api-gateway/yonbip/uspace/event/todocenter/addTodo3.新增“添加待办消息”订阅：用户手册18/524.访问【API调用】节点，对授权Key进行API授权API调用菜单地址：云平台>连接集成服务>API管理>调用API>API调用3.6.2更新待办事件订阅1.首先新增应用【蓝凌更新待办】，鼠标悬停在【蓝凌更新待办】应用条目，点击【事件订阅】按钮。2.查询“监听BIP更新待办事件推送三方系统”API地址，配置回调地址，添加“更新待办消息”订阅事件。事件订阅回调地址格式：https://YonBIP业务中台统一域名/iuap-api-gateway/yonbip/uspace/event/todocenter/updateTodo。用户手册19/52回调地址示例：https://bip-pre.yonyoucloud.com/iuap-api-gateway/yonbip/uspace/event/todocenter/updateTodo3.访问【API调用】节点，对授权Key进行API授权授权API列表：监听BIP更新待办事件推送三方系统3.7配置API路由（待办消息同步需要）菜单目录：云平台>连接集成服务>API管理>调用API>API路由3.7.1添加待办API路由配置注：在当前租户只有一个OA与BIP集成消息时，默认无须配置。1.新增API路由规则，选择“监听BIP添加待办事件推送三方系统”API用户手册20/522.点击【设计】按钮，设计API路由规则3.点击【新建规则】，配置API路由规则名称、触发条件、以及执行集成方案。4.保存路由配置用户手册21/523.7.2更新待办API路由配置1.新增API路由规则，选择“监听BIP更新待办事件推送三方系统”API，点击【设计】按钮，设计API路由规则。2.点击【新建规则】，配置API路由规则名称、触发条件。选择“BIP更新待办消息实时同步更新或删除蓝凌待办消息”集成方案作为执行动作。3.并保存路由配置。用户手册22/52第四章集成方案配置说明4.1正向基础数据同步（BIP同步到蓝凌）4.1.1行政业务单元4.1.1.1BIP业务单元定时同步蓝凌组织机构⚫方案编码：bip_landray_orgunit_base_sync_timer⚫集成场景：定时将BIP的行政业务单元同步新增或更新蓝凌行政组织机构数据，需要根据启停用状态调用启用或停用接口，未启用的数据不同步，要支持扩展属性用户手册23/524.1.2部门4.1.2.1BIP部门定时同步蓝凌组织部门⚫方案编码：bip_landray_dept_base_sync_timer⚫集成场景：定时拉取BIP部门信息同步到蓝凌的行政组织部门，需要根据启停用状态调用启用或停用接口，未启用的数据不同步，要支持扩展属性用户手册24/52用户手册25/524.1.3岗位4.1.3.1BIP岗位定时同步蓝凌组织岗位⚫方案编码：bip_landray_post_base_sync_timer⚫集成场景：定时拉取BIP岗位信息同步到蓝凌的行政组织岗位，需要根据启停用状态调用启用或停用接口，未启用的数据不同步用户手册26/524.1.4职级4.1.4.1BIP职级定时同步蓝凌组织职级⚫方案编码：bip_landray_org_level⚫集成场景：定时拉取BIP职级信息同步到蓝凌的行政组织职级，需要根据启停用状态调用启用或停用接口，未启用的数据不同步用户手册27/52用户手册28/524.1.5职务4.1.5.1BIP职务定时同步蓝凌组织职务⚫方案编码：bip_landray_staff_level⚫集成场景：定时拉取BIP职务信息同步到蓝凌的行政组织职务，需要根据启停用状态调用启用或停用接口，未启用的数据不同步用户手册29/524.1.6员工BIP员工根据项目是否购买人力云分为2种情况，一个是简版人员，即未购买人力云，在BIP的数字化建模里的【员工】节点维护员工信息；一个是人力云员工，即购买人力云，在BIP的人力云的【员工信息】节点维护员工信息，目前蓝凌是用简版人力接口来同步简版人力和复杂人力的人员数据。注：项目组需要根据是否购买人力云，选择使用其中一套集成方案。4.1.6.1BIP简版员工定时同步蓝凌人员⚫方案编码：bip_landray_person⚫集成场景：定时拉取BIP的简版员工同步到蓝凌的人员用户手册30/52用户手册31/524.2待办消息同步（BIP同步到蓝凌）4.2.1BIP和蓝凌用户主键关系定时同步绑定_简版员工⚫方案编码：bip_landary_userrelation_base_binding_sync_timer⚫集成场景：定时将BIP的用户和蓝凌人员主键关系绑定。标准方案现在默认配置的是通过员工code做绑定，项目也可以用员工其他信息替代。用户手册32/524.2.2BIP添加待办消息实时同步新增蓝凌待办消息⚫方案编码：bip_todo_landray_todomessage_add_call⚫集成场景：BIP添加待办消息实时同步新增蓝凌待办消息。用户手册33/52注意：如果需要只给某些类型的待办消息推送消息，其他类型的消息不推送，可以在字段映射配置页面将参数syncFlag是否同步填上对应的公式，示例为根据表单formId进行过滤。用户手册34/52示例为根据value.formId进行筛选，示例公式中的formId将会被同步到蓝凌iif(contains(value.formId,'CUST.cust_customeraddapplycard111')||contains(value.formId,'表单id'),true,false用户手册35/524.2.3BIP更新待办消息实时同步更新或删除蓝凌待办消息⚫方案编码：bip_todo_weaver_todomessage_update_call⚫集成场景：实时将BIP更新待办消息同步更新蓝凌待办消息。用户手册36/52第五章数据同步任务配置说明集成方案生成的所有任务都将会在数据同步任务中进行管理，数据同步任务目录为云平台>连接集成服务>数据集成>集成任务>数据同步任务。集成方案分为定时任务和实时推送两种方式，实时推送方式的集成方案可以通过开放平台中的“数据同步任务-推送数据”接口进行调用，定时任务的集成方案可以通过立即执行和定时执行进行调用。5.1立即执行在数据同步任务列表上点击【立即执行】按钮，会弹出一个对话框，询问是否强制推送、是否根据时间段补录、是否根据增量时间戳进行查询来源系统数据。⚫强制推送：开启则会无视目标数据是否在数据详情中存在，直接调用目标系统保存接口；不开启则会先与数据详情列表中的数据进行比对，如果数据在数据详情中存在且所有字段值都一样则不进行推送，即不会调用目标系统保存接口，否则进行推送。⚫时间段补录：按照选择的时间段进行来源系统数据的查询，分为开始时间和结束时间，前提是来源系统接口支持根据时间段条件进行查询并且连接器操作打上标签。⚫增量时间戳：修改数据同步任务执行的开始时间，一般用在期初数据的同步，前提是来源系统接口支持根据时间段条件进行查询并且连接器操作打上标签。用户手册37/525.2定时执行点击【定时执行】按钮会弹出“设置时间表达式”弹窗，数据同步任务支持页面端配置corn表达式的方式配置定时任务。定时任务支持按分钟、小时、日、月、年配置执行周期、执行频率，并生成对应的Corn表达式。用户手册38/52定时任务定义完成后，弹窗下方会展示定时任务对应的Corn表达式和最近五次执行时间。定时任务创建成功后，可在【定时执行列表】中展示已创建的定时任务。用户手册39/525.3停止运行中的任务可以通过点击【停止】按钮人为干预，终止任务执行。注意：点击停止，任务不会立即停止，同步任务会在执行完本次分页同步后停止。用户手册40/52第六章混合云网关配置混合云网关作为连接配置的选填参数，用于解决企业内服务与公网服务之间的链路通道，混合云网关将部署至本地内网中，用于打通云上云下的内外网穿透。注意：当企业内服务与公网服务网络不通的时候再进行混合云网关的创建与使用。6.1新建网关登录BIP系统，切换到对应租户，在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点点击“新建网关”。录入网关编码和网关名称，点击确定即可。刚创建完的网关默认为离线状态6.2下载网关客户端在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点找到我用户手册41/52们刚创建完的混合云网关，点击【下载终端】按钮，下载对应版本的网关客户端。这里以windows版本为例，下载的文件以及解压后的文件如下需要注意：⚫找一台7x24小时都能访问您企业内部系统，且能访问互联网的机器，安装网关客户端。⚫下载完成后解压，需保证解压后的文件目录不存在中文字符。6.3下载网关密钥每个网关需要有该网关的秘钥进行安全认证，在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点找到我们刚创建完的混合云网关，点击【下载密钥】按钮，下载指定网关的密钥。下载下来的密钥为gateway.config.json文件用户手册42/52将下载的密钥文件（gateway.config.json）移动至网关客户端解压目录的config文件夹下6.4启动本地网关客户端在网关客户端解压目录的bin文件夹，运行iuap-gateway-start.bat。Linux环境在网关客户端解压目录的bin文件夹，运行iuap-gateway-start.sh。双击iuap-gateway-start.bat脚本启动网关，控制台输入1回车。6.5验证网关是否启动成功脚本命令启动成功后，在【连接集成服务】->【集成实施共建】->【连接管理】->【混用户手册43/52合云网关】节点找到我们刚创建完的混合云网关，点击【状态刷新】按钮，可以看到网关状态显示为“在线”，这时我们的本地混合云网关就已经搭建成功了。6.6使用混合云网关当我们在创建连接配置的时候，勾选【启用混合云网关】，即可在【网关信息】属性下拉框中获取当前租户下可用的网关信息。用户手册44/52第七章注意事项7.1关于常量、默认值、直接映射使用说明1、常量配置必须配置来源，按照来源取值作为转换前映射转换后数据，需清除默认值。2、默认值使用必须清除来源字段，否则默认值不生效。7.2数据同步任务执行频率集成应用下的所有集成方案，定时执行的时间频率可根据项目需求自行选择7.3其它1、BIP的单据编号不允许超过32位，否则无法保存。第八章常见问题8.1问题1：API未被授权同步数据失败：同步失败:返回状态{"code":"310037","message":"API未被授权：APPKEY[f47f1197750343c58ffef772c6e454db]未获得要调用的API[/yonbip/digitalModel/orgunit/batchSave]的授权用户手册45/52解决方法：1.在api文档中，搜索未授权的api，找到该api的名称;2.在api调用中，找到需要授权的api，点击api授权按钮，进入授权页面;3.点击右上角的新增按钮;用户手册46/524.搜索需要授权的api，选中此api，点击确认按钮即可。用户手册47/528.2问题2：方案中没有来源主键为**的数据映射关系错误信息：方案名称:蓝凌用户定时同步BIP简版员工，方案编码：lark_user_bip_staff_sync_timer,其中来源字段所属部门ID(jobList.department_ids)数据为[24052401]通过lark_bip_dept_contact_sync_timer方案进行翻译，该lark_bip_dept_contact_sync_timer方案中没有来源主键为[24052401]的数据映射关系.解决方案:请在数据同步任务节点，(lark_bip_dept_contact_sync_timer)方案中，同步并修复来源主键为[24052401]的数据。解决方法：由于蓝凌用户方案同步时依赖蓝凌的部门同步方案，使用翻译时，未找到需要翻译的映射关系。解决方式有两种：方案一（自动同步）：在数据同步任务中，找到编码为lark_bip_dept_contact_sync_timer集成方案，直接点击立即执行，把部门同步过来，再执行蓝凌用户定时同步BIP简版员工集成方案。用户手册48/52方案二（手动维护）：在数据同步任务中，找到编码为lark_bip_dept_contact_sync_timer集成方案，点击数据详情按钮。找到映射关系，点击新增映射主键按钮，在输入框中，输入来源为24052401及目标系统的主键，点击确认即可。用户手册49/528.3问题3：新建连接配置找不到连接器怎么办？在新建连接配置前需先进行连接器导入，然后再选择连接器进行连接器连接配置。用户手册50/528.4问题4：执行同步任务报编码已存在，如何处理？在数据同步任务运行记录的日志中，报[e6g7785d][用户的user_id]编码(+86-15989786543)已经存在？解决方法：在员工中，已经存在相同的手机号，需要修改手机号，在进行任务同步。8.5问题5：执行同步任务报字段长度太长，如何处理？由于数据同步任务映射关系表名为ydirs_p_*****,为自动建表，设计字段长度不足以适用所有场景，私有云项目如发现此问题，临时解决方案可访问iuap_ipaas库，找到相应报错的表，手动修改报错字段长度即可，错误如下图所示8.6问题6：执行同步任务报没检索到可执行函数，如何处理？事件订阅脚本导入完成后，在事件订阅界面点击测试链接保存成功，但是发送待办失败，用户手册51/52在数据同步任务界面查看返回日志如下：需从新导入连接器，进入技术中台，重启集成平台及混合云数据集成服务即可。
