钉钉考勤请假同步插件
1. 简介
1.1 功能简介
钉钉考勤请假同步插件，可以方便快捷的将钉钉中的请假数据同步到简道云表单中，让管理员可以使用这些数据计算员工的出勤率和工资等数据。
1.2 适用对象
适用于公共模式和 钉钉集成模式 的账号，不适用于其他模式。
1.3 预期效果
以使用「同步报表」函数，同步成员请假信息为例，效果如下所示：
2. 钉钉平台配置
2.1 创建钉钉应用
1）管理员需要 PC 端登录 钉钉开放平台，选择「应用开发 >> 钉钉应用」，点击「创建应用」。如下图所示：
注：该应用会占用钉钉中的 API 调用量。
2）在创建应用详情页中，填写应用名称和应用描述，并上传应用图标后，点击「保存」按钮。如下图所示：
2.2 权限申请
在应用开发详情页中，进入「权限管理 >> 考勤」处，勾选「查询企业考勤数据权限」和「钉钉假期查询的权限」，勾选完成后点击「批量申请」按钮。如下图所示：
2.3 记录Appkey和AppSecret
在「凭证与基础信息」处，记录下创建的应用的 Appkey 和 AppSecret ，插件配置时需要填写。如下图所示：
3. 插件安装及配置
3.1 安装插件
1）直接安装
- 您可点击右方链接直接安装插件：钉钉考勤请假同步插件安装。
- 安装成功后，可参考本文【3.2 配置插件】和【3.3 启用插件】，前往「开放平台 >> 插件管理」处配置并启用插件。
2）插件市场处安装
在简道云「插件市场」处，安装「钉钉考勤请假同步」插件。插件市场处安装方法可参见文档：插件市场中【2.3 插件安装】。
3.2 配置插件
1）安装后，在「插件管理」处，点击插件右侧的「设置」按钮，根据【2.3 记录 Appkey 和 AppSecret 】，将「AppKey」、「AppSecret」、「钉钉CorpID」和「OA管理员ID」等信息配置进去，配置完成后点击确定。
2）登录简道云，在「账号中心 >> 企业管理 >> 企业信息 >> 账号模式」处，获取钉钉 CorpID。
3）进入「通讯录 >> 内部组织」中，找到具有钉钉管理权限的成员，查看对应的成员编号，即 OA 管理员 ID。
3.3 启用插件
在插件管理中，打开钉钉考勤请假同步插件右侧开关，启用插件。
4. 表单搭建
新建「考勤请假信息表」，所需要的考勤信息及字段设置如下所示：
名称 | 内容含义 | 字段类型 |
请假单位 | 请假单位：
| 单行文本 |
请假类型 | 请假的具体类型，如病假、年假、事假、产假、调休假等等 | 下拉框 |
请假时长 | 假期时长，结合请假单位来计算 例如 1 天，1 小时 | 数字 |
请假结束时间 | —— | 日期时间 类型：年-月-日 时:分:秒 |
请假开始时间 | 日期时间 类型：年-月-日 时:分:秒 | |
请假所在自然日 | 日期时间 类型：年-月-日 | |
请假成员 | 单行文本：默认支持 成员单选：公共模式下，钉钉 userid 和简道云 userid 一致时，支持进行成员单选，考勤数据即可同步到简道云里 注：选用单行文本字段时，成员信息回填后为一串成员 ID，可读性较差。故建议使用成员单选字段类型 |
5. 智能助手同步数据
表单设计完成后，插件获取到的数据，可通过「智能助手」及时同步到表单中。用户可选择以下任一方式推送。
- 定时重复触发：在每天/每周/每月/自定义周期的固定时间，重复触发智能助手任务。
- 定时单次触发：在指定时间，触发一次智能助手任务。
建议先使用「定时单次触发」将历史数据导入表单中，再使用「定时重复触发」定期导入数据。
两种触发方式的设置方法基本一致，本文将以定时重复触发为例，并对定时单次触发的设置差别进行详细描述。
5.1 新建智能助手
表单制作完成后，切换至「扩展功能」页面，新建智能助手，如下图所示：
5.2 设置触发动作
1）智能助手设置如下所示：
- 触发动作：定时重复触发
- 触发时间：2023-08-05 20:44:33
- 重复类型：每天
- 重复触发结束时间：2023-08-12 20:44:36
2）定时重复触发与定时单次触发的设置项不完全相同，具体设置如下表所示：
触发方式 | 设置项 | 简介 |
定时重复触发 | 触发时间 | 定义：何时开始触发智能助手任务 规则：必填项，精确到秒 |
重复类型 | 选项：「每天」/「每周」/「每两周」/「每月」/「每年」/「自定义重复」 规则：必填项，默认值为「每天」 | |
重复触发结束时间 | 定义：何时结束触发智能助手任务 规则，必填项，精确到秒，「重复触发结束时间」不可早于「触发时间」 | |
定时单次触发 | 触发时间 | 定义：何时触发一次智能助手任务 规则：必填项，精确到秒 |
5.3 设置执行动作
钉钉考勤请假同步插件中，执行动作可以选择【同步记录】和【同步报表】两种方式，区别在于：
- 同步报表支持同步【请假类型】，配置时需填写请假类型参数，请假类型参数为钉钉中已经设置好的假期类型名称，用英文逗号隔开（未配置请假类型的数据不会从钉钉同步过来）；
- 同步报表调用的是钉钉报表的接口，返回的数据是以天为单位的，如果连续请了 2 天假，会被拆成 2 条数据；
以下是具体配置方式：
1）若选择「同步记录」，设置执行动作如下所示：
- 选择插件：选择「钉钉考勤请假同步 >> 同步记录」插件；
- 表单：选择「考勤请假信息表」；
- 同步方式：默认为「仅新增」，不可修改；
- 同步数据起始日期：设置为「字段值」，下拉框内选择为上次运行时间；
- 同步数据结束日期：设置为「字段值」，下拉框内选择为当次运行时间；
- 同步员工范围：设置为「自定义」，自定义添加员工范围；
- 同步内容：
- 请假单位：插入表单字段值「请假单位（ID）」；
- 请假时长：插入表单字段值「请假时长（ID）」；
- 请假开始时间：插入表单字段值「请假开始时间（ID）」；
- 请假结束时间：插入表单字段值「请假结束时间（ID）」；
- 请假成员：插入表单字段值「请假成员（ID）」。
2）若选择「同步报表」，设置执行动作如下所示：
- 选择插件：选择「钉钉考勤请假同步 >> 同步报表」插件；
- 表单：选择「考勤请假信息表」；
- 同步方式：默认为「仅新增」，不可修改；
- 同步数据起始日期：设置为「字段值」，下拉框内选择为上次运行时间；
- 同步数据结束日期：设置为「字段值」，下拉框内选择为当次运行时间；
- 同步员工范围：设置为「自定义」，自定义添加员工范围；
- 假期类型：设置为「自定义」，自定义设置填写假期类型；
- 同步内容：
- 请假成员：插入表单字段值「请假成员（ID）」；
- 假期名称：插入表单字段值「请假类型（ID）」；
- 请假所在自然日：插入表单字段「请假所在自然日（ID）」
- 请假单位：插入表单字段值「请假单位（ID）」；
- 当天请假时长：插入表单字段值「请假时长（ID）」；
注：
1）自定义假期类型时，假期类型需用英文逗号隔开。
2）假期类型数量上限为 20 个。
3）使用「同步报表」函数时，同步间隔不能大于 31 天。
3）定时重复触发与定时单次触发的设置项不完全相同，具体设置如下表所示：
设置项 | 简介 |
表单 | 内容同步的目标表单。
|
同步方式 | 同步方式为「仅新增」，即有新数据推送时，只做增量更新，不做覆盖更新。 |
同步数据起始日期 | 1）定时重复触发：可设置为「字段值」，下拉框需选择「上次运行时间」。 2）定时单次触发：可以选择起始日期和结束日期，均使用日期时间字段，精确到具体时分秒；系统将根据用户设定的时间跨度来同步数据。 |
同步数据结束日期 | 1）定时重复触发：可设置为「字段值」，下拉框需选择「当次运行时间」。 2）定时单次触发：可以选择起始日期和结束日期，均使用日期时间字段，精确到具体时分秒；系统将根据用户设定的时间跨度来同步数据。 |
同步员工范围 | 默认为空，可选择组织架构、角色、成员。 最多可选择 1500 个成员，同步时仅同步前 1500 个成员 |
同步内容 | 可将【4. 表单搭建】处展示的字段数据同步到表单对应字段中。 若表单字段不符合字段类型需求，则无法正常同步，可能无法得到同步内容。 |
6. 效果预览
6.1 触发时间
6.1.1 定时重复触发
「定时重复触发」会按照「触发时间、重复类型、重复触发结束时间」计算智能助手「触发时间」，按照「同步数据起始日期」和「同步数据结束日期」计算导入的数据周期。
例如「触发时间」为 2022-10-11 9:00，「重复触发结束时间」为 2022-10-13 9:00，「重复类型」为每天，「同步数据起始日期」为 「上次运行时间」，「同步数据结束日期」为 「当次运行时间」。
那么，智能助手执行逻辑如下：
- 2022 年 10 月 11 日 9:00 首次同步时，其同步数据的起始时间为「上次运行时间」，即 2022 年 10 月 10 日 9:00 （理论上的时间值，实际上该时间点无数据）；同步数据的结束时间为「当次运行时间」，即 2022 年 10 月 11 日 9:00。
- 2022年 10 月 12 日 9:00 同步数据时，智能助手同步数据的起始时间依然为「上次运行时间」，即 2022 年 10 月 11 日 9:00；同步数据的结束时间为「当次运行时间」，即 2022 年 10 月 12 日 9:00。故可将「2022-10-11」全天的钉钉打卡数据同步至简道云表单中。
- 2022年 10 月 13 日 9:00 同步数据时，智能助手同步数据的起始时间仍然为「上次运行时间」，即 2022 年 10 月 12 日 9:00；同步数据的结束时间为「当次运行时间」，即 2022 年 10 月 13 日 9:00。故可将「2022-10-12」全天的钉钉打卡数据同步至简道云表单中。
6.1.2 定时单次触发
「定时单次触发」会在「触发时间」将「请假数据起始日期」-「请假数据结束日期」的数据导入表单中。
例如「触发时间」为 2021-05-01 零点，「请假数据起始日期」为 2021-03-01，「请假据结束日期」为 2021-04-01。
那么 2021-05-01 零点智能助手将「2021-03-01~2021-04-01」的钉钉请假数据导入简道云表单中。
6.2 数据同步
设置完成后，智能助手会在指定时间同步数据到表单。如下图所示：
6.3 执行日志
用户可在智能助手处查看任务执行日志，执行日志中可以查看执行时间、执行人、触发动作、执行结果等数据。
当执行失败时可以参照日志进行调整，执行失败的原因如下：
执行结果 | 原因说明 |
执行「钉钉考勤请假同步」插件（失败-插件已停用） | 插件安装了但未启用 |
执行「钉钉考勤请假同步」插件（失败-插件已卸载） | 请重新安装「钉钉考勤打卡同步」插件 |
执行「钉钉考勤请假同步」插件（失败-付费版本过期） | 简道云高级版已到期，请续费 |
执行「钉钉考勤请假同步」插件 | 插件执行成功，数据成功新增至表单 |
执行「钉钉考勤请假同步」插件 | 插件执行成功，但是没有数据： - 同步的时间范围内，没有数据; -「同步员工范围」只选择了一级部门（需勾选所有子部门） |
执行「钉钉考勤请假同步」插件（失败-请检查插件配置） | 插件配置中填写的 Appkey 和 AppSecret 不正确 |
执行「钉钉考勤请假同步」插件（失败-执行超时） | 插件执行耗时长，请检查智能助手相关配置 |
执行「钉钉考勤请假同步」插件（失败-同步数据量超过5W条） | 智能助手单次同步数据量不可超过5W条，若数据量过大，请分批多次导入 |
7. 注意事项
1）管理员在 钉钉开放平台 中，创建钉钉应用时，所创建的内部应用会占用钉钉中的 API 调用量。
2）公共模式使用钉钉考勤请假同步插件时需注意：简道云通讯录中的成员编号应与钉钉中的成员编号保持一致。如下所示：
简道云通讯录中的成员编号，可在「通讯录 >> 内部成员 >> 全部成员」中，点击单条成员数据后，进入成员数据详情页查看并修改。
400-111-0890
在线咨询