报表对接简道云插件

1.1 版本

1.2 应用场景

简道云 是一款专业的数据收集和数据管理工具。通过在线的数据收集、数据分析、团队协作，让您可以 DIY 自己的数据管理平台。

FineBI 安装「报表对接简道云插件」，可以实现和简道云的数据对接，能提供给客户更好的数据解决方案。

注：该插件暂不支持对接简道云独享版本。

1.3 功能简介

可将简道云中的数据通过 FineBI 抽取到私有库中。并且当简道云开启推送后，FineBI 会随着简道云的数据更新而更新。

1.4 方案对比

对比项	方案一	方案二
方案简介	本文方法，通过安装「报表对接简道云」插件实现，当简道云开启推送后，私有库中的数据会随着简道云的数据更新而更新	本文不做介绍 FineDataLink 产品 中的 简道云输入 算子，可定时获取指定简道云表单的数据 示例图
数据去向	只支持将数据同步到 MySQL 数据库中	可以将数据同步到三十多种数据源，具体为： 数据开发支持的数据源类型 表格中，支持「数据写入」的数据库 注：简道云输出 算子可将处理后的数据输出到简道云表单中，供简道云使用
支持的简道云	只支持公有云	支持公有云和独享版本
数据处理	简道云中的数据直接通过 FineBI 抽取到 MySQL 数据库中	1）支持对简道云数据进行调整和修改后再进行同步数据 2）支持可视化的解析 json 数组格式
运维	-	支持完备的 任务运维 和错误排查，如果出现了错误，可以进行失败重跑和排查

需注意以下几点：

1）如果 BI 工程存在%BI_HOME%/webapps/webroot/WEB-INF/lib/commons-codec-1.6.jar，则需要删除。

2）若只是同步数据，不需要推送，需要满足：FineBI 工程所在的服务器可以 ping 通云中心的地址：cloud.fanruan.com。如下图所示：

3）若需要数据推送，FineBI 服务器地址需要配置外网。

     如果服务器在内网，需要配置一层转发，在转发服务器配置简道云网络白名单，具体简道云 ip 和域名可以联系 简道云技术人员。

4）该插件目前只支持 MySQL 数据库。

2.1 安装插件

点击下载插件：报表对接简道云插件

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

插件安装完成后，默认启用，管理员登录决策系统，点击「管理系统>简道云对接」，可以进入配置页面。如下图所示：

2.2 简道云创建 API Key

在登录简道云且已购买的情况下，如下图查看简道云的 API Key，即简道云密钥，若没有看到 API Key，点击创建 API Key 即可。如下图所示：

2.3 简道云表单开启数据推送

数据推送（Webhook）可将表单数据推送到 FineBI 服务器，功能介绍及使用说明参见简道云帮助文档：数据推送

注：若需要数据推送，FineBI 服务器地址需要配置外网。

1）在设计完表单之后，进入「扩展功能」，点击「数据推送>新建数据推送」，如下图所示：

2）在「目标服务器」位置选择「FineReport 服务器」，填写服务器地址，地址格式：http://主机名:端口/工程名/decision/view/report?op=fs_jdy

注1：地址中的主机名表示可以被外网访问的因特网主机域名或者 IP 地址，后面「/工程名/decision/view/report?op=fs_jdy」固定。

         如果服务器在内网，需要配置一层转发，在转发服务器配置简道云网络白名单，具体简道云 ip 和域名可以联系 简道云技术人员。

注2：请严格按照文档提供的地址格式填写服务器地址，「/view/report?op=fs_jdy」后缀不能省略。

示例：

http://116.48.6.212:8080/webroot/decision/view/report?op=fs_jdy

http://eqg5xg.natappfree.cc/webroot/decision/view/report?op=fs_jdy，其中端口为80，默认省略。

点击测试连接成功后，保存即可。    

3）设置完成，如下图所示：

