钉钉完全集成方案
概述
钉钉是阿里巴巴集团旗下企业级协同办公平台。观远 BI 支持与钉钉深度集成，实现账号体系打通与统一身份认证，支持在钉钉内直接访问数据分析与智能决策能力。
集成后可实现：
- 观远 BI 成为钉钉的内嵌应用；
- 观远 Web 端可用钉钉扫码登录；
- 从钉钉的工作台访问观远 BI 可免密登录（包括钉钉的移动端和 PC 端）；
- 订阅、预警消息推送至钉钉，一键触达。
前提条件
在开始配置前，请确保满足以下条件：
-
权限要求：
- 拥有「钉钉开发者平台」的企业管理员权限，用于创建和配置应用。
- 拥有观远「管理中心 > 系统集成 > 钉钉」的编辑权限。
-
网络环境： 确保观远 BI 服务器可正常访问钉钉开发者平台的 API 接口。
基础集成配置
操作步骤：
- 钉钉开发者平台创建应用：「钉钉开发者平台 > 应用开发 > 创建应用」，填写相关信息后完成创建。在「钉钉应用」中找到已创建的应用，进入「凭证与基础信息」页面，获取「AgentID」、「Client ID」和「Client Secret」。
- 观远管理中心同步信息：观远「管理中心 > 系统集成 > 办公 OA > 钉钉 > 配置微应用信息」，填写获取到的钉钉应用信息，测试连接成功后「启用」，获取「应用首页地址」、「PC 端首页地址」。
- 权限授权与应用发布、配置范围：在钉钉应用详情页面按需配置「网页应用」、「安全设置」、「权限管理」，完成后「发布应用」，并且配置「应用可用范围」。
钉钉开发者平台创建应用
-
以管理员身份登录 钉钉开发者平台>应用开发模块，点击「创建应用」，填写「应用名称｜、「应用描述」等信息后点击「保存」。
应用创建完成后，系统自动跳转至应用详情页。
-
点击「凭证与基础信息」，在此页面获取「AgentID」、「Client ID」和「Client Secret」，用于观远管理后台配置。
观远管理中心集成应用
- 进入观远「管理中心 > 系统集成 > 办公 OA > 钉钉」页面，点击「配置微应用信息」，在「扫码登录应用信息」弹窗中填入上一步获取的配置信息，「测试连接」成功后点击「确定」。
- 连接成功后开启钉钉集成按钮，系统将生成「应用首页地址」与「PC 端首页地址」链接，用于钉钉应用配置。
钉钉开发者平台配置与发布
可以根据实际需求，为应用开启能力。单个应用可开启多种能力，一个能力可用于一个或多个钉钉场景。
配置「网页应用」
SSO 登录流程基于网页能力实现，因此此能力必须开启。
-
返回 钉钉开发者平台>应用开发模块，在新创建的应用详情页，点击「添加应用能力」，选择「网页应用」，点击下方「添加」，系统跳转至「网页应用」配置页面，
-
将在观远获取的「应用首页地址」填入「移动端首页地址」、「桌面端首页地址」填入「桌面端首页地址」，点击「保存」即可配置成功。
配置「配置重定向 URL」
重定向 URL 是保证 SSO 登录流程能正常进行的基本配置，钉钉接到登录请求后会重定向到 BI 系统，流程才能往下走。
在钉钉应用后台的「安全设置」页面，将在观远获取的「回调域名」填入「重定向 URL」，完成添加。
- https 与 http 协议需要与实际使用的网址一致；
- URL 末尾的
/需要保留。
回调地址可从观远管理后台直接获取。私有化环境下，回调域名地址可在「管理中心 > 系统设置 > 通用设置 > 系统规则 > 域名配置」中进行配置，域名的初始状态是 http://localhost:3001/，需要改成企业实际域名。
7.4 及以上版本支持子域域名修改。
配置「权限管理」
在钉钉应用后台的「权限管理」页面中，搜索需要开通的权限，点击「立即开通」。
应用功能对应的权限可参考下表：
| 应用功能 | 需开通的权限 |
|---|---|
| 免密登录 | 成员信息读权限 |
| 账户同步 | 通讯录部门信息读权限、通讯录部门成员读权限 |
发布应用并配置可见范围
应用配置完成后，需将当前配置发布后方可使用。
-
钉钉应用后台的「版本管理与发布」页面，点击「创建新版本」，填写版本信息后「保存」即可创建并发布应用版本。
-
在「版本详情」页配置相应信息。
-
填写「应用版本号」与「版本描述」，用于展示当前版本信息。
-
配置「应用可见范围」：应用配置完成后，需配置可见范围，在可见范围内的用户才可使用该应用。
选择「部分员工」时，支持通过组织架构/名称搜索选择成员。
-
版本信息与可见范围配置完成后，点击「保存」，即可将应用发布上线。
-
（可选）后续若需要修改应用可见范围，可在「钉钉管理后台 > 应用管理」页面，找到创建的应用点击右侧「设置」，即可对「应用可见范围」进行修改。
观远管理中心关联钉钉账号
BI 管理后台钉钉集成启用后，BI 系统会在「用户基础属性」中自动添加「钉钉账号」，管理员可以通过手动添加的方式关联钉钉账号，也可通过同步账户数据集的方式关联。
手动关联
单个用户关联
在观远 BI「管理中心 > 用户管理 > 用户 > 基本信息」页面，填写用户钉钉账号。
钉钉账号可从「钉钉管理后台 > 通讯录 > 成员 > 员工 UserID」中获取。
批量关联
在观远 BI「管理中心 > 用户管理 > 用户基础属性管理 > 批量设置」页面，点击「批量上传」，下载模板并按照模板填写完成后点击「上传文件」，批量添加用户属性。
通过账户数据集关联
-
在「数据准备 > 数据集 > 新建数据集 > 账户数据集」界面，选择钉钉连接器后点击下一步，选择企业为「默认」。其余配置与 账户数据集 一致。
-
账户同步。
-
在「管理中心 > 用户管理 > 账户同步」界面，选择处理好的数据集。
-
配置钉钉账号用于免秘登录和消息推送。
-
效果展示
配置完成后可在钉钉「工作台」找到创建的应用，点击即可免密登录至观远BI。
同时，观远 BI 登录页面也可选择「钉钉」作为第三方登录方式，点击「确定」可进行钉钉扫码登录。
如需设置默认登录为钉钉，则可在「管理中心 > 系统设置 > 登录设置 > 通用设置」中设置默认登录方式为钉钉。
进阶配置
免密登录至数据应用
若需要从钉钉工作台免密登录进入 BI 某一个具体的应用，需要对钉钉应用的首页地址进行调整。BI 后台默认的主页地址只能登录到应用主页面，不会进入到某一个具体的应用。
免密登录至数据应用有以下两种方式：
- 参考 移动端门户或者移动轻应用配置说明 在 BI 「企业配置 > 简易门户」页面将「企业默认页面」设置为数据应用。
- 通过在钉钉「网页应用」页面配置跳转地址，详细操作如下。
免密登录至移动端应用
无需手动拼接 URL，可在观远「数据应用 > 移动端应用」页面中，点击目标应用的管理下拉框，选择「钉钉集成链接」，快速获取主页地址。
将获取的地址填入 钉钉开发者平台>应用开发模块「移动端首页地址」即可。
免密登录至桌面端应用
需要将应用地址中的路径拼接到 PC 端首页链接中，详细操作如下：
- 在观远「管理中心 > 系统集成 > 办公 OA > 钉钉」页面，获取 PC 端首页地址。
例如：https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=dingc4hmtsn3wppmss2m&response_type=code&scope=snsapi_auth&state=pc&redirect_uri=https%3A%2F%2Fuat.guandata.com%2Fbi-test%2F%3Fprovider%3Ddingtalk%26domain%3Dtesting%26appId%3Ddingc4hmtsn3wppmss2m&ddtab=true
- 在观远 BI「数据应用 > 桌面端 > 应用」页面，找到目标页面点击预览，即可得到想要登录的具体应用链接。
例如：https://uat.guandata.com/bi-test/home/web-app/a0a4e3210ca504685bac55b1
- 将地址进行 URL 转码，可利用 转码工具 得到加密的地址。
例如：https%3A%2F%2Fuat.guandata.com%2Fbi-test%2Fhome%2Fweb-app%2Fa0a4e3210ca504685bac55b1。 - 将加密后的地址替换原有链接
redirect_uri=之后、%3Fprovider之前的部分，得到最终桌面端应用地址。
例如：https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=dingc4hmtsn3wppmss2m&response_type=code&scope=snsapi_auth&state=pc&redirect_uri=https%3A%2F%2Fuat.guandata.com%2Fbi-test%2Fhome%2Fweb-app%2Fa0a4e3210ca504685bac55b1%3Fprovider%3Ddingtalk%26domain%3Dtesting%26appId%3Ddingc4hmtsn3wppmss2m&ddtab=true - 将桌面端应用地址填入 钉钉开发者平台>应用开发模块「PC 端首页地址」即可。
免密登录至移动端门户
免密登录移动端门户与登录桌面端应用基本一致，区别在于获取目标地址方式不同，获取移动端门户地址操作如下。
在观远 BI「数据应用 > 移动端 > 门户」页面，点击预览后复制链接。
将拼接完成后的移动端门户地址填入 钉钉开发者平台>应用开发模块「移动端首页地址」即可。
免密登录至桌面端门户
免密登录桌面端门户与登录桌面端应用基本一致，区别在于获取目标地址方式不同，获取桌面端门户地址操作如下。
在观远 BI「数据应用 > 桌面端 > 门户」页面，点击「编辑」，在编辑页面找到目标页面点击预览，即可得到想要登录的具体链接。
多组织免密登录
当企业存在多组织架构（如子公司、部门、区域等），可在 BI 系统实现跨组织统一管理，实现多组织下的免密登录、消息推送。
前提条件
确保使用新版本钉钉集成页面，旧版无法添加多组织。
新旧版本区别：
- 新版：适配当前钉钉自建应用配置新版本，无需另外配置登录扫码应用；
- 旧版：适配有另外配置登录扫码应用配置的自建应用场景。
集成主组织钉钉应用
参考钉钉应用集成配置。
集成子公司钉钉应用
添加子公司
在「管理中心 > 系统集成 > 办公 OA > 钉钉」页面，点击「添加子公司」，输入子公司名称后点击「确定」，界面出现一个新添加的组织。
集成子公司钉钉应用
参考 钉钉应用集成配置。
关联钉钉账号
手动关联
钉钉配置「启用」后，系统「管理后台 > 用户管理 > 用户 > 基本信息」界面会自动添加「钉钉账号」和「钉钉公司名称」2 个用户属性。
管理员可以给单个用户添加属性，也可以在「用户基础属性」设置中批量修改配置。
钉钉公司名称要与添加子公司时所配置的公司名称保持一致。
-
单个用户关联
在观远 BI「管理中心 > 用户管理 > 用户 > 基本信息」页面，填写用户钉钉账号与钉钉公司名称。
钉钉账号可从「钉钉管理后台 > 通讯录 > 成员 > 员工 UserID」中获取。
-
批量关联
在观远 BI「管理中心 > 用户管理 > 用户基础属性管理 > 批量设置」页面，点击「批量上传」，下载模板并按照模板填写完成后点击「上传文件」，批量添加用户属性。
说明组织名称要与添加子公司时所配置的公司名称保持一致。
通过账户数据集关联
-
关联组织成员数据
在「数据准备 > 数据集 > 新建数据集 > 账户数据集」界面，选择钉钉连接器后点击下一步，选择钉钉组织。其余配置与账户数据集一致。
钉钉多组织情况下会有多个账户数据集，可通过 ETL 进行合并，需要注意以下问题：- 当一个用户在多个组织，会产生重复数据，建议对钉钉的 UserID 进行去重，仅保留一个组织下的用户账号即可（不影响免密登录和消息推送）；
- 增加所属组织的字段，标识用户所在组织，组织名称数据要和添加子公司时所配置的公司名称保持一致，后续做账户同步时，将组织字段关联到用户的「钉钉公司名称」属性上。
数据集创建成功后，在数据集管理界面的对应文件夹目录下能找到对应的账户数据集，点击进入其数据详情页。可在此页面查看数据集概览、相关卡片、数据安全等界面信息，并对各个界面的配置项进行修改。
-
同步账号
-
在「管理中心 > 用户管理 > 账户同步」界面，选择处理好的数据集
-
配置钉钉账号和钉钉公司名称用于免秘登录和消息推送。
-
订阅预警推送
将观远 BI 中配置的订阅与预警，自动推送至钉钉，支持「消息通知」与「群机器人」两种方式。
使用群机器人推送订阅预警时，需要在 钉钉开放平台-开发者后台 完成机器人创建，详情可参考添加钉钉群机器人。
在观远 BI 中配置订阅预警任务时，「通知渠道」选择「钉钉」。
效果展示
系统会自动调用已集成的钉钉应用权限，将消息发送给指定的钉钉用户/群聊。
常见报错
| 发生场景 | 报错内容及截图 | 解决方案 |
|---|---|---|
| 在登录页使用钉钉扫码登录时 | 登录失败没有调用该接口的权限，接口权限申请参考：https://open.dingtalk.com/document/orgapp-server/add-api-permission, {requiredScopes=[qyapi_get_member]}  | 反馈没有调用接口权限的均是钉钉侧报错，请使用 requiredScopes 的变量值在「网页应用」的权限管理界面搜索并赋予相关权限，如图 |
| 在登录页使用钉钉扫码登录时 | 登录失败当前用户未绑定系统账号，请联系管理员完成账号关联操作，bindKey:manager1471  | 请检查对应用户的用户属性中钉钉账号是否配置正确 |
| 在登录页使用钉钉扫码登录时 | 无权限对不起，你无权限查看该页面，redirect_url 的域名不在 appid 的安全域名内 | 在钉钉后台「安全设置」中，将 BI 的域名配置到「重定向 URL（回调域名）」中 |
| 在钉钉应用内免密登录 | 授权个人信息时白屏 | 在钉钉授权时发生错误，常见原因为有：应用链接中的 redirect_uri 地址，或者 BI 中的桌面端/移动端域名，与钉钉后台中的回调地址不同应用链接中的应用 id，或者应用配置中的应用 id，与钉钉后台中的回调地址不同 |
| 在钉钉应用内访问微应用 | 不存在的临时授权码 | 常见原因有：微应用地址中的 appId 错误，请检查钉钉后台中微应用地址与 BI 后台中显示的是否一致。 |