企业身份插件使用指南
钉钉、飞书和企业微信插件可以连接企业通讯录、推送个人应用消息，并提供企业账号单点登录。安装后，在 集成 → 应用 打开对应插件。
先完成平台侧设置：钉钉、飞书、企业微信。插件安装步骤见安装插件。
组织、部门、用户、推送配置和消息日志的逐列说明见企业身份插件列表与操作说明，包含搜索、导出、绑定状态、各弹窗按钮及完整审批提醒操作示例。
按需要开启功能
| 功能 | Soln 入口 | 是否修改内部组织架构 |
|---|---|---|
| 获取外部组织、部门和用户 | 插件 → 组织映射 → 获取通讯录 | 否，只保存外部通讯录快照 |
| 绑定现有组织、部门和成员 | 组织映射 → 绑定 / 自动绑定 | 否，只建立标识对应关系 |
| 按外部数据更新内部组织架构 | 组织映射 → 同步组织架构 | 是，需要单独启用自动同步 |
| 推送个人应用消息 | 插件 → 消息推送 → 推送配置 | 否，使用已绑定的有效成员 |
| 企业账号登录 | 插件 → 应用信息，以及 账户中心 → 单点登录 | 登录本身不创建成员、不调整组织架构 |
只需要消息推送时，完成成员绑定即可，无需启用组织架构同步，也无需绑定群机器人。
获取通讯录
- 确认插件已启用，平台已批准所需接口权限，且通讯录授权范围包含目标成员和部门
- 进入 组织映射，点击列表顶部的 获取通讯录 按钮
- 分别查看 组织、部门、用户 三个列表。固定列显示外部名称、ID 和归属，动态列来自平台实际返回的字段
- 点击 查看 打开详情抽屉；点击下载图标可导出当前搜索条件下的全部数据，包含动态字段和绑定信息
首次获取成功后，租户后台约每 5 分钟更新一次通讯录，关闭页面后仍会执行。插件、租户后台和所需服务需要保持运行；平台限流或请求失败会影响更新时间。
接口权限、通讯录授权范围、应用可见范围是不同的设置。 能登录或能读取一个成员，不代表可以读取整个企业。邮箱、手机号等字段还受字段权限、成员授权和平台规则限制。
绑定现有对象
手动绑定
在对应列表点击 绑定，选择已有 Soln 组织、部门或成员，保存即可。组织、部门、用户分别绑定；同一插件来源、同一类型下，一个外部对象与一个内部对象建立一对一关系。
解绑只移除对应关系，不删除内部对象。修改 Client ID、App ID、CorpId 或 AgentId 等来源身份配置后，需要重新检查当前来源下的通讯录、绑定和推送配置。
自动绑定
- 在目标列表顶部点击 自动绑定
- 选择两边用于比较的字段，例如外部用户邮箱与 Soln 成员邮箱
- 选择精确匹配或忽略大小写，保存规则
保存时会执行匹配，后续每次通讯录获取成功后也会按已保存规则执行。只绑定两边字段均非空、且唯一匹配的未绑定项；重名、重复邮箱、空值和冲突项需要处理后再匹配。已有绑定，包括手动调整的绑定，会保留，不会被下一次匹配覆盖。
自动绑定不会创建组织、部门或成员，也不会修改其归属与权限。成员登录后自动补充插件绑定的流程目前仅接通企业微信，见企业微信登录与绑定。
同步组织架构
只有希望外部平台维护的数据写入 Soln 时，才启用此功能。
- 先获取通讯录；如果内部已有相同对象，先绑定，避免作为新对象导入
- 点击列表顶部 自动绑定 左侧的 同步组织架构
- 在弹窗设置字段映射：左侧是外部字段，右侧是内部字段，例如外部部门名称对应内部
[部门] 名称（so_name） - 可以从 自动映射 菜单选择按名称或按编码匹配，再检查每条结果；自动映射只辅助配置字段，不代表已执行数据同步
- 点击底部 保存映射，保持原有同步开关状态；首次未启用时只保存不会开启同步，准备好后点击 启用自动同步。已启用时，保存后的规则会用于后续同步
内部编码使用 so_ 前缀，按编码自动映射时会处理此前缀。层级、成员归属根据平台关系和对象绑定解析，不能用外部部门 ID 直接替代内部部门 ID。
| 同步规则 | 行为 |
|---|---|
| 来源数量 | 同一租户只能启用一个外部组织架构来源；另一个有效来源已启用时会提示冲突 |
| 更新与新增 | 已绑定对象更新；未绑定对象新增并建立绑定。只有配置了字段映射的对象类型才参与同步 |
| 执行时间 | 启用后由租户后台安排获取通讯录并同步，之后约每 5 分钟执行；关闭页面不影响执行 |
| 字段校验 | 使用内部字段必填、格式、选项、唯一性及归属等校验；不符合要求的对象会记录失败原因 |
| 新增成员 | 以停用状态导入，结果中计为待激活；管理员确认资料和席位后再启用，不会因外部成员已激活而直接占用席位 |
| 已有成员 | 外部禁用或离职会使成员停用；已有停用成员不会自动重新启用，初始成员等受保护对象仍执行内部保护 |
| 成员归属 | 所属组织必填，所属部门可为空；多个外部部门无法确定主部门、上级未绑定或邮箱缺失等情况需要修正 |
| 关闭同步 | 点击 禁用自动同步，后续停止组织架构写入，保留内部对象和已有绑定；通讯录更新、自动绑定是独立功能 |
外部部门删除后
弹窗底部可选择 保留内部部门（默认）、停用内部部门 或 删除内部部门。
只有本次完整获取成功，且插件确认拥有整个企业部门的读取范围，才处理已绑定、但外部已不存在的部门。范围缩小、部分可见、权限不足或获取失败，不会被当作部门已删除。仅能读取根部门不代表完整授权。
删除沿用内部校验：存在下级部门、关联成员（包括停用成员）、业务或权限引用时会阻止删除，保留历史记录与审计。初始部门也可以删除，但必须先处理这些依赖；初始组织不可删除。此配置只处理外部部门缺失，不会自动删除外部暂时不可见的组织或成员。
同步结果可查看新增、更新、未变更、待激活、删除、停用和失败数量，并打开失败记录检查具体错误。
配置消息推送
- 在平台侧开通个人应用消息能力，并确保接收成员属于应用可见范围；钉钉需工作通知权限，飞书需启用应用机器人，企业微信需可信 IP
- 在 组织映射 → 用户 确认接收人与有效 Soln 成员已绑定
- 进入 消息推送 → 推送配置，点击左侧菜单旁的新增按钮
- 选择业务应用；一个业务应用配置一条数据。钉钉还需填写该企业内部应用的 AgentId
- 在 消息模板 下拉框多选允许推送的模板。留空表示这个应用的全部消息，包括没有使用模板的自定义消息；选择模板后，只推送命中的模板消息
- 保存后在列表操作列 启用，再产生一条新的业务提醒验证
仅推送启用后该业务应用在消息中心新产生的提醒，不补发历史提醒。选择审批模板后，推送的是审批提醒卡片与详情链接；不会创建钉钉、飞书或企业微信原生审批实例、工作待办，也不会同步外部审批处理状态。这类接入需另行设计外部调用与回调流程。
生成文件、生成压缩包消息用于通知生成结果，并提供查看入口；不会把生成的文件直接上传为三家平台的附件。其他自定义消息也需要先进入对应业务应用的消息中心，才能按配置参与推送。
查看日志与重试
进入 消息推送 → 消息日志，按应用、状态和时间筛选，点击 查看 打开抽屉，检查结果说明、外部接收人及平台消息或任务 ID。
| 状态 | 含义 |
|---|---|
| 排队中 / 发送中 | 已进入队列或正在提交 |
| 平台已接受 | 平台接受了请求；钉钉可能只返回异步任务 ID，不表示成员已收到或已读 |
| 等待重试 | 等待后台下一次自动尝试 |
| 失败 / 已跳过 | 查看结果说明，检查权限、绑定、可见范围和推送配置 |
| 结果不确定 | 无法确认平台是否已处理，停止自动重试，避免重复发送 |
修复原因后，可在日志详情右上角重试 24 小时内失败或跳过 的记录；对应推送配置必须已启用且仍允许这条消息。不要通过反复发起业务审批来代替排查日志。
消息样式
| 平台 | 当前呈现 |
|---|---|
| 钉钉 | 原生 OA 工作通知卡片，字段以标签和值展示；顶部背景取消息配置，但工作通知顶部文字可能由钉钉使用应用名称，无法保证显示模板标题 |
| 飞书 | 应用机器人卡片，支持的 Markdown 与文字颜色会转换；不传任意自定义顶部背景色 |
| 企业微信 | 应用文本卡片，转换为平台支持的文本样式；不传任意顶部背景色 |
外部平台的颜色、Markdown、按钮和长度限制与 Soln 不同，不能完全还原站内样式。飞书和企业微信会使用配置的顶部标题，没有配置时使用消息标题；不会额外固定加入 Soln 标题。
点击详情入口会进入 Soln 对应消息或业务页面；需要有效登录和访问该业务的权限，推送本身不授予数据访问权。
在 OpenLink 使用插件绑定
在 集成 → OpenLink → 主体映射 顶部点击 同步插件绑定，选择已安装的插件并保存。之后 OpenLink 使用该插件的组织、部门和成员标识映射，原来的独立映射配置不会参与这条链路。取消插件绑定后恢复独立映射入口。
这项设置只选择映射来源，不会启用组织架构同步。插件停用、卸载或企业身份配置变化时，需要处理来源不可用的问题，不能用本地 ID 代替平台 ID。钉钉组织列表中的根 ID 1、飞书的根 ID 0 是组织映射标识，不是企业 CorpId 或 tenant_key。
推荐验证顺序
- 使用一位测试成员完成通讯录获取和绑定
- 创建一条新提醒，检查平台实际消息和 Soln 消息日志
- 测试从工作台登录，并打开提醒中的详情入口
- 确认已有数据绑定、字段映射和席位后，再启用组织架构同步