微信集成

1.1 版本

使用企业微信，需要报表服务器、H5、微信插件版本均匹配才能集成，版本的对应情况如下表所示：

1.2 功能简介

• 安装微信管理插件，可实现微信集成

• 在定时调度的输出设置中，可以配置并推送微信消息

• 支持集成多个应用

1.3 注意事项

注意事项 1 

报表服务器一定是可以被外网访问的，并且一定是域名地址，不能用 IP 地址。

域名地址举例 http://xxx.xxx.com：xxx/webroot/decision 。

如果是http://IP:xxx/webroot/decision，是不可以做微信集成的。

注意事项 2 

报表服务器需要能访问微信服务器。

若报表服务器在内网，无法访问到微信服务器的话，支持正向代理配置，代理配置参考：微信钉钉集成环境准备第 4 节 。

注意事项 3 

微信集成下若使用「扫码控件」、「文件控件」， 则要求单点登录、且域名必须经过校验。

校验方法请参考：「微信集成」文件控件&文本控件扫码无法使用 。

2.1 安装插件

点击下载插件：微信管理、HTML5 移动端展现插件

设计器插件安装方法请参见：设计器插件管理

服务器安装插件方法请参见：服务器插件管理

注：微信/钉钉集成过程中，必须确保各版本相对应，详情参见：微信、钉钉、H5、服务器、JAR 之间的依赖关系

2.2 配置网络环境

在微信集成之前，必须先完成网络环境配置，参考文档：微信钉钉集成环境准备 。

3.1 微信后台创建应用

1）管理员登录企业微信后，在「应用管理」Tab 下点击「创建应用」，如下图所示：

2）上传应用 logo，填写「应用名称」，「应用介绍」选填，设置「可见范围」，设置完成后，点击「创建应用」，如下图所示：

若「可见范围」不是部门而是单独的微信用户，那么在平台「微信管理」的「成员管理」 Tab下会看不到用户信息，因为右边的组织机构是空的，而用户是属于部门的，所以也是空的。对于单独的微信用户，建议先在企业微信通讯录设置好标签，再通过标签的方式添加到FineReport中。

3.2 配置可信IP和域名

由于企业微信针对自建及代开发应用进行安全性升级，2022 年 6 月 20 日之后创建的新应用，都必须先配置可信IP和可信域名。

详情可参见：关于企业微信自建应用安全性升级的说明 。

登录企业微信后台，选择「应用管理」，选择对应的应用，设置「企业可信IP」。如果客户遇到添加 IP，提示是第三方服务商IP（实际不是），需要找企业微信客服验证一下企业可信IP，如下图所示：

3.3 获取微信应用参数

微信应用创建成功之后，需要关注两个参数：

3.3.1 CorpID

点击「我的企业」，可查看「企业ID」，如下图所示：

注：企业 logo 和简称可以修改。

3.3.2 Secret 

1）点击「应用管理」，点击已创建的应用，如下图所示：

2）可查看 Secret ，如下图所示：

以管理员身份进入数据决策系统，点击「管理系统」>「微信管理」，如下图所示：

4.1 应用管理

4.1.1 报表服务器地址

必须设置「报表服务器地址」并保存，如果不设置，推送的时候可能会有问题，报表服务器地址示例：

http://域名:端口号/webroot/decision

注：请使用二级或二级以上域名，且需通过 ICP 备案。

输入「报表服务器地址」，如下图所示：

4.1.2 新建微信应用

点击「新建微信应用」，输入相应的企业应用名称、CorpID、Secret，点击「确定」，如下图所示：

注：请填写合乎规范的信息，企业应用名称、CorpID、Secret 不可为空，且应用名称不可与其他应用的重复。

新建微信应用成功后，可对信息进行修改和删除，支持集成多个微信应用。如下图所示：

4.2 应用快捷配置

4.2.1 微信代理跳转

注1：若报表服务器配置在外网环境中，则不需要设置代理服务器地址。

若服务器是配置在内网，访问不到微信服务器，访问不到外网的时候需要配置「代理服务器地址」。

若服务器是配置在内网，且客户服务器和外网能互相访问到，网络正常，则「微信管理>应用快捷配置>代理服务器地址」，不需要填写。

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.2 节

4.2.2 主页型应用快速配置

功能简介：

