查询金蝶员工策略实战教程:用轻易云把员工主数据从金蝶云星空搬到泛微OA

这个策略解决什么问题

某制造业客户做供应链集成时,泛微OA里的报销、合同、流程发起都要带「员工档案」。但员工主数据其实住在金蝶云星空——部门、岗位、离职状态都在那边维护。让 HR 在两套系统里维护同一份档案,3 个月后必然对不上。「查询金蝶员工」这条策略,就是把金蝶里的员工档案按需拉到泛微OA里,做到一处维护、多处可用。

数据流向与字段映射

整条链路是单向查询:金蝶云星空 → 轻易云中间层 → 泛微OA-E9Http。源端用金蝶的 executeBillQuery WebAPI 把员工表按条件捞出来,目标端在轻易云这一侧用「写入空操作」承接,真正的写入由泛微侧的编排脚本消费结果集去完成。

关键字段对照:

这里特别要说一下:FID 是金蝶系统内的内码,FStaffNumber 才是 HR 真正在用的「员工编码」。轻易云默认用 FName 做 number 字段做幂等键,但姓名是会改的,稳妥的做法是把 number 切到 FStaffNumber,否则同名员工会被合并,典型错误就在这里。

在轻易云上如何配置

进入轻易云数据集成平台的策略编辑界面,这条策略的典型配置要点有 4 个:

1. 源端平台:选 Kingdee.Cloud(代码即平台标识),API 选 executeBillQuery,effect 设为 QUERY,方法 POST。
2. 请求体:把 FNumber、FID、FName、FStaffNumber 加到 request 字段列表里,作为返回值。Limit 放进 otherRequest,由轻易云自动用分页参数填充。
3. 目标端:选轻易云自己的 datahub 平台,API 用「写入空操作」(effect = EXECUTE,method = POST,request/response 都留空)。它的作用是占位 + 落盘原始结果,供下游脚本或泛微侧编排读取。
4. 调度:crontab 写成 */7 7-23 * * *,意思是白天 7 点到 23 点,每 7 分钟跑一次。目标端的 crontab 写成 1 1 1 1 1,代表永不主动触发,完全由源端拉取后被动落盘。

轻易云的「表头表体分阶段」模式在这里特别顺手——员工类基础资料没有表体,所以源端只配一个扁平 request,目标端也只配空操作落盘,链路非常干净。

实施步骤

我们给客户做这条策略时,通常分三步走:

**第一步,跑通增量起点。**先在轻易云里手动触发一次,只拉 1 条员工记录,确认 FStaffNumber 能在泛微侧被正确识别为业务主键。这一步如果在测试环境能稳定复现,后面全量才敢放手。

**第二步,触发全量初始化。**把分页 Limit 调到平台建议值(轻易云里用 {{PAGINATION_PAGE_SIZE}} 占位即可),触发一次全量同步,把历史员工一次性灌进泛微。全量跑完后,务必抽 5 条记录做双向核对——金蝶侧 FStaffNumber 能在泛微里查到、且姓名、状态一致。

**第三步,转入增量调度。**把 crontab 切到 */7 7-23 * * *,轻易云平台会按这个节奏自动跑。白天高频、夜里停摆,是基础资料类同步常见的「办公时段增量」节奏。如果客户有跨国子公司,再单独加一条夜间跑的策略做时区覆盖。

踩坑复盘

1. 幂等键选错字段。默认用 FName 做 number,同名员工会被合并。稳妥的做法是显式把 number 切到 FStaffNumber。
2. 分页参数写死。直接在请求体里写一个数字,后面一旦金蝶数据量上来就翻车。用 {{PAGINATION_PAGE_SIZE}} 让轻易云自动注入。
3. 目标端 crontab 也设了调度。源端已经按 */7 拉了,目标端再设调度会重复落盘,白白吃资源。这里目标端 1 1 1 1 1 才是正确写法。
4. idCheck 误开。目标端 idCheck: true 但 id 字段是 0,校验永远过不去。基础资料同步类策略,目标端 idCheck 建议关闭。
5. 私有化部署忘记开白名单。客户是私有化部署,轻易云调度器访问金蝶云星空的 IP 没加白名单,导致 executeBillQuery 一直 403。这里容易翻车,稳妥的做法是上线第一天就跟客户 IT 把 IP 段对齐。

适用场景与不适用场景

适用:HR 员工档案、岗位、部门等基础资料,从金蝶云星空单向同步到泛微OA、流程系统或者 BI;白天办公时段增量、晚上停摆的低频同步链路。

不适用:实时工时类高频写入(7 分钟一次太慢);需要双向同步的员工状态(轻易云在这条策略里只做了 QUERY,不支持回写);员工照片、附件等二进制大字段(executeBillQuery 不适合,得换附件专用 API)。