序言

此手册描述如何集成 商务智能 插件,此插件用来集成 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

  1. 下载并安装 Pentaho 社区版。

  2. http://www.pentaho.com/marketplace/ 下载 Saiku Analytics 插件 (Meteorite BI),然后安装。

  3. saiku 移到 $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system 下面,这里 $PENTAHO_HOME 是 Pentaho 安装的目录。

  4. 如果 Saiku 插件跟最新版本的 Pentaho 服务器不兼容的话,按照下面步骤解决:

    • $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku/lib 目录删除 cpf-core-6.0.0.0-353.jarcpf-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-corecpf-pentaho Jar 包。

  5. 访问 http://licensing.meteorite.bi 并且注册一个新账号。验证了账号之后,创建一个公司,并且为公司生成一个社区版许可:

    • 登录系统点击 CREATE NEW LICENSE 按钮。

    • 在创建新许可的页面设置许可类型为:COMMUNITY_EDITION。

    • 保存然后下载许可。重命名许可文件为 license.lic 然后拷贝该文件到 $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku 目录。

  6. 下载并安装 Pentaho Data Integration 工具。

  7. 更改 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" />
  8. server.xml 修改 Tomcat shutdown 端口为 8015,避免跟 CUBA 默认的 shutdown 端口冲突:

    <Server port="8015" shutdown="SHUTDOWN">
        ...
    </Server>
  9. 在 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" />
  10. 启动 Pentaho 服务:

    • 切换到 $PENTAHO_HOME/pentaho-server 目录。

    • 运行 start-pentaho.bat

3. 快速开始

我们创建了一个小项目用来示范怎么通过 BI 报表增强 CUBA 应用。这个 demo 应用是演示客户(customers)和订单(orders)的管理,包含一个运行在 Pentaho 服务的嵌入式 Saiku 报表。

3.1. 配置 CUBA 示范应用

  1. 克隆(clone)或者下载项目: https://github.com/cuba-platform/cuba-bi-demo.git

  2. 在 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。

  1. 确保在 Studio 中打开 demo 项目。下面解释的导入过程将会访问项目的 HSQL 数据库。

  2. 运行 Pentaho Data Integration(数据集成)工具:

    • 切换到 Pentaho Data Integration 的安装目录。

    • 运行 spoon.bat.

  3. 打开 $BI_DEMO_PROJECT/demo/kettle/bidemo.kjb,这里 $BI_DEMO_PROJECT 是 demo 项目的目录。

  4. 点击 Run 来更新 Star Schema。

    bi star schema
    Figure 1. Star Schema

现在可以继续创建分析报表

3.2.2. 创建数据库连接

如果需要自己创建 Star Schema,按照下面的步骤做即可。详细介绍可以咨询 Pentaho wiki

  1. $PENTAHO_HOME$/design-tools/data-integration 目录,用 spoon.bat 启动 Pentaho Data Integration

  2. 创建新变换(transformation)。

  3. 为变换创建新数据库连接:

    • 输入 Connection Name(连接名称)

    • Connection Type(连接类型): Hypersonic

    • Access(访问方式): Native (JDBC)

    • Host Name(主机名称): localhost

    • Database Name(数据库名称): bidemo

    • Port Number(端口号): 19001

    • User Name(用户名): sa

    • Password(密码)字段留空

    star schema
    Figure 2. 数据库连接

3.2.3. 创建维度表

维度表将使用 Products 和 Customers。每个 Product 会关联一些 product line(产品线),产品线就是产品的种类,比如 Ford T 属于 Vintage Cars 产品线。

Customers 属于特定的城市,这些城市属于某些国家,国家又按照洲分布。

  1. 首先,创建 Product 变换。拖拽 Table input 节点到工作簿(worksheet)并且定义报表需要的字段:product id, nameproduct_line_id

    star schema 2
    Figure 3. Product 表输入
  2. 然后创建 products 的插入/更新节点:

    star schema 3
    Figure 4. 插入/更新 Product
  3. 创建 product lines 变换:

    star schema 4
    Figure 5. Product 变换
  4. 通过 Update 节点完成第一个变换:

    star schema 5
    Figure 6. 更新 Product
  5. 按照相同的方式创建 Customer 变换,包含城市和洲级别。然后添加到第一个 Product 中:

    star schema 6
    Figure 7. Customer 变换
  6. 当变换准备好之后,再套上外围相应的任务,START - 启动Success - 成功,以及 Abort job 节点用来做出错时退出:

    star schema 12
    Figure 8. 维度任务

3.2.4. 创建事实表

