1.概述
1.1 应用场景
   随着企业内部信息技术的迅猛发展，内部的应用系统越来越多，由于这些系统相互独立，用户在使用每个系统之前都必须   按照相应的系统身份进行登录，为此用户需记住每一个系统的用户名和密码，这给用户带来了不少麻烦。特别是随着系统    的增多，出错的可能性就会增加，收到非法截获和破坏的可能性也会增大，安全性就会相应降低。针对于这种情况，在BI  项 目整体规划中也就有钉钉集成，这样就能减少那些不必要的麻烦，安全性也能够相应的提升。

1.2 功能介绍

环境配置、配置参数、钉钉消息推送

1.3 环境准备

Node,

pm2,

redis,

mysql/sqlite

1.4 版本配置差异

新框架v2.0以后版本做钉钉集成参考：钉钉集成（新）

1.5 流程图

（1）钉钉部署

（2）钉钉添加应用流程

2.操作流程

2.1 钉钉服务部署
（1）把dingding-cloud拷贝放入到ourwarbi根目录Cross_SBI、Cross_SBI_API同级目录下。

（2）拷贝最新补丁覆盖到Cross_DingDing目录下

（3）配置参数
  配置文件路径‘Cross_DingDing/build/config/index.js’
（3.1）sqlite支撑库
 dbType: 'sqlite',
 dbSqlite: '../Cross_SBI_API/powerbimeta.sqlite',//sqlite文件路径
（3.2） mysql支撑库(mssql支撑库类似)
 dbType: 'mysql',
 dbName: 'powerbimeta_test', //数据库实例名或者
 dbUsername: 'root', //数据库用户名
 dbPassword: '123', //数据库密码
 dbOp: {
  host: '192.168.0.11',//数据库服务器名称
  dialect: 'mysql',//'mysql'|'sqlite'|'postgres'|'mssql',,
 port: '3306',//数据库端口
  pool: {
    max: 50,
    min: 0,
    idle: 10000,
    acquire: 60000,
  },
  define: {
    timestamps: false
  }
 },
如图：

2.2 免登参数
  AuthUserLogin: {
  show: true,//开启自动同步用户（登录时如果没有用户自动创建BI用户并绑定，如果没有绑定自动绑定对应云之家BI用 户，username,userid和openid相同）
  admintoken: "",//管理员token
  apiurl: "",//bi对应api地址如http://ip:前端应用端口（默认8080）/api
 }

2.3 钉钉相关
  dingding:{//钉钉新授权方式
  appKey:"dingrndp7nkur",
  appSecret:"VQptjkSiCIbd68JVwvSuTBk390WT43L",
 idFromUserid:true,//钉钉id来自钉钉用户userid（默认false）
 },
 agentId: '199247257', // 登录钉钉官网后台管理，在添加微应用的时候获取
 CorpID: 'ding37eb6378f',  //从钉钉开放平台获取的CorpID （后面有说明）
 钉钉添加应用之后从应用详情里面获取对应参数
（1）登陆钉钉开发平台网站地址：https://open.dingtalk.com/

（2）点击应用开发流程创建应用开发，如图：


（3）查看获取CorpID信息：https://open-dev.dingtalk.com/#/testManage?tab=1中获取CorpID

3.其他参数
  serverPort: '3003', //该系统的运行端口号，一般默认即可
 redisPort: 6379, //redis的端口号一般默认即可
 accessURL: ['http://192.168.0.141:3000/chart?fprojid=1'], //集成应用用户验证成功最终跳转地址（一般为BI系统首页地址）
 accessloginURL: ['http://192.168.0.141:3000/login'], ////集成应用用户验收失败最终跳转地址（一般为BI系统登录地址）

4.启动程序
 cnpm i安装第三包
 npm run pm2 启动程序
 pm2 logs Cross_DingDing查看日志,输出以下日志说明参数配置和启动成功
 如图：

   地址栏访问http://（服务器域名或IP）: 3003(钉钉服务对应的端口配置文件serverPort对应值)，页面现在下面内容说明服   务能正常访问

5.钉钉添加应用流程

