Skip to content

组织架构同步

概述

本文档介绍第三方系统如何与数字底座的组织架构进行同步。

数字底座中有 组织机构(Organizaiton)部门(Department)人员(Person)岗位(Position)用户组(Group) 等组织架构实体。

其中组织机构作为顶层实体 ,部门、人员、岗位、用户组可以作为组织机构或部门的子节点。 人员和岗位、用户组和人员之间可以有多对多的关系。

第三方系统可以根据自己的实际需求选择同步部分或全部实体。通常大多系统只需要同步部门、人员。

步骤

接入数字底座的组织架构同步第一次可以进行全量同步,之后可以隔一段时间进行一次增量同步。

全量同步

根据概述中所述,使用接口 1查询组织机构列表,可使用接口 2 查询组织机构下的部门列表,接口 3 查询组织机构下的人员列表,接口 4 查询组织机构下的岗位列表,接口 5查询组织机构下的用户组列表,之后再递归查询子部门的子节点列表直到无子节点。

增量同步

增量同步是以实体事件重放的方式实现增量同步,使用接口 6 查询实体事件,根据相应的事件类型和事件实体做相应的操作。

接口

1. 查询组织机构列表

接口地址:http://{IP}:{PORT}/platform/services/rest/v1/organization/list

请求方法:GET

描述:根据租户id获取组织机构列表(不包含禁用)

请求参数

参数名参数类型是否必须描述引入版本
tenantIdstringtrue租户 id-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的组织机构列表, 组织机构对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/organization/list?tenantId=11111111-1111-1111-1111-111111111113

响应示例

