序言
此手册描述如何集成 商务智能 插件,此插件用来集成 CUBA 应用程序和 Pentaho Platform。
此处假设读者对于 CUBA 框架开发者手册都很熟悉,手册地址: https://www.cuba-platform.com/manual 。
如果您有任何关于提高本手册的建议,请在源码仓库提交 issue:https://github.com/cubacn/documentation[GitHub]。如果您发现了任何拼写或文字错误、bug 或者任何不一致的地方,请直接 fork 仓库修改。谢谢!
1. 插件概览
此 BI 插件提供以下功能:
-
注册和运行 Pentaho 报表的通用界面。访问注册报表可以通过 CUBA 安全角色进行限制。
-
提供可以将 Pentaho 报表嵌入到任何应用页面的可视化组件。
-
在 CUBA 应用和 Pentaho 之间做单点登录。机制如下:
-
用户需要在 CUBA 应用和 Pentaho 有相同的登录名。
-
当用户打开一个报表的时候,CUBA 应用为用户生成一个 ticket,并且将用户名和 ticket 添加到 Pentaho 请求中。ticket 保存在用户会话里。
-
在 Pentaho 服务器的 CUBA 插件检测到跟请求一起发送的 ticket,然后调用应用程序检查 ticket 是否有效。
-
如果 ticket 有效,在 Pentaho 服务的 CUBA 插件会使用为 Pentaho 平台配置的用户角色来给用户做认证。
-
2. 配置 Pentaho
-
下载并安装 Pentaho 社区版。
-
从 http://www.pentaho.com/marketplace/ 下载 Saiku Analytics 插件 (Meteorite BI),然后安装。
-
将
saiku
移到$PENTAHO_HOME$/pentaho-server/pentaho-solutions/system
下面,这里$PENTAHO_HOME
是 Pentaho 安装的目录。 -
如果 Saiku 插件跟最新版本的 Pentaho 服务器不兼容的话,按照下面步骤解决:
-
从
$PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku/lib
目录删除cpf-core-6.0.0.0-353.jar
和cpf-pentaho5-6.0.0.0-353.jar
。 -
从 Pentaho 的安装目录(比如
$PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/sparkl/lib
或者…/cgg/lib
)拷贝新的 lib 到$PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku/lib
目录。cpf-core-7.1.0.0-12.jar cpf-pentaho-7.1.0.0-12.jar cpk-core-7.1.0.0-12.jar cpk-pentaho5-7.1.0.0-12.jar
Tip也许安装的 Pentaho 版本不带
cpk-core…
和cpk-pentaho…
Jar 包。这样的话只需要使用cpf-core
和cpf-pentaho
Jar 包。
-
-
访问 http://licensing.meteorite.bi 并且注册一个新账号。验证了账号之后,创建一个公司,并且为公司生成一个社区版许可:
-
登录系统点击 CREATE NEW LICENSE 按钮。
-
在创建新许可的页面设置许可类型为:COMMUNITY_EDITION。
-
保存然后下载许可。重命名许可文件为
license.lic
然后拷贝该文件到$PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku
目录。
-
-
下载并安装 Pentaho Data Integration 工具。
-
更改 Pentaho 默认端口为 18081:
-
目录切换到
$PENTAHO_HOME/pentaho-server/tomcat/conf
。 -
在
server.xml
文件中修改 Tomcat 默认端口为 18081:
<Connector URIEncoding="UTF-8" port="18081" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="18443" />
-
-
在
server.xml
修改 Tomcat shutdown 端口为 8015,避免跟 CUBA 默认的 shutdown 端口冲突:<Server port="8015" shutdown="SHUTDOWN"> ... </Server>
-
在 Pentaho 设置 CUBA 用户的认证:
-
下载 cuba-bi-pentaho-1.5.0.jar 然后拷贝到
$PENTAHO_HOME$/pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib
。 -
下载 cuba-bi-pentaho-1.5.0-plugin.zip,解压后拷贝
saiku-cuba-bi
目录到$PENTAHO_HOME/pentaho-server/pentaho-solutions/system
。 -
在
$PENTAHO_HOME/pentaho-server/pentaho-solutions/system
目录创建新文件cuba-pentaho-community-authentication.xml
,并添加如下内容:<?xml version="1.0" encoding="UTF-8"?> <!--+ | Application context containing FilterChainProxy. +--> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util" xmlns:sec="http://www.springframework.org/schema/security" xmlns:pen="http://www.pentaho.com/schema/pentaho-system" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-4.1.xsd http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-4.1.xsd http://www.pentaho.com/schema/pentaho-system http://www.pentaho.com/schema/pentaho-system.xsd" default-lazy-init="true"> <!-- ======================== FILTER CHAIN ======================= --> <!-- if you wish to use channel security, add "channelProcessingFilter," in front of "httpSessionContextIntegrationFilter" in the list below --> <bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy"> <constructor-arg> <util:list> <sec:filter-chain pattern="/webservices/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,cubaAuthenticationFilter,basicProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" /> <sec:filter-chain pattern="/api/repos/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,cubaAuthenticationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS,preFlightFilter" /> <sec:filter-chain pattern="/api/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,cubaAuthenticationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" /> <sec:filter-chain pattern="/plugin/reporting/api/jobs/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS,preFlightFilter" /> <sec:filter-chain pattern="/plugin/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" /> <sec:filter-chain pattern="/**" filters="securityContextHolderAwareRequestFilter,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,httpSessionReuseDetectionFilter,logoutFilter,authenticationProcessingFilter,cubaAuthenticationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,sessionMgmtFilter,exceptionTranslationFilter,filterInvocationInterceptor" /> </util:list> </constructor-arg> </bean> <bean id="cubaAuthenticationProvider" class="com.haulmont.addon.bi.pentaho.CubaAuthenticationProvider"/> <!-- ======================== AUTHENTICATION ======================= --> <bean id="authenticationManager" class="org.springframework.security.authentication.ProviderManager"> <constructor-arg> <util:list> <ref bean="cubaAuthenticationProvider"/> <pen:bean class="org.springframework.security.authentication.AuthenticationProvider"/> <ref bean="anonymousAuthenticationProvider" /> </util:list> </constructor-arg> <property name="eraseCredentialsAfterAuthentication" value="false" /> <property name="authenticationEventPublisher"> <ref bean="defaultAuthenticationEventPublisher" /> </property> </bean> <bean id="cubaAuthenticationFilter" class="com.haulmont.addon.bi.pentaho.CubaPentahoAuthenticationFilter"> <property name="userRoleDao"> <ref bean="userRoleDaoTxn" /> </property> <property name="authenticationManager"> <ref bean="authenticationManager" /> </property> <property name="extraRoles" ref="extraRoles" /> <property name="cubaConnectionUrl" value="http://localhost:8080/app"/> </bean> </beans>
Tip在
cubaAuthenticationFilter
bean 中的cubaConnectionUrl
属性设置 CUBA 应用程序的 URL:<property name="cubaConnectionUrl" value="http://localhost:8080/app"/>
-
在
pentaho-solutions/system
目录下编辑pentaho-spring-beans.xml
文件在<import resource="applicationContext-spring-security.xml" />
后添加一行<import resource="cuba-pentaho-community-authentication.xml" />
:<import resource="applicationContext-spring-security.xml" /> <import resource="cuba-pentaho-community-authentication.xml" />
-
-
启动 Pentaho 服务:
-
切换到
$PENTAHO_HOME/pentaho-server
目录。 -
运行
start-pentaho.bat
-
3. 快速开始
我们创建了一个小项目用来示范怎么通过 BI 报表增强 CUBA 应用。这个 demo 应用是演示客户(customers)和订单(orders)的管理,包含一个运行在 Pentaho 服务的嵌入式 Saiku 报表。
3.1. 配置 CUBA 示范应用
-
克隆(clone)或者下载项目: https://github.com/cuba-platform/cuba-bi-demo.git
-
在 IDE 或者 CUBA Studio 中打开这个项目,运行
createDb
命令并且启动应用服务。
3.2. 加载数据到 Star Schema
在我们的 Pentaho 报表中,将会使用从多个数据库表做的聚合数据。这些数据会存在额外的表里面,然后加载到 Star Schema。Star Schema 会包含一个事实表(fact table) - Orders,以及两个维度表(dimension tables) - Customer 和 Product,由此提供可以下钻(drill)的报表结构。
3.2.1. Loading Data For the Impatient
可以使用 demo 项目携带的准备好的 Star Schema。
-
确保在 Studio 中打开 demo 项目。下面解释的导入过程将会访问项目的 HSQL 数据库。
-
运行 Pentaho Data Integration(数据集成)工具:
-
切换到 Pentaho Data Integration 的安装目录。
-
运行
spoon.bat
.
-
-
打开
$BI_DEMO_PROJECT/demo/kettle/bidemo.kjb
,这里$BI_DEMO_PROJECT
是 demo 项目的目录。 -
点击 Run 来更新 Star Schema。
Figure 1. Star Schema
现在可以继续创建分析报表。
3.2.2. 创建数据库连接
如果需要自己创建 Star Schema,按照下面的步骤做即可。详细介绍可以咨询 Pentaho wiki。
-
在
$PENTAHO_HOME$/design-tools/data-integration
目录,用spoon.bat
启动 Pentaho Data Integration。 -
创建新变换(transformation)。
-
为变换创建新数据库连接:
-
输入 Connection Name(连接名称)
-
Connection Type(连接类型): Hypersonic
-
Access(访问方式): Native (JDBC)
-
Host Name(主机名称): localhost
-
Database Name(数据库名称): bidemo
-
Port Number(端口号): 19001
-
User Name(用户名): sa
-
Password(密码)字段留空
Figure 2. 数据库连接 -
3.2.3. 创建维度表
维度表将使用 Products 和 Customers。每个 Product 会关联一些 product line(产品线),产品线就是产品的种类,比如 Ford T 属于 Vintage Cars 产品线。
Customers 属于特定的城市,这些城市属于某些国家,国家又按照洲分布。
-
首先,创建 Product 变换。拖拽 Table input 节点到工作簿(worksheet)并且定义报表需要的字段:product
id
,name
和product_line_id
。Figure 3. Product 表输入 -
然后创建 products 的插入/更新节点:
Figure 4. 插入/更新 Product -
创建 product lines 变换:
Figure 5. Product 变换 -
通过 Update 节点完成第一个变换:
Figure 6. 更新 Product -
按照相同的方式创建 Customer 变换,包含城市和洲级别。然后添加到第一个 Product 中:
Figure 7. Customer 变换 -
当变换准备好之后,再套上外围相应的任务,START - 启动 和 Success - 成功,以及 Abort job 节点用来做出错时退出:
Figure 8. 维度任务
3.2.4. 创建事实表
对于事实度量,使用 Orders 和 Order line。
-
首先,创建 Order Line 变换。拖拽 Table input 节点到工作簿(worksheet)并且定义报表需要的字段:
id
、product_id
、quantity
和order_id
:Figure 9. OrderLine 表输入 -
然后创建 order lines 的插入/更新节点:
Figure 10. 插入/更新 OrderLine -
创建 orders 变换:
Figure 11. Order 变换 -
最后,在表中更新 customer ID:
Figure 12. 更新 customers -
现在事实变换创建好了:
Figure 13. 事实变换 -
在变换外面套上相应的任务:
Figure 14. Facts job
3.3. 配置 Pentaho 分析报表
-
打开 Pentaho 终端:
http://localhost:18081/pentaho
用Admin/password
登录。 -
点击 File → Manage Data Sources(管理数据源).
-
点击配置按钮然后选择 New Connection - 新建连接:
Figure 16. 数据库连接 -
创建 HSQLDB 连接:
-
Host Name:
localhost
-
Database Name:
bidemo
-
Port Number:
19001
-
User Name:
sa
Figure 17. 数据库连接 -
3.3.1. 使用 Demo 报表
下面是查看 Saiku 报表样式的最简单方法,只需要导入带有分析和报表结构的 ZIP 文件。
-
点击 Import Analysis - 导入分析.
-
选择
BIDemo
数据源并且导入$BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip
Mondrian 文件,报表的结构也会被导入。Figure 18. 导入分析 -
点击 New → Saiku Analytics → Create a new query。选择
BiDemo
Cube 然后按照这个页面填写 measure, columns, 以及 rows:Figure 19. 创建查询 -
在
/home/admin
目录保存报表,名称为ProductsByTypeAndLocation
。
现在可以在 CUBA 应用中打开 Saiku 报表。
3.3.2. 手动创建数据源和分析报表
- 创建数据源
-
-
点击 New 数据源.
-
选择数据源: Database Table(s).
-
在可选的数据库连接里选择
BIDemo
。 -
选择 Reporting and Analysis 作为此数据源的目标。
Figure 20. 数据源向导 -
选择我们在 Spoon 中创建的维度表和事实表:
"PENTAHO_DIM_CUSTOMER"
,"PENTAHO_DIM_PRODUCT"
,"PENTAHO_FACT_ORDER_LINE"
:Figure 21. 数据源向导 -
定义这些表之间的 join:
Figure 22. 数据源向导 -
自定义维度表结构:
Figure 23. 数据源模型编辑器 -
保存数据源。在可用数据源选择这个数据源然后导出创建的分析以便将来使用:
Figure 24. 导出数据源
-
- 创建分析报表
-
-
点击 New → Saiku Analytics → Create a new query. 选择
BiDemo
Cube 然后按照这个页面填写 measure, columns, 以及 rows:Figure 25. 创建查询 -
在
/home/admin
目录保存报表,名称为ProductsByTypeAndLocation
。
现在可以在 CUBA 应用中打开 Saiku 报表。
-
4. 应用中添加 BI
-
在项目中引入此插件
-
在 Studio 打开项目。
-
编辑 Project properties,在 App components 面板点击 Custom components 边上的 plus 按钮。
-
在 Custom application component 弹窗,输入 BI 插件的属性:
-
Artifact group:
com.haulmont.addon.bi
-
Artifact name:
cuba-bi-global
-
Version:
1.5.0
根据项目使用的 CUBA 框架版本选取兼容的插件版本:
平台版本 插件版本 6.5.x
1.1.1
6.6.x
1.2.1
6.7.x
1.2.3
6.8.x
1.2.4
6.9.x
1.3.0
6.10.x
1.4.0
7.0.x
1.5.0
示例:
Figure 27. BI 插件
-
-
-
在
web-app.properties
文件添加cuba.web.mainTabSheetMode
属性,以便在切换应用标签页的时候能保留报表内容:cuba.web.mainTabSheetMode = MANAGED
-
在插件提供的 BI > BI Reports 页面,注册 BI 报表。点击 Create 设置路径为本地保存的 Pentaho 报表:
Figure 28. BI 报表页面通过添加角色列表可以控制报表只对部分特定用户可用。如果这个列表是空的,那么所有人都能用这个报表。
现在用户可以在 BI > Run BI Reports 页面运行报表。
-
另一个方法是可以使用插件提供的
biComponent
可视化组件将 BI 报表嵌入到应用页面。示例:<cubabi:biComponent id="biComponent" height="100%" reportPath=":home:admin:ProductsByTypeAndLocation.saiku" width="100%"/>
reportPath
属性是 Pentaho 用户终端中报表文件的路径。另外,需要在window
元素的xmlns
属性添加cubabi
命名空间:xmlns:cubabi="http://schemas.company.com/cubabi/0.1/ui-component.xsd"