该功能即对微信主页应用进行快速配置，配置的内容包括：可信域名、应用主页链接、自定义菜单中设置一个菜单并添加主页链接。

应用场景：

如果客户这里要用配置的主页，是想要直接登录到平台，显示移动端的目录的话，只需要在上面点击微信「一键配置」，会自动把各个 url 都填写上的，不需要用户额外操作。

操作步骤：

默认为企业微信列表中的第一个，通过下拉框选择需要配置的企业应用名称，然后点击「一键配置」，即可快速的配置主页型应用，不需要用户再到微信后台配置。如下图所示：

若配置前，微信应用的主页链接和菜单为空，点击「一键配置」按钮后，直接进行快速配置。进入微信应用，可信域名、应用主页链接、自定义菜单中设置一个菜单并添加主页链接已设置完成，如下图所示：

4.2.3 生成微信链接

• 生成链接的时候一定要选择对应企业应用名称。
  

• 可以生成两种微信链接：一是用来单点登录到平台目录的；二是用来单点登录到模板的。

注：使用 V11.0.74 插件生成的单点链接，若回退插件，需使用老版本插件重新生成链接配置主页。

• 应用场景：应用的 主页 配置；

  定时调度最后一步「文件处理>客户端通知」推送「自定义链接」。可参考文档：定时调度任务详细设置步骤；

  模板消息事件插件推送。 模板消息事件插件 可以将该链接推送给移动端用户，用户点开后即可访问链接对应的内容。

4.2.3.1 生成微信链接

1）生成访问决策平台的微信链接

首先要选择「企业应用名称」，链接页面下拉选择「决策平台」，点击「生成链接」后，点击「复制」按钮即可。如下图所示：

2）生成访问某个模板的微信链接

首先要选择「企业应用名称」，链接页面下拉选择「单个模板」，然后选择一张模板，如果需要设置参数，可以点击「设置参数默认值」进行设置，设置了参数后点击「解析参数值」，最后点击「生成链接」，点击「复制」按钮即可，如下图所示：

3）生成自定义链接

生成在微信能够访问的应用封装链接。

首先，选择「企业应用名称」，生成「自定义链接」并填入「应用封装」中生成的链接。然后点击「生成链接」并复制即可。如下图所示：

生成的链接：

4.2.3.2 生成应用主页链接

如果只想主页那边挂一个模板，且支持单点登录打开模板，不仅需要在这里生成对应模板链接。

还需将生成的链接粘贴到微信工作台或者自定义菜单里。在「网页授权及JS-SDK」下设置可信域名/申请域名校验（域名例如：demo.fanruan.com，步骤请参考：「微信集成」文件控件&文本控件扫码无法使用）。

注：设置可信域名就是说的你的微应用地址是可用的、合法的。

1）设置「应用主页」。在「工作台应用主页」中点击设置「网页地址」，粘贴平台中生成的微信链接，点击「确定」。

2）在「自定义菜单」中点击「设置」，填写主菜单，设置菜单内容为跳转到网页，填写网址（上面生成的微信链接粘贴过来），点击「保存」并「发布」。

3）在「网页授权及JS-SDK」中点击设置可信域名，输入可信域名，点击确定。

注：设置可信域名就是说的你的微应用地址是可用的、合法的。

下面介绍下如何配置参数，如果想要使用「设置参数默认值」功能需要将插件更新到 V10.4.76 版本，如果想要使用「解析参数值」功能需要更新到 V10.4.97 版本。

• 设置参数默认值

点击「设置参数默认值」后，如果模板本身有参数，那么会显示在下方，用户可以设置参数的默认值，当然也可以点击右上角新增参数，如下图所示：

注：如果想删除参数，可以鼠标悬浮在参数列表的右边，会出现删除按钮。

• 解析参数值

假如一张模板「a.cpt」设置了一个参数「date」，其值为公式${today}。

1. 如果勾选了「解析参数值」，那么点击「生成链接」后，链接中会自动解析出今天的日期，也就是变成了：a.cpt&date=2020-11-03。点开模板会自动显示今天的数据信息（2020-11-03）。
   

2. 如果不想链接中直接解析参数，想要保留这个公式，可以取消勾选「解析参数值」，点击「生成链接」后，公式保留：a.cpt&date=${today}。

注1：微信/钉钉集成链接必须勾选解析参数值，否则将导致参数丢失。

注2：模板消息推送的消息链接可选择不解析参数值，从而实现推送的公式计算。

