同步工具部署及操作指引

1、部署方式及版本更新说明

部署说明

部署方式：8.2版本支持补丁部署，8.2以下版本仅提供私包部署。

EAS V8.2版本最新补丁：PT159287(2021/06/08日发放)

EAS V8.5版本最新补丁：PT159362（2021/07/15日发放）

EAS Cloud V8.6.1版本最新补丁：PTM160880(2021/08/28日发放)

8.1/8.0版本最新私包

补丁部署方式具体步骤

1、下载补丁

2、在管理控制台安装补丁，并重启服务。

私包部署方式具体步骤

1、在管理控制台执行脚本bs_xtsync_create_table.sql

2、按照eas文件夹目录结构部署文件到服务器（把对应路径下的文件替换为最新），重启服务。

注意：如果之前有部署同步工具的私包，现需要打同步工具的补丁，则需要先将\eas\server\lib\sp 目录下的sp-base_xtsync-server.jar和 \eas\server\metas\sp目录下的 sp-base_xt_metas.jar 两个架包删除后，再执行补丁部署方式。如未删除架包，直接部署补丁，会导致同步工具部分功能不可用。

补丁更新说明

同步工具补丁PT119872，其前置补丁PT120449

组织部分
1、同步工具同步组织调用接口时，按照先更名，再挪动，再更新排序，再删除，最后新增的顺序进行调用。主要修复组织挪动后，层级显示不对的问题。

人员部分
1、人员排序功能增强，按照SHR中人员的排序逻辑进行排序。
2、人员离职后自动清理上下级汇报关系。
3、同步工具调用云之家新的新增部门负责人接口，按组织ID新增部门负责人。
4、同步工具调用云之家新的删除部门负责人接口，按组织ID删除部门负责人。
5、同步工具调用云之家新的新增员工接口，新增员工时，不新增组织。
6、人员信息显示XTID字段。
7、人员绑定按照手机或者邮箱加姓名进行绑定。
8、用户邮箱为空时，取职员邮箱同步。
9、离职人员绑定关系不做再次重新绑定。
10、同步工具调用新增员工接口前检查中间表，如果云之家存在相同手机号，
且该手机号绑定在其它员工上，且员工为在职状态，则不调用新增接口，且给予错误提示“云之家上该手机号已被其他人员使用”
11、修复修改手机号不成功但日志显示成功的问题。同步工具将原来按照手机号联查日志更改为通过OPENID来联查日志。

其他
1、防止测试账套往云之家工作圈同步数据，上传key的时候，保存key、数据中心编码。
2、同步工具日志列表按照时间逆序排序，便于问题排查

补丁PT117697，10月27日

1、上级同步可配置只同步直接行政上级，或者包含兼职所对应上级

2、新增企业工号同步(注意：如系统中存在一个职员对应多个用户的情况，建议通过自定义方式同步工号）

3、修复离职人员重返后不能同步的问题（比如删除用户或者职员后重新恢复的）

4、更新手机号时，增加时间判断，如：eas修改时间晚于云之家，以最新修改的手机为准

5、增加手工绑定EAS数据和云之家数据功能。

补丁PT116256，09月1日

1、支持更新组织排序、支持人员排序。

2、修改更新手机号逻辑。

支持从云之家修改手机号后同步到EAS，也支持从EAS上修改手机号后同步到云之家。如云之家和EAS上手机号同时有修改，最终会以云之家手机号为准，同时修改 EAS中职员及用户的手机号，如有启用SHR还会修改SHR中的手机号及联系方式。

虽然目前可以说实现了手机号的双向同步，由于手机号对云之家而言具有登录及认证意义，但在此建议大家修改手机号最好通过云之家进行修改和校验。

对于集团的手机号，员工离职后，手机会交给其他新入职人员使用。对于不同人员使用同一个手机号的情况，云之家管理中心有一个注销手机的功能，可以注销本团队的手机号，注销时需验证短信，注销后新入职人员就可以重新使用该手机了。如果不使用手机注销的功能，那么使用该手机号的人员在云之家中显示的信息会还是上一个人员的。

3、支持自定义人员信息更新。

支持云之家上没有显示的人员信息的同步更新。需要写SQL语句实现。

4、支持查看每次的同步记录

显示每次同步后的具体结果。

5、支持删除云之家全部部门负责人、兼职、上级

便于历史数据或垃圾数据的清理。

6、修改自动事务同步报错的问题。

7、使用s-HR8.2SP2及以上版本客户特殊说明 参见文档 按照用工关系状态定义同步至云之家的员工.docx

使用s-HR8.2SP2及以上版本客户，可以根据企业实际需求定义用工关系状态对应的人员状态，进而控制哪类用工关系状态的员工同步至云之家（人员状态为在职、返聘员工的将同步云之家，其它状态不同步）

对应补丁号：PT116190（注意，依赖于8.2SP2 PTM112673）

06月15日（new）

1、修正手机号码返回消息不正确的错误。

所有版本必须使用谷歌浏览器。

8.2版本 补丁PT113597  05月10日（new）

增强数据查看的数据问题分析能力

1、数据查看页面提供组织、人员的状态查看，快速定位数据问题。

2、提供日志查看页面；

3、提供组织、人员数据导出功能；

4、提供中间表数据操作功能：删除、插入离职人员。

2、同步工具菜单配置及同步环境设置

同步工具菜单配置说明

1. 所有版本同步工具必须使用谷歌浏览器访问。

2. 仅administrator有权操作同步工具。

3. 701/703/7.5版本必须购买企业门户才能使用，否则不支持使用同步工具。

1) 701/703版本登录界面会出现错版，但是能够使用，不用担心。701/703版本先

