如何配置部门职位扩展字段

本文介绍在专属集成平台中配置钉钉通讯录同步时，如何处理用户部门职位字段，并同步 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，则需要按本文的上游映射表达式进行转换。

适用对象

角色	关注点
实施工程师	上游映射表达式配置、下游字段映射、验证测试
系统管理员	部门职位同步状态监控、数据准确性验证

前提条件

已创建钉钉连接器，并完成账号授权

已完成组织同步，外部部门 ID 已能匹配到专属集成平台部门

实施人员具备连接器属性映射配置权限

已确认本次同步需要处理部门职位、国际化职位或部门主管字段

字段模型说明

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`

常见问题

Q：connector_group_positions[].extension.manager_userid 是系统自动写的吗？

Q：如果上游已经有 cust_position_list，还需要写转换脚本吗？

Q：title_i18n 应该放在 position 还是 extension？

Q：manager_userid 应该放在 manager 还是 extension.manager_userid？

Q：下游同步什么时候才需要写 JS 表达式？

如何配置部门职位扩展字段

概述#

适用对象#

前提条件#

字段模型说明#

操作步骤#

上游集成：上游系统同步到专属集成平台#

下游同步：专属集成平台推送到钉钉#

推荐配置汇总#

验证与测试#

常见问题#

概述