Skip to main content
Version Pentaho
Hitachi Vantara Lumada and Pentaho Documentation

Embed Pentaho Server Functionality into Web Applications

  1. Last updated
  2. Save as PDF
  1. Get Started with the Embedded Samples
  2. Reporting Samples
    1. Execute a Report from a HTML Form (POSTing Parameters)
    2. Render a Report in an IFRAME
    3. Render Report Viewer with Available Parameters and Executed Report
  3. Publish a File to the Pentaho Server
  4. Analyzer Samples
    1. Display a Report in Viewer Mode
    2. Display a Report in Editor Mode
    3. Create a New Report
    4. Integrate into a Custom Web Application via an IFRAME
    5. Specify the Select Schema Service
  5. Interactive Reporting Samples
    1. Display an Interactive Report
    2. Create a New Interactive Report
    3. Integrate into a Custom Web Application via an IFRAME
  6. Action Sequence Samples
    1. Run an Action Sequence to Generate a Report
    2. Run an Action Sequence to Generate a Report with Prompts
  7. Configure the Proxy Trusting Filter
  8. Developer Support
    1. License Information

The following samples use various development techniques to demonstrate how to embed Pentaho Server functionality and content into another web application.

These samples are for developers with HTML and JavaScript experience. We assume also you have a correctly installed and configured the Pentaho Server running locally on your machine along with knowing how to start and stop the server if necessary.

Get Started with the Embedded Samples

The samples are available on the Pentaho Customer Support Portal.

  1. On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet.
  2. Click Downloads, then navigate to the Pentaho GA Release which matches your version of the software.
  3. On the bottom of the Pentaho GA Release page, in the Box widget, click the SDK folder and download the pentaho-sdk- 5.0.0.zip file. The readme file contains the information for deployment.

To deploy the samples to your Pentaho Server, follow these steps:

  1. Stop the Penthao Server.
  2. Run SDK > Installer.bat (or the corresponding script for your OS) to uncompress these two folders to your selected location: the integration-examples folder and platform-plugins.
  3. Copy the integration-examples directory to your pentaho-server/tomcat/webapps directory.
  4. Open the platform-plugins directory and copy these two folders: example-visualization and oem-tools.
  5. Paste them into the .../pentaho-server/pentaho-solutions/system directory.
  6. Restart the Pentaho Server.

The samples are deployed and can be accessed by opening a web browser and navigating to http://localhost:8080/integration-examples. If you want to access the OEM tools, browse to http://localhost:8080/pentaho/conten...web/index.html. If you want to access the example-visualization, look under the Charts menu in Analyzer. It will be listed as Example KPI.

To deliver content as well as expose various services, we use a REST web interface. These sections comment on the various samples and how they use the REST URLs. For the full reference of the Pentaho REST API, please refer to http://javadoc.pentaho.com.

The REST APIs often allow interaction with repository files. The REST API expects references to repository files to be specified using the : character as file separator.

Reporting Samples

The following samples show how to render reports in various web applications.

Execute a Report from a HTML Form (POSTing Parameters)

This sample renders a prpt report by posting the report parameters to the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/generatedContent

The POST request contains all parameters the report expects, plus the additional rendering parameter output-target, which controls the rendering format (HTML, PDF, XLS, etc.)

The following output formats are supported:

Option Purpose
table/html;page-mode=stream

HTML as a single page, all report pagebreaks are ignored.
table/html;page-mode=page

HTML as a sequence of physical pages, manual and automatic pagebreaks are active.
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;page-mode=flow

Excel 2007 XLSX Workbook
table/excel;page-mode=flow

Excel 97 Workbook
table/csv;page-mode=stream

CSV output
table/rtf;page-mode=flow

Rich text format
pageable/pdf

PDF output
pageable/text

Plain text
pageable/xml

Pageable layouted XML
table/xml

Table-XML output
pageable/X-AWT-Graphics;image-type=png

A single report page as PNG.
mime-message/text/html

MIME email with HTML as body text and all style and images as inline attachments.

Render a Report in an IFRAME

This sample renders a prpt report using a regular GET request, by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/generatedContent?<parameters>

The request contains all parameters as part of the URL.

Render Report Viewer with Available Parameters and Executed Report

The sample renders the Pentaho Report Viewer IU by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/viewer?<parameters>

The request contains the initial report parameters as part of the URL.

Publish a File to the Pentaho Server

Follow this process if you want to publish a file to the Pentaho Server:

Click the link that publishes a file to the Pentaho Server: http://localhost:8080/api/repo/publish/publishfile. This publishes the file to the provided path in the repository. Note that the file will be overwritten if the overwrite flag is set to true.

Table 1. Parameters
Name Description Type Default
pathId (colon separated path for the repository file) formdata false
fileContents (input stream containing the data) formdata false
overwriteFile (flag to determine whether to overwrite the existing file in the repository or not) formdata false
fileInfo (information about the file being imported) formdata false

Sample code for reference purposes can be found at Github for Pentaho. Look for the file called PublishRestUtil.java under the pentaho-reporting repostitory.

The file is now published to the Pentaho Server and is available to users.

Analyzer Samples

The following samples show how to embed analysis reports into other web applications.

Display a Report in Viewer Mode

This sample renders a display using a regular GET request, by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/viewer

The viewer has limited possibilities for interaction and does not allow changing the report.

Display a Report in Editor Mode

The sample renders a full Analyzer IU by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/editor