json
{
  "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

描述:获取下一级部门列表(不包含禁用)

请求参数

参数名参数类型是否必须描述引入版本
tenantIdstringtrue租户 id-
parentIdstringtrue父节点唯一标识(组织机构 id 或 部门 id)-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的部门列表, 部门对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/department/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064

响应示例

json
{
  "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

描述:获取下一级人员列表(不包含禁用)

请求参数

参数名参数类型是否必须描述引入版本
tenantIdstringtrue租户 id-
parentIdstringtrue父节点唯一标识(组织机构 id 或 部门 id)-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的人员列表, 人员对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/person/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064

响应示例

json
{
  "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

描述:获取下一级岗位列表(不包含禁用)

请求参数

参数名参数类型是否必须描述引入版本
tenantIdstringtrue租户 id-
parentIdstringtrue父节点唯一标识(组织机构 id 或 部门 id)-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的岗位列表, 岗位对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/position/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064

响应示例

json
{
  "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

描述:获取下一级用户组列表(不包含禁用)

请求参数

参数名参数类型是否必须描述引入版本
tenantIdstringtrue租户 id-
parentIdstringtrue父节点唯一标识(组织机构 id 或 部门 id)-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的用户组列表, 用户组对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/group/listByParentId?tenantId=11111111-1111-1111-1111-111111111113&parentId=1666895850843480064

响应示例

json
{
  "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

描述:从上一次同步成功的时间后开始获取组织节点实体事件列表

请求参数

参数名参数类型是否必须描述引入版本
sinceDatetrue上次成功同步时间,日期格式为 yyyy-MM-dd HH:mm:ss-
tenantIdstringtrue租户 id-

响应字段

字段类型描述引入版本
successboolean操作是否成功-
codeint32错误代码-
msgstring操作描述-
dataobject操作成功返回的实体事件列表, 实体事件对象字段参考-

请求示例

http
GET http://{IP}:{PORT}/platform/services/rest/v1/orgSync/incrSync?tenantId=11111111-1111-1111-1111-111111111113&since=2025-06-06 14:30:00

响应示例

json
{
  "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)

字段类型描述引入版本
idstring唯一标识-
parentIdstring父节点ID-
tenantIdstring租户Id-
createTimestring创建时间-
updateTimestring更新时间-
disabledboolean是否禁用-
descriptionstring描述-
customIdstring自定义ID-
dnstring域名称-
namestring名称-
orgTypeenum节点类型
[Enum: ORGANIZATION("Organization", "组织机构")
, DEPARTMENT("Department", "部门")
, GROUP("Group", "用户组")
, POSITION("Position", "岗位")
, PERSON("Person", "人员")
, MANAGER("Manager", "三员管理员")
]
-
propertiesstring扩展属性(json格式)-
tabIndexint32序号-
guidPathstring由ID组成的父子关系列表,之间用逗号分隔-
enNamestring英文名称-
organizationCodestring机构代码-
organizationTypestring组织机构类型-
virtualboolean机构类型,0=实体组织,1=虚拟组织-

部门(Department)

字段类型描述引入版本
idstring唯一标识-
parentIdstring父节点ID-
tenantIdstring租户Id-
createTimestring创建时间-
updateTimestring更新时间-
disabledboolean是否禁用-
descriptionstring描述-
customIdstring自定义ID-
dnstring域名称-
namestring名称-
orgTypeenum节点类型
[Enum: ORGANIZATION("Organization", "组织机构")
, DEPARTMENT("Department", "部门")
, GROUP("Group", "用户组")
, POSITION("Position", "岗位")
, PERSON("Person", "人员")
, MANAGER("Manager", "三员管理员")
]
-
propertiesstring扩展属性(json格式)-
tabIndexint32序号-
guidPathstring由ID组成的父子关系列表,之间用逗号分隔-
aliasNamestring部门简称-
deptGivenNamestring特定名称-
enNamestring英文名称-
gradeCodestring等级编码-
divisionCodestring区域代码-
deptAddressstring部门地址-
deptOfficestring办公室-
deptFaxstring传真号码-
deptPhonestring电话号码-
zipCodestring邮政编码-
establishDatestring成立时间-
bureauboolean是否委办局-

人员(Person)

字段类型描述引入版本
idstring唯一标识-
parentIdstring父节点ID-
tenantIdstring租户Id-
createTimestring创建时间-
updateTimestring更新时间-
disabledboolean是否禁用-
descriptionstring描述-
customIdstring自定义ID-
dnstring域名称-
namestring名称-
orgTypeenum节点类型
[Enum: ORGANIZATION("Organization", "组织机构")
, DEPARTMENT("Department", "部门")
, GROUP("Group", "用户组")
, POSITION("Position", "岗位")
, PERSON("Person", "人员")
, MANAGER("Manager", "三员管理员")
]
-
propertiesstring扩展属性(json格式)-
tabIndexint32序号-
guidPathstring由ID组成的父子关系列表,之间用逗号分隔-
loginNamestring登录名称-
passwordstring密码-
avatorstring人员头像-
officialint32编制名称-
officialTypestring编制类型-
dutystring职务-
dutyLevelint32职级-
dutyLevelNamestring职级名称-
caidstringCA认证码-
emailstring邮箱-
sexenum性别
[Enum: MALE(1, "男")
, FEMALE(0, "女")
]
-
provincestring人员籍贯-
officeAddressstring办公室地址-
officePhonestring办公室电话-
officeFaxstring电话传真-
mobilestring手机号-
personTypestring人员类型,管理员用户:adminPerson,单位用户:deptPerson,个人用户:userPerson,专家用户:expertPerson-
weixinIdstring微信id-
orderedPathstring排序序列号-
originalboolean是否原始人员,0:添加的人员,1:新增的人员-
originalIdstring原始人员id-

岗位(Position)

字段类型描述引入版本
dataobject操作成功返回的数据-
idstring唯一标识-
parentIdstring父节点ID-
tenantIdstring租户Id-
createTimestring创建时间-
updateTimestring更新时间-
disabledboolean是否禁用-
descriptionstring描述-
customIdstring自定义ID-
dnstring域名称-
namestring名称-
orgTypeenum节点类型
[Enum: ORGANIZATION("Organization", "组织机构")
, DEPARTMENT("Department", "部门")
, GROUP("Group", "用户组")
, POSITION("Position", "岗位")
, PERSON("Person", "人员")
, MANAGER("Manager", "三员管理员")
]
-
propertiesstring扩展属性(json格式)-
tabIndexint32序号-
guidPathstring由ID组成的父子关系列表,之间用逗号分隔-
jobIdstring职位id-
JobNamestring职位名称-
orderedPathstring排序序列号-

用户组(Group)

字段类型描述引入版本
idstring唯一标识-
parentIdstring父节点ID-
tenantIdstring租户Id-
createTimestring创建时间-
updateTimestring更新时间-
disabledboolean是否禁用-
descriptionstring描述-
customIdstring自定义ID-
dnstring域名称-
namestring名称-
orgTypeenum节点类型
[Enum: ORGANIZATION("Organization", "组织机构")
, DEPARTMENT("Department", "部门")
, GROUP("Group", "用户组")
, POSITION("Position", "岗位")
, PERSON("Person", "人员")
, MANAGER("Manager", "三员管理员")
]
-
propertiesstring扩展属性(json格式)-
tabIndexint32序号-
guidPathstring由ID组成的父子关系列表,之间用逗号分隔-
typeenum岗位组或者用户组
[Enum: POSITION("position")
, PERSON("person")
]
-

人员岗位关联表(PersonsPositions)

字段类型描述引入版本
idstring唯一标识-
positionIdstring岗位id-
personIdstring人员Id-
positionOrderstring岗位排序号-
personOrderstring人员排序号-

人员用户组关联表(PersonsGroups)

字段类型描述引入版本
idstring唯一标识-
groupIdstring用户组id-
personIdstring人员Id-
groupOrderstring用户组排序号-
personOrderstring人员排序号-

实体事件

字段类型描述引入版本
orgObjobject事件实体对象,参考下方事件类型和事件实体的对应关系表-
eventTypestring事件类型,参考下方事件类型和事件实体的对应关系表-
tenantIdstring租户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)
RISEORGEVENT_TYPE_POSITION_ORDER更新人员岗位关联表(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)
RISEORGEVENT_TYPE_GROUP_ORDER更新用户组-人员的关联人员用户组关联表(PersonsGroups)

Released under the GPL-3.0 License.