使用登录地址登录，然后把地址改为“IP：端口/easweb/base/xtsync/syncCenter.jsp”

4. 7.5版本以上的链接地址配置：

1) 未购买企业门户模块：只能通过直接访问网址IP：端口号/easweb/base/xtsync/syncCenter.jsp，进入后可根据指引文档操作。

2) 有购买企业门户门户模块：可以通过顶部链接和菜单链接打开云之家同步工具

3) 8.1、8.0、7.5版本需要自行配置顶部链接菜单，配置指南如下：

在门户管理的顶部链接配置中增加同步工具菜单，配置链接地址“/easweb/base/xtsync/syncCenter.jsp”，选择新窗口打开。或者使用网址“IP：端口号/easweb/base/xtsync/syncCenter.jsp”直接打开。

4) 8.2版本购买企业门户管理的产品，都可以通过顶部链接和菜单链接打开云之家同步工具

5） 8.5及以上版本，云之家同步工具免费使用，不再受门户管理模块许可控制。

设置同步环境

参数设置

1. 设置云之家地址：系统已默认设置云之家公有云地址；云之家私有云需根据客户的云之家部署环境自行设置。

2. 设置同步环境：当企业注册号为空时，系统会根据产品license自动获取对应企业的工作圈；若企业已有云之家工作圈，可手工修改企业注册号，并上传KEY文件。

特别提醒：若变更企业注册号，系统将进行初始化，初始化后会清除EAS组织、用户与云之家所有的关联关系和同步记录。系统提供手工初始化环境功能，谨慎使用。登录的哪个账套，key就绑定了哪个账套；同步环境是数据库隔离的。

3. 设置同步项目：系统已默认设置需要同步项目。用户也可根据自己的需求调整同步项目。

勾选需要上传云之家的同步项目，则下次同步时，会增加该项目涉及数据的上传。

同步工具目前能支持的功能如下：

组织：新增组织、更新组织名称、删除组织、组织挪动、更新组织排序

人员：新增人员、删除人员、仅同步关联用户的职员、从EAS更新手机到云之家、更新人员组织、更新人员姓名、更新人员编码（企业工号）、更新人员性别、更新人员职位、更新人员排序、更新人员生日、更新人员入职日期、自定义人员信息。

支持部门负责人、兼职、上级同步。

支持从云之家更新EAS手机。

特别提示：增加同步项目后，建议使用一次全量同步。

特别注意：

1、 若之前有使用旧同步工具，请先把旧工具的文件清理掉，需要替换的可不用管；若配置后台事务，也必须删除掉；

3、同步原理及同步数据准备

同步原理简述

首先将EAS数据创建到中间表（映射关系）中，扫描并标识数据是否可同步，然后中间表再上传数据到云之家，同时将云之家的数据拉取到中间表（云之家数据），通过组织、人员的映射关系进行EAS数据和云之家数据的绑定。同步结论更新至中间表日志中。

