本文面向身份集成管理员。完成后，你可以按照当前页面完成“钉钉集成连接器如何配置属性映射”相关配置，并通过用户、组织、关系或同步结果回读确认效果。本文不覆盖目标系统自身的采购、网络和管理员审批流程。本文按 6.7.1 系列固定源码基线整理。由于当前仓库没有独立的 6.7.1.1 Tag，正式发布前还需核对实际构建版本，并在目标租户完成运行验证。
准备工作#
| 前提条件 | 说明 |
|---|
| 已完成连接器创建 | 已在专属集成平台中创建钉钉集成连接器 |
| 了解钉钉字段结构 | 熟悉钉钉开放平台返回的用户、部门、角色数据结构 |
| 了解平台字段结构 | 了解专属集成平台中用户、组织、角色的属性定义 |
操作步骤#
步骤 1：了解属性映射方式#
在配置具体映射之前，需要先理解三种映射方式的含义和使用场景：| 映射方式 | 说明 | 适用场景 |
|---|
| 不映射 | 不同步该属性至平台 | 用于不需要同步的字段或包含敏感信息的字段 |
| 仅创建 | 仅在创建用户时同步该属性，后续更新不再同步 | 用于初始值设置，后续应在上游保持不变或由平台独立管理 |
| 创建且更新 | 创建和更新用户信息时均同步该属性 | 用于需要持续与上游保持同步的核心属性 |
重要：对于用户唯一标识、姓名、手机号等核心字段，强烈建议使用“创建且更新”映射方式，确保数据持续一致。
步骤 2：配置用户属性映射#
在「用户」选项卡中，配置钉钉用户属性与平台用户属性的映射关系。用户属性映射表#
| 钉钉属性 | 专属集成平台属性 | 建议映射方式 | 说明 |
|---|
| userid | sub | 创建且更新 | 用户唯一标识，必须映射 |
| name | name | 创建且更新 | 用户姓名 |
| mobile | phone_number | 创建且更新 | 手机号码 |
| email | email | 创建且更新 | 电子邮箱 |
| department | primary_org_id | 创建且更新 | 部门 ID |
| active | active | 创建且更新 | 用户状态（启用/禁用） |
| position | title | 创建且更新 | 职位名称 |
| job_number | user_job_number | 创建且更新 | 工号 |
注意：钉钉的 department 字段包含用户所属部门 ID 列表，同步时会自动解析并关联到对应组织节点。
提示：如钉钉用户数据中包含其他业务字段（如入职日期、办公地点等），可根据需要添加额外映射。
步骤 3：配置部门属性映射#
在「部门」选项卡中，配置钉钉部门属性与平台部门属性的映射关系。部门属性映射表#
| 钉钉属性 | 专属集成平台属性 | 建议映射方式 | 说明 |
|---|
| id | connector_org_id | 创建且更新 | 部门唯一标识，必须映射 |
| name | name | 创建且更新 | 部门名称 |
| parentid | parentRefId | 创建且更新 | 父部门 ID，用于构建部门层级关系 |
| order | seq | 创建且更新 | 部门排序值，决定同级部门的显示顺序 |
| dept_manager_userid | manager | 创建且更新 | 部门负责人 ID |
重要：parentid 的映射至关重要，错误的映射会导致部门层级混乱或循环引用。
步骤 4：配置角色属性映射#
如在前置步骤中选择了角色集成（角色集成类型设为“按角色集成”或“按角色组集成”），在「角色」选项卡中配置钉钉角色属性与平台角色属性的映射关系。角色属性映射表#
| 钉钉属性 | 专属集成平台属性 | 建议映射方式 | 说明 |
|---|
| id | connector_role_id | 创建且更新 | 角色唯一标识，必须映射 |
| name | name | 创建且更新 | 角色名称 |
| groupid | parentRefId | 创建且更新 | 角色组 ID，用于角色分组 |
提示：如不需要同步角色信息，可在同步策略中将「角色集成类型」设为“不集成”。
步骤 5：配置扩展字段映射#
对于钉钉中的自定义字段，可以通过扩展字段映射进行配置：3.
映射格式通常为：appuser.extension.字段名
| 钉钉扩展字段 | 映射表达式 | 说明 |
|---|
| 护照 | appuser.extension.护照 | 将钉钉自定义“护照”字段映射到平台扩展属性 |
| 入职日期 | appuser.extension.入职日期 | 将钉钉自定义“入职日期”字段映射到平台扩展属性 |
| 工龄 | appuser.extension.工龄 | 将钉钉自定义“工龄”字段映射到平台扩展属性 |
注意：扩展字段名称必须与钉钉中定义的字段名完全一致（包括大小写和字符）。
验证结果#
属性映射验证方法#
| 验证步骤 | 操作方法 |
|---|
| 字段映射完整性检查 | 逐一核对各选项卡中的映射配置，确保核心字段已正确映射 |
| 连接测试验证 | 在连接测试中选择信息完整的用户账号，验证返回数据中各字段能否正常匹配 |
| 同步结果验证 | 执行手动全量同步后，在「用户管理」页面抽查用户信息的完整性和准确性 |
| 增量更新验证 | 在上游修改某用户属性后触发同步，确认修改能被正确捕获并更新 |
常见映射错误排查#
| 错误现象 | 可能原因 | 解决方法 |
|---|
| 同步后用户名称为空 | name 字段未映射或映射方式为“不映射” | 将 name 字段映射方式设为“创建且更新” |
| 同步后手机号为空 | mobile 字段未映射或上游用户无手机号数据 | 检查映射配置，确保上游数据包含手机号 |
| 部门层级混乱 | parentid 映射错误 | 检查 department 和 parentid 的映射是否正确 |
| 用户无法关联 | sub 字段映射错误 | 确保 userid 正确映射到 sub 字段 |
注意事项#
| 注意事项 | 说明 |
|---|
| 唯一标识字段必须映射 | 用户（userid → sub）和部门（id → connector_org_id）的唯一标识字段为必填映射 |
| 核心字段使用创建且更新 | 姓名、手机号、邮箱等核心字段建议使用“创建且更新”模式 |
| 自定义字段需精确匹配 | 扩展字段名称必须与钉钉中定义的字段名完全一致 |
| 避免敏感信息同步 | 对于包含敏感信息的字段，使用“不映射”方式 |
| 先测试后全量 | 配置完成后先进行小范围测试，验证无误后再执行全量同步 |
常见问题#
| 问题 | 解决方案 |
|---|
| 属性映射保存后未生效 | 点击「保存」后需要重新执行一次同步，映射变更才会在后续同步中生效 |
| 新增自定义字段无法映射 | 确认自定义字段在钉钉开放平台中已正确配置并可正常获取 |
| 部门负责人显示异常 | 检查 dept_manager_userid 映射是否正确，确认负责人用户已同步至平台 |
| 角色数据未同步 | 确认同步策略中「角色集成类型」已选择“按角色集成”或“按角色组集成” |
停用或回滚#
停止相关任务或调度后，再恢复上一版配置并使用测试对象复核。涉及删除、覆盖或外部系统写入的数据不能只靠恢复配置找回；执行高风险操作前应保留可恢复的数据基线。 
