YonBIPV3.0(R6_2407_1)旗舰版云平台-三方集成资产-集成资产BIP和AD域集成资产实施指南用户手册1/43版权©2024用友集团版权所有。未经用友集团的书面许可，本用户手册任何整体或部分的内容不得被复制、复印、翻译或缩减以用于任何目的。本用户手册的内容在未经通知的情形下可能会发生改变，敬请留意。请注意：本用户手册的内容并不代表用友网络所做的承诺。用友网络科技股份有限公司2024年9月用户手册2/43目录第一章概述.............................................................................................................................................................41.1业务场景...................................................................................................................................................41.2关键词.......................................................................................................................................................51.3专业名词术语..........................................................................................................................................5第二章集成资产包导入与配置.........................................................................................................................62.1集成应用导入..........................................................................................................................................62.2API授权....................................................................................................................................................62.3BIP连接配置创建...................................................................................................................................82.4AD域连接配置创建............................................................................................................................102.5集成应用连接配置绑定......................................................................................................................12第三章集成方案配置说明................................................................................................................................133.1BIP组织定时同步AD域....................................................................................................................133.2BIP组织停用同步AD域....................................................................................................................153.3BIP部门定时同步AD域....................................................................................................................173.4BIP部门停用同步AD域....................................................................................................................203.5BIP员工同步AD域用户....................................................................................................................223.6BIP员工停用同步AD域用户...........................................................................................................25第四章混合云网关配置....................................................................................................................................304.1新建网关.................................................................................................................................................304.2下载网关客户端...................................................................................................................................304.3下载网关密钥........................................................................................................................................314.4启动本地网关客户端..........................................................................................................................324.5验证网关是否启动成功.....................................................................................................................32用户手册3/434.6使用混合云网关...................................................................................................................................33第五章数据同步任务配置说明.......................................................................................................................345.1立即执行.................................................................................................................................................345.2定时执行.................................................................................................................................................345.3停止..........................................................................................................................................................36第六章注意事项..................................................................................................................................................386.1关于常量、默认值、直接映射使用说明......................................................................................386.2数据同步任务执行频率.....................................................................................................................386.3其它..........................................................................................................................................................38第七章常见问题..................................................................................................................................................397.1新建连接配置找不到连接器怎么办？..........................................................................................397.2集成连接器导入时，缺jar包..........................................................................................................397.3集成方案执行API授权错误.............................................................................................................407.4集成方案执行报连接配置错误........................................................................................................41附AD域常见错误码...........................................................................................................................................42用户手册4/43第一章概述1.1业务场景本文档描述了AD域和YonBIP集成场景，包括将YonBIP的组织、部门和人员数据同步到AD域系统，部门在AD域创建对应安全组，AD域离职人员移动至离职组。通过AD域和YonBIP集成资产包的实施可以快速实现YonBIP与AD域之间的组织、部门和人员数据的集成，帮助项目快速完成项目交付，降低和AD域的集成难度、成本。YonBIP和AD域的集成场景如下图所示：详细集成场景说明如下表所示：数据集成说明行政业务单元定时将BIP的行政业务单元同步新增或更新AD域组织数据。定时将BIP停用行政业务单元同步删除AD域组织数据部门定时将BIP的行政业务单元和部门同步新增或更新AD域组织数据定时将BIP停用行政业务单元或部门同步删除AD域组织数据员工定时将BIP的员工同步新增或更新AD域的用户数据定时将BIP离职、停用的员工同步至AD域离职组用户手册5/431.2关键词集成方案、连接器、混合云网关、安全组、删除组1.3专业名词术语混合云网关：指用于企业内服务与公网服务之间的通道；连接器：打通三方系统业务，提供封装好的认证，操作能力；集成方案：异构系统间的数据集成规则制定并生成执行任务；AD域系统：是由微软公司开发的一种网络服务目录服务，它为企业网络提供了一个集中管理和组织资源和用户信息的平台；安全组：AD域安全组是一种在活动目录(ActiveDirectory)中实现安全性的方法。它允许管理员将具有相似安全需求的用户或计算机组织在一起，并对它们赋予相同的权限；AD域连接器：AD域连接器是用友提供的一种技术解决方案，用于实现不同YonBIP与AD系统之间的快速对接和数据同步。AD&YonBIP集成资产包：AD&YonBIP集成资产包是一个专注于实现AD域与YonBIP系统间无缝集成的解决方案。通过此集成资产包，企业可以更加高效、安全地实现组织、部门、员工跨系统同步与交互，从而优化业务流程，提升工作效率，降低运营成本。用户手册6/43第二章集成资产包导入与配置2.1集成应用导入在用友YonBIP系统中的云平台>连接集成服务>数据集成>集成设计>集成方案设计界面，点击右上角“集成应用设计”按钮，将取得的集成应用包在该界面，左上角点击“导入”功能，完成集成应用的导入新建工作。2.2API授权进入“API调用”节点，点击“添加”按钮输入“授权KEY描述”，点击确定用户手册7/43点击“API授权”点击“新增API”，选择“开放API”，进行相关接口的授权需要授权接口如下：接口名称分类名称业务单元列表数据同步_集成数字化建模部门列表数据同步_集成数字化建模员工列表查询(简版人力)数字化建模员工详情查询数字化建模用户手册8/432.3BIP连接配置创建集成应用导入成功之后，需要进行连接配置后才能使用，操作步骤如下：1、在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击新建连接按钮>选择对应的连接器>填写基本配置信息>确认>测试连接，提示连接测试成功即可。选择用友YonBIP旗舰版连接器2、填写host、appkey、appsecret（用上面创建授权配置获取的appkey、appsecret）host:域名，根据部署环境填写（例如：https://bip-new18.yyuap.com）用户手册9/433、填写完毕后点击测试连接用户手册10/432.4AD域连接配置创建在用友YonBIP系统中的云平台>连接集成服务>集成实施工具>连接管理>连接配置界面，点击新建连接按钮>选择对应的连接器>填写基本配置信息>确认>测试连接，提示连接测试成功即可。具体创建步骤可参照BIP连接配置创建。用户手册11/43具体属性说明：表格属性名称说明编码定义连接配置编码名称定义连接配置名称集成系统根据实际情况选填，非必填AD域地址AD域地址，只填写IP或域名，ldap://或ldaps://不用填写。是否SSL认证是，SSL认证AD域地址需要填写域名。AD域端口设置AD域端口,SSL认证默认端口636，非SSL认证默认端口389AD域管理员账号设置AD域管理员账号AD域管理员密码设置AD域管理员密码域信息设置域信息用户身份创建默认密码是/否用户默认密码设置默认密码是否创建安全组是/否是否创建离职组是/否离职组名称设置默认离职组名称离职组分类默认、年月网关代理是否启用网关网关信息选择对应网关场景说明：1.当"用户身份创建默认密码"选择为"是"时，必须使用SSL认证。选择为"否"时是否使用SSL认证无限制。2.当"是否创建安全组"选择为"是"时，AD域新增部门后，部门下会新增部门同名的安全组。选择为"否"时，同步部门只会新增部门，不会创建对应安全组。3.当"是否创建离职组"选择为"是"时，必须设置离职组名称，名称按需求自定义。选择为"否"时，当BIP离职员工同步至AD域，用户会在当前组织下停用。4.离职组支持默认和年月两种分类，当设置为"默认"时，离职组下不再有其他目录，BIP离职员工同步至AD域，会将员工移动至离职组目录下，同时员工设置为停用。当设置为"年月"时，BIP离职员工同步至AD域，会将员工移动至离职组下的当前年、月组织下，若离职组下的不存在当前年月目录会自动创建，同时员工设置为停用。5.使用域名需要添加本地host域名解析，使用混合云网关需要在网关所在服务器添加本地用户手册12/43host，windows示例：打开C:\Windows\System32\drivers\etc下hosts文件，添加域名解析。2.5集成应用连接配置绑定来源系统和目标系统连接配置创建完成之后，点击集成应用的编辑按钮，将刚创建的连接配置选择上，连接器1和连接器2都需要选择对应的连接配置，进行保存即可。用户手册13/43第三章集成方案配置说明3.1BIP组织定时同步AD域⚫方案编码：bip_ad_org_sync⚫集成场景：定时将BIP组织同步到AD域来源系统和目标系统字段映射关系查询条件设置为：```{用户手册14/43"funcTypeCode":"adminorg",//行政组织"enable":1,//启用"dr":0//未删除}```AD域系统效果：用户手册15/433.2BIP组织停用同步AD域⚫方案编码：bip_ad_org_stop⚫集成场景：定时将BIP停用组织同步到AD域⚫前置任务：BIP部门停用同步AD域来源系统和目标系统字段映射关系：用户手册16/43查询条件设置为：```{"funcTypeCode":"adminorg",//行政组织"enable":2,//停用}```用户手册17/43AD域系统效果：AD域系统会删除相对于组织信息。依赖前置任务:需先执行BIP部门停用同步AD域数据同步任务。3.3BIP部门定时同步AD域⚫方案编码：bip_ad_dept_sync⚫集成场景：定时将BIP部门同步到AD域⚫前置任务：BIP组织定时同步AD域用户手册18/43组织类型orgType设置默认值2。查询条件设置为：```{"enable":1,//启用"dr":0//未删除}```用户手册19/43AD域系统效果：若连接配置选择了创建安全组，部门下同时创建同名的安全组。用户手册20/433.4BIP部门停用同步AD域⚫方案编码：bip_ad_dept_stop⚫集成场景：定时将BIP部门同步到AD域组织类型orgType设置默认值2。用户手册21/43查询条件设置为：```{"enable":2//停用}```用户手册22/43AD域系统效果：AD域系统会删除相对于部门信息，若存在安全组，会同时删除部门下安全组信息。3.5BIP员工同步AD域用户⚫方案编码：bip_ad_user_sync⚫集成场景：定时将BIP的员工同步到AD域用户用户手册23/43当连接配置"用户身份创建默认密码"选择为"是"时userAccountControl设置默认值为512，否则设置为66080。查询条件设置为：是否需要详情数据:true员工状态:1用户手册24/43AD域系统效果：部门下新增用户信息，若存在安全组，组下包含用户信息。安全组下用户信息：用户手册25/433.6BIP员工停用同步AD域用户⚫方案编码：bip_ad_user_stop⚫集成场景：定时将BIP停用员工同步到AD域用户用户手册26/43当连接配置"用户身份创建默认密码"选择为"是"时userAccountControl设置默认值为514，否则设置为66082。查询条件设置为：是否需要详情数据:true员工状态:2用户手册27/43AD域系统效果：1.连接配置未设置离职组时，用户在当前部门下变为停用状态。所属部门信息和安全组信息不变。用户手册28/432.当设置离职组，离职组分类为默认时，用户会从当前组织下移动至离职组，并解绑所属安全组。3.当设置离职组，离职组分类为年月时，用户会从当前组织下移动至当前年月组织下，并解绑所属安全组。用户手册29/43用户手册30/43第四章混合云网关配置混合云网关作为连接配置的选填参数，用于解决企业内服务与公网服务之间的链路通道，混合云网关将部署至本地内网中，用于打通云上云下的内外网穿透。注意：当企业内服务与公网服务网络不通的时候再进行混合云网关的创建与使用。4.1新建网关登录BIP系统，切换到对应租户，在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点点击“新建网关”。录入网关编码和网关名称，点击确定即可。刚创建完的网关默认为离线状态4.2下载网关客户端在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点找到我用户手册31/43们刚创建完的混合云网关，点击【下载终端】按钮，下载对应版本的网关客户端。这里以windows版本为例，下载的文件以及解压后的文件如下需要注意：⚫找一台7x24小时都能访问您企业内部系统，且能访问互联网的机器，安装网关客户端。⚫下载完成后解压，需保证解压后的文件目录不存在中文字符。4.3下载网关密钥每个网关需要有该网关的秘钥进行安全认证，在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点找到我们刚创建完的混合云网关，点击【下载密钥】按钮，下载指定网关的密钥。下载下来的密钥为gateway.config.json文件用户手册32/43将下载的密钥文件（gateway.config.json）移动至网关客户端解压目录的config文件夹下4.4启动本地网关客户端在网关客户端解压目录的bin文件夹，运行iuap-gateway-start.bat。Linux环境在网关客户端解压目录的bin文件夹，运行iuap-gateway-start.sh。双击iuap-gateway-start.bat脚本启动网关，控制台输入1回车。4.5验证网关是否启动成功脚本命令启动成功后，在【连接集成服务】->【集成实施共建】->【连接管理】->【混合云网关】节点找到我们刚创建完的混合云网关，点击【状态刷新】按钮，可以看到网关状用户手册33/43态显示为“在线”，这时我们的本地混合云网关就已经搭建成功了。4.6使用混合云网关当我们在创建连接配置的时候，勾选【启用混合云网关】，即可在【网关信息】属性下拉框中获取当前租户下可用的网关信息。用户手册34/43第五章数据同步任务配置说明集成方案生成的所有任务都将会在数据同步任务中进行管理，数据同步任务目录为云平台>连接集成服务>数据集成>集成任务>数据同步任务。集成方案分为定时任务和实时推送两种方式，实时推送方式的集成方案可以通过开放平台中的“数据同步任务-推送数据”接口进行调用，定时任务的集成方案可以通过立即执行和定时执行进行调用。5.1立即执行在数据同步任务列表上点击【立即执行】按钮，会弹出一个对话框，询问是否强制推送、是否根据时间段补录、是否根据增量时间戳进行查询来源系统数据。⚫强制推送：开启则会无视目标数据是否在数据详情中存在，直接调用目标系统保存接口；不开启则会先与数据详情列表中的数据进行比对，如果数据在数据详情中存在且所有字段值都一样则不进行推送，即不会调用目标系统保存接口，否则进行推送。⚫时间段补录：按照选择的时间段进行来源系统数据的查询，分为开始时间和结束时间，前提是来源系统接口支持根据时间段条件进行查询并且连接器操作打上标签。⚫增量时间戳：修改数据同步任务执行的开始时间，一般用在期初数据的同步，前提是来源系统接口支持根据时间段条件进行查询并且连接器操作打上标签。5.2定时执行点击【定时执行】按钮会弹出“设置时间表达式”弹窗，数据同步任务支持页面端配置用户手册35/43corn表达式的方式配置定时任务。定时任务支持按分钟、小时、日、月、年配置执行周期、执行频率，并生成对应的Corn表达式。定时任务定义完成后，弹窗下方会展示定时任务对应的Corn表达式和最近五次执行时间。用户手册36/43定时任务创建成功后，可在【定时执行列表】中展示已创建的定时任务。5.3停止运行中的任务可以通过点击【停止】按钮人为干预，终止任务执行。用户手册37/43注意：点击停止，任务不会立即停止，同步任务会在执行完本次分页同步后停止。用户手册38/43第六章注意事项6.1关于常量、默认值、直接映射使用说明1、常量配置必须配置来源，按照来源取值作为转换前映射转换后数据，需清除默认值。2、默认值使用必须清除来源字段，否则默认值不生效。6.2数据同步任务执行频率集成应用下的所有集成方案，定时执行的时间频率可根据项目需求自行选择6.3其它BIP的单据编号不允许超过32位，否则无法保存。用户手册39/43第七章常见问题7.1新建连接配置找不到连接器怎么办？在新建连接配置前需先进行连接器导入，然后再选择连接器进行连接器连接配置。7.2集成连接器导入时，缺jar包如遇到提示缺jar包，需先更新仓库，操作如下图：用户手册40/43仓库地址：https://pan.yonyou.com/s/yOpbN2jWRSw7.3集成方案执行API授权错误```API调用提示{"code":"310037"，"message":"API未被授权:APPKEY[acc4be8db3554b79bf92fc7aa01ee68a]末获得要调用的APl[/yonbip/digitalModel/iuap-apcom-bipuser/lUserldentityService/addldentityByUserldAndUserType]的授权”，"data":null}```请去API调用进行API授权，操作如下：用户手册41/437.4集成方案执行报连接配置错误```{"code":"200","data":{"status":3,"data":null,"error_code":"GWAPI10041","msg":"SICommonException:连接配置数据为空，请检查。"}}```请检查连接器及集成应用连接配置，如图所示：用户手册42/43附AD域常见错误码例:```[LDAP:errorcode19-********```错误码说明2协议错误7认证方法未被支持8需要强认证11超出管理员权限12Critical扩展无效14需要SASL绑定16未找到该属性17未定义的属性类型19约束冲突，字段定义超长20属性或值已存在21无效的属性语法32未找到该对象33别名有问题34无效的DN语法49无效的Credential50访问权限不够64命名冲突，字段定义超长66不允许在非叶结点执行此操作68Entry已存在