5.1.1 打开钉钉官网，管理员登录

打开官网：https://www.dingtalk.com/登入后台，选择工作台下面的自建应用

扫码登录

5.1.2登录成功后，开始建立H5微应用 

找到企业内部开发

5.1.3在企业应用中选择新建应用

5.1.4完成微应用相关属性填写

5.1.5创建完成后可见应用id与密钥等信息

记录以下三个信息交给实施人员

5.1.6 CorpID的获取

记录以下CorpID发送给实施人员

5.1.7应用信息填写》》首页地址填写

填写的首页地址：http://服务器域名或IP（可参考bi访问ip）: 3003/dd/（奥威nodejs中间层钉钉服务的地址）

端口基本不会更改，如要更改可更改钉钉服务对应的端口配置文件serverPort对应值

注：以下ip及地址的填写要考虑外网地址的情况，如是外网地址端口号及地址以外网地址的为准

5.1.8创建完应用在钉钉工作台可见

5.1.9应用可见权限以及通讯录访问权限的开启

5.2钉钉服务与BI系统的配置（由实施人员实现）

必备条件：

1、首先要确保该文档的1-4章节的条件满足，就是环境准备与服务正常启动（云之家与钉钉用的是同一个服务）

2、钉钉后台配置（客户完成）完成之后需要从客户手中拿到几个必备信息，如下

应用key:appKey（截图标注 2）  应用密钥：appSecret（截图标注 3）

应用代理id: agentId（截图标注 1）  公司id: CorpID（截图标注 4）

5.2.1钉钉基本信息的使用与配置

BI系统》第三方集成管理》基本信息页面 处使用，如下图

admin登录才可以配置

钉钉服务配置文件处用，配置文件位置如下图

注：修改好之后关闭文件再次编辑文件验证是否更改成功

各项配置好之后启动/重启钉钉服务，然后浏览器输入地址验证是否有以下截图效果，如有则说明钉钉服务已在正常运行中，

地址如下：

http://服务器域名或IP（可参考bi访问ip）: 3003/dd/（奥威nodejs中间层钉钉服务的地址）

5.2.2验证是否有权限获取到用户数据（admin登录）

5.2.3配置的检查，如各项正常可忽略

1、应用信息配置，参考该文档2.3钉钉相关

2、数据库配置，参考该文档2.1数据库参数

3、BI地址配置以及钉钉服务端口配置，参考该文档3其他参数

5.2.4钉钉服务是否正确被访问到，可查看实时日志

点击访问应用应有实时日志输出，如有报错信息也可以看到

5.3钉钉内免登第三方网站

https://developers.dingtalk.com/document/app/logon-free-third-party-websites?  spm=ding_open_doc.document.0.0.3752d3943IEJQy#topic-2021767

5.4常见问题

5.4.1提示ip不在白名单中，导致访问不了

如果访问不了请查看输出日志

存在以下情况则需要把ip填入钉钉后台网站的服务器出口ip中，请细看本文档5.1.7

6.钉钉消息推送

6.1配置白名单
 登录钉钉后台找到对应应用填写ip地址，ip地址为部署BI的服务器ip地址

6.2配置Cross_Task项目config

 multiplatform: {
    dd: {
        agentId:'89xxx',
        appK ey:"dinxxx",
        appSecret:"GJgxxxx"
    },
 }

 在应用基础信息中可以找到

6.3特别说明
  消息推送需要使用userid所以配置相关参数时请把idFromUserid设置为true
 idFromUserid:true,//钉钉id来自钉钉用户userid（默认false）

6.4配置邮箱信息

订阅主要消息是邮件，邮箱的配置 和 用户的邮箱信息是必不可少的

6.5发送的报表链接配置

在Cross_Task项目中config文件添加如下配置,接在6.2multiplatform后方

emailConfig: {

  agreement: "http",//发送的报表链接协议
  clientServer: "192.168.0.148",//发送的报表链接域名/ip地址120.236.240.186
  Cross_dingdingUrl:"http://192.168.0.148:3003",//单点登录集成服务地址如(http://ip:3003)
  port: 3000,//发送的报表链接端口
   sendEmailEnable: true,//订阅邮件发送开启
  image: true,//是否在邮件中显示预览图片和是否加载图片附件

}

