CUBA Platform. Интеграция с BI

Предисловие

Данный документ является руководством по дополнению 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

Скачайте и установите Pentaho Community Edition.
Скачайте и распакуйте плагин Saiku Analytics (Meteorite BI) с http://www.pentaho.com/marketplace/
Перенесите папку saiku в папку $PENTAHO_HOME$/pentaho-server/pentaho-solutions/system, где $PENTAHO_HOME - папка, в которую установлен Pentaho.

Плагин 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`.

Перейдите на 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/server/pentaho-server/tomcat/conf
- Измените порт Tomcat по умолчанию на 18081 в файле server.xml:
<Connector URIEncoding="UTF-8" port="18081" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="18443" />
Измените shutdown порт Tomcat по умолчанию на 8015 в файле server.xml, чтобы избежать пересечений с портом CUBA:
<Server port="8015" shutdown="SHUTDOWN"> ... </Server>

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

Скачайте cuba-bi-pentaho-1.6.0.jar и скопируйте его в папку $PENTAHO_HOME$/pentaho-server/tomcat/webapps/pentaho/WEB-INF/lib.
Скачайте cuba-bi-pentaho-1.6.0-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" />
```

Запустите сервер Pentaho:
- Перейдите в папку $PENTAHO_HOME/pentaho-server.
- Выполните start-pentaho.bat

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

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

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

Клонируйте или скачайте демонстрационное приложение с https://github.com/cuba-platform/cuba-bi-demo.git
Откройте проект в IDE или в CUBA Studio, выполните команду createDb и запустите сервер приложения.

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

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

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

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

Убедитесь, что демо-проект открыт в Studio. В процессе импорта, описанном ниже, мы будем обращаться к HSQL базе данных проекта.
Запустите утилиту Pentaho Data Integration:
- Перейдите в папку, где установлена утилита Pentaho Data Integration.
- Выполните spoon.bat.
Откройте файл $BI_DEMO_PROJECT/demo/kettle/bidemo.kjb, где $BI_DEMO_PROJECT - папка, в которой находится демо-проект.
Нажмите Run для обновления схемы звезды.

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

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

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

Откройте утилиту Pentaho Data Integration, запустив spoon.bat в папке $PENTAHO_HOME$/design-tools/data-integration.
Создайте новую трансформацию.
Создайте для трансформации новое подключение к БД:
- Введите имя подключения в поле Connection Name
- Connection Type: Hypersonic
- Access: Native (JDBC)
- Host Name: localhost
- Database Name: bidemo
- Port Number: 19001
- User Name: sa
- Поле Password field оставьте пустым

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

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

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

Для начала создадим трансформацию для Product. Перетащите узел Table input на рабочий лист и укажите поля, которые будут использованы в отчёте: id продукта, name и product_line_id.
Далее создайте для продуктов узел Insert/Update:
Создайте трансформацию для строк продукта:
Завершите трансформацию узлом Update:
Создайте трансформацию для сущности Customer тем же образом, включив в неё уровни City и Territory, и добавьте её к трансформации сущности Product:
Закончив создание трансформации, оберните её в соответствующую задачу, используя узлы START и Success, а также узел Abort job для выхода в случае ошибки:

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

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

Начнём с создания трансформации для Order Line. Перетащите узел Table input на рабочий лист и укажите поля, которые будут использованы в отчёте: id, product_id, quantity и order_id:
Далее создайте для строк заказа узел Insert/Update:
Создайте трансформацию для заказов:
Наконец, обновите ID покупателей в таблице:
Трансформация фактов готова:
Оберните трансформацию в соответствующую задачу:

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

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

Добавьте узел START для запуска задачи.
Перед выполнением добавьте проверку условия Check Db connections.
На случай, если подключение к БД отсутствует, добавьте выходной узел Abort job.
Затем добавьте последовательно задачи Update Dimensions и Update Facts, которые мы создали ранее.
Завершите задачу узлом Success и запустите её выполнение:
Сохраните все файлы задач и трансформаций в папку проекта для дальнейшего использования.

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

Откройте консоль администратора Pentaho: http://localhost:18081/pentaho и войдите под Admin/password.
Нажмите File → Manage Data Sources.
Нажмите на шестерёнку настроек и выберите New Connection:
Создайте подключение к HSQLDB:
- Host Name: localhost
- Database Name: bidemo
- Port Number: 19001
- User Name: sa

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

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

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

Нажмите Import Analysis.
Выберите источник данных BIDemo и импортируйте файл Mondrian $BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip. Будет загружена готовая структура отчёта.
Нажмите New → Saiku Analytics → Create a new query. Выберите куб BiDemo и заполните меры, измерения и ряды, как на скриншоте ниже:
Сохраните отчёт в каталог /home/admin, указав имя файла ProductsByTypeAndLocation.

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

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

Создайте источник данных

Нажмите New Data Source.
Выберите тип источника: Database Table(s).
Выберите новое подключение BIDemo из списка доступных подключений.
Выберите назначение Reporting and Analysis для нового источника.
Выберите таблицы измерений и фактов, которые мы создали ранее в Spoon: "PENTAHO_DIM_CUSTOMER", "PENTAHO_DIM_PRODUCT", "PENTAHO_FACT_ORDER_LINE":
Определите Joins для выбранных таблиц:
Задайте иерархию измерений:
Сохраните источник данных. Выберите его в списке доступных источников и экспортируйте созданный анализ для дальнейшего использования:

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

Нажмите New → Saiku Analytics → Create a new query. Выберите куб BiDemo и заполните меры, измерения и ряды, как на скриншоте ниже:
Сохраните отчёт в каталог /home/admin, указав имя файла ProductsByTypeAndLocation.

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

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

Перейдите по адресу http://localhost:8080/app
Откройте Shop → BI Saiku в главном меню приложения:

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

Добавьте аддон в свой проект.
- Кликните дважды Add-ons в дереве проекта CUBA.
- Перейдите на вкладку Marketplace и найдите аддон Business Intelligence.
- Кликните Install и затем Apply & Close.
- Кликните Continue в появившемся диалоговом окне.
  
  Аддон, соответствующий используемой версии платформы, будет добавлен в проект.
Добавьте свойство cuba.web.mainTabSheetMode к файлу web-app.properties, чтобы содержимое отчёта сохранялось при переключении между вкладками приложения:
```
cuba.web.mainTabSheetMode = MANAGED
```
Зарегистрируйте свой BI-отчёт на экране BI > BI Reports, предоставленном вместе с дополнением. Нажмите Create и пропишите путь к отчёту Pentaho:

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

Теперь пользователи могут формировать отчёт на экране BI > Run BI Reports.
Другой вариант - встроить 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"