这里同步工具的定义是：将符合要求的EAS组织和人员数据同步到云之家

注意及说明：

• 是EAS单向同步到云之家，并非双向的同步 。只有手机号目前是有条件的支持双向同步。            

• 能同步的数据有前提条件限制。            

• EAS和云之家数据并非100%一致。

已支持的同步功能和不支持的同步功能

数据准备

怎样的数据可以同步？

1、组织同步

前提条件：EAS组织必须是行政组织，才能与云之家同步。

新增组织：EAS组织是正常状态。上传数据为组织长名称，云之家会按照上传的组织长名称的层级，建立云之家的多级组织。

删除组织：EAS组织是封存状态，且已与云之家组织映射。

映射关系：EAS组织长名称与云之家一致。（若组织未绑定，会导致后续人员、部门负责人等接口出现问题，必须优先解决）

2、人员同步

前提条件：必须是有职位的职员，才能与云之家同步。

新增人员：

• 状态为正常、试用、返聘员工（职员表t_bd_person的FEmployeeTypeID对应T_HR_BDEmployeeType表中的FinService等于1或者4）；

•  关联用户的职员：职员未禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =1） 、用户未删除（EAS用户表T_PM_USER中用户删除FIsDelete = 0）；

• 未关联用户的职员：职员未禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =1）。

• 手机或者邮箱正常。（不为空，不重复）

• 与云之家未绑定。（T_PM_EASXTUSERMAP中FXtId为空）

必须满足以上所有条件才能上传云之家。

映射关系：EAS人员与云之家人员的手机号及姓名一致，则建立映射关系。（若人员未绑定，会导致后续上级、兼职等接口出现问题，必须优先解决）

无关联用户的职员或者一个职员对应一个用户的情况，EAS职员只对应一个云之家用户；若一个职员关联了N个用户，EAS职员对应生成N个云之家用户，需特别注意。手机号码获取规则如下：

手机号码获取规则变化：有关联用户的职员，优先从用户获取手机,用户手机为空则获取职员手机；无关联用户的职员，获取职员手机。

修改手机号码建议直接修改用户的手机。

注意：由于目前接口不支持邮箱更新，如需要在云之家中显示邮箱字段，建议在同步前，维护好用户的邮箱，否则后续邮箱无法再同步到云之家。

删除人员：

前提条件已与云之家绑定（T_PM_EASXTUSERMAP中FXtId不为空）

• 状态不是正常、试用、返聘员工（职员表t_bd_person的FEmployeeTypeID对应T_HR_BDEmployeeType表中的FinService不等于1和4）；

• 职员禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =2） 

• 用户删除（EAS用户表T_PM_USER中用户删除FIsDelete =1）。

满足以上3个条件任意其一，则删除云之家人员。（T_PM_EASXTUSERMAP的同步状态设置为离职，Fstatus=0）

历史数据处理

首先按照下面步骤操作，然后再根据下面内容具体分析出现的问题。

A. 若之前有使用旧同步工具，请先把旧工具的文件从对应路径下删除掉（删除旧文件参考旧同步工具包中的部署文档）；

若配置后台事务，也需要在后台事务删除掉：

a、进入系统平台->后台事务->后台事务定义

找到同步任务，找到任务为oneKeyBinding的同步事项删除掉。

b、进入系统平台->后台事务->后台事务定义表，找到对应任务，把任务禁用。

B. 历史留存的数据，会影响到人员新增、离职等。可在安装新补丁包后，执行以下语句：

删除人员中间表 DELETE FROM T_PM_EASXTUSERMAP

删除组织中间表 DELETE FROM T_PM_EASXTORGMAP

C. 若云之家的组织存在问题或云之家遗留了大量的离职人员，建议在云之家执行组织初始化。

4、在数据同步页面点击全量同步。（若数据量比较大，可执行一次数据更新，提前预加载数据，提升执行效率。）+

4、具体操作指引及功能说明

数据准备好以后，就可进行同步了。数据同步前建议先做异常数据扫描操作。

异常数据扫描

首先系统提供不合规数据的校验：1、无手机号码且无邮箱；2、手机号码重复；3、邮箱重复。此3类人员数据都不上传到云之家。

可以查看及导出具体的数据

其次，组织不支持下划线格式和斜杠格式的组织名称上传，例如“aaa_bbbb”、“aaa\bbbb”。这种名称，上传时同步工具会截断名称，导致出错。