6.6订阅报表

添加触发器，分配报表与用户，点击执行验证效果，是否有收到邮件与钉钉消息

配置之后点击右上角的“全部启动”

要确保分配的bi用户和钉钉用户匹配上，才会发送钉钉消息给对应的钉钉用户

注：如果接收到的订阅消息后，点击订阅消息打不开报表或者提示无权限，请检查分配的用户是否有报表的权限

6.7验证效果

钉钉消息如下图，邮件也会收到对应消息

7.V8.1.55版本新增功能
（1）第三方系统集成入口
从奥威BI平台首页的【系统管理】—【集成管理】进入，打开页面如下;


（2）功能及属性
a．基本信息
基本信息页是连通第三方和奥威BI的窗口。
第三方的基本信息包含了钉钉应用对应的AppKey、钉钉应用对应的AppSecret、钉钉应用对应的AgentID的钉钉企业的匹配信息，是连通第三方钉钉与奥威BI的关键。
PS：三者的获取方式参考： https://ding-doc.dingtalk.com/（钉钉开放平台）


b．匹配列
匹配列通过基本信息的窗口，将第三方钉钉用户与奥威BI通过API返回的字段一对一匹配。
匹配列页面包含的基本信息：API结果列、API结果列描述、用户表匹配列。
API结果列：根据API返回结果固定（字段）。
API结果列描述：固定描述。
用户表匹配列：匹配对应用户表字段，设置默认值，可更改。
PS：用户表匹配列根据API返回结果的字段匹配钉钉工号、钉钉手机和钉钉姓名。



注：用户表匹配列，userid和fmobile字段必须匹配，才可在匹配行进行操作，否则匹配行不能进行功能操作。



c．匹配行
匹配行是根据匹配列的匹配方式，匹配第三方钉钉用户与现有BI用户，同时还可以选择对应的第三方钉钉用户同步新增为BI用户。
 


1）用户匹配方式

用户匹配方式有以下4种匹配方式及匹配原则：
①根据钉钉工号匹配：自动根据匹配列中BI用户工号对应的API结果列匹配。
②根据钉钉手机匹配：自动根据匹配列中BI用户手机号对应的API结果列匹配。
③根据钉钉姓名匹配：自动根据匹配列中BI用户姓名对应的API结果列匹配。
④手动匹配：手动选择已有的BI用户绑定。
PS：用户匹配关系下拉（选择匹配方式）更新之后，下面表的【绑定用户列】自动更新，同时表的匹配关系自动更新。
注：在②根据钉钉手机匹配的匹配方式时，若钉钉用户的电话号码有多个（不唯一）时，按照此用户的第一个电话号码进行匹配。


2）选择筛选用户方式及搜索
选择筛选用户方式分为：获取全部用户、获取已匹配用户、获取未匹配用户等3种方式。


3）更新通讯录
我们内部逻辑是将第三方用户的信息表复制到BI的数据库表中方便做一些复杂业务逻辑，所以当第三方用户信息有更新时并不会实时同步到BI存储的第三方用户表，这时就可以通过更新通讯录来同步信息。
例：第三方钉钉通讯录有新增用户张三，管理员可以通过更新通讯录功能将张三的钉钉信息同步到BI中的第三方用户表中，从而才可以进一步使用同步功能将张三同步到BI用户表中成为BI用户。

 
4）同步
我们使用更新通讯录功能将第三方用户的信息表复制存储到到BI的数据库中，进一步使用同步功能将张三同步到BI用户表中成为BI用户。
例：第三方钉钉用户有张三、李四、王五三个用户，BI用户只存在其中部分用户或者不存在其中的用户，这时就可通过同步功能将第三方用户同步成为BI用户。

 
（3）移动端入口
手机钉钉-工作台-115测试（窗口）。

 
从手机端钉钉的bi第三方窗口登陆bi，成功登陆打开的页面如下：