1. 概述
1.1 版本
| 报表服务器版本 | JAR 包版本 | 插件版本 |
|---|---|---|
| 10.0 | 2019-06-11 | V1.9 |
1.2 简道云简介
简道云是一款专业的数据收集和数据管理工具。通过在线的数据收集、数据分析、团队协作，让您可以 DIY 自己的数据管理平台。
FineReport 和简道云在数据管理场景下各有优劣，简道云在支撑业务部门新增的数据采集场景有其灵活方便的优势，而 FineReport 在数据展现上是更加灵活和丰富的。
有关简道云的详细介绍可以参见：简道云官网
1.3 应用场景
设计器安装「报表对接简道云插件」，可以实现 FineReport 和简道云的数据对接，能提供给客户更好的数据解决方案。
注：该插件暂不支持对接简道云私有化版本，详情参见本文 4.5 节的说明。
1.4 功能简介
可将简道云中的数据通过 FineReport 抽取到私有库中。并且当简道云开启推送后，FineReport 会随着简道云的数据更新而更新。
2. 操作步骤
需注意以下几点：
1）如果报表工程内存在%FR_HOME%/webapps/webroot/WEB-INF/lib/commons-codec-1.6.jar，则需要删除。
2）若只是同步数据，不需要推送，需要满足：FineReport 工程所在的服务器可以 ping 通云中心的地址：cloud.fanruan.com。如下图所示：
3）若需要数据推送，FineReport 报表服务器地址需要配置外网。
如果服务器在内网，需要配置一层转发，在转发服务器配置简道云网络白名单，具体简道云 ip 和域名可以联系 简道云技术人员。
4）该插件目前只支持 MySQL 数据库。
2.1 安装插件
点击下载插件：报表对接简道云插件
设计器插件安装方法参照 设计器插件管理
服务器安装插件方法参照 服务器插件管理
插件安装完成后，默认启用，管理员登录决策系统，点击「管理系统>简道云对接」，可以进入配置页面。如下图所示：
2.2 简道云创建 API Key
在登录简道云且已购买的情况下，如下图查看简道云的 API Key，即简道云密钥，若没有看到 API Key，点击创建 API Key 即可。如下图所示：
2.3 简道云表单开启数据推送
数据推送（Webhook）可将表单数据推送到 FineReport 服务器，功能介绍及使用说明参见简道云帮助文档：数据推送
注：若需要数据推送，FineReport 报表服务器地址需要配置外网。
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 FineReport 插件同步表单数据
2.4.1 配置关联第一次同步数据
1）管理员登录决策系统，点击「管理系统>简道云对接>数据同步>配置关联」，填写简道云密钥，填写私有数据库的信息：包含驱动、地址、用户名、密码，示例使用的是 MySQL 数据库，如下图所示：
需要注意以下几点：
私有库暂时只支持 MySQL 数据库。
「地址」处填写格式为：jdbc:mysql://IP:端口号/<数据库名>
MySQL 数据库同步含有 emoji 的文本会出错，需要先把 MySQL 数据库改成 utf8mb4 编码。
如果简道云传过来的是数组，FineReport 转化成字符串，要用","分隔。
2）点击「开始连接」，连接成功后，点击「开始同步」，弹出「同步成功」，如下图所示：
3）同步成功后可以看到状态变为「关联成功」，同时简道云里的表单也同步到私有库里，如下图所示：
注：同步到 MySQL 数据库中的表中，有些表包含 _childid 字段，该字段表示当前子表单的 id ；_id 代表父表单的 id 。
2.4.2 修改私有库表名
配置成功后，可以双击私有库表名，进行重命名，勾选对应表单名，然后点击「同步表单数据」即可，如下图所示：
注：修改私有库表名后，在简道云中关闭数据推送时，会删掉数据库中同步表的记录，再次开启推送时会重新按照规则生成新的表名。
2.4.3 同步表单或表单数据
表单和表单数据支持「自动同步」和「手动同步」两种方式：
自动同步：当表单出现变化时，简道云系统会自动将表单变化推送给数据决策系统。
手动同步：管理员手动触发从简道云同步到数据决策系统的同步。
1）自动同步
管理员必须在简道云端设置数据推送，表单方可进行实时同步。
如未设置推送，仅在数据决策平台设置了关联库，则虽然显示同步成功，但无相关数据。
2）手动同步
管理员可在数据决策系统端手动点击「同步表单」/「同步表单数据」按钮，实现手动同步简道云数据到数据决策系统。
同步设置如下图所示：
同步表单：同步表结构的变化，包含数据库表的增删改和表字段的增删。
同步表单数据：同步表内容的变化，包含表内容的增删改。
2.5 运行监控
切换到「运行监控」标签页，只监控表结构的变化，包含数据库表的增删改和表字段的增删，不需要记录具体表数据的变化，如下图所示：
3. 扩展内容
3.1 解析子表单
如果有子表单，报表对接简道云插件 V1.5 及之后的版本支持解析子表单，如下图所示：
3.2 配置存储
1）私有库相关的配置信息存储到 jdyconfig.xml 中，xml在插件所处文件夹下，例如：/WEB-INF/plugins/plugin-com.fr.plugin.third.integrate.jdy-1.0/jdyconfig.xml
2）表单和表名的对应关系存储到数据库里（同步的 MySQL 数据库里）
在私有库配置成功后，数据库中新增表JDY_CONFIG（如果已存在则加数字编号，从 0 开始），表结构如下：
| 字段 | 含义 |
|---|---|
| id | 主键 |
| jdyformid | 简道云表单 id |
| jdyformname | 简道云表单名称 |
| frtablename | FineReport 私有库表名称 |
3）表字段的 ID 和实际名称的对应关系存储到数据库（同步的 MySQL 数据库里）
数据库中新增表 JDY_FIELD_CONFIG（如果已存在则加数字编号，从0开始），表结构如下：
| 字段 | 含义 |
|---|---|
| id | 主键 |
| jdyformid | 简道云表单 id |
| jdyfieldid | 简道云字段 id |
| jdyfieldname | 简道云字段名称 |
表JDY_FIELD_CONFIG 中存在以下固定字段 ID：
| 字段 ID | 含义 |
|---|---|
| creator | 提交人 |
| updater | 修改人 |
| deleter | 删除人 |
| createTime | 提交时间 |
| updateTime | 更新时间 |
| deleteTime | 删除时间 |
| flowState | 流程状态 |
| ext | 扩展字段 |
4. 注意事项
4.1 MySQL 数据库乱码
报表对接简道云时，使用的 MySQL 数据库若中文乱码，请参见：MySQL数据库中文乱码 解决。
4.2 禁止向保留地址发送 API 请求
问题描述
数据推送时，推送失败，报错：禁止向保留地址发送API请求。如下图所示：
原因分析
FineReport 报表服务器地址不是外网。
解决方案
数据推送时，FineReport 报表服务器地址需要配置外网。如果服务器在内网，需要配置一层转发，在转发服务器配置简道云网络白名单，具体简道云 ip 和域名可以联系帆软技术人员。技术支持联系方式：前往「服务」，选择「在线支持」、电话「400-811-8890」。
4.3 参数不正确
问题描述
报表配置关联时报错：参数不正确。如下图所示：
原因分析
简道云密钥填写错误。
解决方案
参考本文 2.2 节复制正确的简道云密钥。
4.4 同步失败没有数据
问题描述
报表关联成功，也获取到了表单，但是同步失败没有数据。
解决方案
数据库的编码设置为utf-8。详情请参见：配置MySQL5外接数据库 文档的 2.3 节内容。
4.5 不支持简道云私有化版本
目前插件不支持简道云私有化版本，插件对接私有化版本，数据同步会报错：同步失败，请检查数据连接或网络连接，如下图所示：