注：这一步必须成功才可以，如果推送失败，简道云会重试最多 5 次。如果连续重试 5 次均失败，该表单的数据推送功能将被关闭，管理员将会获得消息通知。管理员需要在数据推送设置中重新启动数据推送，数据推送才会继续。

至此一张表单开启 Webhook 的工作已经完成，需要同步的表单，都需要开启 Webhook 。

2.4 插件同步表单数据

2.4.1 配置关联第一次同步数据

1）管理员登录决策系统，点击「管理系统>简道云对接>数据同步>配置关联」，填写简道云密钥，填写私有数据库的信息：包含驱动、地址、用户名、密码，示例使用的是 MySQL 数据库，如下图所示：

需要注意以下几点：

• 私有库暂时只支持 MySQL 数据库。

• 「地址」处填写格式为：jdbc:mysql://IP:端口号/<数据库名>

• MySQL 数据库同步含有 emoji 的文本会出错，需要先把 MySQL 数据库改成 utf8mb4 编码。

• 如果简道云传过来的是数组，FineBI 转化成字符串，要用","分隔。

2）点击「开始连接」，连接成功后，点击「开始同步」，弹出「同步成功」，如下图所示：

3）同步成功后可以看到状态变为「关联成功」，同时简道云里的表单也同步到私有库里，如下图所示：

注：同步到 MySQL 数据库中的表中，有些表包含 _childid 字段，该字段表示当前子表单的 id ；_id 代表父表单的 id 。

2.4.2 修改私有库表名

配置成功后，可以双击私有库表名，进行重命名，勾选对应表单名，然后点击「同步表单数据」即可，如下图所示：

2.4.3 同步表单或表单数据

简道云设置推送后，表单就是实时同步的。如未设置推送，仅在数据决策平台设置了关联库，则需要手动点击同步表单更新。

同步设置如下图所示：

• 同步表单：同步表结构的变化，包含数据库表的增删改和表字段的增删。

• 同步表单数据：同步表内容的变化，包含表内容的增删改。

2.5 运行监控

切换到「运行监控」标签页，只监控表结构的变化，包含数据库表的增删改和表字段的增删，不需要记录具体表数据的变化，如下图所示：

3.1 配置存储

1）私有库相关的配置信息存储到 jdyconfig.xml 中，xml在插件所处文件夹下，例如：/WEB-INF/plugins/plugin-com.fr.plugin.third.integrate.jdy-1.0/jdyconfig.xml

2）表单和表名的对应关系存储到数据库里（同步的 MySQL 数据库里）

在私有库配置成功后，数据库中新增表JDY_CONFIG（如果已存在则加数字编号，从 0 开始），表结构如下：

3）表字段的 ID 和实际名称的对应关系存储到数据库（同步的 MySQL 数据库里）

数据库中新增表 JDY_FIELD_CONFIG（如果已存在则加数字编号，从0开始），表结构如下：

表JDY_FIELD_CONFIG 中存在以下固定字段 ID：

4.1 MySQL 数据库乱码

报表对接简道云时，使用的 MySQL 数据库若中文乱码，请参见：MySQL数据库中文乱码 解决。

4.2 禁止向保留地址发送 API 请求

问题描述

数据推送时，推送失败，报错：禁止向保留地址发送API请求。如下图所示：

原因分析

FineBI 报表服务器地址不是外网。

解决方案

数据推送时，FineBI 服务器地址需要配置外网。如果服务器在内网，需要配置一层转发，在转发服务器配置简道云网络白名单，具体简道云 ip 和域名可以联系帆软技术人员。技术支持联系方式：「服务平台>在线支持」、电话「400-811-8890」。

4.3 参数不正确

问题描述

报表配置关联时报错：参数不正确。如下图所示：

原因分析

简道云密钥填写错误。

解决方案

参考本文 2.2 节复制正确的简道云密钥。

4.4 同步失败没有数据

问题描述

报表关联成功，也获取到了表单，但是同步失败没有数据。

解决方案

数据库的编码设置为utf-8。详情请参见：配置MySQL5外接数据库 文档的 2.3 节内容。