Предисловие
Данный документ является руководством по дополнению 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
-
Скачайте и установите Pentaho Community Edition с https://community.hds.com/community/products-and-solutions/pentaho/.
-
Скачайте и распакуйте плагин 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 с https://community.hds.com/community/products-and-solutions/pentaho/:
-
Downloads → Main Downloads → Data Integration
-
-
Измените порт Pentaho по умолчанию на 8081:
-
Перейдите в папку
$PENTAHO_HOME/server/pentaho-server/tomcat/conf
-
Измените порт Tomcat по умолчанию на 8081 в файле
server.xml
:
<Connector URIEncoding="UTF-8" port="8081" 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.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:18080/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$
. -
Выполните
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:8081/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.
-
4. Добавление BI к вашему приложению
-
Подключите дополнение 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.2.1
Выберите версию дополнения, совместимую с версией платформы 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
Например:
-
-
-
Добавьте свойство
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"