The IFRAME now renders the full Analyzer user interface, allowing users to interact with the data.

Create a New Report

The sample prepares a new report by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/xanalyzer/editor?catalog=<Schema>&cube=<CubeName>

The mandatory catalog and cube parameters specify the analysis schema and cube to use for the new report.

Integrate into a Custom Web Application via an IFRAME

The sample opens a new page that mimics a parent application that integrates Analyzer using an IFrame. The parent application has a set of buttons interacting with the Analyzer UI in the embedded IFRAME. Studying this page is a good starting point, if you are trying to deeply integrate analyzer into your own web application.

Specify the Select Schema Service

The sample is opened with a specified data service.

http://localhost:8080/pentaho/api/repos/xanalyzer/service/selectSchema

After a data service is selected, the sample opens and shows an unsaved Analyzer report using that data service.

Interactive Reporting Samples

The following samples show how to embed interactive reports into other web applications.

Display an Interactive Report

This sample renders a .prpti report using a regular GET request, by populating an HTML IFRAME with the report REST URL. The viewer has limited possibilities for interaction and can't edit the report. The example below shows how to do this by replacing the path within the <> with the URL for the report that you want to view.

http://localhost:8080/pentaho/api/repos/<%3Ayour%3Apath%3Agoes%3Ahere.prpti>/prpti.view

You can use the prpti.edit end-point instead, to allow more user interaction with the report.

http://localhost:8080/pentaho/api/repos/<%3Ayour%3Apath%3Agoes%3Ahere.prpti>/prpti.edit

Create a New Interactive Report

The sample prepares a new report by populating an HTML IFRAME with the report REST URL.

http://localhost:8080/pentaho/api/repos/pentaho-interactive-reporting/prpti.new

In order to show the toolbar buttons so that users can create, open, or save Interactive reports, add the following to the end of the URL.

?showRepositoryButtons=true

Users will be prompted to select the data source they want to work with.

Integrate into a Custom Web Application via an IFRAME

The sample opens a new page that mimics a parent application that integrates the Interactive Reporting editor using an IFrame. The parent application has a set of buttons interacting with the Interactive Reporting UI in the embedded IFRAME. Studying this page is a good starting point, if you are trying to deeply integrate Interactive Reporting into your own web application.

Action Sequence Samples

The following samples show how to embed an action sequence into other web applications.

Run an Action Sequence to Generate a Report

This sample renders an xaction report using a regular GET request, by populating an HTML IFRAME with the report REST URL:

http://localhost:8080/pentaho/api/repos/<path>/generatedContent?<parameters>

The parameters for the xaction are passed as simple GET parameters on the URL.

Run an Action Sequence to Generate a Report with Prompts

The sample prepares a form to collect parameters and POSTs them to the xaction REST URL:

http://localhost:8080/pentaho/api/repos/<path>/generatedContent

The xaction now retrieves its parameters from the POST request body.

Configure the Proxy Trusting Filter

If you have set the Pentaho Server to run on a specific IP address or hostname other than the default 127.0.0.1, you must modify the trusted proxy to match that address or hostname for Pentaho plugins to run as expected. Additionally, if you have applications that access Pentaho Server resources, such as REST APIs, you must add that application's IP address so that the Pentaho Server will accept those requests.

  1. Stop the Pentaho Server.
  2. Open pentaho-server/tomcat/webapps/pentaho/WEB-INF/web.xml and search for TrustedIpAddrs.

    The param-value immediately below TrustedIpAddrs is a comma-separated list of IP addresses that should be trusted.

  3. Add the IP address of the host machine. 
    <filter>
    <filter-name>Proxy Trusting Filter</filter-name>
    <filter-class>org.pentaho.platform.web.http.filters.ProxyTrustingFilter</filter-class>
        <init-param>
            <param-name>TrustedIpAddrs</param-name>
            <param-value>127.0.0.1</param-value>
            <description>Comma separated list of IP addresses of a trusted hosts.</description>
        </init-param>
</filter>
  4. Start the Pentaho Server.

Developer Support

The examples in this section are simple and easy to follow, but with more complex requirements come more advanced programs. While reading the source code comments can help quite a bit, you may still need help to develop an application within a reasonable time-frame. Should you need personal assistance, you can have direct access to the most knowledgeable support resources through a Pentaho Enterprise Edition software vendor annual subscription:

ISV/OEM support options

If phone and email support are not enough, Pentaho can also arrange for an on-site consulting engagement:

Consultative support options

License Information

Most of the software comprising Pentaho Business Analytics is open source, licensed under the GNU General Public License version 2. Business Analytics also contains a large volume of third-party open source libraries that are registered under a number of different licenses. Most of this software is freely redistributable, with the notable exceptions of the following Pentaho-authored programs:

  • Dashboard Designer
  • Analyzer
  • Interactive Reporting
  • Various individual BI Platform JARs

If you already have regular Pentaho licenses for the BI Platform, Dashboard Designer, Interactive Reporting, and Analyzer, then no further licenses are required to integrate Pentaho Business Analytics functionality into a third-party application. If you wish to embed pieces of the Pentaho Server into an application that you intend to sell or distribute, you must familiarize yourself with the licenses of all of the pieces you are including in order to make sure you are complying properly. Proprietary Pentaho software may not be redistributed under any circumstances.

This section is not intended for redistribution. However, the example code and example application that accompany this document may be freely modified or reused.