数据同步

点击全量同步（或快速同步），即可完成EAS数据同步至云之家。

同步完成后，可以查看同步情况。

在同步记录中，可查看成功及失败日志

新增人员成功日志

新增人员失败日志

注：

1、全量同步：会下载云之家全量的数据与EAS信息进行对比；上传完成后，会下载更新后的云之家全量数据。

2、增量同步：以上次同步时间为起点，只会下载该时间点之后更新过的云之家组织、人员数据与EAS信息进行对比；上传完成后，也之后下载本次同步时间之后云之家更新的数据。

具体功能说明

1. 数据查看功能介绍

a. EAS本地组织信息与云之家组织信息对比

b. 中间表显示的人员信息

c. EAS人员信息与云之家人员信息对比

EAS与云之家不一致的信息会有颜色标识。目前只支持姓名、手机、邮箱、工号、部门、职位、状态、性别、上级姓名、上级、兼职职位的对比。

2. 组织状态查看

查看组织的绑定状态和异常分析。

3. 人员状态查看

显示人员的职员、用户状态：

A．在职状态（中间表）：为中间表中已存在的静态在职状态；在职状态（实时）：根据HR状态、职员禁用、用户删除等状态实时计算员工的动态在职状态。

在职判断：

• 状态为正常、试用、返聘员工（职员表t_bd_person的FEmployeeTypeID对应T_HR_BDEmployeeType表中的FinService等于1或者4）；

• 关联用户的职员：职员未禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =1） 、用户未删除（EAS用户表T_PM_USER中用户删除FIsDelete = 0）；

• 未关联用户的职员：职员未禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =1）。

必须满足以上所有条件才为在职。

离职判断：

• 状态不是正常、试用、返聘员工（职员表t_bd_person的FEmployeeTypeID对应T_HR_BDEmployeeType表中的FinService不等于1和4）；

• 职员禁用（T_BD_Person中职员禁用状态FDELETEDSTATUS =2）

• 用户删除（EAS用户表T_PM_USER中用户删除FIsDelete =1）。

满足以上3个条件任意其一，则为离职。

B．员工的手机、邮箱所取值，在字段后通过“√”标识为职员手机或用户手机。

4. 导出数据：导出全部组织、导出全部人员、导出未绑定组织、导出未绑定人员

注：导出的数据为人员数据，岗位为主岗位数据。数据查看界面中人员因为同时显示了兼职数据，数量会有不同。

组织数据：可查看组织相关的信息。

人员数据：可查看人员相关的信息。

5. 查看日志：组织、人员、负责人、兼职、上级

可按照不同的同步类型、同步时间、成功状态等过滤数据。可导出查询的数据，以便线下分析。

6. 查看日志：云之家组织、云之家人员、云之家手机修改记录

可查看EAS下载的云之家组织、人员及手机修改记录。

7. 同步控制：人员、组织设为不可同步、设为可同步

手工控制人员、组织是否上传。人员按照职员来控制，若一个职员有多个用户，则选择一个用户为不上传，则会修改该职员对应所有的用户本次同步不做新增、更新。

8. 数据更新

预加载中间表数据，下载最新云之家数据，建立绑定关系。在点击快速同步时，可提升数据同步的速度。

如果EAS不做为数据源上传云之家，又想建立与云之家的绑定关系，可只执行数据更新功能。

9. 离职人员插入中间表

如果云之家上有离职人员的数据，但是本地又没有绑定关系。为了删除云之家上已离职的人员，需要先执行该功能“离职人员插入中间表”，会把离职人员增加入中间表，并绑定云之家上已有人员的openID，再执行快速同步，即会调用删除人员项目，删除云之家多出的人员。

10. 删除中间表人员

若数据发生错误时，需对某个人的数据进行初始化操作，可使用该功能，把该人从中间表删除掉。下次执行同步时，会重新新增人员至中间表。

11. 删除云之家全部负责人、云之家兼职、云之家上级

若数据发生错误时，需要删除云之家的数据，可使用该功能。

12. 显示中间表不存在人员

勾选后，可显示不在中间表中的人员，可查看已离职人员的信息。

注：数据查看页面只显示了正常的行政组织。封存的组织查看可以通过导出全部组织查看。

