1. 概述
1.1 版本
| FineBI 版本 | 微信管理插件 | HTML5移动端展现插件 |
|---|---|---|
| 6.0 | V11.0 | V11.0 |
1.2 功能简介
安装微信管理插件，可实现微信集成
在定时调度的输出设置中，可以配置并推送微信消息
支持集成多个应用
注：示例的是非私有化部署环境下的集成步骤。
1.3 注意事项
注意事项 1
BI服务器一定是可以被外网访问的，并且一定是域名地址，不能用 IP 地址。域名地址举例http://xxx.xxx.com：xxx/webroot/decision。如果是http://IP:xxx/webroot/decision，是不可以做微信集成的。
注意事项 2
BI 服务器需要能访问外网，若 BI 服务器在内网，无法访问到微信服务器的话，需要进行正向代理配置，代理配置参考：微信钉钉集成环境准备 4.3 服务器私有化部署
2. 前期准备
2.1 安装插件
点击下载插件：微信管理、HTML5 移动端展现插件
插件安装方法参照 插件管理
2.2 配置环境
1）不建议用户在本地工程做企业微信集成，建议将 BI 工程部署到 tomcat 服务器参见 tomcat服务器部署 中，做企业微信集成。
2）在配置集成之前，必须先完成网络环境配置，参考文档：微信钉钉集成环境准备
3. 新建应用
3.1 微信后台创建应用
1）管理员登录企业微信后，在「应用管理」Tab 下点击「创建应用」，如下图所示：
2）上传应用「 logo」，填写「应用名称」，「应用介绍」选填。设置「可见范围」（必须是部门），设置完成后，点击「创建应用」。
注：若「可见范围」不是部门而是单独的微信用户，那么在平台「微信管理>成员管理」 下会看不到用户信息，因为右边的组织机构是空的，而用户是属于部门的，所以也是空的。
对于单独的微信用户，建议先在企业微信通讯录设置好标签，再通过标签的方式添加到FineReport中。
3.2 获取应用参数
微信应用创建成功之后，需要关注两个参数：
| 参数 | 含义 |
|---|---|
| CorpID | 企业 ID |
| Secret | 授权码 |
3.2.1 CorpID
点击我的企业，可查看企业ID，如下图所示：
注：企业 logo 和简称可以修改。
3.2.2 Secret
1）点击「应用管理」，点击已创建的应用，如下图所示：
2）点击可查看 Secret ，如下图所示：
4. 平台微信管理
在 2.1 节安装插件后，以管理员身份进入数据决策系统，点击「管理系统>微信管理」，如下图所示：
4.1 应用管理
4.1.1 设置服务器地址
必须设置「报表服务器地址」并保存如下图所示。如果不设置，推送的时候可能会有问题，例如：http://域名:端口号/webroot/decision
注：请使用二级或二级以上域名，且需通过 ICP 备案。
4.1.2 新建企业微信应用
点击「新建微信应用」，输入相应的「企业应用名称」、和 3.2 节获取的「CorpID」、「Secret」，点击确定，如下图所示：
注：请填写合乎规范的信息，企业应用名称、CorpID、Secret 不可为空，且应用名称不可与其他应用的重复。
新建微信应用成功后，可对信息进行修改和删除，支持集成多个微信应用。如下图所示：
4.2 应用快捷配置
4.2.1 微信代理跳转
外网环境：
外网环境不需要设置代理服务器地址。
内网环境：
若 BI 服务器是配置在内网，则需要配置代理服务器地址，来进行微信的访问。
1）先判断报表服务器上，ping qyapi.weixin.qq.com，能 ping 通，「微信管理>应用快捷配置>代理服务器地址」不用填写。
2）ping 不通，找一个代理服务器配置 nginx 正向代理，代理配置如下：
server {
listen 8113; // 微信代理服务器端口
server_name 10.2.2.3; //微信代理服务器IP
location / {
proxy_redirect off;
proxy_pass https://qyapi.weixin.qq.com;//微信服务器域名
}
location = /favicon.ico {
log_not_found off;
}
}
3）平台配置
文本框中输入正确的「代理服务器地址」，点击「测试连接并保存」，当连接成功，提示「连接成功」如下图所示：
注：当客户需要配置正向代理时，可将对应代理服务器的地址填写在快捷配置这里，具体正向代理的配置可以参考：微信钉钉集成环境准备第 4 节
4.2.2 主页型应用快速配置
生成微信链接包含两种方法：主页型应用快速配置、生成微信链接
主页型应用快速配置：
应用场景：
如果客户这里要用配置的主页，是想要直接登录到 BI 平台，显示移动端的目录的话，只需要在上面点击微信「一键配置」，会自动把各个 url 都填写上的，不需要用户额外操作。
操作步骤：
1）选择需要配置的「企业应用名称」点击「一键配置」，即可快速的配置主页型应用，不需要用户再到微信后台配置。如下图所示：
2）若配置前，微信应用的主页链接和菜单为空，「一键配置」后进入第 3 节新建的微信应用，「可信域名」、「应用主页链接」、「自定义菜单」中设置一个菜单并添加主页链接已设置完成。如下图所示：
4.2.3 生成微信链接
可以生成两种微信链接：一是用来单点登录到平台目录的；二是用来单点登录到模板的。
生成链接的时候一定要选择对应「企业应用名称」。
应用场景：1）应用的 主页 配置；2）定时调度最后一步「文件处理>客户端通知」推送「自定义链接」。可参考文档：定时调度任务设置步骤；
4.2.3.1 生成微信链接
1）生成访问决策平台的微信链接
选择「企业应用名称」，链接的页面为「决策平台」，点击「生成链接」，点击「复制」，如下图所示：
2）生成访问某个模板的微信链接
首先，选择「企业应用名称」，链接页面选择「单个模板」，然后，选择要生成链接的仪表板或者模板，点击「生成链接」后「复制」。
单个模板可设置「BI仪表板」和「报表」：
单个模板选择「BI仪表板」时：
①（只有选择仪表板和制作仪表板的人都在同一部门，该情况才生效）若用户分配到部门，可选择到：部门内可管理用户制作的仪表板、其他部门的用户制作的仪表板、自己账号下的仪表板；
②若用户未分配到部门，跟随定时调度的权限规则。
注 1：若没有设置其他用户的管理权限，则只能选择自己的仪表板。
注 2：关于用户部门管理可参考：用户管理
单个模板选择「报表」下模板时：操作步骤参考报表平台的 企业微信集成 4.2.3 节单个模板设置内容。
3）生成自定义链接
生成在微信能够访问的轻应用链接。
首先，选择「企业应用名称」，生成「自定义链接」并填入「移动端轻应用」中生成的链接。然后点击「生成链接」并复制即可。如下图所示：
生成的链接：
4.2.3.2 设置应用主页链接
进入第 3 节新建的微信应用，设置「应用主页」，如下图所示：
3）在「工作台应用主页」中点击设置「网页地址」，粘贴 BI 平台中生成的微信链接，点击「确定」。如下图所示：
4）在「自定义菜单」中点击「设置」，填写主菜单，设置菜单内容为跳转到网页，填写网址（上面生成的微信链接粘贴过来），点击保存，如下图所示：
点击发布，如下图所示：
5）在「网页授权及JS-SDK」中点击设置可信域名，输入可信域名，点击确定。如下图所示：
4.2.4 申请域名校验
1）打开第 3 节新建的应用，在网页授权及JS-SDK中点击申请校验域名，点击下载文件，下载校验文件。
2）把 txt 校验文件放在根目录下。例如：%FineBI_HOME%/webapps/ROOT/ 。如果修改了服务器根目录的，就要做对应调整。
注：本地安装部署的 BI 和部分独立部署的工程本身没有 ROOT 路径。Tomcat 可以自行创建路径。
本地安装部署的自行创建也不生效，不建议本地部署的工程做集成。
3）勾选已上传域名归属校验文件，点击确定，看到已启用，说明域名校验成功。如下图所示：
示例中的可信域名为：secure.finedevelop.com:63777
4.2.5 新建微信群
用户可使用应用新建微信群，自定义「微信群名称」、「群主」和「群成员」，支持通过定时调度推送群消息到微信群。
注：除群主外，群成员不可少于 2 人。
详情请参见文档：定时调度客户端通知-APP通知
成功添加后如下图所示：
4.3 成员管理
4.3.1 用户匹配方式
可根据实际情况选择一种用户匹配方式。
用户匹配方式：微信号匹配、手机账号匹配、手动匹配、自定义匹配。「成员管理」页面如下图所示：
注1：不管集成几个微信应用，用户统一进行管理。
注2：企业微信安全策略升级，企业微信在userId换取用户信息的接口中，不再返回手机号码。
因此2022-06-20之后新建的应用不推荐使用手机号匹配，可以使用微信号匹配等其他匹配方式的功能，但老的应用不受影响。
注3：切换了匹配方式后，都需要再次同步一下用户。
注4：若用户匹配不成功，用户通过企业微信登录系统时，单点登录失败，需要重新输入用户名密码。
微信号匹配：
微信号匹配和手机号匹配展示列相同。
微信号匹配，则是微信成员名与 BI 里的用户名匹配，为一对一匹配。
手机号匹配，微信用户的手机号是唯一的，但是 BI 用户可以设置多个用户有同一个手机号，此时的匹配逻辑为哪个报表用户先创建则匹配哪个
选择这两个匹配方式时，微信通讯录信息展示：微信成员名、姓名、微信部门、微信成员手机号，如下图所示：
注：这些匹配的用户信息并不会存到某张表里。
手动匹配：
当匹配方式为手动匹配时，微信成员列表中多出「报表用户名」一列信息，点击出现下拉框，选择相应的报表用户名，进行手动匹配。如下图所示：
注1：手动匹配时，BI 用户名支持选择「不选」选项。
注2：手动匹配方式是用户可以自由选择与微信用户匹配的 BI 用户，可实现多个微信用户匹配同一个 BI 用户。
自定义匹配：
即通过设置的服务器数据集，将对应数据列的微信用户和报表用户相匹配。若出现一个微信用户对应了多个报表用户的情况，默认匹配第一个报表用户
选择自定义匹配时，下方多出「匹配设置」项，选择数据集、微信用户名及报表用户名，进行匹配。如下图所示：
注：自定义匹配时，微信用户列填写的是微信用户名。
4.3.2 通讯录更新
点击左侧「立即更新」按钮，立即更新通讯录内容。也可设置定时更新。
点击「设置自动更新」按钮，弹出设置框，设置更新频率。
注1：用户匹配方式为「微信号匹配」或「手机号匹配」时，如果用户增删改 BI 用户或者在后台增删改微信用户，需要手动同步通讯录更新。
注2：用户匹配方式为「手动匹配」或「自定义匹配」时，如果用户增删改 BI 用户或者在后台增删改微信用户，无需更新同步。
5. 效果查看
完成集成后，用户即可在微信的 PC 端或移动端查看 FineBI 工程和仪表板了。
5.1 企业微信
进入企业微信，点击工作台，点击FineBI 微信集成，该用户会看到自己权限内可以查看的目录，如下图所示：
5.2 个人微信
上面描述为在企业微信中的效果。
普通微信可以扫描二维码关注，在普通微信中即可出现一个企业号，可在企业号中查看主页内容或收到推送消息。
1）在「通讯录」 ，点击微信邀请，邀请关注，扫描二维码，即可加入此企业。如下图所示：
2）进入企业后，点击创建的应用「应用主页」，设置看到的内容与是否勾选在「微信插件中始终进入主页有关」，如下图所示：
若勾选「在微信插件中始终进入主页」，收不到推送消息。
若不勾选「在微信插件中始终进入主页」，同时需要在「企业微信我>设置>新消息通知」里关闭「仅在企业微信中接受消息」，个人微信可收到推送消息，可以查看推送的内容和配置的自定义菜单，如下图所示：
6. 推送微信消息
1）参考［通用］定时任务推送消息至 App ，「文件处理」步骤中选择微信通知即可，如下图所示：
2）企业微信用户登录企业微信，可收到消息。如下图所示：
注：钉钉推送消息内容支持显示图片消息、文件消息，设置步骤详细可参考 微信钉钉推送支持其他消息类型
7. 注意事项
7.1 内网开放白名单
在做微信集成时，有的客户为内网环境，不允许所有网页都能访问，但要确保能访问微信的域名：https://qyapi.weixin.qq.com
7.2 企业微信 PC 端还是移动端效果
用户希望做了企业微信集成后，在使用 PC 端企业微信时，可以展示 PC 端效果，而不是移动端。
但是现有的方法集成后，PC 端使用时就是移动端效果，那么如何实现 PC端效果呢？
只需要修改下企业微信后台设置的链接，将 mobile 相关参数去掉即可，位置如下图所示：
7.3 网络异常
1）问题描述
企业微信集成在平台新建微信应用时，如下图所示：
添加的 CorpID 等信息，一直报错：网络异常，请检查网络配置或 access_token 为空，corpId 和 secret 设置错误，如下图所示：
2）解决方案
如果内网服务器访问外网正常，需要检查下报表平台的端口是不是被防火墙禁掉了，端口被禁就不能访问外网了。下面给出解决方案：
先在代理服务器上面向报表服务器开一个端口。
nginx 代理配置文件中配置正向代理。
平台上配置代理服务器地址，走通网络以后，添加应用正常，问题解决。
7.4 微信扫码登录报错
问题现象：
企业微信扫码登录，部分成员扫码后会报错，检查了该用户名，和企业微信名称一样；扫码出错的和正常的用户在权限配置上是一样的。
问题原因：
用户在平台没有绑定手机号。
解决方案：
1）可以先登录平台进行绑定手机号；
2）或者在同步用户时（或者手动添加用户时）添加上手机号，即也要维护手机号信息。
7.5 微信单点登录慢
问题现象：
微信单点从点击应用到显示目录，需要 3s 的时间。本地一般也是需要 3-4s 。
问题原因：
单点速度除了受网络、手机性能影响外，还受到数据传输和页面加载的 js 的影响。加载 H5 页面有如下几个耗时点：一是请求 js 资源，一个一般是 1 到 2 秒，然后浏览器把资源加载到内存，大概 200 毫秒，最后再把图形渲染出来也需要一些时间，导致页面加载缓慢。
8. 微信集成问题处理
1）环境是否配置好：微信钉钉集成环境准备
2）使用工具排查出现的各类常见（单点登录失败、同步通讯录失败、消息推送失败）问题：微信钉钉调试工具、微信钉钉推送/单点/同步失败通过日志定位
3）「微信管理」页面的「应用管理」报错；定时调度消息推送报错；网络异常等：微信钉钉应用列表报错
4）出现错误码，对照错误码找问题：微信钉钉错误码对照表
