Более новая версия доступна в разделе документации.

Предисловие

Данный документ является руководством по дополнению Business Intelligence, используемому для интеграции приложений на платформе CUBA с инструментами Pentaho Platform.

Предполагается, что читатель ознакомлен с Руководством по разработке приложений, доступным по адресу https://www.cuba-platform.ru/manual.

Если у Вас имеются предложения по улучшению данного руководства, обратитесь, пожалуйста, в службу поддержки по адресу http://www.cuba-platform.ru/support. При обнаружении ошибки в документации укажите, пожалуйста, номер главы и приведите небольшой участок окружающего текста для облегчения поиска.

1. Обзор дополнения

Дополнение BI предоставляет следующую функциональность:

  • Универсальные шаблоны экранов для регистрации и запуска отчётов Pentaho. Доступ к зарегистрированным отчётам можно ограничить с помощью ролей в подсистеме безопасности CUBA.

  • Визуальный компонент для встраивания отчётов Pentaho в любой экран приложения.

  • Технология единого входа (SSO) между приложениями CUBA и Pentaho, которая работает следующим образом:

    • Имя пользователя в приложении CUBA и Pentaho должно совпадать.

    • Когда пользователь открывает отчёт, приложение создаёт тикет и прикрепляет имя пользователя и тикет к запросу на Pentaho. Тикет хранится в сессии пользователя.

    • Плагин для CUBA на сервере Pentaho обнаруживает тикет, пришедший вместе с запросом, и в ответном запросе к приложению проверяет, действителен ли тикет.

    • Если тикет действителен, плагин авторизует пользователя на сервере Pentaho, применив к нему роли, настроенные для этого пользователя в Pentaho.

2. Установка и настройка Pentaho

  1. Скачайте и установите Pentaho с http://www.pentaho.com/download

  2. Остановите фоновые процессы Pentaho Server и Pentaho Solution Repository в службах Windows Services или их аналоге.

  3. Измените порт Pentaho по умолчанию на 8081.

    • Перейдите в папку $PENTAHO_HOME/server/pentaho-server/tomcat/conf, где $PENTAHO_HOME - папка, в которую установлен Pentaho.

    • Измените порт Tomcat по умолчанию на 8081 в файле server.xml:

    <Connector URIEncoding="UTF-8" port="8081" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="18443" />
  4. Настройте аутентификацию пользователей CUBA в Pentaho.

    • Скачайте https://dl.bintray.com/cuba-platform/main/com/haulmont/addon/bi/cuba-bi-pentaho/1.1.1/cuba-bi-pentaho-1.1.1.jar и скопируйте его в папку $PENTAHO_HOME$/server/pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib.

    • Создайте новый файл cuba-pentaho-authentication.xml в папке $PENTAHO_HOME/server/pentaho-server/pentaho-solutions/system со следующим содержимым:

      <?xml version="1.0" encoding="UTF-8"?>
      <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 ======================= -->
          <bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy">
              <constructor-arg>
                  <util:list>
                      <!-- You can safely remove the first pattern starting with /content/dashboards/print, if you're not using Enterprise Dashboards or not allowing printing of Dashboards, -->
                      <sec:filter-chain pattern="/api/repos/dashboards/print" filters="securityContextHolderAwareRequestFilter,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,preAuthenticatedSecurityFilter,httpSessionReuseDetectionFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor" />
                      <sec:filter-chain pattern="/webservices/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,cubaAuthenticationFilter,basicProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" />
                      <sec:filter-chain pattern="/api/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,cubaAuthenticationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" />
                      <sec:filter-chain pattern="/plugin/**" filters="securityContextHolderAwareRequestFilterForWS,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilterForWS,filterInvocationInterceptorForWS" />
                      <sec:filter-chain pattern="/**" filters="securityContextHolderAwareRequestFilter,httpSessionPentahoSessionContextIntegrationFilter,httpSessionContextIntegrationFilter,httpSessionReuseDetectionFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,requestParameterProcessingFilter,anonymousProcessingFilter,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" />
          </bean>
      
          <!-- Automatically receives AuthenticationEvent messages -->
          <bean id="loggerListener" class="org.pentaho.platform.engine.security.event.PentahoLoggerListener" />
          <bean id="basicProcessingFilter" class="org.pentaho.platform.web.http.security.PentahoBasicProcessingFilter">
              <constructor-arg ref="authenticationManager" />
              <constructor-arg ref="basicProcessingFilterEntryPoint" />
          </bean>
          <bean id="basicAuthPostFilter"
                class="org.pentaho.platform.web.http.security.PentahoBasicPostProcessingFilter">
          </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

      Укажите URL вашего приложения CUBA в свойстве cubaConnectionUrl бина cubaAuthenticationFilter.

    • Отредактируйте файл pentaho-spring-beans.xml в папке pentaho-solutions/system, добавив в него строку <import resource="cuba-pentaho-authentication.xml" /> после строки <import resource="applicationContext-spring-security.xml" />:

      <import resource="applicationContext-spring-security.xml" />
      <import resource="cuba-pentaho-authentication.xml" />
  5. Снова запустите фоновые процессы Pentaho Server и Pentaho Solution Repository в службах Windows Services или их аналоге.

