跳到主要内容

钉钉集成说明和步骤

概述

在HAP中搭建的应用，可以直接安装在钉钉的工作台，您可以在钉钉中就能体验HAP的服务。区别于一般的SaaS与钉钉集成方案，我们采用了钉钉自建内部应用的方式进行集成。效果如下图：

  • 电脑端效果：

    通过系统默认浏览器或钉钉内，打开HAP。

    HAP：将整个平台集成到钉钉工作台

    OKR：将单个应用集成到钉钉工作台

  • 手机端效果：

免费版不支持集成钉钉

集成操作步骤​

步骤简述

  1. 在钉钉管理后台安装一个微应用，建立钉钉和HAP的信息对接。

  2. 同步钉钉通讯录，完成HAP集成到钉钉。

  3. 优化配置：将待办消息（审批、填写）同步到钉钉

  4. 将HAP的单个应用安装在钉钉工作台。

请严格按照以下步骤进行操作，任何一步出错都会导致集成失败。

一、建立钉钉和HAP的连接​

1. 打开HAP对接指南页面​

HAP 管理员点击【个人头像】 > 【组织管理】 > 【集成】 > 【企业身份】，选择钉钉进入集成页面，然后点击如何获取对接信息打开对接操作指南页面，此页面不要关闭，后面的步骤需要页面中的以下信息：

  • LOGO

  • 应用首页地址

  • PC端首页地址

HAP 只能对接一个平台，如果已经对接了一个，其他平台不再显示，关闭已集成后可以对接其他平台。

2. 在钉钉中创建对接应用​

钉钉管理员登录钉钉开发者平台，创建一个企业内部应用。

3. 添加网页应用能力​

进入左侧导航栏【应用能力 → 添加应用能力】页面，在「网页应用」卡片下方点击【+ 添加】按钮。

4. 填写首页地址​

添加网页应用能力后，填写应用首页地址和PC端首页地址。

两个地址信息可在第1步打开的对接指南页面的[完成接口信息]中复制

5、确定同步的员工范围​

特别重要！

企业在钉钉中的实际使用人数，可能与使用 HAP 的人数不一致。

例如：钉钉有 100 人，但实际使用 HAP 的可能只有 50 人，因此无需同步全部账号。

建议根据实际使用情况，按部门或指定人员设置同步范围。

在【权限管理】中配置同步范围：

  • 若全员使用 HAP ：选择【全部员工】

  • 若部分人员使用 HAP ：选择【部分员工】

6、获取通讯录权限接口​

特别重要！

在【权限管理】页面中，添加所需的通讯录读取权限。可复制下方权限名称进行搜索，并点击右侧【申请权限】完成授权。

  • 通讯录部门信息读权限

  • 通讯录个人信息读权限

  • 成员信息读权限

  • 通讯录部门成员读权限

  • 企业员工手机号信息

  • 个人手机号信息

  • 邮箱等个人信息

7、发布应用​

完成以上步骤后，钉钉的配置已经完成，接下来需要创建应用版本并发布应用，让成员可以使用，保存后直接发布生效。

  • 版本号

    只要新版本号比旧版本号大即可

  • 版本描述

    简要描述本次做了什么配置

  • 待发布内容

    本次创建或更新的能力模块，选择“网页应用”

  • 可见范围

    第4步设定的范围是同步账号的人员范围，如果需要同步的人在钉钉工作台可见HAP应用，还需要设置以下范围，这部分人在钉钉工作台可以看见HAP应用的入口。

    在测试阶段，可先选择部分人员可见。这样就只有几个人在钉钉工作台可看到HAP应用。

    待后面的步骤也测试完毕后，确认正式使用了，再回来修改应用的可见范围并发布新版即可。这里选择的人，在钉钉工作台都会看到HAP应用。 一般和第4步同步范围选择的人员是一致的。

二、在HAP同步数据​

1、录入钉钉中的信息​

组织管理员返回HAP后台的钉钉对接界面，将CorpId等4个对接信息录入。

获取CorpId等4个对接信息的方法如下：

  • AgentId、ClientID、ClientSecret

    进入钉钉中创建的应用详情，在【凭证与基础信息】页面获取3个信息。

  • CorpId

    在钉钉开放平台的首页可直接找到CorpId。

点击保存，并确定如何处理映射关系

2、同步通讯录​

点击 【同步】按钮，可以将钉钉的通讯录同步到HAP。

同步的信息有：姓名，公司，联系电话，部门，职位，头像。

每次同步钉钉的信息都会覆盖写入HAP，但HAP头像只在第一次同步时会覆盖。

同步前必看​

将钉钉通讯录同步到HAP，是依据手机号和邮箱（优先手机号）进行匹配关联的。如果HAP的组织中有相同手机号的账户，则直接建立和钉钉账号的关联，如果没有则自动创建新的HAP账户。 也就是说，能和现有HAP账户关联有两个条件：

  • 两个平台间绑定的手机号相同

  • HAP账号要在组织内

示例： 在钉钉中，员工绑定的手机号是199-9999-9999， 在同步到HAP的组织时，这个组织内有个账户也绑定了手机号199-9999-9999， 如果有则直接关联，如果没有，则自动创建一个新的账户并关联。如果HAP系统中现在有个199-9999-9999的账户，但不在您的组织内，依然不会同步并关联的，而是自动创建一个新的HAP账户。

在手机号匹配不上时，会再按邮箱搜索匹配。

