Integrating or Embedding Pentaho Business Intelligence into your application

The Pentaho BA Server is highly extensible, embeddable, and scriptable business intelligence web application. Internally, it is composed of content-generating engines that provide reporting, online analytical processing (OLAP), and data integration (ETL) functionality. These engines are managed by the Pentaho BI Platform process-flow engine, which as designed for but not exclusive to running such business intelligence tasks as: retrieving data from multiple disparate data sources, creating data-driven reports, and other content, scheduling, and conditionally automating content delivery.

End users interact with these services through an ad-hoc reporting interface, a choice of OLAP visualization tools (Pentaho Analyzer or JPivot), a dashboard designer, and a convenient scheduling interface.

The BI Platform is a process-flow engine that forms the operational core of the BA Server. It ties the other content engines — Reporting, Analysis, and Data Integration — to the Pentaho User Console to provide content display, delivery, and scheduling functionality. Additionally, the BI Platform offers a powerful scripting framework for conditionally automating tasks. Typically, the BI Platform is used to automate business intelligence tasks that rely on other engines, but it could theoretically be used for practically any logical task.

Embedding refers to adding individual pieces of Pentaho BA Server into your application on a code level without having to run a separate BA Server instance.

Integrating refers to running a fully operational Pentaho BA Server instance in order to access its content and use its functionality. This scenario accomplishes mosts or all of the goals of embedding BA Server.

Embedding is what most Pentaho users think that they should do. However, the interconnected nature of the BA Server prevents this from being a quick and easy process. Embedding is a highly complex operation that requires skilled programmers and lots of developer support resources from Pentaho's services and engineering teams. Integrating accomplishes most or all of the goals of embedding without the development overhead. For example, instead of embedding Interactive Reporting into your application, you can simply display it in an iframe. Page 22 through page 28 of Integrating Pentaho Software and Content provides example for running Pentaho Analyzer, Interactive Reporting, Adhoc Reporting in an iframe, and seems to provide hooks / callbacks so that Pentaho can invoke your logic when certain event occur such as when the user save a report. All of the Interactive Reporting functionality that you get through the Pentaho User Console will be available to you when you integrate in this manner.

The BI Platform is a lightweight process-flow engine that defines the order of execution of one or more components of the Pentaho BI Platform. It does not generate content itself, so it has to rely on separate engines for creating reports and other content.

Pentaho relies on the Spring Security pluggable authentication framework. By default, the BA Server uses a JDBC based data access object that is tied to a Hibernate database. Users and roles are configured through the Pentaho Enterprise Console, and content authorization is controlled by the BA Server administrator. However, you can easily configure the server to use existing security tables in a different database, or to authenticate through your existing LDAP server or Central Authentication Service. Pentaho's security is also extensible to the point that you can create your own data access object, or completely remove all authentication functionality.

The BA Server is programmable directly through Java code, or dynamically through XML files known as "action sequences". An action sequence contains a set of actions and parameters (input, output, and external resources) in an XML file with a .xaction extension. For this reason, action sequences are sometimes called xactions.

Action sequences activate BI Platform components and compel them to do work. They can be run anytime while the BA Server is active. You can also arrange for action sequences to be run at certain times, or intervals through the built-in scheduling service.

The simplest methods of integrating content generated from Pentaho BA Server are:

  • Direct services provided via servlets that deliver content in the URL outputstream
  • Web services provided via servlets that deliver content packaged as a SOAP response.

The Pentaho BA Server is capable of serving content using only a definition file. For example, a report created with Report Designer can be served from the BA Server directly from the .prpt definition file. This applies to Analyzer reports, Dashboard Designer views, and Pentaho Data Integration results as well. The BA Server is also capable of processing several steps — or actions — sequentially and returning the resulting output or content.

What is ViewAction?