3. Быстрый старт

В качестве примера интеграции мы создали простой демонстрационный проект, содержащий BI-отчёт. Это уже привычное нам демо-приложение для учёта покупателей и заказов, в которое мы встроили отчёт Pentaho.

3.1. Установка демо-приложения CUBA

  1. Клонируйте или скачайте демонстрационное приложение с https://github.com/cuba-platform/cuba-bi-demo.git

  2. Откройте проект в IDE или в CUBA Studio, выполните команду createDb и запустите сервер приложения.

3.2. Загрузка данных в схему звезды

В нашем отчёте Pentaho мы будем использовать агрегированные данные из нескольких таблиц. Для хранения этих данных будут созданы дополнительные таблицы, откуда они затем будут загружены в схему звезды (Star Schema). В нашем случае схема звезды состоит из одной таблицы фактов (Orders) и двух таблиц измерений (Customer и Product), что даёт возможность "проваливаться" вглубь иерархии отчёта.

3.2.1. Загрузка данных для нетерпеливых

Вы можете использовать уже готовую схему, скачанную вместе с демо-проектом.

  1. Убедитесь, что демо-проект открыт в Studio. В процессе импорта, описанном ниже, мы будем обращаться к HSQL базе данных проекта.

  2. Запустите утилиту Pentaho Data Integration.

  3. Откройте файл $BI_DEMO_PROJECT/demo/kettle/bidemo.kjb, где $BI_DEMO_PROJECT - папка, в которой находится демо-проект.

  4. Нажмите Run для обновления схемы звезды.

    bi star schema

Теперь вы можете перейти к главе создание аналитического отчёта.

3.2.2. Подключение к базе данных

Если вы хотите создать схему звезды самостоятельно, выполните следующие шаги. Более подробные инструкции можно найти на Pentaho wiki.

  1. Откройте утилиту Pentaho Data Integration, запустив spoon.bat в папке $PENTAHO_HOME$/design-tools/data-integration.

  2. Создайте новую трансформацию.

  3. Создайте для трансформации новое подключение к БД:

    • Введите имя подключения в поле Connection Name

    • Connection Type: Hypersonic

    • Access: Native (JDBC)

    • Host Name: localhost

    • Database Name: bidemo

    • Port Number: 19001

    • User Name: sa

    • Поле Password field оставьте пустым

    star schema

3.2.3. Создание измерений

В качестве измерений мы будем использовать сущности Products и Customers. Каждый продукт содержит ссылку на строку продукта product line, в которой содержится тип продукта, например, Ford T принадлежит к типу Vintage Cars.

Покупатели содержат ссылку на определённый город, который, в свою очередь, ссылается на страну, страны сгруппированы в несколько территорий.

  1. Для начала создадим трансформацию для Product. Перетащите узел Table input на рабочий лист и укажите поля, которые будут использованы в отчёте: id продукта, name и product_line_id.

    star schema 2
  2. Далее создайте для продуктов узел Insert/Update:

    star schema 3
  3. Создайте трансформацию для строк продукта:

    star schema 4
  4. Завершите трансформацию узлом Update:

    star schema 5
  5. Создайте трансформацию для сущности Customer тем же образом, включив в неё уровни City и Territory, и добавьте её к трансформации сущности Product:

    star schema 6
  6. Закончив создание трансформации, оберните её в соответствующую задачу, используя узлы START и Success, а также узел Abort job для выхода в случае ошибки:

    star schema 12

3.2.4. Создание фактов

Для меры фактов мы используем заказы (Orders) и строки заказов (Order Lines).

  1. Начнём с создания трансформации для Order Line. Перетащите узел Table input на рабочий лист и укажите поля, которые будут использованы в отчёте: id, product_id, quantity и order_id:

    star schema 7
  2. Далее создайте для строк заказа узел Insert/Update:

    star schema 8
  3. Создайте трансформацию для заказов:

    star schema 9
  4. Наконец, обновите ID покупателей в таблице:

    star schema 10
  5. Трансформация фактов готова:

    star schema 11
  6. Оберните трансформацию в соответствующую задачу:

    star schema 13

3.2.5. Создание схемы звезды

Теперь соберём задачи измерений и мер в готовую схему звезды:

  1. Добавьте узел START для запуска задачи.

  2. Перед выполнением добавьте проверку условия Check Db connections.

  3. На случай, если подключение к БД отсутствует, добавьте выходной узел Abort job.

  4. Затем добавьте последовательно задачи Update Dimensions и Update Facts, которые мы создали ранее.

  5. Завершите задачу узлом Success и запустите её выполнение:

    star schema 14
  6. Сохраните все файлы задач и трансформаций в папку проекта для дальнейшего использования.