对于事实度量,使用 Orders 和 Order line。

  1. 首先,创建 Order Line 变换。拖拽 Table input 节点到工作簿(worksheet)并且定义报表需要的字段:idproduct_idquantityorder_id

    star schema 7
    Figure 9. OrderLine 表输入
  2. 然后创建 order lines 的插入/更新节点:

    star schema 8
    Figure 10. 插入/更新 OrderLine
  3. 创建 orders 变换:

    star schema 9
    Figure 11. Order 变换
  4. 最后,在表中更新 customer ID:

    star schema 10
    Figure 12. 更新 customers
  5. 现在事实变换创建好了:

    star schema 11
    Figure 13. 事实变换
  6. 在变换外面套上相应的任务:

    star schema 13
    Figure 14. Facts job

3.2.5. 创建 Star Schema

现在我们将维度表任务和事实表任务组装近 star schema:

  1. 添加 START 节点来启动任务。

  2. 带有 Check Db connections - 检查数据库连接 条件的启动任务。

  3. 如果 DB 没有连上,添加 Abort job 节点来退出任务。

  4. 然后按顺序添加我们之前设计好的 Update DimensionsUpdate Facts 任务。

  5. 最后添加 Success 完成任务配置:

    star schema 14
    Figure 15. Star Schema 任务
  6. 将所有任务和变换都保存到项目文件夹以便将来使用。

3.3. 配置 Pentaho 分析报表

  1. 打开 Pentaho 终端: http://localhost:18081/pentahoAdmin/password 登录。

  2. 点击 File → Manage Data Sources(管理数据源).

  3. 点击配置按钮然后选择 New Connection - 新建连接:

    bi pentaho
    Figure 16. 数据库连接
  4. 创建 HSQLDB 连接:

    • Host Name: localhost

    • Database Name: bidemo

    • Port Number: 19001

    • User Name: sa

    bi pentaho 2
    Figure 17. 数据库连接

现在可以使用项目携带的分析报表或者按照以下步骤自己创建。

3.3.1. 使用 Demo 报表

下面是查看 Saiku 报表样式的最简单方法,只需要导入带有分析和报表结构的 ZIP 文件。

  1. 点击 Import Analysis - 导入分析.

  2. 选择 BIDemo 数据源并且导入 $BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip Mondrian 文件,报表的结构也会被导入。

    bi pentaho 3
    Figure 18. 导入分析
  3. 点击 New → Saiku Analytics → Create a new query。选择 BiDemo Cube 然后按照这个页面填写 measure, columns, 以及 rows:

    bi pentaho 5
    Figure 19. 创建查询
  4. /home/admin 目录保存报表,名称为 ProductsByTypeAndLocation

现在可以在 CUBA 应用中打开 Saiku 报表。

3.3.2. 手动创建数据源和分析报表

创建数据源
  1. 点击 New 数据源.

  2. 选择数据源: Database Table(s).

  3. 在可选的数据库连接里选择 BIDemo

  4. 选择 Reporting and Analysis 作为此数据源的目标。

    pentaho console
    Figure 20. 数据源向导
  5. 选择我们在 Spoon 中创建的维度表和事实表: "PENTAHO_DIM_CUSTOMER", "PENTAHO_DIM_PRODUCT", "PENTAHO_FACT_ORDER_LINE"

    pentaho console 2
    Figure 21. 数据源向导
  6. 定义这些表之间的 join:

    pentaho console 3
    Figure 22. 数据源向导
  7. 自定义维度表结构:

    pentaho console 5
    Figure 23. 数据源模型编辑器
  8. 保存数据源。在可用数据源选择这个数据源然后导出创建的分析以便将来使用:

    pentaho console 4
    Figure 24. 导出数据源
创建分析报表
  1. 点击 New → Saiku Analytics → Create a new query. 选择 BiDemo Cube 然后按照这个页面填写 measure, columns, 以及 rows:

    bi pentaho 5
    Figure 25. 创建查询
  2. /home/admin 目录保存报表,名称为 ProductsByTypeAndLocation

现在可以在 CUBA 应用中打开 Saiku 报表。

3.4. 在 CUBA 示例项目打开 BI Widget

  1. 打开 http://localhost:8080/app

  2. 打开 Shop → BI Saiku 主菜单项:

saiku
Figure 26. BI Saiku 页面

4. 应用中添加 BI

  1. 在项目中引入此插件

    • 在 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

        示例:

        bi component
        Figure 27. BI 插件
  2. web-app.properties 文件添加 cuba.web.mainTabSheetMode 属性,以便在切换应用标签页的时候能保留报表内容:

    cuba.web.mainTabSheetMode = MANAGED
  3. 在插件提供的 BI > BI Reports 页面,注册 BI 报表。点击 Create 设置路径为本地保存的 Pentaho 报表:

    bi create
    Figure 28. BI 报表页面

    通过添加角色列表可以控制报表只对部分特定用户可用。如果这个列表是空的,那么所有人都能用这个报表。

    现在用户可以在 BI > Run BI Reports 页面运行报表。

  4. 另一个方法是可以使用插件提供的 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"
. . .