如何配置部门职位扩展字段
适用版本与验收边界
本文介绍在专属集成平台中配置钉钉通讯录同步时，如何处理用户部门职位字段，并同步 title_i18n、manager_userid等部门职位扩展信息。
概述
| 字段 | 所属系统 | 说明 |
|---|---|---|
dept_position_list | 钉钉 | 钉钉接口使用的部门职位列表，包含部门、职位、国际化职位、部门主管、主部门标识 |
cust_position_list | 钉钉连接器 | 平台内部用于承接钉钉部门职位的中间字段 |
connector_group_positions | 专属集成平台用户字段 | 专属集成平台用于保存外部部门职位关系的标准字段 |
| 配置方向 | 目标 | 推荐配置 |
|---|---|---|
| 上游集成 | 上游业务系统数据同步到专属集成平台 | 将上游部门职位列表转换为专属集成平台 connector_group_positions |
| 下游同步 | 专属集成平台数据推送到钉钉 | 将专属集成平台 connector_group_positions 映射到钉钉 cust_position_list，由后端自动转换为 dept_position_list |
提示：如果钉钉连接器已经直接输出 cust_position_list，可直接配置cust_position_list -> connector_group_positions。如果接口实际返回的是dept_position_list，则需要按本文的上游映射表达式进行转换。
适用对象
| 角色 | 关注点 |
|---|---|
| 实施工程师 | 上游映射表达式配置、下游字段映射、验证测试 |
| 系统管理员 | 部门职位同步状态监控、数据准确性验证 |
准备工作
字段模型说明
connector_group_positions 是专属集成平台的多值对象字段。每一项表示用户在一个外部部门下的职位关系。[
{
"code": "1059638032",
"path": "销售中心/华东销售部",
"name": "华东销售部",
"position": "销售",
"manager": "023840570303647234",
"is_main": 1,
"order": 100,
"is_manager": 0,
"state": "active",
"extension": {
"title_i18n": {
"en_US": "Sales"
},
"manager_userid": "023840570303647234"
}
}
]| 字段 | 是否推荐配置 | 说明 |
|---|---|---|
code | 是 | 外部部门 ID。同步部门关系时优先使用该字段匹配部门 |
position | 是 | 用户在该部门下的职位 |
manager | 是 | 用户在该部门下的主管 userid，下游推送钉钉时会转换为 manager_userid |
is_main | 是 | 是否主部门，1 表示是，0 表示否 |
order | 按需 | 用户在部门内的排序 |
extension.title_i18n | 按需 | 职位国际化信息，下游推送钉钉时会平铺为 title_i18n |
extension.manager_userid | 按需 | 主管 userid 的扩展保存方式；如果存在，下游 可用于补齐 manager |
操作步骤
上游集成：上游系统同步到专属集成平台
步骤 1：确认上游返回字段
以下示例使用钉钉
dept_position_list 字段结构说明映射方法。若上游系统不是钉钉，请将上游字段替换为对应系统的部门 ID、职位、国际化职位、部门主管和主部门字段。{
"userid": "513963508",
"dept_id_list": "1059638032",
"dept_position_list": [
{
"dept_id": 1059638032,
"title": "销售",
"title_i18n": {
"en_US": "英文2销售2"
},
"manager_userid": "023840570303647234",
"is_main": true
}
]
}步骤 2：配置专属集成平台目标字段
| 配置项 | 值 |
|---|---|
| 专属集成平台目标字段 | connector_group_positions |
| 上游来源字段 | appuser.dept_position_list，或其他上游系统的部门职位列表字段 |
| 字段类型 | 多值对象 |
步骤 3：填写上游映射表达式
将上游部门职位列表转换为专属集成平台 转换后的专属集成平台数据示例：
connector_group_positions。以下表达式以 appuser.dept_position_list 为例：[
{
"code": "1059638032",
"position": "销售",
"manager": "023840570303647234",
"is_main": 1,
"extension": {
"title_i18n": {
"en_US": "英文2销售2"
},
"manager_userid": "023840570303647234"
}
}
]注意： extension.manager_userid不会由系统自动生成。只有在上游映射表达式中写入，或者上游数据本身已经带有该字段时，它才会存在。
下游同步：专属集成平台推送到钉钉
步骤 1：直接配置字段映射
下游同步默认不需要填写 JS 表达式。直接将专属集成平台字段映射到钉钉连接器字段即可：
| 钉钉目标字段 | 专属集成平台来源字段 | 配置方式 |
|---|---|---|
cust_position_list | user.connector_group_positions | 直接字段映射 |
注意：下游是否能正确推送 title_i18n和manager_userid，取决于上游写入专属集成平台时，connector_group_positions中是否已经保存了manager、extension.title_i18n等字段。下游默认只负责把已保存的数据交给钉钉连接器后端处理。
步骤 2：理解后端自动转换规则
配置到
最终推送给钉钉的效果示例：
cust_position_list 后，后端会自动转换为钉钉接口字段：| 专属集成平台结构 | 钉钉接口结构 |
|---|---|
code | dept_id |
position | title |
manager | manager_userid |
is_main: 1 | is_main: true |
extension.title_i18n | title_i18n |
extension.manager_userid | manager_userid |
[
{
"dept_id": 1059638032,
"title": "销售",
"title_i18n": {
"en_US": "英文2销售2"
},
"manager_userid": "023840570303647234",
"is_main": true
}
]提示：实施人员不需要在下游映射中手动把 code改成dept_id，也不需要手动把is_main: 1改成is_main: true。钉钉连接器后端会处理这些转换。
推荐配置汇总
| 场景 | 目标字段 | 映射来源 | 是否需要 JS 转换 |
|---|---|---|---|
| 上游：上游部门职位列表写入专属集成平台 | connector_group_positions | appuser.dept_position_list，或其他上游字段 | 是 |
上游：钉钉连接器已生成 cust_position_list 写入专属集成平台 | connector_group_positions | appuser.cust_position_list | 否，通常可直接映射 |
| 下游：专属集成平台推送到钉钉 | cust_position_list | user.connector_group_positions | 否，直接字段映射 |
验证结果
| 验证项 | 验证方法 | 预期结果 |
|---|---|---|
| 上游字段写入 | 运行一次上游同步，查看专属集成平台用户详情 | connector_group_positions 中存在 code、position、manager、extension.title_i18n |
| 部门关系匹配 | 查看用户所属部门 | 用户被同步到 code 对应的专属集成平台部门 |
| 国际化职位 | 查看专属集成平台字段或同步日志 | extension.title_i18n.en_US 保留英文职位 |
| 下游推送 | 运行一次下游同步，查看钉钉接口日志 | 请求中出现 dept_position_list |
| 主管字段 | 查看钉钉用户部门职位数据 | manager_userid 正确写入 |
| 主部门字段 | 查看钉钉用户部门职位数据 | is_main 为布尔值 true 或 false |
常见问题
停用或回滚
修改于 2026-09-14 10:20:56