3.3. Создание аналитического отчёта Pentaho

  1. Откройте консоль администратора Pentaho: http://localhost:8081/pentaho и войдите под Admin/password.

  2. Нажмите File → Manage Data Sources.

  3. Выберите New Connection:

    bi pentaho
  4. Создайте подключение к HSQLDB:

    • Host Name: localhost

    • Database Name: bidemo

    • Port Number: 19001

    • User Name: sa

    bi pentaho 2

Теперь вы можете либо использовать готовый отчёт, поставляемый с демо-проектом, либо создать создать его самостоятельно, следуя инструкции ниже.

3.3.1. Использование готового отчёта

Здесь описан наиболее простой способ познакомиться с отчётами Pentaho, в котором достаточно импортировать ZIP-файлы с анализом и структурой отчёта.

  1. Нажмите Import Analysis.

  2. Выберите источник данных BIDemo и файл Mondrian $BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip.

    bi pentaho 3
  3. Нажмите Browse Files в главном окне. Выберите папку home/Admin и нажмите Upload.

  4. Выберите $BI_DEMO_PROJECT/demo/pentaho/ProductsByTypeAndLocation.xanalyzer.zip и загрузите его.

    bi pentaho 4

Теперь вы можете открыть отчёт Pentaho в приложении CUBA.

3.3.2. Создание источника данных и структуры отчёта

Создайте источник данных
  1. Нажмите New Data Source.

  2. Выберите тип источника: Database Table(s).

  3. Выберите новое подключение BIDemo из списка доступных подключений.

  4. Выберите назначение Reporting and Analysis для нового источника.

    pentaho console
  5. Выберите таблицы измерений и фактов, которые мы создали ранее в Spoon: "PENTAHO_DIM_CUSTOMER", "PENTAHO_DIM_PRODUCT", "PENTAHO_FACT_ORDER_LINE":

    pentaho console 2
  6. Определите Joins для выбранных таблиц:

    pentaho console 3
  7. Сохраните источник данных. Выберите его в списке доступных источников и экспортируйте созданный анализ для дальнейшего использования:

    pentaho console 4
Создайте аналитический отчёт
  1. На домашней странице консоли администратора Pentaho нажмите NewAnalysis Report.

  2. Выберите источник данных BIDemo.

3.4. Использование виджета BI в приложении CUBA

  1. Перейдите по адресу http://localhost:8080/app

  2. Откройте Shop → BI в главном меню приложения:


4. Добавление BI к вашему приложению

  1. Подключите дополнение BI к своему проекту.

    • Если в приложении не используются другие премиум-дополнения CUBA, добавьте следующие строки в секцию buildscript.repositories файла build.gradle:

      buildscript {
          // ...
          repositories {
              // ...
              maven {
                  url 'https://repo.cuba-platform.com/content/groups/premium'
                  credentials {
                      username(rootProject.hasProperty('premiumRepoUser') ?
                          rootProject['premiumRepoUser'] : System.getenv('CUBA_PREMIUM_USER'))
                      password(rootProject.hasProperty('premiumRepoPass') ?
                          rootProject['premiumRepoPass'] : System.getenv('CUBA_PREMIUM_PASSWORD'))
                  }
              }
          }
    • Откройте проект в CUBA Studio.

    • Откройте окно редактирования Project properties и на панели App components нажмите кнопку плюс рядом с Custom components.

    • В диалоговом окне Custom application component введите координаты дополнения BI:

      • Artifact group: com.haulmont.addon.bi

      • Artifact name: cuba-bi-global

      • Version: 1.1.1

        Выберите версию дополнения, совместимую с версией платформы CUBA, используемой в проекте:

        Platform Version Add-on Version

        6.5.x

        1.1.1

        Например:

        bi component
  2. Добавьте свойство cuba.web.mainTabSheetMode к файлу web-app.properties, чтобы содержимое отчёта сохранялось при переключении между вкладками приложения:

    cuba.web.mainTabSheetMode = MANAGED
  3. Зарегистрируйте свой BI-отчёт на экране BI > BI Reports, предоставленном вместе с дополнением. Нажмите Create и пропишите путь к отчёту Pentaho:

    bi create

    Список ролей позволяет настроить видимость отчёта только для определённых пользователей приложения. Если список ролей пуст, отчёт будет виден всем пользователям.

    Теперь пользователи могут формировать отчёт на экране BI > Run BI Reports.

  4. Другой вариант - встроить BI-отчёт в экран приложения с помощью визуального компонента biComponent, поставляемого с дополнением. Например:

    <cubabi:biComponent id="biComponent"
                        height="100%"
                        reportPath=":home:admin:ProductsByTypeAndLocation.xanalyzer"
                        width="100%"/>

    Атрибут reportPath содержит путь к файлу отчёта в панели Pentaho User Console. Также необходимо включить пространство имён cubabi в атрибут xmlns элемента window:

    xmlns:cubabi="http://schemas.company.com/cubabi/0.1/ui-component.xsd"
. . .