4.2.4 申请域名校验

步骤请参考文档：「微信集成」文件控件&文本控件扫码无法使用

4.2.5 新建微信群

JAR 包在 2020-07-08 及之后，且企业微信管理插件在 V10.4.80 及之后的版本，新增微信群设置。

用户可使用应用新建微信群，自定义微信群名称、群主和群成员，支持通过定时调度推送群消息到微信群。

详情请参见：微信定时推送消息

4.3 成员管理

4.3.1 用户匹配方式

可根据实际情况选择一种用户匹配方式。

用户匹配方式：微信号匹配、手机账号匹配、手动匹配、自定义匹配、邮箱匹配。「成员管理」页面如下图所示：

注1：不管集成几个微信应用，用户统一进行管理。

注2：企业微信安全策略升级，企业微信在userId换取用户信息的接口中，不再返回手机号码。

         因此2022-06-20之后新建的应用不推荐使用手机号匹配，可以使用微信号匹配等其他匹配方式的功能，但老的应用不受影响。

注3：切换了匹配方式后，都需要同步一下用户。

1）微信号/手机账号/邮箱匹配

微信号匹配、手机账号匹配 和 邮箱匹配 展示列及匹配规则相同。

• 微信号匹配，则是微信成员名与报表里用户名匹配，为一对一匹配。

• 手机账号匹配，微信用户的手机号是唯一的，但是报表用户可以设置多个用户有同一个手机号，此时的匹配逻辑为匹配用户存储表中按顺序查到的第一个报表用户 。

• 邮箱匹配，由于报表用户可以设置多个用户有同一个邮箱（企业微信的email字段），此时的匹配逻辑为匹配用户存储表中按顺序查到的第一个报表用户 。

注：建议保证用户一对一的匹配关系。

选择这三个匹配方式时，微信通讯录信息展示：姓名、微信成员名、微信部门、微信成员手机号 和 微信成员邮箱。如下图所示：

注：这些匹配的用户信息并不会存到某张表里。

2）手动匹配

当匹配方式为「手动匹配」时，微信通讯录信息展示：姓名、用户名、微信成员名、微信部门、微信成员手机号。如下图所示：

列表中多出「报表用户名」一列信息，点击出现下拉框，选择相应的报表用户名，进行手动匹配。如下图所示：

注1：手动匹配时，报表用户名支持选择「不选」选项。

注2：手动匹配方式是用户可以自由选择与微信用户匹配的报表用户，可实现多个微信用户匹配同一个报表用户。

3）自定义匹配

即通过设置的「服务器数据集」，将对应数据列的微信用户和报表用户相匹配。

若出现一个微信用户对应了多个报表用户的情况，默认匹配查到的第一个报表用户。

选择自定义匹配时，下方多出「匹配设置」项，选择「数据集」、「微信用户名」及「报表用户名」，进行匹配。如下图所示：

注：自定义匹配时，微信用户列填写的是微信用户名。

4.3.2 微信通讯录

点击左侧「立即更新」按钮，立即更新通讯录内容。也可设置定时更新，点击「自动更新」按钮，弹出设置框，设置更新频率。如下图所示：

注1：用户匹配方式为「微信号/手机账号/邮箱匹配」时，如果用户增删改报表用户或者在后台增删改微信用户，需要手动同步通讯录更新。

注2：用户匹配方式为「手动/自定义匹配」时，如果用户增删改报表用户或者在后台增删改微信用户，无需更新同步。

4.3.3 用户同步

报表版本 V11.0.2 ，微信管理插件版本 V11.0.54 之后，支持将企业微信通讯录的用户信息同步到「用户管理」界面中，保存到平台。

用户同步配置详情请参见：同步用户

注：微信用户的同步只是拿到微信用户信息表，为了后续跟报表用户表进行匹配关系的建立，微信用户的同步操作不会覆盖现有报表平台用户。

1）同步配置

在「用户管理」中进行「同步用户」，用户来源选择「从企业微信同步」，选中对应的微信应用，即可根据企业微信通讯录实现同步效果。

注：「微信管理>成员管理」的通讯录手动更新和自动更新；「用户管理>同步用户」都能实现平台用户信息的更新。

2）同步成功后，用户信息同步到平台。

