Embed Pentaho Server Functionality into Web Applications
- Get Started with the Embedded Samples
- Reporting Samples
- Publish a File to the Pentaho Server
- Analyzer Samples
- Interactive Reporting Samples
- Action Sequence Samples
- Configure the Proxy Trusting Filter
- Developer Support
The following samples use various development techniques to demonstrate how to embed Pentaho Server functionality and content into another web application.
Get Started with the Embedded Samples
The samples are available on the Pentaho Customer Support Portal.
- On the Customer Portal home page, sign in using the Pentaho support user name and password provided in your Pentaho Welcome Packet.
- Click Downloads, then navigate to the Pentaho GA Release which matches your version of the software.
- 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:
- Stop the Penthao Server.
- 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.
- Copy the integration-examples directory to your
- Open the platform-plugins directory and copy these two folders: example-visualization and oem-tools.
- Paste them into the
- 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.
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:
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:
HTML as a single page, all report pagebreaks are ignored.
HTML as a sequence of physical pages, manual and automatic pagebreaks are active.
Excel 2007 XLSX Workbook
Excel 97 Workbook
Rich text format
Pageable layouted XML
A single report page as PNG.
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:
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:
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
|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.
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:
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:
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:
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.
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.
You can use the prpti.edit end-point instead, to allow more user interaction with the report.
Create a New Interactive Report
The sample prepares a new report by populating an HTML IFRAME with the report REST URL.
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.
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:
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:
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.
- Stop the Pentaho Server.
- 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.
- 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>
- Start the Pentaho Server.
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:
If phone and email support are not enough, Pentaho can also arrange for an on-site consulting engagement:
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
- 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.