Предисловие
Данный документ является руководством по дополнению 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 с http://www.pentaho.com/download
-
Остановите фоновые процессы Pentaho Server и Pentaho Solution Repository в службах Windows Services или их аналоге.
-
Измените порт 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" />
-
-
Настройте аутентификацию пользователей 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" />
-
-
Снова запустите фоновые процессы Pentaho Server и Pentaho Solution Repository в службах Windows Services или их аналоге.
3. Быстрый старт
В качестве примера интеграции мы создали простой демонстрационный проект, содержащий BI-отчёт. Это уже привычное нам демо-приложение для учёта покупателей и заказов, в которое мы встроили отчёт 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.
-
Откройте файл
$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. Использование готового отчёта
Здесь описан наиболее простой способ познакомиться с отчётами Pentaho, в котором достаточно импортировать ZIP-файлы с анализом и структурой отчёта.
-
Нажмите Import Analysis.
-
Выберите источник данных
BIDemo
и файл Mondrian$BI_DEMO_PROJECT/demo/pentaho/BiDemo.zip
. -
Нажмите Browse Files в главном окне. Выберите папку
home/Admin
и нажмите Upload. -
Выберите
$BI_DEMO_PROJECT/demo/pentaho/ProductsByTypeAndLocation.xanalyzer.zip
и загрузите его.
Теперь вы можете открыть отчёт Pentaho в приложении 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 для выбранных таблиц:
-
Сохраните источник данных. Выберите его в списке доступных источников и экспортируйте созданный анализ для дальнейшего использования:
-
- Создайте аналитический отчёт
-
-
На домашней странице консоли администратора Pentaho нажмите New → Analysis Report.
-
Выберите источник данных
BIDemo
.
-
3.4. Использование виджета BI в приложении CUBA
-
Перейдите по адресу http://localhost:8080/app
-
Откройте Shop → BI в главном меню приложения:
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.1.1
Выберите версию дополнения, совместимую с версией платформы CUBA, используемой в проекте:
Platform Version Add-on Version 6.5.x
1.1.1
Например:
-
-
-
Добавьте свойство
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.xanalyzer" width="100%"/>
Атрибут
reportPath
содержит путь к файлу отчёта в панели Pentaho User Console. Также необходимо включить пространство имёнcubabi
в атрибутxmlns
элементаwindow
:xmlns:cubabi="http://schemas.company.com/cubabi/0.1/ui-component.xsd"