注：因为企业微信接口限制，所以无法同步密码，报表用户初始密码随机生成。如果用户在 APP 或 PC 端想通过账号密码登录，需点击 忘记密码 ，重置后才能登录。

同步出现问题请参见：同步/导入用户常见问题

3）同步触发方式

注意事项：

1）企业微信通讯录添加的用户，要保证姓名、账号、部门、手机号不为空；

2）使用企业微信同步前，平台同步功能是打开的，且不能清空过同步数据；

不满足以上两点，同步企业微信用户到平台会失败

3）企业微信和平台同步字段的映射关系

将企业微信中的成员信息，同步到「用户管理」中时，每条字段的映射关系。

5.1 企业微信

进入企业微信，点击「工作台」，点击「FineReport 微信集成」，该用户会看到自己权限内可以查看的目录，如下图所示：

注：不建议在电脑版企业微信访问移动端模板。

5.2 个人微信

普通微信可以扫描二维码关注，在普通微信中即可出现一个企业号，可在企业号中查看主页内容或收到推送消息。

1）在「通讯录」 Tab 页下点击「微工作台」，点击「微信邀请」，邀请关注，扫描二维码，即可加入此企业。如下图所示：

2）进入企业后，点击应用，看到的内容与是否勾选「在微信插件中始终进入主页」有关，如下图所示：

• 若勾选在微信插件中始终进入主页，收不到推送消息。

• 若不勾选「在微信插件中始终进入主页」，同时需要在「企业微信」>「我」>「设置」>「新消息通知」里关闭「仅在企业微信中接受消息」，则可收到推送消息，可以查看推送的内容和配置的自定义菜单，如下图所示：

6.1 单点登录

在手机企业微信 App 里，您可以看到是不需要登录 FS，直接可以查看结果的。而如果您使用手机浏览器访问相同的报表，您会发现，是需要登录的。那是因为，将微信成员与报表用户关联后，通过微信企业应用进入查看报表时，在 FineReport 后台，我们会使用微信的 OAuth2.0 接口进行用户验证并获取对应微信成员名，然后关联报表用户并自动登录，从而实现微信单点登录。

6.2 权限控制

微信应用的菜单是在微信中管理，所以哪些成员可以看到的哪些报表这是在微信中控制。比如您可以创建多个报表应用，每个应用的查看权限选择不同的成员或组。

用户在微信中打开报表，是否可以查看报表的内容，以及可以查看的数据这部分是在 FR 报表端控制的，控制方法与 PC 端是一样的，比如可以通过角色控制可查看的报表，可以在报表模板中通过 SQL 语句通过用户名过滤来实现不同用户看到的数据不同等等。

7.1 内网开放白名单

在做微信集成时，有的客户为内网环境，不允许所有网页都能访问，但要确保对 qyapi.weixin.qq.com  这个域名开放访问权限。

7.2 微信扫码登录报错

问题现象：

企业微信扫码登录，部分成员扫码后会报错，检查了该用户名，和企业微信名称一样；扫码出错的和正常的用户在权限配置上是一样的。

问题原因：

用户在平台没有绑定手机号。

解决方案：

1）可以先登录平台进行绑定手机号；

2）或者在同步用户时（或者手动添加用户时）添加上手机号，即也要维护手机号信息。

7.3 微信单点登录慢

问题现象：

微信单点从点击应用到显示目录，需要 3s 的时间。本地一般也是需要 3-4s 。

问题原因：

单点速度除了受网络、手机性能影响外，还受到数据传输和页面加载的 js 的影响。加载 H5 页面有如下几个耗时点：一是请求 js 资源，一个一般是 1 到 2 秒，然后浏览器把资源加载到内存，大概 200 毫秒，最后再把图形渲染出来也需要一些时间，导致页面加载缓慢。

7.4 23001网络异常

微信部署代理服务器时，插件日志出现 error 级别的日志报错，报错码为「23001」则是网络异常的问题。

可以参考文档解决异常：代理服务器连接外网 3.1节。

1）环境是否配置好：微信钉钉集成环境准备

2）使用工具排查出现的各类常见（单点登录失败、同步通讯录失败、消息推送失败）问题：微信钉钉调试工具、微信钉钉推送/单点/同步失败通过日志定位

3）「微信管理」页面的「应用管理」报错；定时调度消息推送报错；网络异常等：微信钉钉应用列表报错

4）出现错误码，对照错误码找问题：微信钉钉错误码对照表