基于事件表的增量事件同步,可以对 DHR 中发生的事件进行顺序处理,可以达到近实时的处理速度。

下游应该使用一个游标记录当前处理至的事件表ID,然后根据当前记录的游标来不断轮询事件表中的新事件,分页取出这些新事件,并依次进行针对性处理,然后更新最新的游标记录用于下次轮询。如果处理失败,下游应该将游标停留在当前事件上,直到问题解决后,才继续执行事件表中的下一个事件,以此保证上下游系统的数据一致性。

每次轮询的间隔可以根据下游对数据实时性要求调整为每隔 1 分钟甚至更长。

获取异步事件列表

请求地址 /api/ext/eventTable/list
返回格式 JSON
content-type application/json
请求方式 GET
请求参数 QUERY 参数
请求举例 请求示例:/api/ext/eventTable/list?sinceId=566565&limit=100
返回值 事件对象数组
调用说明 调用者通过指定sinceId参数,获取指定事件ID后的事件列表,并将sinceId指定为事件列表最后一条事件的“事件表记录ID”字段进行下一次调用。注意:对于第一次调用该方法的时候不知道sinceId参数,可以到系统的【系统运维】->【事件表监控】中查找第一次接入的时间点的事件ID。

该接口一次最多返回200条事件数据,推荐一次拉取 20~50 条数据进行处理。

参数 类型 说明 举例 必选
since int [已弃用]某个时间点(number of milliseconds since 1970-01-01 00:00:00 GMT) 0 No
sinceId long 获取指定事件ID后的事件 No
limit int 最大数据条数, 默认为50 200 No

事件对象结构

属性 类型 说明
id long 事件表记录ID
eventId String 事件ID,具有唯一性
eventType String 事件类型
occurredOn long 事件发生时间
bizKey String 事件关联的业务主键
eventBody Map 事件的详细信息,不同的事件类型,事件的详细信息结构不一样,详细见事件说明

下游系统的数据对齐以及幂等操作

为了双方系统集成的稳定可靠与健壮,下游应该将 新建更新 两个动作包装到一个 幂等 方法中,即:存在子集数据映射即更新,不存在映射即新建。

为双方系统的数据子集建立映射关系通常有两种做法:

  1. 使用上下游系统子集内容值相同的共有唯一字段直接映射对应关系:如双方系统中的员工工号、手机号等唯一字段。前提是字段不会被变更(DHR 系统允许变更员工工号),否则需要处理变更的情况。
  2. 下游建立子集映射表,将上游 DHR 系统的子集业务主键与下游系统子集业务主键(xxx_id)做关联,维护映射表。

2) 下游系统的员工子集映射表字段示例:

employee_id dhr_employee_id
xxxxx xxxxx

常见数据子集需要监听的事件内容

组织子集

DHR 组织 子集的业务主键字段名称为 no,与其他子集发生业务时一般常见为 orgNoorganizationNodepartmentNodeptNo

在 DHR 系统中,部门成本中心区域子集均属于组织类型。若下游系统仅需处理部门相关的组织事件,可通过监听以下事件中的 orgType 字段进行筛选。具体实现时,通过检查 orgType.equals("Supervisory") 条件(其中 "Supervisory"部门这一组织类型的常量标识),即可确保只处理与部门子集相关的事件,不关心成本中心、区域等。

要监听的事件描述 对应要监听的事件类型(eventType) 下游需要做的动作
组织信息变更生效 HRM.MasterData.Organization.Update.TakeEffect 创建或更新组织(幂等)
组织封存生效 HRM.MasterData.Organization.Disable.TakeEffect 删除(封存)组织
组织解封生效 HRM.MasterData.Organization.Enable.TakeEffect 创建或更新组织(幂等)
组织移动生效 HRM.MasterData.Organization.Move.TakeEffect 创建或更新组织(幂等)
新增组织生效 HRM.MasterData.Organization.New.TakeEffect 创建或更新组织(幂等)
组织作废删除事件 HRM.MasterData.Organization.DELETED 删除(封存)组织
业务角色分配生效(需要同步组织负责人时) HRM.MasterData.Organization.RoleAssignment.TakeEffect 创建或更新组织(幂等)(同时更新组织负责人对应员工)
业务角色分配取消事件(需要同步组织负责人时) HRM.MasterData.Organization.RoleAssignment.Cancelled 创建或更新组织(幂等)(同时更新组织负责人对应员工)

员工子集

DHR 员工 子集的业务主键字段名称为 id,与其他子集发生业务时一般常见为 employeeIdownerId

要监听的事件描述 对应要监听的事件类型(eventType) 下游需要做的动作
员工入职 Masterdata.Employee.Onboard 创建或更新员工(幂等)
员工信息更新 HRM.MasterData.Employee.UPDATED 创建或更新员工(幂等)
员工试用期转正生效 Masterdata.Employee.BecomeRegular 创建或更新员工(幂等)
员工任职信息(包括主岗和兼岗)生效 Masterdata.JobInfo.TakeEffect 创建或更新员工(幂等)
离职生效 Masterdata.Employee.QuitEffective 删除(禁用)员工
创建员工 HRM.MasterData.Employee.CREATED 创建或更新员工(幂等)
员工关键信息变更 Masterdata.Employee.KeyInfoChanged 创建或更新员工(幂等)
员工任职信息(包括主岗和兼岗)调整生效事件(需要支持时间线特性时) Masterdata.Employee.JobInfoAdjust.TakeEffect 创建或更新员工(幂等)
添加家庭成员(需要同步家庭成员时) HRM.MasterData.FamilyMember.CREATED 创建或更新员工相关信息(幂等)
更新家庭成员(需要同步家庭成员时) HRM.MasterData.FamilyMember.UPDATED 创建或更新员工相关信息(幂等)
删除家庭成员(需要同步家庭成员时) HRM.MasterData.FamilyMember.DELETED 创建或更新员工相关信息(幂等)
添加银行账户(需要同步银行账户时) HRM.MasterData.BankCard.CREATED 创建或更新员工相关信息(幂等)
更新银行账户(需要同步银行账户时) HRM.MasterData.BankCard.UPDATED 创建或更新员工相关信息(幂等)
删除银行账户(需要同步银行账户时) HRM.MasterData.BankCard.DELETED 创建或更新员工相关信息(幂等)
作者:稳赢云  创建时间:2023-03-10 10:32
最后编辑:Ash Yang  更新时间:2025-05-21 10:22