ViewAction is a servlet included in the Pentaho BA Server that executes action sequences and returns their output in the specified format. ViewAction has required and optional parameters, and will also accept action sequence input parameters. Should the action sequence require a parameter, and this parameter is not supplied by the caller, then the server will return an HTML page requesting the missing parameters instead of the requested content.

When to use ViewAction?

ViewAction is most obviously useful when you want to execute an action sequence rather than generating content directly from content definition files. Other considerations for using ViewAction are:

  • You are able to directly reference a URL in the context of the Pentaho web application
  • You can use either POST or GET HTTP methods for sending parameter values to ViewAction

How to use ViewAction?

ViewAction is executed as an HTTP URL. Both operational parameters and action sequence input parameters are specified after the question mark as name/value pairs. This example demonstrates how to display the result of an action sequence that generates a tabular HTML report. This example uses both the required and optional parameters as well as input parameters from action sequence:


The parameters Region and outputType are both input parameters that the action sequence needs in order to execute the report generation action.

What is ReportViewer?

The Pentaho ReportViewer is a GWT application plugin that will render Pentaho reports with optional interactive features:

  • Page controls for paginated reports
  • Filter components such as text boxes, drop-down list boxes, and radio buttons for parameter filters.

When to use ReportViewer?

ReportViewer renders prpt report definitions into reports. It does not need (and is unable to execute) an action sequence to render a report. When you want to deliver an interactive report, you should use ReportViewer. When a report is published to the BA Server, the Pentaho User Console uses ReportViewer to render it. ReportViewer is accessed via HTTP URL, so it is easy to integrate into any web application.

How to use ReportViewer?

ReportViewer is executed as an HTTP URL. Both operational parameters and report input parameters are specified after the question mark as name/value pairs.


What is the Reporting URL?

The Reporting URL is a servlet included in the BA Server that enables execution of a Pentaho report and returns the rendered output in the specified format. In comparison with the ReportViewer, this service has no bells and whistles. It expects that the report has all the parameters satisfied using either defaults or name/value pairs in the URL, and these values are not intended to be changed once the report is rendered. The report also has no pagination. When your reporting needs are relatively static, this is a good service to use because it trims that overhead that comes along with the ReportViewer GWT application. The Reporting URL submits the report definition and its parameters directly to the reporting content generator for processing, returning only the report content that was requested.

How to use the Reporting URL?

The Reporting URL is an HTTP URL. Both operational parameters and report input parameters are specified after the question mark as name/value pairs.


What are Analyizer Service URLs?

Analyzer is a plugin to Pentaho BA Server that serves slice-and-dice and data visualization functionality using a OLAP cube as a data source. Pentaho Analyzer differs from Pentaho Reporting in that Analyzer has two modes of operation for an Analyzer report: a report can be executed in viewer mode, or editor mode (with options). While the service URLs vary only slightly, the functionality is distinctly different.

When to use Analyzer Service URLs?

These service URLs are valuable when you want to provide interactive OLAP analysis views and capabilities to your users. The editor mode of the service opens Analyzer with full slice-and-dice capabilities from both saved and new reports. The viewer mode of Analyzer limits the interactivity of the analysis report, and removes all edit controls in favor of a larger data grid. This mode is more suitable for dashboarding and static display of OLAP report data. The viewer mode does still allow some interactivity through a context menu, such as changing the dimension selections for the report.

How to use Analyzer Service URLs?

The Analyzer URLs are HTTP URLs. Operational parameters are specified after the question mark as name/value pairs.

You can append a static parameter value onto a URL for any Analyzer report that contains query parameters. Ordinarily report users will select the parameter value in the filter dialogue, thus altering the report. However, you can set the filter value by hand by using a URL parameter. First, your report must have a parameter defined in it. You cannot create parameters through URLs. You can only set values for them. Next, you must append the parameter name and a valid value to the URL. For example, if you have a parameter name line that lists product lines, your URL snippet may look like:


The full URL, with other name/value pairs would be:


Operational Interactive Reporting URL Parameters

Interactive Reporting has query parameters similar to Analyzer. The base URL for interactive reporting:


To create a new interactive report, you must specify: command, solution, path, and file.

To open an existing interactive report, you only need to use the model parameter.

Displaying an Analyzer Report in viewer mode:

The viewer URL requires the solution, path, and action parameters in order to locate the analyzer report to display. This example will display the report with almost all interactive capabilities hidden:

http://localhost:8080/pentaho/content/analyzer/viewer?solution=steel-wheels&path=/analysis&action=Top 5 Product Lines by Territory.xanalyzer

Displaying an Analyzer Report in editor mode:

http://localhost:8080/pentaho/content/analyzer/editor?command=open&solution=steel-wheels&path=analysis&action=Top 5 Product Lines by Territory.xanalyzer

Creating a new Analyzer report:

This example demonstrates starting a new Analyzer report in editor mode, and specifying the OLAP cube and catalog to start data analysis. The catalog and cube must be defined in the Pentaho BA Server before requesting to use them in a new report.

http://localhost:8080/pentaho/content/analyzer/editor?command=new&showFilterList=true&catalog=SampleData&cube=Quadrant Analysis

Running client tools in an iframe:

Page 22 through page 28 of Integrating Pentaho Software and Content provides example for running Pentaho Analyzer, Interactive Reporting, Adhoc Reporting in an iframe.

What is the SolutionRepositoryService?

SolutionRepositoryService is a servlet included in the Pentaho BA Server that allows users with the appropriate permissions to request solution repository service methods, then receive an XML response with the requested data or status of the request.

Service methods available through the SolutionRepositoryService are:

  • getSolutionRepositoryDoc: the request returns a list of all accessible files and folders in the solution repository along with file/folder metadata attributes. The list can be filtered by type (file extension)
  • getSolutionRepositoryFileDetails: given a path, this request returns detailed metadata for this file or folder
  • createNewFolder: creates a new folder in the solution repository in the requested location with the requested name and description
  • delete: deletes the folder or file at the requested location. If the folder has children folders or files, they will also be deleted
  • setAcl: sets the specified access control list (ACL) on the requested solution file or folder
  • getAcl: gets the ACL for the requested solution file or folder

When to use SolutionRepositoryService?

SolutionRepositoryService is useful in a number of scenarios. Perhaps, you would like to programmatically create a standard folder structure for new users on first login, or possibly delete all content in a particular folder when a user is no longer valid in the system.

SolutionRepositoryService's ability to list the repository contents in XML format also provides easy access to the data needed to build a custom solution user interface using XSLT or some other web technology that works directly with XML.

How to use SolutionRepositoryService?

The base URL for SolutionRepositoryService:


After the question mark, the first parameter you should specify is component. This is the parameter that facilitates the service method that you are interested in.

What is a ServiceAction?

ServiceAction is a servlet included in Pentaho BA Server that provides service methods for executing action sequences, and for retrieving security model details. The output from service methods in ServiceAction is formatted as a SOAP response.

When to use ServiceAction?

ServiceAction can be used in many of the same instances that you would use ViewAction. The primary difference is the format of the output. You can only use action sequences that return content with text MIME types ('text/xml', 'text/html', etc) with ServiceAction. ServiceAction also serves a unique set of methods that provide security model details. These methods allow you to query the server for the list of users, roles, and/or ACLs for a given resources known to the BA Server. This services requires that you have administrator access to the BA Server in order to execute any security-related requests.

How to use ServiceAction?

ServiceAction is executed as an HTTP URL.

What is the Ajax API?

The Pentaho AJAX API is a JavaScript library that enables you to make asynchronous action sequence execution requests to the Pentaho BA Server. The core library file pentaho-ajax.js holds two methods of interest: pentahoAction() and pentahoService(). These methods expose ViewAction and ServiceAction.

When to use AJAX API?

Typically, you would use this interface when you want to integrate with another AJAX-based application. Pentaho Dashboard Designer uses AJAX API at its core.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License