飞书

如果您已经在使用飞书作为您的办公IM软件，您可以通过配置飞书作为数据源，将您的组织架构快速导入到OneID中，同时进行后续的同步。

本文档将指导您如何配置飞书数据源，完成配置之后，通过自动同步或手动同步您可以将飞书组织架构数据同步至OneID目录中。在此之前，您需要拥有飞书管理后台和飞书开放平台的权限。

第一步：飞书侧应用创建及配置

1、创建应用

若已有稳定可用的已发布应用，此处也可不新建，直接点击需选用的应用进入详情页进行操作即可，为确保应用稳定可用，此处建议新建应用

1）打开飞书开放平台。（若链接无法直达，可如下图操作，通过进入飞书官网，登录后点击头像旁更多按钮，展开下拉界面中选择「开放平台」按钮，跳转至飞书开放平台页面，点击页面右上方「开发者后台」按钮，进入后台管理界面）

2）在飞书开放平台首页点击「创建企业自建应用」按钮。

3）在弹出的“创建企业自建应用”弹窗中，填写必要的信息。点击「创建」按钮后进入新创建应用的详情页。

4）在应用详情页的左侧菜单栏中找到「凭证与基础信息」，点击进入后在应用凭证模块中获取APP ID和APP Secret，请您复制并做好记录，用于后续在OneID中配置。

2、应用权限开通

1）在应用详情页的左侧菜单栏中找到「权限管理」，点击后默认进入「API权限」配置子菜单页面，需在本页面中操作为此自建应用开通必要权限。

通讯录权限：

建议全量开通（此处需注意，若想全量权限开通的话，页面全选勾选功能仅能勾选当前页面10条权限，实际权限不止10条，需滑动到最下方进行页面切换后再次全选勾选，直至全部勾选后点击「批量开通」按钮进行开通）；

若不全量开通，则至少保证开通以下必要权限：【获取企业信息】、【获取通讯录基本信息】、【获取部门基础信息】、【获取通讯录部门组织架构信息】、【获取用户基本信息】、【获取用户组织架构信息】、【获取用户受雇信息】，以及开通以下任意之一权限：【管理应用自身资源】/【获取应用信息】;
另外，若在配置数据源字段映射功能时若需要选择的字段中有邮箱/手机字段映射需求，此处也需开通权限：【获取用户邮箱信息】/【获取用户手机号】。

企业信息权限：必须勾选【获取企业信息】权限。

2）「API权限」子菜单配置完成后，切换至「数据权限」子菜单页面，点击查看通讯录权限范围配置，此处可选择需同步给OneID的部门及人员的范围。

3、版本发布

1）创建版本：在应用详情页的左侧菜单栏中找到「版本管理与发布」，进入页面后点击「创建版本」按钮进行版本创建。

2）申请线上发布。

3）应用审核：进入飞书管理后台，左侧菜单栏中点击「工作台」-「应用审核」，进入页面后，将刚刚自建的应用的发布进行审核通过。

4）在飞书管理后台，点击「工作台」-「应用管理」，进入对应应用配置页，为此自建应用开通需要同步数据的范围（按需选择，选择后，将只同步选择范围的部门及人员至OneID中）。

第二步：OneID侧数据源配置

1、数据源选择&应用凭证绑定

1）登录OneID管理后台，在通讯录模块下点击「数据源」，进入页面后，选择飞书数据源。

2）若认证源已绑定飞书应用凭证，此处可选择直接引用已有凭证，不需重新手动输入，若认证源未绑定或已绑定中无想要选择的凭证，可选择自行输入凭证进行绑定。自行输入的内容为上一步从飞书开发者平台获取到的APP ID和APP Secret。

2、数据源功能详情配置

2.1 数据范围配置

需注意，此处OneID暂不支持设置部门或人员范围，若同步过程有指定范围的要求，可在第一步创建飞书应用时在「数据权限」子菜单中进行设置。

2.2 字段映射配置

有关字段映射的更多问题可查看字段映射说明文档

1）部门字段对应关系固定，不可修改；

2）人员字段对应关系中，姓名字段为oneid侧固有字段，必须设置对应关系，邮箱/手机号/登录名字段为三选一必填字段，至少有一个对应关系存在才可正常保存；

