组织架构同步
概述
本文档介绍第三方系统如何与数字底座的组织架构进行同步。
数字底座中有 组织机构(Organizaiton)
、部门(Department)
、人员(Person)
、岗位(Position)
、用户组(Group)
等组织架构实体。
其中组织机构作为顶层实体 ,部门、人员、岗位、用户组可以作为组织机构或部门的子节点。 人员和岗位、用户组和人员之间可以有多对多的关系。
第三方系统可以根据自己的实际需求选择同步部分或全部实体。通常大多系统只需要同步部门、人员。
步骤
接入数字底座的组织架构同步第一次可以进行全量同步,之后可以隔一段时间进行一次增量同步。
全量同步
根据概述中所述,使用接口 1查询组织机构列表,可使用接口 2 查询组织机构下的部门列表,接口 3 查询组织机构下的人员列表,接口 4 查询组织机构下的岗位列表,接口 5查询组织机构下的用户组列表,之后再递归查询子部门的子节点列表直到无子节点。
增量同步
增量同步是以实体事件重放的方式实现增量同步,使用接口 6 查询实体事件,根据相应的事件类型和事件实体做相应的操作。
接口
1. 查询组织机构列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/organization/list
请求方法:GET
描述:根据租户id获取组织机构列表(不包含禁用)
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
tenantId | string | true | 租户 id | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的组织机构列表, 组织机构对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/organization/list?tenantId=11111111-1111-1111-1111-111111111113
响应示例:
{
"success": true,
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "1666895850843480064",
"parentId": null,
"tenantId": "",
"createTime": "2024-06-04 10:09:00",
"updateTime": "2024-12-11 07:42:24",
"disabled": false,
"description": "",
"customId": "",
"dn": "o=组织",
"name": "组织",
"orgType": "Organization",
"properties": null,
"tabIndex": 3,
"guidPath": "1666895850843480064",
"enName": "",
"organizationCode": "",
"organizationType": "",
"virtual": false
}
]
}
2. 根据父节点 id 查询下一级部门列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/department/listByParentId
请求方法:GET
描述:获取下一级部门列表(不包含禁用)
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
tenantId | string | true | 租户 id | - |
parentId | string | true | 父节点唯一标识(组织机构 id 或 部门 id) | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的部门列表, 部门对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/department/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064
响应示例:
{
"success": true,
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "1735712741608464384",
"parentId": "1666895850843480064",
"tenantId": "",
"createTime": "2024-12-11 07:42:46",
"updateTime": "2025-06-06 02:17:25",
"disabled": false,
"description": "",
"customId": "",
"dn": "ou=设计部,o=组织",
"name": "设计部",
"orgType": "Department",
"properties": null,
"tabIndex": 0,
"guidPath": "1666895850843480064,1735712741608464384",
"aliasName": "",
"deptGivenName": "",
"enName": "",
"gradeCode": null,
"divisionCode": "",
"deptAddress": "",
"deptOffice": "",
"deptFax": "",
"deptPhone": "",
"zipCode": "",
"establishDate": null,
"bureau": false
},
{
"id": "1735712810541850624",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-12-11 07:43:02",
"updateTime": "2025-06-06 02:17:25",
"disabled": false,
"description": "",
"customId": null,
"dn": "ou=运维部,o=组织",
"name": "运维部",
"orgType": "Department",
"properties": null,
"tabIndex": 2,
"guidPath": "1666895850843480064,1735712810541850624",
"aliasName": "",
"deptGivenName": "",
"enName": "",
"gradeCode": null,
"divisionCode": "",
"deptAddress": "",
"deptOffice": "",
"deptFax": "",
"deptPhone": "",
"zipCode": "",
"establishDate": null,
"bureau": false
}
]
}
3. 根据父节点 id 查询下一级人员列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/person/listByParentId
请求方法:GET
描述:获取下一级人员列表(不包含禁用)
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
tenantId | string | true | 租户 id | - |
parentId | string | true | 父节点唯一标识(组织机构 id 或 部门 id) | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的人员列表, 人员对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/person/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064
响应示例:
{
"success": true,
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "1666895850885423104",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-06-04 10:09:00",
"updateTime": "2025-06-06 02:17:25",
"disabled": false,
"description": "",
"customId": "",
"dn": "cn=业务用户,o=组织",
"name": "业务用户",
"orgType": "Person",
"properties": null,
"tabIndex": 3,
"guidPath": "1666895850843480064,1666895850885423104",
"loginName": "user",
"password": "$2a$10$73.IYgT5JicPuRxFeZxBnebujgsKbEMHYZL7av9KYsUrmRVkTzGby",
"avator": "/files/1785987326093914112.jpg",
"official": 1,
"officialType": "",
"duty": null,
"dutyLevel": null,
"dutyLevelName": null,
"caid": "111",
"email": null,
"sex": 1,
"province": null,
"officeAddress": "",
"officePhone": "",
"officeFax": "",
"mobile": "13511111111",
"personType": "deptPerson",
"weixinId": null,
"orderedPath": "00003,00003",
"original": true,
"originalId": null
},
{
"id": "1725571954663436288",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-11-13 08:06:54",
"updateTime": "2025-06-06 02:17:25",
"disabled": false,
"description": "",
"customId": "",
"dn": "cn=销售,o=组织",
"name": "销售",
"orgType": "Person",
"properties": null,
"tabIndex": 4,
"guidPath": "1666895850843480064,1725571954663436288",
"loginName": "saler",
"password": "$2a$10$mfX5sW8q44.b4gd3v9HPe.XplcnSLccyMAKfE8M7kfq0FU2mHBC5y",
"avator": null,
"official": 1,
"officialType": null,
"duty": null,
"dutyLevel": null,
"dutyLevelName": null,
"caid": "",
"email": null,
"sex": 1,
"province": null,
"officeAddress": "",
"officePhone": "",
"officeFax": "",
"mobile": "13111111111",
"personType": "deptPerson",
"weixinId": null,
"orderedPath": "00003,00004",
"original": true,
"originalId": null
}
]
}
4. 根据父节点 id 查询下一级岗位列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/position/listByParentId
请求方法:GET
描述:获取下一级岗位列表(不包含禁用)
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
tenantId | string | true | 租户 id | - |
parentId | string | true | 父节点唯一标识(组织机构 id 或 部门 id) | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的岗位列表, 岗位对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/position/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064
响应示例:
{
"success": true,
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "1666895851376156672",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-06-04 10:09:00",
"updateTime": "2025-06-06 02:18:31",
"disabled": false,
"description": "",
"customId": null,
"dn": "cn=普通职位(业务用户),o=组织",
"name": "普通职位(业务用户)",
"orgType": "Position",
"properties": null,
"tabIndex": 3,
"guidPath": "1666895850843480064,1666895851376156672",
"jobId": "1659608588908699648",
"orderedPath": "00003,00003",
"jobName": "普通职位"
},
{
"id": "1725571956383100928",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-11-13 08:06:54",
"updateTime": "2025-06-06 02:18:31",
"disabled": false,
"description": null,
"customId": null,
"dn": "cn=普通职位(销售),o=组织",
"name": "普通职位(销售)",
"orgType": "Position",
"properties": null,
"tabIndex": 4,
"guidPath": "1666895850843480064,1725571956383100928",
"jobId": "1659608588908699648",
"orderedPath": "00003,00004",
"jobName": "普通职位"
}
]
}
5. 根据父节点 id 查询下一级用户组列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/group/listByParentId
请求方法:GET
描述:获取下一级用户组列表(不包含禁用)
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
tenantId | string | true | 租户 id | - |
parentId | string | true | 父节点唯一标识(组织机构 id 或 部门 id) | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的用户组列表, 用户组对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/group/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064
响应示例:
{
"success": true,
"code": 0,
"msg": "操作成功",
"data": [
{
"id": "1738951430307127296",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2024-12-20 06:12:09",
"updateTime": "2025-06-06 02:17:25",
"disabled": false,
"description": "",
"customId": null,
"dn": "cn=用户组 55,o=组织",
"name": "用户组 55",
"orgType": "Group",
"properties": null,
"tabIndex": 7,
"guidPath": "1666895850843480064,1738951430307127296",
"type": "person"
}
]
}
6. 获取组织增量同步的实体事件列表
接口地址:http://{IP}:{PORT}/platform/services/rest/v1/orgSync/incrSync
请求方法:GET
描述:从上一次同步成功的时间后开始获取组织节点实体事件列表
请求参数:
参数名 | 参数类型 | 是否必须 | 描述 | 引入版本 |
---|---|---|---|---|
since | Date | true | 上次成功同步时间,日期格式为 yyyy-MM-dd HH:mm:ss | - |
tenantId | string | true | 租户 id | - |
响应字段:
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
success | boolean | 操作是否成功 | - |
code | int32 | 错误代码 | - |
msg | string | 操作描述 | - |
data | object | 操作成功返回的实体事件列表, 实体事件对象字段参考 | - |
请求示例:
GET http://{IP}:{PORT}/platform/services/rest/v1/orgSync/incrSync?tenantId=11111111-1111-1111-1111-111111111113&since=2025-06-06 14:30:00
响应示例:
{
"success": true,
"code": 0,
"msg": "获取成功!",
"data": [
{
"orgObj": {
"id": "1757831312105926656",
"groupId": "1738951430307127296",
"personId": "1725571954663436288",
"groupOrder": 0,
"personOrder": 0
},
"eventType": "RISEORGEVENT_TYPE_GROUP_ORDER",
"tenantId": "11111111-1111-1111-1111-111111111113"
},
{
"orgObj": {
"id": "1757831312152064000",
"groupId": "1738951430307127296",
"personId": "1727741116784685056",
"groupOrder": 0,
"personOrder": 1
},
"eventType": "RISEORGEVENT_TYPE_GROUP_ORDER",
"tenantId": "11111111-1111-1111-1111-111111111113"
},
{
"orgObj": {
"orgType": "Department",
"id": "1799837157715431424",
"parentId": "1666895850843480064",
"tenantId": "11111111-1111-1111-1111-111111111113",
"createTime": "2025-06-06 06:30:17",
"updateTime": "2025-06-06 06:30:17",
"disabled": false,
"description": "",
"customId": null,
"dn": "ou=销售部,o=组织",
"name": "销售部",
"properties": null,
"tabIndex": 8,
"guidPath": "1666895850843480064,1799837157715431424",
"aliasName": "",
"deptGivenName": "",
"enName": "",
"gradeCode": null,
"divisionCode": "",
"deptAddress": "",
"deptOffice": "",
"deptFax": "",
"deptPhone": "",
"zipCode": "",
"establishDate": null,
"bureau": false
},
"eventType": "RISEORGEVENT_TYPE_ADD_DEPARTMENT",
"tenantId": "11111111-1111-1111-1111-111111111113"
}
]
}
实体类
组织机构(Organizaiton)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
parentId | string | 父节点ID | - |
tenantId | string | 租户Id | - |
createTime | string | 创建时间 | - |
updateTime | string | 更新时间 | - |
disabled | boolean | 是否禁用 | - |
description | string | 描述 | - |
customId | string | 自定义ID | - |
dn | string | 域名称 | - |
name | string | 名称 | - |
orgType | enum | 节点类型 [Enum: ORGANIZATION("Organization", "组织机构") , DEPARTMENT("Department", "部门") , GROUP("Group", "用户组") , POSITION("Position", "岗位") , PERSON("Person", "人员") , MANAGER("Manager", "三员管理员") ] | - |
properties | string | 扩展属性(json格式) | - |
tabIndex | int32 | 序号 | - |
guidPath | string | 由ID组成的父子关系列表,之间用逗号分隔 | - |
enName | string | 英文名称 | - |
organizationCode | string | 机构代码 | - |
organizationType | string | 组织机构类型 | - |
virtual | boolean | 机构类型,0=实体组织,1=虚拟组织 | - |
部门(Department)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
parentId | string | 父节点ID | - |
tenantId | string | 租户Id | - |
createTime | string | 创建时间 | - |
updateTime | string | 更新时间 | - |
disabled | boolean | 是否禁用 | - |
description | string | 描述 | - |
customId | string | 自定义ID | - |
dn | string | 域名称 | - |
name | string | 名称 | - |
orgType | enum | 节点类型 [Enum: ORGANIZATION("Organization", "组织机构") , DEPARTMENT("Department", "部门") , GROUP("Group", "用户组") , POSITION("Position", "岗位") , PERSON("Person", "人员") , MANAGER("Manager", "三员管理员") ] | - |
properties | string | 扩展属性(json格式) | - |
tabIndex | int32 | 序号 | - |
guidPath | string | 由ID组成的父子关系列表,之间用逗号分隔 | - |
aliasName | string | 部门简称 | - |
deptGivenName | string | 特定名称 | - |
enName | string | 英文名称 | - |
gradeCode | string | 等级编码 | - |
divisionCode | string | 区域代码 | - |
deptAddress | string | 部门地址 | - |
deptOffice | string | 办公室 | - |
deptFax | string | 传真号码 | - |
deptPhone | string | 电话号码 | - |
zipCode | string | 邮政编码 | - |
establishDate | string | 成立时间 | - |
bureau | boolean | 是否委办局 | - |
人员(Person)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
parentId | string | 父节点ID | - |
tenantId | string | 租户Id | - |
createTime | string | 创建时间 | - |
updateTime | string | 更新时间 | - |
disabled | boolean | 是否禁用 | - |
description | string | 描述 | - |
customId | string | 自定义ID | - |
dn | string | 域名称 | - |
name | string | 名称 | - |
orgType | enum | 节点类型 [Enum: ORGANIZATION("Organization", "组织机构") , DEPARTMENT("Department", "部门") , GROUP("Group", "用户组") , POSITION("Position", "岗位") , PERSON("Person", "人员") , MANAGER("Manager", "三员管理员") ] | - |
properties | string | 扩展属性(json格式) | - |
tabIndex | int32 | 序号 | - |
guidPath | string | 由ID组成的父子关系列表,之间用逗号分隔 | - |
loginName | string | 登录名称 | - |
password | string | 密码 | - |
avator | string | 人员头像 | - |
official | int32 | 编制名称 | - |
officialType | string | 编制类型 | - |
duty | string | 职务 | - |
dutyLevel | int32 | 职级 | - |
dutyLevelName | string | 职级名称 | - |
caid | string | CA认证码 | - |
string | 邮箱 | - | |
sex | enum | 性别 [Enum: MALE(1, "男") , FEMALE(0, "女") ] | - |
province | string | 人员籍贯 | - |
officeAddress | string | 办公室地址 | - |
officePhone | string | 办公室电话 | - |
officeFax | string | 电话传真 | - |
mobile | string | 手机号 | - |
personType | string | 人员类型,管理员用户:adminPerson,单位用户:deptPerson,个人用户:userPerson,专家用户:expertPerson | - |
weixinId | string | 微信id | - |
orderedPath | string | 排序序列号 | - |
original | boolean | 是否原始人员,0:添加的人员,1:新增的人员 | - |
originalId | string | 原始人员id | - |
岗位(Position)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
data | object | 操作成功返回的数据 | - |
id | string | 唯一标识 | - |
parentId | string | 父节点ID | - |
tenantId | string | 租户Id | - |
createTime | string | 创建时间 | - |
updateTime | string | 更新时间 | - |
disabled | boolean | 是否禁用 | - |
description | string | 描述 | - |
customId | string | 自定义ID | - |
dn | string | 域名称 | - |
name | string | 名称 | - |
orgType | enum | 节点类型 [Enum: ORGANIZATION("Organization", "组织机构") , DEPARTMENT("Department", "部门") , GROUP("Group", "用户组") , POSITION("Position", "岗位") , PERSON("Person", "人员") , MANAGER("Manager", "三员管理员") ] | - |
properties | string | 扩展属性(json格式) | - |
tabIndex | int32 | 序号 | - |
guidPath | string | 由ID组成的父子关系列表,之间用逗号分隔 | - |
jobId | string | 职位id | - |
JobName | string | 职位名称 | - |
orderedPath | string | 排序序列号 | - |
用户组(Group)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
parentId | string | 父节点ID | - |
tenantId | string | 租户Id | - |
createTime | string | 创建时间 | - |
updateTime | string | 更新时间 | - |
disabled | boolean | 是否禁用 | - |
description | string | 描述 | - |
customId | string | 自定义ID | - |
dn | string | 域名称 | - |
name | string | 名称 | - |
orgType | enum | 节点类型 [Enum: ORGANIZATION("Organization", "组织机构") , DEPARTMENT("Department", "部门") , GROUP("Group", "用户组") , POSITION("Position", "岗位") , PERSON("Person", "人员") , MANAGER("Manager", "三员管理员") ] | - |
properties | string | 扩展属性(json格式) | - |
tabIndex | int32 | 序号 | - |
guidPath | string | 由ID组成的父子关系列表,之间用逗号分隔 | - |
type | enum | 岗位组或者用户组 [Enum: POSITION("position") , PERSON("person") ] | - |
人员岗位关联表(PersonsPositions)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
positionId | string | 岗位id | - |
personId | string | 人员Id | - |
positionOrder | string | 岗位排序号 | - |
personOrder | string | 人员排序号 | - |
人员用户组关联表(PersonsGroups)
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
id | string | 唯一标识 | - |
groupId | string | 用户组id | - |
personId | string | 人员Id | - |
groupOrder | string | 用户组排序号 | - |
personOrder | string | 人员排序号 | - |
实体事件
字段 | 类型 | 描述 | 引入版本 |
---|---|---|---|
orgObj | object | 事件实体对象,参考下方事件类型和事件实体的对应关系表 | - |
eventType | string | 事件类型,参考下方事件类型和事件实体的对应关系表 | - |
tenantId | string | 租户id | - |
事件实体对象和事件类型的对应关系如下表:
事件类型 | 描述 | 实体类 |
---|---|---|
RISEORGEVENT_TYPE_ADD_ORGANIZATION | 添加组织机构 | 组织机构(Organizaiton) |
RISEORGEVENT_TYPE_DELETE_ORGANIZATION | 删除组织机构 | 组织机构(Organizaiton) |
RISEORGEVENT_TYPE_UPDATE_ORGANIZATION | 更新组织机构 | 组织机构(Organizaiton) |
RISEORGEVENT_TYPE_ADD_DEPARTMENT | 添加部门 | 部门(Department) |
RISEORGEVENT_TYPE_DELETE_DEPARTMENT | 删除部门 | 部门(Department) |
RISEORGEVENT_TYPE_UPDATE_DEPARTMENT | 更新部门 | 部门(Department) |
RISEORGEVENT_TYPE_ADD_PERSON | 添加人员 | 人员(Person) |
RISEORGEVENT_TYPE_DELETE_PERSON | 删除人员 | 人员(Person) |
RISEORGEVENT_TYPE_UPDATE_PERSON | 更新人员 | 人员(Person) |
RISEORGEVENT_TYPE_ADD_POSITION | 添加岗位 | 岗位(Position) |
RISEORGEVENT_TYPE_DELETE_POSITION | 删除岗位 | 岗位(Position) |
RISEORGEVENT_TYPE_UPDATE_POSITION | 更新岗位 | 岗位(Position) |
RISEORGEVENT_TYPE_POSITION_ADDPERSON | 岗位添加人员 | 人员岗位关联表(PersonsPositions) |
RISEORGEVENT_TYPE_POSITION_REMOVEPERSON | 岗位删除人员 | 人员岗位关联表(PersonsPositions) |
人员岗位关联表(PersonsPositions) | ||
RISEORGEVENT_TYPE_ADD_GROUP | 添加用户组 | 用户组(Group) |
RISEORGEVENT_TYPE_DELETE_GROUP | 删除用户组 | 用户组(Group) |
RISEORGEVENT_TYPE_UPDATE_GROUP | 更新用户组 | 用户组(Group) |
RISEORGEVENT_TYPE_GROUP_ADDPERSON | 用户组添加人员 | 人员用户组关联表(PersonsGroups) |
RISEORGEVENT_TYPE_GROUP_REMOVEPERSON | 用户组删除人员 | 人员用户组关联表(PersonsGroups) |
人员用户组关联表(PersonsGroups) |