13. 异常情况手工绑定

为便于管理员操作，在有异常数据且无法确定数据异常原因的情况下，比如一条EAS数据对应了两条云之家数据时，无法通过同步工具进行绑定时，可通过此功能选择具体的数据建立绑定关系。

选择一条数据记录，点击异常情况手工绑定，会过滤出与当前选择数据的姓名或手机号或邮箱号相同的云之家数据，管理员选择其中一条数据手工建立绑定关系。

14. 后台事务（自动同步配置）

数据未稳定前，不建议配置自动同步事务。8.2后台事务尤其要注意与云平台同步之间影响，见第二章节。

同步后台事务的配置前提：

1、同步的异常数据（重复上传、数据出现错误等现象）已经全部处理；

2、手工同步多次后，数据传递稳定无异常。

系统平台-->后台事务-->事务定义-->后台事务定义表

EAS 8.2以下版本需要自己配置后台事物，操作方法如下：

1、找到 \eas\server\properties\SubSystem_bos.xml

2、在该位置增加：<row fullname="com.kingdee.eas.base.xtsync" name="xtsync" alias_l1="xtsync" alias_l2="云之家同步" alias_l3="云之家同步" isleaf="1" parent="com.kingdee.eas.base.user" />

系统平台-->后台事务-->事务定义-->后台事务定义表

5、高阶：常见问题及数据排查

根据同步结果，处理历史数据带来的影响，经常出现的情况如下：

组织同步问题（组织一定要绑定成功，不然会影响人员数据同步）：

1） 新增组织项目中，总是出现组织未绑定的同步记录。从页面看，云之家和EAS组织名称是一样的。

解决方法：EAS组织名称创建时，多建了一个空格，导致跟云之家的组织名称不一致，无法绑定成功，需要把多出空格的组织名称修改正确。

2） 组织不支持下划线格式和斜杠格式的组织名称上传，例如“aaa_bbbb”、“aaa\bbbb”。这种名称，上传时同步工具会截断名称，导致出错。

3） 其他问题，请看论坛中的案例分析。

人员同步问题（正常人员一定要绑定成功，不然会影响部门负责人、兼职、上级等接口同步）：

1） 检查HR的用工状态是否符合同步规则：

select h.FINSERVICE ,h.*  from T_HR_BDEmployeeType h

需上传用工状态类型必须为1或者4.

2） 在云之家管理中心页面，未分配中存在大量人员，需要处理：

a、 剩余的人员多为离职或更换过手机号码的人员，可全部删除。

b、 处理完成后，再执行一次全量同步，未分配中不会再有人员。

3） 新增人员中，总是出现未绑定的人员。

解决方法：在云之家管理中心页面，对应的组织下查找该人员，与EAS的手机、邮箱对比。

人员绑定的逻辑是：优先对比手机号码，若一致则绑定。若手机号码为空，则对比邮箱，邮箱一致则绑定。

经常出现的现象有：

1、云之家中的人员只有邮箱，但EAS人员有手机、邮箱。

原因：之前只有邮箱的时候就上传了，补齐EAS手机，但是再上传更新不了手机。

操作方法：删除云之家的人员，去掉EAS人员的邮箱，再上传。

2、对应组织下有该人，但从云之家获取的手机不一致。

原因：EAS手机成了该人员的副账号。下载时只会获取主账号，导致无法绑定。

操作方法：找云之家支持人员解决。或者云之家中把主账号改为该手机，再同步即可。

3、新增人员出现失败的数据。

操作方法：在同步日志中，都有原因说明。若手机号码不规范，则修改手机号码；邮箱不规范修改邮箱。有种特别现象，是手机末尾多出一空格，看着一样，其实已经是12位。这个要修改。

4） 更新人员辅助信息总是在重复上传。

原因：更新的信息，云之家未更新修改时间。

操作方法：在数据查看页面，执行数据更新操作，再执行快速同步就不会出现了。

5） 更新人员组织总是在重复上传。

操作方法：组织上传有问题，需先解决组织上传问题。

6） 其他问题，请持续关注论坛更新。

作者：王水泉

来源：金蝶云社区

原文链接：https://wenku.my7c.com/article/234636851871676160?productLineId=8&isKnowledge=2

著作权归作者所有。未经允许禁止转载，如需转载请联系作者获得授权。