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

Предисловие

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

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

Если у Вас имеются предложения по улучшению данного руководства, мы будем рады принять ваши pull request’ы и issues в исходниках документации на GitHub. Если вы увидели ошибку или несоответствие в документе - пожалуйста, форкните репозиторий и исправьте проблему. Заранее спасибо!

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

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

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

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

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

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

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

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

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

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

  1. Скачайте и установите Pentaho Community Edition.

  2. Скачайте и распакуйте плагин Saiku Analytics (Meteorite BI) с http://www.pentaho.com/marketplace/

  3. Перенесите папку saiku в папку $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system, где $PENTAHO_HOME - папка, в которую установлен Pentaho.

  4. Плагин Saiku по умолчанию не поддерживает последние версии Pentaho Server. Чтобы избежать ошибок при сохранении отчёта, сделайте следующее:

    • Удалите файлы библиотек cpf-core-6.0.0.0-353.jar и cpf-pentaho5-6.0.0.0-353.jar из папки $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/saiku/lib.

    • Скопируйте более новые версии этих библиотек из какой-либо другой папки в вашей версии Pentaho (например, $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system/sparkl/lib или …​/cgg/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

      Библиотеки cpk-core…​ и cpk-pentaho…​ могут отсутствовать в вашей версии Pentaho. В этом случае используйте только cpf-core и cpf-pentaho.

  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/server/pentaho-server/tomcat/conf

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

    <Connector URIEncoding="UTF-8" port="18081" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="18443" />

  8. Измените shutdown порт Tomcat по умолчанию на 8015 в файле server.xml, чтобы избежать пересечений с портом CUBA:

    <Server port="8015" shutdown="SHUTDOWN">
    ...
</Server>

  9. Настройте аутентификацию пользователей CUBA в Pentaho:

    • Скачайте cuba-bi-pentaho-1.2.4.jar и скопируйте его в папку $PENTAHO_HOME$/pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib.

    • Скачайте cuba-bi-pentaho-1.2.4-plugin.zip, распакуйте архив и скопируйте папку saiku-cuba-bi в папку $PENTAHO_HOME/pentaho-server/pentaho-solutions/system.

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

      <?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

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

      <property name="cubaConnectionUrl" value="http://localhost:8080/app"/>

    • Отредактируйте файл 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-community-authentication.xml" />

  10. Запустите сервер Pentaho:

    • Перейдите в папку $PENTAHO_HOME/pentaho-server.

    • Выполните start-pentaho.bat

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

В качестве примера интеграции мы создали простой демонстрационный проект, содержащий BI-отчёт. Это уже привычное нам демо-приложение для учёта покупателей и заказов, в которое мы встроили отчёт Saiku на сервере 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:

    • Перейдите в папку, где установлена утилита Pentaho Data Integration.

    • Выполните spoon.bat.

  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:18081/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. Использование готового отчёта

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

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

  2. Выберите источник данных BIDemo и импортируйте файл Mondrian $BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip. Будет загружена готовая структура отчёта.

    bi pentaho 3

  3. Нажмите New → Saiku Analytics → Create a new query. Выберите куб BiDemo и заполните меры, измерения и ряды, как на скриншоте ниже:

    bi pentaho 5

  4. Сохраните отчёт в каталог /home/admin, указав имя файла ProductsByTypeAndLocation.

Теперь вы можете открыть отчёт Saiku в приложении 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 5

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

    pentaho console 4
Создайте аналитический отчёт

  1. Нажмите New → Saiku Analytics → Create a new query. Выберите куб BiDemo и заполните меры, измерения и ряды, как на скриншоте ниже:

    bi pentaho 5

  2. Сохраните отчёт в каталог /home/admin, указав имя файла ProductsByTypeAndLocation.

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

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

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

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

saiku

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.3.0

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

        Platform Version Add-on Version

        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

        Например:

        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.saiku"
                    width="100%"/>

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

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