3）飞书侧字段选择时，下拉选框仅提供基础字段选择，若需要的字段不在已有的下拉选框中可选，可以选择“自定义脚本”选项，选择后将自动弹出脚本输入弹窗，在弹窗中输入自定义的字段或脚本；

4）「映射配置数据测试」按钮为高级调试功能按钮，大多数情况为映射关系中存在自定义脚本时会用到，点击后弹出调试弹窗，可使用模拟数据或搜索真实人员数据，查看当前的映射关系下，oneid侧同步后的数据形式。

2.3 删除保护配置

此处为了防止您误删除操作，我们设置了删除保护条件，系统执行同步任务之前将识别本次操作是否会触发保护条件，若满足保护条件，则本次同步任务将不会进行，我们会给您留下的联系方式发送通知，删除保护条件可支持修改（为了避免误删除操作带来的影响，若非频繁触发导致日常同步难以进行，不建议修改保护条件）。

2.4 定时器配置

定时器默认关闭，关闭时可通过手动点击「手动同步」按钮，进行数据同步。建议开启定时器功能，开启后可以根据您实际的诉求，让同步任务定时触发，让飞书中的组织架构的变更能周期性地同步到OneID中。

2.5 应用凭证信息修改（一般情况下不建议修改）

可点击凭证信息卡片内的修改图标，唤起应用凭证弹窗，进行凭证更换，此处需注意，提交修改之后，还需点击页面整体的「保存配置」按钮，凭证修改才会生效。

2.6 保存页面配置

点击「保存配置」按钮，对页面全局改动进行保存，即完成了整体钉钉数据源配置流程。

3. 数据源同步记录查看

1）上一步数据源功能详情配置操作完成之后，如果需要进行一次导入和同步，可点击「手动同步」按钮（需注意，如果详情配置未完成时，手动同步按钮是不可点击的），若已开启定时器功能，也可等到定时器触发自动同步，同步任务完成后可在同步记录列表中查看同步结果。

2）同步记录列表中，详情列若存在「同步详情」按钮，可点击进入结果详情页查看本次同步的详情记录：

详情页右侧为整体情况概览，包括人员/部门的成功变更条数及失败记录条数（需注意，本页面只记录变更记录，若本次同步无变更内容，将不会在本页面进行记录）；
详情页左侧可选择查看人员/部门的具体变更记录情况，可通过筛选条件筛选出需要查看的内容（需注意，一个部门/人员由于变更行动中操作内容不同，会产生多条记录，每条记录的操作行为不同，请注意查看备注中的操作行为）。

4.数据源更换（非必要不建议更换）

1）点击「数据源更换」按钮，二次确认更换后可更换数据源类型（此处若只需要更换应用凭证而非更换数据源类型，可参考上一步中修改凭证操作）；

2）需注意，更换数据源操作后，原有数据源的所有配置和同步记录将清空，但是已同步至oneid侧的人员将保留。

FAQ

1、字段映射测试功能

1）Q：字段映射测试功能必须要开通额外权限吗？

A：额外权限开通场景为：需要通过手机号/邮箱搜索真实人员做映射实例时才需要开通，若直接用默认实例查看映射关系或通过userid搜索真实人员的情况，则不需要开通额外权限。

2）Q：需要开通些什么额外权限，如何在飞书侧开通？

A：权限开通操作流程请参考本文档中第一步-第2点「应用权限开通」模块相关描述，额外开通【根据手机号或邮箱获取用户ID】权限。

3）Q：如何在飞书侧获取user_id？

A：登录飞书管理后台，进入「组织架构-成员与部门」模块，查看成员列表，选定需要查看的成员，在弹出的人员信息浮层中找到【用户ID】字段，字段下方的内容即为该员工的user_id。

4）Q：映射结果中预览处提示字段缺失怎么办？

A：此处的【字段】指的是您在字段映射模块设置的映射关系中飞书侧选择的字段，【缺失】指的是在脚本编辑框中未找到对应的被选字段。若此处测试时您选择的搜索真实人员数据做映射，则出现该报错的原因可能是因为飞书侧应用创建时未开通对应字段的权限，请检查权限。