因此在同步前，管理员要明晰以下4点：

  • 确定好使用HAP的钉钉账号范围， 范围设置参考本文一.4章节。

  • 一定要让员工核对好HAP账户绑定的手机号和钉钉的手机号是否一致，如果不一致，请尽快绑定或换绑保持一致，全部确认后再进行同步通讯录的操作。

  • 已经有HAP账号保证已经在组织内（在组织后台，人员部门管理显示了才算加入组织）

  • 还没有主动注册HAP账户的员工，点击同步后，会自动创建一个HAP账户

开始同步​

组织超级管理员进入 组织管理后台 > 集成 > 第三方平台 ，点击【同步】按钮。 查看同步内容说明

指定人员不同步​

如果您想同步完整的部门结构，又有一些用户不想同步到HAP（如实习生、兼职人员），您可在钉钉的组织架构中添加自定义文本信息字段命名为“同步”，HAP会识别此标识且不进行同步。

  1. 添加自定义字段

    钉钉管理员在管理后台依次进入“通讯录”-“通讯录高级设置”-"成员信息管理",然后点击"+添加字段"按钮， 新字段名称为“同步”,类型为“文本”。

  2. 将不同步的成员设置为“0”

三、钉钉中打开HAP​

前面步骤操作后，就完成了HAP整个平台安装到钉钉的操作了。在钉钉工作台就能看到HAP入口。点击即可打开。

钉钉中看不到HAP？​

新的应用属于未分组应用，管理员可将其添加到全员分组中。

四、其他功能配置​

1、待办消息同步​

工作流中的待办（待审批、待填写、待查看）可以同步到钉钉的待办任务。在钉钉或HAP任意一方处理后，处理状态都会同步更新。

  • 启用待办

    在集成钉钉后，切换到"其他"标签栏,即可看到启用钉钉待办任务。

  • 权限申请

    由于钉钉接口调整，需要访问钉钉旧版申请权限。点此登录钉钉旧版，打开对接的钉钉应用，只需添加【待办事项】接口。

    依次进入“应用开发” >“H5微应用” > 对接应用 > "权限管理"，添加待办任务分类下的"待办事项"接口。

2、钉钉PC端打开HAP的方式​

在钉钉PC端打开HAP时，可以选择是在钉钉内打开，还是跳转到系统浏览器打开。在钉钉集成配置页面，选择“其他”标签栏，即可看到打开方式的选项。

3、钉钉中的消息链接打开方式​

支持“独立窗口”打开和“侧边栏”打开两种方式。

独立窗口： 新开浏览器页面打开

侧边栏： 在钉钉APP内右侧打开

调整打开方式后，新的消息将按新的方式打开，历史消息按当时的配置方式打开。

4、通过机器人发送消息​

集成后，默认以工作通知的方式发送给钉钉用户，也可以开启以机器人的方式发送，开启后默认方式失效。具体参考

5、同步根目录​

开启【同步根目录】后，将钉钉中组织架构的根节点（通常为组织名称），作为一级部门进行同步。

五、将单个应用安装在钉钉工作台​

完成平台间的集成后，可以将单个应用安装到钉钉工作台。

  1. 应用管理员进入应用管理的发布页面，打开此应用的安装指南和信息页面。

    每个应用的配置信息是不同的,需要安装的应用都需要这样操作一遍。

  2. 在钉钉中创建对接应用并填写信息

    参考对接指南的步骤，在钉钉开发者后台创建应用，只需设置名称、LOGO、应用首页地址和PC端首页地址、使用范围。

    如果您需要进入应用的一个特定页面，可以将页面链接生成相应的主页地址，粘贴到钉钉应用中的应用首页地址和PC端首页地址。

  3. 应用安装在钉钉后，用户即可在工作台中看到此应用，点击直接进入应用页面。

    打开后如果提示无权限或应用不存在，请联系HAP中应用管理员调整您的权限。

六、其他方式登录HAP​

钉钉扫码登录​

配置了二级域名的组织，在二级域名登录页会显示钉钉登录的方式，可以使用钉钉APP扫码或已登录账号验证登录。

配置步骤：

  1. 在组织管理后台，配置二级域名

    例如示例组织配置了dingding，组织的二级域名地址就是dingding.mingdao.com。

    注：私有部署的HAP不需要配置二级域名。

  2. 在钉钉集成中启用“钉钉扫码登录”

  3. 在钉钉中的对接应用下添加“通讯录个人信息读权限”,查看钉钉集成所有所需接口

  4. 在钉钉的对接应用中，添加重定向URL。

    在开发配置>安全设置>重定向URL(回调域名) 中，添加1中配置的二级域名地址。

    注：私有部署直接填写HAP的域名，如果HAP私有部署为多组织，集成钉钉组织的扫码登录的页面为域名/network?projectId=组织ID

  5. 发布新版本

    钉钉内的调整要正式发布后才能生效。

  6. 以上配置完成后，在二级域名页面会显示钉钉登录的按钮

如何通过账号密码登录HAP​

除了通过钉钉直接进入HAP系统，还可以直接通过账号和密码登录HAP系统。

需对账号进行登录账号和密码的设置：

  • 1、绑定手机号

  • 2、设置密码

设置步骤

  1. 从钉钉工作台进入HAP

  2. 绑定手机号并设置密码

    • 点击头像，进入账号绑定页面。

    • 输入手机号和接收到的验证码，然后设置密码。

密码设置后，您可以使用前面绑定的手机号和刚设置密码直接从HAP登录。