You can grab a copy of the guide in Google Docs format and the SQL Script Pack at the projects page.

As always please let me know if you find any errors and also if you would like to see any further additions to guides and support for other databases.

Prashant.

This guide has been tested and works with the latest version of Pentaho BI Server 3.6.

Updated 28/02/2010

This guide has been tested and works with the latest version of Pentaho BI Server 3.5.2.

Updated 09/02/2010

All the guides have been updated as well as the MySQL and PostgreSQL SQL Packs. I have made a bunch of fixes to grammatical and spelling errors (ouch!), cleaned up the layout and process flow, extended the Java and Tomcat-Apache sections and added SMTP and Publishing sections (all changes are listed on the front page of each guide).

Last year I created a tutorial on how to install Pentaho Business Intelligence Server 2.0 with MySQL on Linux and the response was overwhelming with the amount of people who found the tutorial helpful.

I have taken the suggestions and feedback and have updated the tutorial for 3.5 and added PostgreSQL 8+ and Oracle 10g (XE and 11g) to the list, all the tutorials are split up for Windows and Linux operating systems.

Can’t wait? Head over to the Pentaho project page and start downloading!

Scenario.

I have two separate data sources, the first data source (ds01) has information about my employees i.e. employee code, office location, created date. My second data source (ds02) has satisfaction survey responses for each employee which was provided by an external company i.e. employee code, question title, response. I would like to retrieve for each employee the question and response from the satisfaction survey but only for employees who were created in the last month.

Flow.

The flow of the Jobs and Transformations which will make up this ETL process are:

• Job : Process employee satisfaction
  • Transformation : Get employee details
    • Get system data : Get last months date
    • Table input : Get employee data
    • Copy rows to result
  • Transformation : Get employee satisfaction
    • Get rows from result
    • Table input : Get satisfaction data
    • Excel output : Store results

Data sets.

The first data set ds01 (employee data) looks like this:

The second data set ds02 (satisfaction data) looks like this:

Step 1. Create the parent Job.

The first step is to create the parent Job, Process employee satisfaction. Once PDI has started to create a New Job you can either click on the File > New > Job option or use the CTRL + ALT + N shortcut.

Save the Job (using the File > Save option or CTRL+S shortcut) and name the file Process employee satisfaction.

Step 2. Create the Shared Database connections.

The next step is to create two shared database connections one for ds01 the other for ds02. While the Process employee satisfaction job is open make sure the View tab is visible (in the left hand side pane) and right click on the Database connections item and select the New option.

The Database Connection window will appear. You will then to fill out the available options for your database connection, as an example ds01 uses a MySQL database so my options after they were filled out looked like this:

• Connection Name : Name of your connection i.e. ds01
• Host Name : Host of your database server i.e. localhost
• Database Name : Name of the database which holds your information i.e. employees
• Port Number : Port which your database is listening on i.e. 3306
• Username : User to access the database i.e. root
• Password : Password to access the database

For ds02 my connection options looked like this:

• Connection Name : Name of your connection i.e. ds02
• Host Name : Host of your database server i.e. localhost
• Database Name : Name of the database which holds your information i.e. satisfaction
• Port Number : Port which your database is listening on i.e. 3306
• Username : User to access the database i.e. root
• Password : Password to access the database

After filling out the required fields you should always test your connection by clicking the Test button, you should receive a success message similar to the one below:

Repeat the steps above for the second database connection ds02. When you are done you should have both ds01 and ds02 database connections listed under the Database connections folder:

The last step is to share both the database connections so that they can be used throughout any other jobs and transformations which are created. Right click on the ds01 database connection and click the Share option:

Repeat the above step for ds02, you should now see both database connections in bold:

Now that the database connections have been created and shared save the Job and restart Kettle. In the following steps you will create the transformations.

It is important that you restart Kettle so that the shared database connections can be used within the transformations.

Step 3. Create the Transformations.

1. Get employee details.

The first transformation that you will need to create will require the following steps:

1. Get System Data : Get last month date
2. Table input : Get employee data
3. Copy rows to result

The first step is to create the Transformation, Get employee information. To create a new Transformation you can either click on the File > New > Transformation option or use the CTRL + N shortcut.

Save the transformation and name it Get employee information.

The first step will retrieve last month’s date using the Get System Data step. Drag and drop the Get System Data (under Inputs) step from the left hand side onto the workspace and double click on it to edit the options. After making the changes the Get System Data step now look like this:

After clicking the OK button the workspace now looks like this:

The next step, Get employee data uses a Table input (under Inputs) step which also utilises the previous steps (Get last month date) value as a variable in the WHERE clause. Drag and drop the Table input step from the left hand side pane onto the workspace and create a Hop between the Get last month date and the Table input step.

To create Hops click on the first step, hold down the SHIFT button and drag the arrow to next step.

Double click on the Table input step to change the options, after making the changes the options now look like this:

• Step name : Name of the step i.e. Get employee data
• Connection : The connection which the step is using i.e. ds01
• SQL : SQL statement used to retrieve the information, in this example we are retrieving employee codes who were created in the last month (which has been replaced with a ? to make it dynamic)
• Replace variables in script : Checked, we are using variables from the previous step which I have represented with a ? in the SQL statement
• Insert data from step : Selected the previous step, Get last month date as this contains the variable needed in the SQL statement

You can read more into how to use variables in Table input steps on the Pentaho Wiki.

After clicking the OK button the workspace now looks like this:

You can make sure that the variable replacement is working you can preview the output of the Get employee data step by clicking on the step and then the preview (icon) or right clicking on the step and selecting the Preview option. This will open up a Transformation debug dialog window:

Click the step which you would like to preview which in this example is Get employee data and click the Quick launch button, you should now be shown a preview of the data set from the Get employee data step:

The last step is a Copy rows from result step, this will copy the output from the previous step Get employee data to the result (memory). Drag and drop the Copy rows from result step (under Job) from the left hand side pane on to the workspace and create a Hop between the Get employee data and the Get rows from result step.

Save the transformation.

2. Get employee satisfaction.

The second transformation you will need to create will require the following steps:

1. Get rows from result
2. Table input : Get satisfaction data
3. Excel output

The first step is to create the Transformation, Get employee information. To create a new Transformation you can either click on the File > New > Transformation option or use the CTRL + N shortcut.

Save the Transformation and name it Get employee satisfaction.

The first step will retrieve the data which is stored in the result (memory) by the Copy rows to result step in the previous transformation using the Get rows from result step. Drag and drop the Get rows from result (under Jobs) step from the left hand side onto the workspace and double click on it to edit the options. After making the changes to the Get rows from result step the options now look like this:

Make sure you enter the exact name of the fields that you copied to the result which in this example was from the Table input step Get employee data, these were named emp_code.

The next step Get satisfaction data will be use Table input (under Scripts) step which will utilise the values of the previous step, Get rows from result in the WHERE clause. Drag and drop the Table input step from the left hand side pane onto the workspace and create a Hop between the Get rows from result and the Table input step:

Double click on the Table input step to change the options, after making the changes the options now look like this:

• Step name : Name of the step i.e. Get satisfaction data
• Connection : The connection which the step is using i.e. ds02
• SQL : SQL statement used to retrieve the information, in this example we are retrieving employee satisfaction results for each employee code (which has been replaced with a ? to make it dynamic) stored in the result (memory) from the Get rows from result step
• Replace variables in script : Checked, we are using variables from the previous step which I have represented with a ? in the SQL statement
• Insert data from step : Selected the previous step, Get rows from result as this contains the variable needed in the SQL statement
• Execute for each row? : Check, in this example we need to run this query for each row stored in the result (memory)

Click OK your workspace will now look like this:

The last step is to create an Excel Output step which will store the results from the Get satisfaction data step. Drag and drop the Excel Output step from the left hand side pane onto the workspace and create a Hop between the Get satisfaction data and Excel Output step.

Double click on the Excel Output step to change the options, after making the changes the options now look like this:

• File tab
  • Filename : Name and location of where the Excel file will be stored i.e. /Users/prashantraju/Desktop/result
  • Extension : Extension of the file i.e. .xls
• Content tab
  • Append : Append the results to the file, in this example the output will run for each row in the result (memory) so you will need to append the results to the file otherwise you will only see the last row from the ETL process
  • Header : Include the header in the output, in this example that is emp_code, emp_name, question_title and response
• Fields tab
  • The fields which will be outputted into the Excel sheet, in this example it is only emp_code, question_title and response

Click OK to save the step and also save the Transformation.

Step 4. Complete the Job.

The last and final step is to complete the Job which we created in Step 1, the job will require four steps:

1. START
2. Transformation: Get employee information
3. Transformation: Get satisfaction information
4. Success

Open the Process employee satisfaction job and drag and drop a START step (under General), two Transformation steps (under General) and a Success step (also under General) onto the workspace and create a Hop between each of them so that your workspace now looks like this:

You will need to make changes to both Transformation steps so that they point to the Get employee information and Get employee satisfaction transformations which were created in Step 3. Double click on the first transformation and change the options so that they now look like this:

Click OK to save the step.

Repeat the above steps but for the Get employee satisfaction step.

Click OK to save the step and also save the Job. Now you are ready to test the Job.

Step 5. Test the Job.

To run the ETL process make sure you have the Process employee satisfaction job open and click on the (run) icon to run the Job, this will display a Execute a job window after changing the options i.e. log detail etc:

After clicking the Launch button and opening the result.xls file on my Desktop the output shows for each employee code the question and response:

Downloads.

Final Notes.

This example may not be the best way to represent the use of Table inputs and variables but hopefully the detail and the inclusion of storing rows in results, using system variables and debugging steps can help you with your PDI learning curve (not that that there is a big one anyway!).

As always, enjoy!

Scenario.

I wanted to create a bar chart which has a dynamic width (expand or contract) depending on the amount of categories a user selected from a multi value list parameter. This would ensure that the chart didn’t become squashed and unreadable. in this tutorial I will be using a data set which represents population by countries.

Data Set.

Below is an example of the data set I will be using for this tutorial, as you can see each country has a population (you can download a spreadsheet version of the sample data at the end of this tutorial).

* Population is calculated in the millions

Step 1 – Data Source.

Start PRD and create a new report. Right click on the Data Sets icon and select the JDBC option from the menu.

After selecting the JDBC option a JDBC Data Source window will appear. I have already created a connection to my database which includes the data that I will be working on, in this example it is called Geography.

Once you have a working connection to your database you are now ready to create your queries.

Step 2 – Queries.

This report contains two separate queries:

1. qCountries : Retrieves a distinct list of countries, this will be used for the countries parameter
2. qDataset : Retrieves the population for the countries selected by a user

pCountries.

The qCountries query needs to return a distinct list of countries, the SQL query looks like this:

SELECT   DISTINCT COUNTRY
FROM     dataset

A screen shot of the JDBC Data Source window of the qCountries query looks like this:

qDataset.

The qDataset query needs to return the population for countries which the user has selected, the SQL query looks like this (this query will need to use a parameter which I will add in later):

-- Use a sub query to calculate the total amount of countries selected
SELECT    t1.COUNTRY AS COUNTRY,
               SUM(t1.POPULATION) AS POPULATION,
               SUM(t2.COUNTRY_COUNT) AS COUNTRY_COUNT
FROM      dataset t1,
          (
              SELECT COUNT(*) AS COUNTRY_COUNT
              FROM dataset
              GROUP BY COUNTRY
          ) t2
GROUP BY COUNTRY

A screen shot of the JDBC Data Source window with the qDataset query looks like this:

Step 3 – Parameter.

There is only one (multi value list) parameter in this report which will display a distinct list of countries and be populated by the qCountries query. To create a new parameter right click on the Parameters option under the Data tab and click the Add Parameter… option:

This will bring up the Add Parameter window. After filling out all the options the Add Parameter window now looks like this:

Where the options and values are:

• Name : This is the name of the parameter, this is used within report queries i.e. the WHERE clause of qDataset
• Label : The text which sits next to the parameter on the report i.e. Select one or more countries
• Value Type : The data type of the sCountries value i.e. COUNTRY is a String
• Mandatory : For the report to run a parameter value must be selected i.e. Checked (true)
• Display Type : The parameter type i.e. Multi Value List
• Value : The parameters value which will used within queries etc. i.e. the field COUNTRY
• Display Name : What the user will see the parameter value as i.e. the field COUNTRY
• Visible items : The amount of items which are shown to the user in the multi value list parameter i.e. 3

Click OK to save the parameter, it should now be visible under the Parameters item under the Data tab.

After adding the sCountries parameter the next step is to use the parameter as part of the qDataset WHERE clause. Right click on the qDataset item under the Data tab and click the Edit Query option:

Modify the qDataset query so that it now includes the sCountries parameter:

-- Use a sub query to calculate the total amount of countries selected
SELECT    t1.COUNTRY AS COUNTRY,
               SUM(t1.POPULATION) AS POPULATION,
               SUM(t2.COUNTRY_COUNT) AS COUNTRY_COUNT
FROM      dataset t1,
          (
              SELECT COUNT(*) AS COUNTRY_COUNT
              FROM dataset
              WHERE COUNTRY IN (${sCountries})
              GROUP BY COUNTRY
          ) t2
WHERE COUNTRY IN (${sCountries})
GROUP BY COUNTRY

Step 4 – Bar Chart.

The next step is to create a bar chart whose width is dynamic based on the amount of countries a user selects. To get started drag and drop the chart object onto the report header.

As you can see the width is fixed at the moment but before I start to make any changes to the chart’s width I will need to configure my chart to display our data and see how it becomes unreadable when we increase the amount of categories on the x axis. Double click on the chart and to bring up the Edit Chart window.

By default the chart is set to a bar chart and without going through every available option I made the following changes to represent my data set:

• chart-title : Chart title i.e. Population of Countries (optional)
• gridlines : Are the vertical and horizontal grid markers i.e. Set to False (optional)
• x-axis-title : Label of the x-axis i.e Countries
• x-axis-label-rotation : Rotation of the x-axis label i.e. 90
• y-axis-title : Label of the y-axis i.e. Population (millions)
• category-column : Field which will be on the x-axis i.e. COUNTRY
• value-columns : Field which populates the y-axis i.e. POPULATION
• series-by-field : Field which defines the series i.e. COUNTRY

After previewing the chart with all the countries selected you can see that the output is squashed and unreadable.

One way around this is to make the width (or height) of your chart dynamic by the amount of countries the user selects from the multi value list parameter. Select the chart and on the right hand side under the Style tab locate the size & position option and click the icon under the Formula column. This will display an Expression window, click on the icon which will then open the Formula Editor window.

The formula below retrieves the COUNTRY_COUNT field and multiplies it by the width of the chart which suits one category (country) on the x axis, which in this example is 150.

# If there is only one country selected then use default width otherwise calculate width
=IF([COUNTRY_COUNT]=1;150;[COUNTRY_COUNT]*150)

Save the formula. Now you are ready to preview the report.

Step 5 – Preview.

Click on the preview icon and select one country from the multi value list parameter, as you can see the width is set to our default width, 150.

Selecting two countries from the multi value list parameter will expand the width to 300.

Selecting four countries from the multi list parameter will expand the width to 600.

So that is how you create a chart which can expand or contract depending on the amount of categories displayed on the x axis.

Downloads.

Final Notes.

A couple of things to note about the method I used:

• The query to generate the amount of selected countries uses a sub query and could cause performance issues with large data sets etc.
• This method can be used for both the width and height and on any other object within PRD i.e. shapes, labels, pictures etc.

Hopefully this comes in handy when you start handling large data sets and charts!

Enjoy!

My current report (based on the Steel Wheels sample data) displays the product code and product name based on multiple selections of product codes using a multi value list parameter type:

To populate the above report I use the following queries:

-- Name: product
-- Description: Populates the main report
SELECT
  PRODUCTCODE, PRODUCTNAME
FROM
  PRODUCTS
WHERE
  PRODUCTCODE IN (${productCodes})
 
-- Name: productsList
-- Description: Populates the product code parameter
SELECT
  DISTINCT PRODUCTCODE
FROM
  PRODUCTS

The options for the product code multi value list parameter are:

Now I need to display the multi list parameter values (product codes) in the report header but formatted like this:

S10_1678, S10_1949, S10_2016

To create the above format I’m going to use MySQL’s GROUP_CONCAT function (there are similar functions out there for PostgreSQL, Oracle, SQL Server etc.) in a new query. The query which uses the GROUP_CONCAT function looks like this:

-- Name: productsSelected
-- Description: Displays a friendly formatted list of parameters inside the sub-report using the productCodes parameter
 
SELECT
  GROUP_CONCAT(PRODUCTCODE, ', ')
FROM
  PRODUCTS
WHERE
  PRODUCTCODE IN ({$productCodes})

As this is a separate query I will need to create an inline sub-report. The first step is to drag and drop the sub-report object from the left pane onto the report-header and assign the productsSelected query:

The next step is to double click on the sub-report to work inside it. Once the sub-report has opened under the Data tab right click on the Parameters item and select the Edit Sub-report Parameters… option. From the Sub-report parameters window add in the productCode parameter under the Import Parameters area (Outer and Inner) and click OK to save.

To display the multi value list field (GROUP_CONCAT(PRODUCTCODE, ‘, ‘)), I dragged and dropped the field from the productsSelected query under the Data tab onto the report header section and also added a label Selected Product Codes:

After the previewing the report I can now see that the parameters from the multi value list are displayed in a friendly format:

This method does have a downfall as it runs another query but it is a simple and clean way of outputting the values of multi value list parameters.

Do you use a different method? Let me know by posting a comment!

Enjoy.

I have 40 sale campaigns. I need to put together a quick presentation (as a PDF) which will show 2 key metrics (New and Loss revenue) for each of the 40 sale campaigns. Do you know of a quick way I can produce this presentation?

I thought this would the perfect opportunity to show off Pentaho Report Designer (PRD) as an alternative to Mircosoft Excel, Access or other big BI vendors. Below is a step by step guide on how I accomplished this.

Scenario.

The above statement sums up the users requirements, visually the the report needed to look like this:

After I knew the structure of the report I got the user to export the data into an Excel Worksheet – this was going to be my data source – after this it took me only 5 minutes to create the presentation using PRD.

Data Source.

The end user was able to produce a raw extract of the data which the report needed to be based on. Here is a preview of the data:

• Campaign: Campaign identifier which duplicates for each week row
• Week: Week ending date which is for 2010
• New_09, Loss_09: Revenue for 2009
• New_10, Loss_10: Revenue for 2010

To use an Excel worksheet as a data source make sure the Data tab is active, right click on the Data Sets icon and select the Table option:

After clicking the Table option a Table Datasource Editor window is displayed:

Step 1. Create a Query.

The first step is to create a query which will store the data set. Click on the  (Add Query) icon and then specify a name, in this example I’m naming the query dataset.

Step 2. Select the Excel Worksheet.

The next step is to select the Excel worksheet which contains the data set. Click on the  icon located in the bottom left hand corner to open up a file browser window, select the Excel file which contains the data set and click OK. Your data set should now be visible (as my Excel worksheet has headers I have checked the Use First Row as Header option).

At the moment you can only use .XLS files so if you are using Office 2007+ make sure you save the extension as .XLS instead of .XLSX and if your .XLS file contains formulas they will not be recognised by PRD so be sure to paste special as values.

Step 3. Manipulate the Data.

You can add empty rows and columns or remove rows and columns by using these icons:

You are also able to change the column headers and data type by double clicking on the column header:

In this example I didn’t need to make any modifications to the data however I did have trouble converting the Week_Ending field into a date format so in the Excel worksheet I converted it into a string using the TEXT() function – if anyone knows how to get this working please lleave a comment.

Once you are happy with the data set click the OK button. The data set should now be visible as fields under the Data Sets > Table > dataset icon under the Data tab:

Building the Report.

The next step was to build the report, from the report structure (above) I knew I had to create one group Campaign, and within that group add 2 charts which represented the New and Loss Revenue for 2009 and 2010.

Step 1. Add the Group.

To get started add the Campaign field as a group by right clicking on the Groups item under the Structure tab and selecting the Edit Group .. option:

After clicking the Edit Group .. option an Add Group window will appear, specify a name for the group i.e. Campaign and using the arrows move the field over which defines the group which in this example is Campaign and click OK when done.

The Campaign field will now be defined under the Attributes tab for the Group item:

The next step is to make the Group Header and Details Header are visible on the report canvass. Click on the Groups > Group Header item under the Structure tab and and under the Attributes tab uncheck the hide-on-canvass option:

Repeat the above steps for the Groups > Details Body > Details Header item as well:

Step 2. Functions.

I will need to create three functions; one which will convert the Week_Ending field into a date and the other two will be display dynamic chart titles.

Converting the Date.

As I mentioned above I had some issues with letting PRD convert the Week_Ending field into a date from the Table Datasource Editor, so to get around this I created a formula which would take the Week_Ending field (as a string) and convert it into a Date.

To do this create a new function by right clicking on the Functions option under the Data tab and click the Add Function… option.

From the Add Function… window expand the Common folder and select the Open Formula option and click the Add button:

This will add an Open Formula function under the Functions option (seen under the Data tab) :

To change the name of the function (named by default as FormulaExpression1) click on the function and in the area below change the value that is set for the Function Name, in this example I named the function New_Week_Ending:

To edit the formula of the function click on the  icon which is displayed when you click in the Formula value area, this will display a Formula Editor window:

As my date is in the current format YYYY-MM-DD I needed to use the DATE function with a combination of LEFT, MID and RIGHT functions to convert it into a date. I won’t go into too much detail with this section as all these functions are pretty self explanatory and are well documented in the Formula Editor but the final formula looked like this:

=DATE(LEFT([Week_Ending];4);MID([Week_Ending];6;2);RIGHT([Week_Ending];2))

Click the OK button to save the New_Week_Ending formula. I have just created a function which will convert the Week_Ending (string) field into a New_Week_Ending (date) field so that the X-Y Chart TimeSeries Collector will now recognise it as a date.

Dynamic Chart Titles.

Each chart needs to have a dynamic title which will output the campaign and the measure which is represented i.e. 1 – New Revenue ($). As I have two charts for each campaign I will need to create two functions: one for the New Revenue chart and one for the Loss Revenue chart.

Following the steps outlined above to create two new functions (with the names sNewChart and sLossChart) using the Open Formula type and specify the formulas to be:

# New Revenue Charts (sNewChart)
=[Campaign] & " - New Revenue ($)"
# Loss Revenue Charts (sLossChart)
=[Campaign] & " - Loss Revenue ($)"

I have now created three functions:

Step 2. Add the Group Header.

To add the Campaign as the Group Header drag and drop the Campaign field from the Data tab onto the Group Header area and apply some formatting:

Step 3. Add the Charts.

Each chart needed to look similar to this mockup (I have already created the Chart Title and New_Week_Ending functions):

Drag and drop a chart object from the panel located on the left hand side onto the Details Header section and double click the object to open up the Edit Chart (properties) window . To create a X-Y Chart which uses a TimeSeries Collector make sure you Edit Chart (properties) window looks like this:

After setting up all the options the Edit Chart (properties) window now look like this (for the New Revenue measure):

• Title
  • chart-title-field: Field or function which is the chart title i.e. sNewChart or sLossChart
• Primary DataSource
  • Common
    
    • category-time-option: Value of the x-axis, this must match the amount of series you have in the value-column option i.e. New_Week_Ending (twice)
    • time-period-type: Type of period the above field is i.e. Week and New_Week_Ending is an increment of weeks
    • value-column: Field(s) which contain the y-axis, you can specify more than one as there can be multiple series i.e. New_09 and New_10 or Loss_09 and Loss_10
  • Series
    • series-by-value: Name of the each series specified for the above option i.e. 2009 and 2010
  • Group
    • reset-group: Reset the charts after a specific group(s) i.e. Campaign

There was alot of extra formatting on the charts so be sure to check out the available .PRPT file if you interested in what they look like.

After I created the chart for New Revenue I just copied and pasted the chart object and made changes to the properties to create the Loss Revenue chart:

The final report structure looks like this:

There are a lot of options in the charting library of PRD so I suggest you pick up Will Gorman’s book Pentaho Reporting 3.5 for Java Developers which has a couple of chapters which cover the charting library in detail.

Step 4. Add the Page Break.

The last step was to add a page break after each Campaign group. To do this click on the Details Body item under the Structure tab and check the pagebreak-after option:

Output.

After previewing the report the final output as a PDF looks like this (you can download the actual PDF file below):

Downloads.

Final Notes.

This post is very detailed as it covers some interesting areas but as this was an ad hoc request it took me under 5 minutes to whip together this report and have it in the user’s inbox. Do you have any examples of how you handled ad hoc requests with PRD? If so, leave a comment or send me an email.

One user converted n to go! Enjoy.

• Login page and dialog
• Messages
• Main toolbar, menu bar and logo panel
• Launch page (covered in this post)

In this post I will show you how to customise the launch page.

The Launch Page

The launch page is the default page that is displayed when you log into the PUC, below is a screenshot of the launch page:

launch.jsp

The contents of the launch page are generated by the launch.jsp file which is located under the tomcat/webapps/pentaho/mantle/launch/ directory, the images which are used for the launch page are located under the tomcat/webapps/pentaho/mantle/launch/images directory.

The contents of the launch.jsp are:

<%@ taglib prefix='c' uri='http://java.sun.com/jstl/core'%><%@
    page
  language="java"
  import="java.io.InputStream,
      java.util.Locale,
      java.util.PropertyResourceBundle,
      java.util.ResourceBundle,
      java.util.regex.Pattern,
      java.util.regex.Matcher,
      org.pentaho.platform.util.messages.LocaleHelper,
      org.pentaho.platform.api.engine.IPentahoSession,
      org.pentaho.platform.api.engine.IPluginManager,
      org.pentaho.platform.api.repository.ISolutionRepository,
      org.pentaho.platform.engine.core.system.PentahoSystem,
      org.pentaho.platform.engine.core.system.StandaloneSession,
      org.pentaho.platform.util.logging.Logger,
      org.pentaho.platform.web.jsp.messages.Messages,
      org.pentaho.platform.web.http.PentahoHttpSessionHelper,
      org.apache.commons.lang.StringEscapeUtils"%>
<%
  /*
   * Copyright 2006 Pentaho Corporation.  All rights reserved.
   * This software was developed by Pentaho Corporation and is provided under the terms
   * of the Mozilla Public License, Version 1.1, or any later version. You may not use
   * this file except in compliance with the license. If you need a copy of the license,
   * please go to http://www.mozilla.org/MPL/MPL-1.1.txt. The Original Code is the Pentaho
   * BI Platform.  The Initial Developer is Pentaho Corporation.
   *
   * Software distributed under the Mozilla Public License is distributed on an "AS IS"
   * basis, WITHOUT WARRANTY OF ANY KIND, either express or  implied. Please refer to
   * the license for the specific language governing your rights and limitations.
   *
   * @created Jul 23, 2005
   * @author James Dixon
   *
   */
%>
 
<%@page import="org.pentaho.ui.xul.XulOverlay"%>
<%@page import="org.pentaho.platform.api.engine.IPluginManager"%><html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
 
 
<title><%=Messages.getString("UI.PUC.LAUNCH.TITLE")%></title>
 
<style type="text/css">
<!--
body {
  color: #000000;
  background-color: #FFFFFF;
  margin: 0px;
}
 
p {
  margin: 0px;
  padding: 0px;
}
 
A:link,A:visited,A:hover {
  color: #7e932f;
  text-decoration: underline;
}
 
A:hover {
  color: #ca6333;
  text-decoration: underline;
}
 
.launchPanel {
  background-color: white;
  background-image: url(images/quicklaunch_bg.png);
  background-repeat: no-repeat;
  background-position: center;
  height: 100%;
}
 
.ql_container {
  width: 620px;
  margin-bottom: 50px;
}
 
.ql_icon_bar_left {
  width: 41px;
  height: 147px;
  vertical-align: top;
  padding-top: 25px;
}
 
.ql_icon_bar_middle {
  background-image:
    url(images/ql_icon_bar_middle.png);
  background-repeat: repeat-x;
  width: 100%;
  height: 199px;
}
 
.ql_icon_bar_right {
  width: 41px;
  height: 147px;
  vertical-align: top;
  padding-top: 25px;
}
 
.ql_spacer {
  width: 20px;
}
 
.ql_btn {
  width: 167px;
}
 
.ql_btn_left {
  width: 41px;
  height: 56px;
}
 
.ql_btn_middle {
  background-image: url(images/ql_btn_middle.png);
  background-repeat: repeat-x;
  width: 100%;
  font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
  font-size: 1.25em;
  line-height: 20px;
  font-weight: 300;
  text-align: center;
  vertical-align: top;
  white-space: nowrap;
  padding-top: 5px;
}
 
.ql_btn_right {
  width: 41px;
  height: 56px;
}
 
.ql_btn_left_hover {
  width: 41px;
  height: 56px;
}
 
.ql_btn_middle_hover {
  background-image:
    url(images/ql_btn_middle_hover.png);
  background-repeat: repeat-x;
  width: 100%;
  font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
  font-size: 1.25em;
  line-height: 20px;
  font-weight: 300;
  text-align: center;
  vertical-align: top;
  white-space: nowrap;
  padding-top: 5px;
}
 
.ql_btn_right_hover {
  width: 41px;
  height: 56px;
}
 
.ql_new_report {
  width: 120px;
  height: 130px;
  padding-bottom: 13px;
  cursor: pointer;
}
 
.ql_new_analysis {
  width: 120px;
  height: 130px;
  padding-bottom: 13px;
  cursor: pointer;
}
 
.ql_manage {
  width: 120px;
  height: 130px;
  padding-bottom: 13px;
  cursor: pointer;
}
 
.ql_logo {
  width: 290px;
  height: 91px;
  padding-bottom: 30px;
}
 
.button {
  cursor: pointer;
  width: 167px;
  padding: 0px;
  spacing: 0px;
  height: 56px;
}
 
.btn_left {
  background-image: url("images/ql_btn_left.png");
  background-repeat: no-repeat;
  height: 56px;
  width: 22px;
}
 
.btn_right {
  background-image: url("images/ql_btn_right.png");
  background-repeat: no-repeat;
  height: 56px;
  width: 22px;
}
 
.btn_center {
  background-image: url(images/ql_btn_middle.png);
  background-repeat: repeat-x;
  width: 100%;
  font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
  font-size: 1.25em;
  line-height: 20px;
  font-weight: 300;
  text-align: center;
  vertical-align: top;
  white-space: nowrap;
  padding-top: 5px;
}
 
.btn_left_hover {
  background-image:
    url("images/ql_btn_left_hover.png");
  background-repeat: no-repeat;
  height: 56px;
  width: 22px;
}
 
.btn_right_hover {
  background-image:
    url("images/ql_btn_right_hover.png");
  background-repeat: no-repeat;
  height: 56px;
  width: 22px;
}
 
.btn_center_hover {
  background-image:
    url(images/ql_btn_middle_hover.png);
  background-repeat: repeat-x;
  width: 100%;
  font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
  font-size: 1.25em;
  line-height: 20px;
  font-weight: 300;
  text-align: center;
  vertical-align: top;
  white-space: nowrap;
  padding-top: 5px;
}
-->
</style>
 
<script type="text/javascript">
Button = function(label, container){
 
    var btn = document.createElement("input");
    btn.setAttribute("type","button");
 
 
    table = document.createElement("table");
    document.getElementById(container).innerHTML="";
    document.getElementById(container).appendChild(table);
 
    table.setAttribute("cellpadding","0");
    table.setAttribute("cellspacing","0");
    table.setAttribute("border","0");
    table.className="button";
    table.setAttribute("height","56");
    table.setAttribute("width","167");
    table.cellSpacing = "0px";
    table.cellPadding = "0px";
 
    var tbody = document.createElement("tbody");
 
    var tr = document.createElement("tr");
 
    var left_td = document.createElement("td");
    left_td.className="btn_left";
    left_td.innerHTML = "<img src='images/ql_spacer.png'/ width='22' height='1'/><br/>";
    tr.appendChild(left_td);
 
    var center_td = document.createElement("td");
    center_td.setAttribute("width","100%");
    center_td.className="btn_center";
    center_td.onselectstart=function(){return false;}
    center_td.style.MozUserSelect='none';
    center_td.innerHTML = label;
    tr.appendChild(center_td);
 
    var right_td = document.createElement("td");
    right_td.innerHTML = "<img src='images/ql_spacer.png'/ width='22' height='1'/><br/>";
    right_td.className="btn_right";
    tr.appendChild(right_td);
    tbody.appendChild(tr);
 
    table.appendChild(tbody);
 
    table.onmouseover=function(){
      window.selectedButton = this;
      left_td.className="btn_left_hover";
      right_td.className="btn_right_hover";
      center_td.className="btn_center_hover";
    };
    this.reset = function(){
      left_td.className="btn_left";
      right_td.className="btn_right";
      center_td.className="btn_center";
    }
 
    table.onmouseout = this.reset;
 
    this.onClick=function(onClick){
      if(window.parent && window.parent.mantle_initialized){
        table.onclick = function(){eval("window.parent." + onClick)};
      }
    };
}
 
window.onresize = function(){
  if(window.selectedButton){
     window.selectedButton.onmouseout();
  }
 
 
  // IE_6_FIX: When resized by PUC, IE will display rendering issues. This is accounted for by the code below. 
  if(window.isIE6){
 
    // IE6 has a rate limit on the number of resize events that it will fire. This means we cannot rely on the
    // resize event alone to determine when the reisize is complete. The timer ensures that the layout is
    // recomputed after PUC is done resizing the iframe.
    setTimeout(function(){
      window.tableWrapperDiv.style.top = "1px";
      window.tableWrapperDiv.style.top = "0px";
    }, 350);
 
  }
 
}
 
function loader(){
 
  // IE_6_FIX: We're using a CSS filter to enable transparany in IE 6. This has the side-effect of trapping mouse events in the
  // filtered area. The standard workaround is to wrap that area in two divs, one absolutely positioned inside a relative one.
 
  var navAgent = window.navigator.userAgent;
  window.isIE6 = false;
  var reg = new RegExp("MSIE ([0-9]{1,}[\.0-9]{0,})").exec(navAgent)
  if (reg != null) {
    var version = parseFloat( RegExp.$1 );
    window.isIE6 = version >= 6.0 && version < 7.0;
  }
 
  // The following wrapps the button table with two DIVs, one positioned relative and the other absolute.
  if(window.isIE6){
    var buttonTable = document.getElementById("buttonTable");
    var parent = buttonTable.parentNode;
    window.tableWrapperDiv = document.createElement("div");
    var absDiv = document.createElement("div");
 
    with(tableWrapperDiv.style){
      position = "relative";
      width = "100%";
      height = "100%";
    }
    with(absDiv.style){
      position = "absolute";
      top = "0px";
      left = "0px";
    }
 
    parent.removeChild(buttonTable);
    parent.appendChild(tableWrapperDiv);
    tableWrapperDiv.appendChild(absDiv);
    absDiv.appendChild(buttonTable);
    tableWrapperDiv.id = "buttonWrapperDiv";
  }
  // End IE_6_FIX
 
    new Button("<%=Messages.getString( "UI.PUC.LAUNCH.NEW_REPORT" )%>", "launch_new_report").onClick("openWAQR()");
    new Button("<%=Messages.getString( "UI.PUC.LAUNCH.NEW_ANALYSIS" )%>", "launch_new_analysis").onClick("openAnalysis()");
<%!
  private static ResourceBundle getBundle(String messageUri) {
    Locale locale = LocaleHelper.getLocale();
    IPentahoSession session = new StandaloneSession( "dashboards messages" ); //$NON-NLS-1$
    try {
        if (messageUri.startsWith("content/")) {
          messageUri = "system/" + messageUri.substring(8); //$NON-NLS-1$
        }
      InputStream in = PentahoSystem.get(ISolutionRepository.class, session).getResourceInputStream(messageUri, true, ISolutionRepository.ACTION_EXECUTE);
      return new PropertyResourceBundle( in );
    } catch (Exception e) {
      Logger.error( Messages.class.getName(), "Could not get localization bundle", e ); //$NON-NLS-1$
    }
    return null;
  }
%><% 
  boolean pluginButton = false;
  String buttonLabel = "";
  String buttonCommand = "";
  String buttonImage = "";
  IPluginManager pluginManager = PentahoSystem.get(IPluginManager.class, PentahoHttpSessionHelper.getPentahoSession(request)); //$NON-NLS-1$
    if (pluginManager != null) {
        for(XulOverlay overlayObj : pluginManager.getOverlays()) {
          if (overlayObj.getId() != null && overlayObj.getId().equals("launch")) {
      ResourceBundle bundle = getBundle(overlayObj.getResourceBundleUri());
        // replace I18N parameters
        Pattern p = Pattern.compile("\\$\\{([^\\}]*)\\}");
        Matcher m = p.matcher(overlayObj.getOverlayXml());
        StringBuffer sb = new StringBuffer();
        while (m.find()) {
          String param = m.group(1);
          m.appendReplacement(sb, bundle.getString(param));
        }
        m.appendTail(sb);
        String overlay = sb.toString();
 
      if (overlay.indexOf("id=\"manage_content\"") >= 0) {
        int startButtonLabel = overlay.indexOf("label=\"");
        int endButtonLabel = overlay.indexOf("\"", startButtonLabel + 7);
        buttonLabel = overlay.substring(startButtonLabel + 7, endButtonLabel);
 
        int startButtonImage = overlay.indexOf("image=\"");
        int endButtonImage = overlay.indexOf("\"", startButtonImage + 7);
        buttonImage = overlay.substring(startButtonImage + 7, endButtonImage);
 
        int startButtonCommand = overlay.indexOf("command=\"");
        int endButtonCommand = overlay.indexOf("\"", startButtonCommand + 9);
        buttonCommand = overlay.substring(startButtonCommand + 9, endButtonCommand);
        pluginButton = true;
        break;
      }
          }
      }
    }
  if (pluginButton) {
%>    new Button("<%=buttonLabel%>", "manage_content").onClick("<%= buttonCommand%>");
<%
  } else {
%>    new Button("<%=Messages.getString( "UI.PUC.LAUNCH.MANAGE_CONTENT" )%>", "manage_content").onClick("openManage()");
<%  }  %>
    fixPNGs();
}
 
</script>
  <script type="text/javascript" src="../pngfix.js"></script>
  <script type="text/javascript">
      PngFix.spacerURL = "images/ql_spacer.png";
  </script>
</head>
 
<body onLoad="loader()">
 
<div style="margin: 0px; padding: 0px; width: 100%; height: 100%;">
<table style="width: 100%; height: 100%;" class="launchPanel" id="launchPanel"
  cellpadding="0" cellspacing="0">
  <tr>
    <td style="vertical-align: middle;" align="center">
 
    <table width="564" border="0" align="center" cellpadding="0"
      cellspacing="0" class="ql_container">
      <tr>
        <td colspan="3" align="center"><img
          src="images/ql_logo.png" alt="Pentaho.com"
          class="ql_logo" /></td>
      </tr>
      <tr>
        <td class="ql_icon_bar_left"><img
          src="images/ql_icon_bar_left.png" width="41"
          height="147" /></td>
        <td class="ql_icon_bar_middle" >
 
            <table id="buttonTable" width="100%" border="0" cellspacing="0" cellpadding="0"
              height="100%">
              <tr>
                <td align="center" valign="top" onClick="window.parent.openWAQR()"><img
                  src="images/btn_ql_newreport.png"
                  class="ql_new_report" /></td>
                <td align="center" valign="top">&nbsp;</td>
                <td align="center" valign="top"
                  onClick="window.parent.openAnalysis()"><img
                  src="images/btn_ql_newanalysis.png"
                  class="ql_new_analysis" /></td>
                <td align="center" valign="top">&nbsp;</td>
<% if (pluginButton) { %>
                <td align="center" valign="top"
                  onClick="window.parent.<%=buttonCommand %>"><img
                  src="../../<%=buttonImage %>"
                  class="ql_manage" /></td>
<% } else { %>
                <td align="center" valign="top"
                  onClick="window.parent.openManage()"><img
                  src="images/btn_ql_manage.png"
                  class="ql_manage" /></td>
<% } %>
              </tr>
              <tr>
                <td id="launch_new_report" height="100%"><!--  container for New Report Button -->
                </td>
                <td><img src="images/ql_spacer.png"
                  class="ql_spacer" /></td>
                <td id="launch_new_analysis"><!--  container for New Analysis Button -->
                </td>
                <td><img src="images/ql_spacer.png"
                  class="ql_spacer" /></td>
                <td id="manage_content"><!--  container for manage content Button -->
                </td>
              </tr>
          </table>
 
        </td>
        <td class="ql_icon_bar_right"><img
          src="images/ql_icon_bar_right.png"
          width="41" height="147" /></td>
      </tr>
    </table>
    </td>
  </tr>
</table>
</div>
 
</body>
</html>

Before you make any changes to launch.jsp make sure you keep a backup copy.

Example 1

The launch.jsp page is like any other JSP (or HTML) page. For example, if I wanted to make the launch.jsp page display my blog’s logo all I need to do is change the contents of the launch.jsp file so that they now look like this:

<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Launch</title>
</head>
<body>
<div style="margin: 0px; padding: 0px; width: 100%; height: 100%;">
<table style="width: 100%; height: 100%;" class="launchPanel" id="launchPanel" cellpadding="0" cellspacing="0">
  <tr>
    <td style="vertical-align: middle;" align="center">
      <img src="images/logo.jpg" alt="Logo"/>
    </td>
    </table>
  </tr>
</table>
</div>
</body>
</html>

I have placed the logo.jpg image under the tomcat/webapps/pentaho/mantle/launch/images/ directory.

After refreshing the browser the new launch.jsp now looks like this:

Example 2

You could also embed information from other sites i.e. intranet home page etc. by using an iframe. For example, to include Google News instead of the default launch page I will need to make changes to the launch.jsp page so that it now looks like this:

<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Launch</title>
</head>
<body>
<iframe src="http://www.google.com/news" width="100%" height="100%" frameborder="0">
  <p>Your browser does not support iframes.</p>
</iframe>
</body>
</html>

After refreshing the browser the new launch.jsp now looks like this:

Example 3

Another example would be to add a list of links to key reports, analysis views and/or dashboards using xactions. Just say I would like to create a list which are links for the following:

• Area Chart Example (Steel Wheels > Charts)
• Marketing Analysis by Year (Steel Wheels > Analysis)

After making changes the launch.jsp file now looks like this:

<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<title>Launch</title>
</head>
<body>
<h1>Steel Wheels Launch pad</h1>
<p>Maybe one of these reports/analysis/dashboards can help you:</p>
<ul>
  <li><a href="http://localhost:8080/pentaho/ViewAction?&solution=steel-wheels&path=charts&action=areachart_data.xaction">Area Chart Example</a></li>
  <li><a href="http://localhost:8080/pentaho/ViewAction?&solution=steel-wheels&path=analysis&action=analysis_customers.analysisview.xaction">Marketing Analysis by Year</a></li>
</ul>
</body>
</html>

After refreshing the browser the new launch.jsp now looks like this:

Example 4

You can also redirect the launch.jsp page to a xaction, to do this change the contents of the launch.jsp file so that they now look like this:

<%
    // xactionPath is the xaction path
    String xactionPath = "http://localhost:8080/pentaho/ViewAction?&solution=steel-wheels&path=analysis&action=analysis_customers.analysisview.xaction";
    response.sendRedirect(xactionPath);
%>

After refreshing the browser the new launch.jsp will automatically redirect to the xaction specified.

Final Notes

If you want to embed or replace the launch.jsp with xactions, dashboards, reports etc. I believe that you should use the startup-urls option instead, this option is covered in my previous post Customising the Pentaho User Console – Part 3.

Do you have any other examples? Post a comment or drop me an email and I’ll add it to this post.

Enjoy.

The Scenario.

I need to create a public schedule which will run out of business hours. Coincidently after creating the public schedule I’m approached by a Sales Manager who requests that I run the Top N Analysis report which is needed for tomorrow’s weekly meeting. As this particular report takes a while to run I will assign it to public schedule (created earlier) which will run the report out of business hours and email to the Sales Manager before his/hers weekly meeting.

Step 1 – Setup SMTP.

The first step is to make sure you have setup the Pentaho BI Server to talk to your SMTP server correctly. The configuration file for the SMTP server is email_config.xml which is located under the /pentaho-solutions/system/smtp-email/ directory. The contents of the email_config.xml looks like this:

<email-smtp>
  <!-- The values within <properties> are passed directly to the JavaMail API.
       For a list of valid properties see http://java.sun.com/products/javamail/javadocs/index.html -->
	<properties>
		<!-- This is the address of your SMTP email server for sending email. e.g. smtp.pentaho.org -->
		<mail.smtp.host></mail.smtp.host>
		<!--  This is the port of your SMTP email server. Usually this is 25. For GMail this is 587 -->
		<mail.smtp.port>25</mail.smtp.port>
		<!--  The transport for accessing the email server. Usually this is smtp. For GMail this is smtps -->
		<mail.transport.protocol>smtp</mail.transport.protocol>
		<!--  Usually this is 'false'. For GMail it is 'true' -->
		<mail.smtp.starttls.enable>false</mail.smtp.starttls.enable>
		<!-- Set to true if the email server requires the sender to authenticate -->
		<mail.smtp.auth>true</mail.smtp.auth>
		<!--  This is true if the email server requires an SSL connection. Usually 'false'. For GMail this is 'true' -->
		<mail.smtp.ssl>false</mail.smtp.ssl>
  	<!--  Output debug information from the JavaMail API -->
   	<mail.debug>false</mail.debug>
    <!-- For GMail this is 'false' -->
    <!--mail.smtp.quitwait>false</mail.smtp.quitwait-->
	</properties>
	<!-- The is the address of your POP3 email server for receiving email. e.g. pop.pentaho.org -->
	<!-- It is currently not used -->
	<mail.pop3></mail.pop3>
	<!-- This is the default 'from' address that emails from the Pentaho BI Platform will appear to come from e.g. joe.pentaho@pentaho.org -->
	<mail.from.default></mail.from.default>
	<!-- This is the user id used to connect to the email server for sending email
       It is only required if email-authenticate is set to true
       This is never sent or shown to anyone -->
	<mail.userid></mail.userid>
	<!-- This is the password used to connect to the email server for sending email It is only required if email-authenticate is set to true
       This is never sent or shown to anyone -->
	<mail.password></mail.password>
</email-smtp>

Below is the email_config.xml settings I used for my GMail account:

<email-smtp>
	<properties>
		<!-- This is the address of your SMTP email server for sending email. e.g. smtp.pentaho.org -->
		<mail.smtp.host>smtp.gmail.com</mail.smtp.host>
		<!--  This is the port of your SMTP email server. Usually this is 25. For GMail this is 587 -->
		<mail.smtp.port>587</mail.smtp.port>
		<!--  The transport for accessing the email server. Usually this is smtp. For GMail this is smtps -->
		<mail.transport.protocol>smtps</mail.transport.protocol>
		<!--  Usually this is 'false'. For GMail it is 'true' -->
		<mail.smtp.starttls.enable>true</mail.smtp.starttls.enable>
		<!-- Set to true if the email server requires the sender to authenticate -->
		<mail.smtp.auth>true</mail.smtp.auth>
		<!--  This is true if the email server requires an SSL connection. Usually 'false'. For GMail this is 'true' -->
		<mail.smtp.ssl>true</mail.smtp.ssl>
    <!-- For GMail this is 'false' -->
    <mail.smtp.quitwait>false</mail.smtp.quitwait>
	</properties>
	<!-- The is the address or your POP3 email server for receiving email. e.g. pop.pentaho.org -->
	<!-- It is currently not used -->
	<mail.pop3></mail.pop3>
	<!-- This is the default 'from' address that emails from the Pentaho BI Platform will appear to come from e.g. joe.pentaho@pentaho.org -->
	<mail.from.default>prashant.g.raju@gmail.com</mail.from.default>
	<!-- This is the user id used to connect to the email server for sending email
       It is only required if email-authenticate is set to true
       This is never sent or shown to anyone -->
	<mail.userid>prashant.g.raju@gmail.com</mail.userid>
	<!-- This is the password used to connect to the email server for sending email 
       It is only required if email-authenticate is set to true
       This is never sent or shown to anyone -->
	<mail.password><!-- passoword --></mail.password>
</email-smtp>

You can test if you have configured Pentaho BI Server to talk to the SMTP server correctly by running the Burst Sales Report which is located under the BI Developer Examples/Reporting/ solution folder.
Click on the report and fill out the prompts including your email address:

After clicking the Run button you should receive an email for each employee and the report as a PDF attachment.

Step 2 – Create a Public Schedule.

The next step is to create a Public Schedule. To do this you must have access to the Pentaho Administration Console (PAC), after logging into PAC click on the Administration menu item and then the Scheduler tab:

To create a new schedule click on the icon (Create schedule), this will display a Schedule Creator window with the Schedule tab active:

• Public Schedule – Allow users access to the schedule : Check this option to make this schedule public
• Name : Name of your schedule i.e. Ad hoc Reports
• Group : Group which your schedule belongs to i.e. Ad hocs
• Description : Description of your schedule i.e. Use this schedule to run lengthy ad hoc reports out of business hours
• Recurrence : How often do you want the schedule to run i.e. Daily
  • Recurrence pattern : On which days you want the schedule to run (this will be different for Monthly, Yearly etc. recurrences) i.e. On weekdays
  • Range of recurrence : The date the schedule is to start and end i.e. The schedule is start on the 2nd of March 2010 till no end date

After filling out the options the Schedule Creator window now looks like this:

You can also assign files directly to this schedule by clicking on the Selected Files tab:

Within the Selected Files tab you are able to assign reports (and xactions) to the schedule, in this example I will not be assigning any reports to this schedule. If you want to add reports click the icon (Add item) and use the file browser to locate your report:

When you have found your report click on the Select button to add it to the schedule.

After completing all the options available on the Schedule tab click the OK button. You should now see the Ad hoc reports schedule in the schedule list:

Step 3 – Setup and Email the Report.

The next step is to assign the report to the schedule, setup the parameters (including the email address) and schedule the report all from the PUC. Log into the PUC with a user who has access to the report (Top N Analysis) and can schedule reports – in this example I’m using the user Joe. The report that needs to be sent out is Top N Analysis which is located under the /Steel Wheels/Reporting/ solutions folder. Right click on the report under the Files section and select the Share option:

Within the Properties window click the Advanced tab and check the Use Public Schedules option and move the Ad hoc Reports option under the Available: list to the Current: list using the > arrow and click the OK button:

Right click on the report again and select the Schedule… option:

After clicking the Schedule… option the Top N Analysis report will open up in a new tab:

The Report Parameters section is where you define the default parameters for this report. The Sales Manager has requested that the report parameters are:

Before entering this parameters make sure you uncheck the Auto Submit option

• Product Line : Classic Cars
• Region : APAC
• Year : 2003
• Top N Customers : 10
• Output Type : PDF

The Schedule Report section is the new improvement with Pentaho’s BI Server 3.5.2:

• Report Name : The title of the report this is also displayed in the Email subject line i.e. Top 10 Classic Car Customers for APAC
• E-mail To : The report recipient’s email addresses i.e. prashant.g.raju@gmail.com. If you would like to specify more than one address seperate the emails with a , (comma) i.e. prashant.g.raju@gmail.com,prashant@analysethis.com.au
• Subscription : Which public subscription this report belongs to i.e. Ad hoc

After filling out all the options click the View Report button to preview the report before you schedule it:

Once you are happy with the report preview click the Schedule button. If successful you should receive the following message:

Step 4 – Check the Report Schedule.

You can check the status of the report by clicking on the icon (Workspace) on the main toolbar. You are able to see the status of the Ad hoc public schedule under the All Schedules (Admin Only) section and the status of the Top 10 Classic Car Customers for APAC under the Public Schedules section:

Step 5 – The Email.

When the sales manager receives the email it will look similar to this:

Step 6 – Delete the Scheduled Report.

After the report has successfully run and has been emailed to the Sales Manager you will need to remove it from the Ad hoc schedule (if you don’t the Sales Manager will keep receiving this email on weekdays out of business hours). Click on the icon (Workspace) on the main toolbar and click on the Delete link next the report under the Public Schedules section:

Final Notes.

I’m not sure that the example I provided is a viable solution as in most cases the users can log in and run the report themselves. I personally see this functionality beneficial when running large reports which need to be run and sent out of business hours i.e. extracts.

Enjoy.

• Login page and dialog
• Messages
• Main toolbar, menu bar and logo panel (covered in this post)
• Launch page

In this post I will show you how to customise the main-toolbar, menu-bar, logo-panel and other features for the PUC.

The Pentaho User Console

Below is a screenshot with overlays that highlight the different areas of the PUC:

Table of Contents

This tutorial has been tested with Pentaho BI Server 3.5.0 and 3.5.2.

I have split the tutorial into 4 different sections which involve making modifications to .PROPERTIES, .XUL, .PNG files and checking out and building the source code. Here is a ‘table of contents’ for this tutorial:

• MantleSettings.properties
  • Displaying Tabs when PUC Launches
  • Show/Hide the menu-bar, main-toolbar and logo-panel
  • Other Options
• Change the Default logo-panel Logo
• main_toolbar.xul
  • Show/Hide Buttons on the main-toolbar
• Modifying the Source Code
  • Requirements
  • Checking Out the Source Code
  • Examples
    • Show/Hide menu-bar Items
    • Change the URL of the logo-panel
    • Add a Logout Button to the main-toolbar
  • Building the source

MantleSettings.properties

The MantleSettings.properties file is located inside the mantle-3.5.0.stable.jar file under the /tomcat/webapps/pentaho/WEB-INF/lib/ directory.

To make modifications to the MantleSettings.properties you will need to have an archive tool installed i.e. WinZip, WinRAR etc. in this example I will be using WinZip. Right click on the mantle-3.5.0.stable.jar file and click the Open With > WinZip option:

Once you have opened the mantle-3.5.0.stable.jar file with your archive tool find the MantleSettings.properties file which is located under the org\pentaho\mantle\server\ directory and open it with a text editor – in this example I will be using PSPad. Right click on the MantleSettings.properties and click the Open With > PSPad editor option:

You should now be able to see the contents of the MantleSettings.properties file:

show-explorer-view-on-startup=true
show-advanced-features=false
# startup urls (each displays in its own tab)
num-startup-urls=0
startup-url-1=/pentaho/welcome/welcome.html
startup-name-1=Welcome
startup-url-2=http://www.pentaho.com
startup-name-2=Pentaho Business Intelligence
startup-url-3=/pentaho/ViewAction?solution=samples&path=/reporting&action=JFree_Quad.xaction
startup-url-4=/pentaho/SampleDashboard
# plugin perspectives
num-plugin-perspectives=0
plugin-perspective-url-1=/pentaho/adhoc/waqr.html
plugin-perspective-name-1=Ad hoc Reporting
plugin-perspective-url-2=/pentaho/interactive-reporting/index.html
plugin-perspective-name-2=Interactive Reporting
# ui customization settings (if menu/toolbar are disabled, the logo panel is disabled automatically)
show-menu-bar=true
show-main-toolbar=true
show-logo-panel=true

After you save any changes you make to the MantleSettings.properties your archive tool should prompt you to update the mantle-3.5.0.stable.jar archive. For example WinZip displays the following prompt box after I save any changes to the MantleSettings.properties file:

Displaying Tabs when PUC Launches

The startup-urls option provides functionality to tell the PUC to open tabs with predefined content when it launches i.e. welcome, intranet pages etc. The following section within the MantleSettings.properties file is where you define these options:

# startup urls (each displays in its own tab)
num-startup-urls=0
startup-url-1=/pentaho/welcome/welcome.html
startup-name-1=Welcome
startup-url-2=http://www.pentaho.com
startup-name-2=Pentaho Business Intelligence
startup-url-3=/pentaho/ViewAction?solution=samples&path=/reporting&action=JFree_Quad.xaction
startup-url-4=/pentaho/SampleDashboard

• num-startup-urls : The amount of URLs you would like to load when PUC launches
• startup-url-x : The location of the content which will appear in the tab (x is a user defined unique id) i.e. a webpage or xaction
• startup-name-x : The title of the tab which will contain the content you specified in the startup-url-x option (x is a user defined unique id) i.e. Welcome or Sales Dashboard

In this example I would like to load two tabs when a user logs into the PUC:

1. A tab titled Welcome which will display the /pentaho/welcome/welcome.html page
2. A tab titled Pentaho Business Intelligence which will display the /pentaho/ViewAction?solution=samples&path=/reporting&action=JFree_Quad.xaction xaction

After making changes to the MantleSettings.properties file the startup-urls section now looks like this:

# startup urls (each displays in its own tab)
num-startup-urls=2
startup-url-1=/pentaho/welcome/welcome.html
startup-name-1=Welcome
startup-url-2=http://www.pentaho.com
startup-name-2=Pentaho Business Intelligence
startup-url-3=/pentaho/ViewAction?solution=samples&path=/reporting&action=JFree_Quad.xaction
startup-url-4=/pentaho/SampleDashboard

Restart your Apache-Tomcat server and clear your browsers cache. When you launch the PUC two tabs are loaded automatically (with the titles and content defined above):

Show/Hide the menu-bar, main-toolbar and logo-panel

The show-menu-bar, show-main-toolbar and show-logo-panel options can show/hide the menu-bar, main-toolbar or logo-panel. If you decide to hide the menu-bar or main-toolbar the logo-panel is automatically hidden.

The following section within the MantleSettings.properties file is where you define these options:

# ui customization settings (if menu/toolbar are disabled, the logo panel is disabled automatically)
show-menu-bar=true
show-main-toolbar=true
show-logo-panel=true

Below are the different options and screenshots in action (after making any changes make sure you restart your Apache-Tomcat server and clear your browsers cache):

Show All

show-menu-bar=true
show-main-toolbar=true
show-logo-panel=true

show-menu-bar=false

show-menu-bar=false
show-main-toolbar=true
show-logo-panel=true

show-main-toolbar=false

show-menu-bar=true
show-main-toolbar=false
show-logo-panel=true

show-logo-panel=false

show-menu-bar=true
show-main-toolbar=true
show-logo-panel=false

Other Options

You may have noticed other options available in the MantleSettings.properties file:

show-explorer-view-on-startup=true
show-advanced-features=false
...
# plugin perspectives
num-plugin-perspectives=0
plugin-perspective-url-1=/pentaho/adhoc/waqr.html
plugin-perspective-name-1=Ad hoc Reporting
plugin-perspective-url-2=/pentaho/interactive-reporting/index.html
plugin-perspective-name-2=Interactive Reporting
...

Below is my attempt of trying to explain these options (if you have more information on these options please let me know):

show-explorer-view-on-startup=false

When this option is set to false the default solution browser is disabled and is replaced in the main content area with the old version (1.7) solution browser.

show-advanced-features=true

When this option is set to true advanced options are enabled on the menu-bar. These advanced options include Favourite solution folders and User Preferences.

plugin perspectives

I believe this has to do with Pentaho’s BI Server new plugin architecture and works similar to the startup-urls option, if I set the num-plugin-perspectives option from 0 to 2 the Ad hoc Reporting and Interactive Reporting items the View menu item.

Change the Default logo-panel Logo

To change the default logo seen on the logo-panel you will need to modify or replace the logo.png file which is under the tomcat/webapps/pentaho/mantle directory.

The new or modified logo.png image must be:

• 152 pixels wide
• 70 pixels high
• A transparent .PNG image (optional)

For example I would like to replace the logo.png image with the following image:

After replacing the logo.png with the above image the logo-panel now looks like this:

There is no need to restart your Apache-Tomcat server to reflect this change however if no change is apparent clear your browsers cache.

main_toolbar.xul

The main-toolbar is built using XUL mark up (XUL was created by Mozilla and you can read up more on it here). At the moment only the main-toolbar uses XUL mark-up (to make modifications to the menu-bar you will need to modify the source code). The main_toolbar.xul file is located under the tomcat/webapps/pentaho/mantle/xul/ directory.

You can open the main_toolbar.xul file with a text editor, the contents of this file look like this:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window width="400" height="275" title="Placeholder"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"  xmlns:pen="http://www.pentaho.org/2008/xul" onload="mainToolbarHandler.init()">
  <toolbar id="mainToolbar">
    <toolbarspacer width="10"/>
    <toolbarbutton id="openButton" image="mantle/images/open_32.png" onclick="mainToolbarHandler.openClicked()" tooltiptext="${openEllipsis}"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="newAdhocButton" image="mantle/images/new_report_32.png" onclick="mainToolbarHandler.newAdhocClicked()" tooltiptext="${newAdhocReport}"/>
    <toolbarbutton id="newAnalysisButton" image="mantle/images/new_analysis_32.png" disabledimage="mantle/images/new_analysis_32_disabled.png" onclick="mainToolbarHandler.newAnalysisClicked()" tooltiptext="${newAnalysisView}"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="editContentButton" image="mantle/images/editContent_32.png" disabledimage="mantle/images/editContent_32_disabled.png"  onclick="mainToolbarHandler.editContentClicked()" tooltiptext="${editContent}" disabled="true" type="toggle" pen:visible="false"/>
    <toolbarspacer id="editButtonSpacer" width="20" pen:visible="false"/>
    <toolbarbutton id="saveButton" image="mantle/images/save_32.png" disabledimage="mantle/images/save_32_disabled.png" onclick="mainToolbarHandler.saveClicked()" tooltiptext="${save}" disabled="true"/>
    <toolbarbutton id="saveAsButton" image="mantle/images/saveAs_32.png" disabledimage="mantle/images/saveAs_32_disabled.png"  onclick="mainToolbarHandler.saveAsClicked()" tooltiptext="${saveAs}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="printButton" image="mantle/images/print_32.png" disabledimage="mantle/images/print_32_disabled.png" onclick="mainToolbarHandler.printClicked()" tooltiptext="${print}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="workspaceButton" image="mantle/images/workspace_32.png" type="toggle" onclick="mainToolbarHandler.workspaceClicked()" tooltiptext="${workspace}"/>
    <toolbarbutton id="showBrowserButton" image="mantle/images/browser_show_32.png" downimage="mantle/images/browser_hide_32.png" type="toggle" onclick="mainToolbarHandler.showBrowserClicked()" tooltiptext="${toggleSolutionBrowser}"/>
  </toolbar>
</window>

Here are descriptions of the key elements and attributes which make up this file:

• toolbarspacer : This element creates a blank space on the main toolbar
  • width : Is an attribute of the toolbarspacer element and defines how wide the blank space on the main toolbar is i.e. 20 is equivalent to 20 pixels wide
• toolbarbutton : This element creates a button on the main toolbar
  • id : A unique identifier of the button – this is set for any JavaScript interaction
  • image : The image of the button, these images are located under the tomcat/webapps/pentaho/mantle/images directory
  • disabledimage : The image which is displayed when the button is disabled (this happens when you set the disabled element to true), these images are located under the tomcat/webapps/pentaho/mantle/images directory
  • onclick : The function to call when the button is clicked
  • tooltiptext : The tooltip text to display when a user hovers over the button, most of these are setup in the messages_xx.properties file (this was covered in this post)
  • downimage : The image which is displayed when the button is toggled
  • type : The button type – for example if the button is a toggle button
  • disabled : When this option is set to true the button will be disabled and the disabledimage image will be displayed

The image below describes how the above mark up contributes to the main-toolbar:

Show/Hide Buttons on the main-toolbar

In this example I would like to remove a spacer, New Adhoc Report and New Analysis buttons from the main-toolbar, you can do this by deleting or commenting out lines from the main_toolbar.xul file (I will be removing the lines). The lines of code which I will to need remove are:

<toolbarspacer width="20"/>
<toolbarbutton id="newAdhocButton" image="mantle/images/new_report_32.png" onclick="mainToolbarHandler.newAdhocClicked()" tooltiptext="${newAdhocReport}"/>
<toolbarbutton id="newAnalysisButton" image="mantle/images/new_analysis_32.png" disabledimage="mantle/images/new_analysis_32_disabled.png" onclick="mainToo

After making the changes the main_toolbar.xul file now looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window width="400" height="275" title="Placeholder"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"  xmlns:pen="http://www.pentaho.org/2008/xul" onload="mainToolbarHandler.init()">
  <toolbar id="mainToolbar">
    <toolbarspacer width="10"/>
    <toolbarbutton id="openButton" image="mantle/images/open_32.png" onclick="mainToolbarHandler.openClicked()" tooltiptext="${openEllipsis}"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="editContentButton" image="mantle/images/editContent_32.png" disabledimage="mantle/images/editContent_32_disabled.png"  onclick="mainToolbarHandler.editContentClicked()" tooltiptext="${editContent}" disabled="true" type="toggle" pen:visible="false"/>
    <toolbarspacer id="editButtonSpacer" width="20" pen:visible="false"/>
    <toolbarbutton id="saveButton" image="mantle/images/save_32.png" disabledimage="mantle/images/save_32_disabled.png" onclick="mainToolbarHandler.saveClicked()" tooltiptext="${save}" disabled="true"/>
    <toolbarbutton id="saveAsButton" image="mantle/images/saveAs_32.png" disabledimage="mantle/images/saveAs_32_disabled.png"  onclick="mainToolbarHandler.saveAsClicked()" tooltiptext="${saveAs}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="printButton" image="mantle/images/print_32.png" disabledimage="mantle/images/print_32_disabled.png" onclick="mainToolbarHandler.printClicked()" tooltiptext="${print}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="workspaceButton" image="mantle/images/workspace_32.png" type="toggle" onclick="mainToolbarHandler.workspaceClicked()" tooltiptext="${workspace}"/>
    <toolbarbutton id="showBrowserButton" image="mantle/images/browser_show_32.png" downimage="mantle/images/browser_hide_32.png" type="toggle" onclick="mainToolbarHandler.showBrowserClicked()" tooltiptext="${toggleSolutionBrowser}"/>
  </toolbar>
</window>

Save the main_toolbar.xul file, restart your Apache-Tomcat server and clear your browsers cache. The main-toolbar now looks like this:

Modifying the Source Code

The following section assumes that you have experience in Java, Subversion and the Eclipse IDE.

Requirements

Some of the excerpts below have been taken from this wiki entry.

Before you get started you must have the following tools installed:

• Eclipse IDE
• Ant
• IvyDE
• Subclipse

Eclipse IDE

The Eclipse platform is the IDE of choice at Pentaho

To download the latest version of the Eclipse IDE for your operating system click here – I use the Eclipse IDE for Java Developers version.

If you are using Windows there is no installation package or wizard so extract the file to a working location i.e. C:\eclipse. If you are using a Linux workstation i.e. Ubuntu or Fedora you should be able to use the software package managers to install the Eclipse IDE.

The first time you start up Eclipse you will be prompted to set your default Workspace – this is where you will be checking out all the required folders to build the Pentaho BI Server.

Ant

Ant is a Java-based build tool that Pentaho uses to build the server platform, among other projects

By default Apache Ant is pre-packaged with Eclipse IDE but if you would like to install/setup Apache Ant manually follow the guide posted on this wiki entry.

IvyDE

IvyDE is an IDE that lets you manage your dependencies declared in an ivy.xml file in your Java Eclipse projects

To install IvyDE click on this link. Once the file has downloaded extract its contents to your Eclipse home directory i.e. C:\eclipse, it will extract files into the features/ and plugins/ directories.

For more detailed instructions or if you already have a version of IvyDE installed click here.

Subclipse

Subclipse is an Eclipse plugin that enables Subversion access from within the Eclipse environment

To install Subclipse follow the instructions on this wiki entry.

You can also install Subclipse manually by downloading the latest version here (the latest version at the time of writing this was 1.6.8) and extracting its contents to your Eclipse home directory i.e. C:\eclipse, it will extract files into the features/ and plugins/ directories.

The next step is to configure Eclipse to use Subclipse for all SVN related tasks. Once you have installed Subclipse start Eclipse and click on the Windows > Preferences option to display the Preferences window. Expand the Team item from left frame and click the SVN option. In the right frame make sure the SVN Interface is set to SVNKit (Pure Java) SVNKit … and click the OK button.

Checking out the Source Code

Create a New Project

The first step before you start to check out any code is to create a new project. Start up Eclipse and click on File > New > Project option from the menu bar:

This will launch a New project wizard. Expand the General folder and select the Project option and click the Next > button:

The next window will ask you to setup your Project resource. Enter pentaho for the Project name and leave the Use default location check box checked and click the Finish button:

You should now be able to see the project pentaho under the Package Explorer tab:

Checkout All Necessary Folders

The next step is to checkout all the folders which are required to build the Pentaho BI Server from source. You will need to checkout these 4 folders:

• svn://source.pentaho.org/svnroot/bi-platform-v2/tags/3.5.0-GA
• svn://source.pentaho.org/svnroot/legacy/pentaho-xul/trunk
• svn://source.pentaho.org/svnroot/pentaho-commons/pentaho-gwt-modules/trunk
• svn://source.pentaho.org/svnroot/pentaho-open-admin-console/tags/3.5.0-GA

You can browse the repository with your browser by visiting this URL: http://source.pentaho.org/svnroot/.

You will need to repeat the steps seen below for each folder, I have used the first folder as an example (3.5.0-GA).

The first step is to import the svn://source.pentaho.org/svnroot/bi-platform-v2/tags/3.5.0-GA (bi-platform-v2/tags/3.5.0-GA) into the pentaho project which we created earlier. Right click on the pentaho project under the Package Explorer tab and click on the Import… option:

An Import window will appear asking you for the source of the import, expand the SVN folder and click the Checkout Projects from SVN option and click the Next > button:

The next window will ask you if you would like to Create a new repository location or Use existing repository location, click the Create a new repository location option and click the Next > button:

The next window will ask you the location of the repository, enter in the URL for the folder if you are doing this for the first time enter svn://source.pentaho.org/svnroot/bi-platform-v2/tags/3.5.0-GA as the URL and click the Next > button:

The next window will ask you which folder you would like to check out, as you need all folders under each listed URL – select the root folder which in this example can be seen listed as svn://source.pentaho.org/svnroot/bi-platform-v2/tags/3.5.0-GA and click the Next > button:

The next window will ask you how you want to check out the folder. Click on the Check out as a project in the workspace option and leave the Project name to the populated name, leave the rest of the options to the defaults and click the Next > button:

The last window will ask you where you would like to check out the folder to, uncheck the Use the default workspace location option and make sure the Location points to the pentaho project’s folder under your workspace i.e. C:\Users\prashant\workspace\pentaho\3.5.2.stable\mantle\dist then click the Finish button:

After the checking out is complete (it may take a while depending on your internet connection) you will see the project listed under the pentaho/project on the Package explorer tab:

Repeat the above steps for the next 3 URLs, after you have completed this you should now see the following projects under your pentaho project on the Package explorer tab:

While you are checking out folders IvyDE will automatically retrieve any dependencies which the source code needs – this may take a while as it downloads packages etc. so just keep an eye on the bottom right hand corner to make sure that all the dependencies have downloaded for all the folders you have checked out:

Now you are ready to start modifying the source code.

Examples

As you can almost do anything when modifying the source code I decided to keep the examples to minor changes to the PUC user interface – hopefully these examples can give you a head start with any modifications you need to do.

Show/Hide menu-bar Items

To change the items which are appear on the menu-bar you will need to edit the MantleApplication.java file within Eclipse, this file is located under the pentaho/3.5.0-GA/mantle/org/pentaho/mantle/client/ directory (pentaho is the name of the project).

To understand how menu items are added to the menu bar below is a high level breakdown of the code.

The following piece of code:

1. Creates the Save menu item
2. Assigns the save message defined in the messages_xx.properties file
3. Assigns the SaveCommand function to the Save menu item
4. Assigns save as an element id

saveMenuItem = new PentahoMenuItem(Messages.getString("save"), new SaveCommand(solutionBrowserPerspective, false)); //$NON-NLS-1$
saveMenuItem.getElement().setId("save");

The following piece of code:

1. Adds the Save menu item to the File menu item
2. Adds a separator (horizontal bar) to the File menu

fileMenu.addItem(saveMenuItem);
fileMenu.addSeparator();

In this example I want to hide the Help menu item, to do this you will need to comment out the following line of code:

menuBar.addItem(helpMenuBar);

After commenting the above line looks like this:

//menuBar.addItem(helpMenuBar);

If you were going to make this change permanent I would suggest you remove all instances of the Help menu item and sub items.

Save the file and rebuild the pentaho project and copy over the new directories and files, after this is complete the new menu-bar now looks like this:

Another example is if I wanted to remove the following menu items (which are part of the File menu item):

• File
  • New (remove including sub items)
  • — (remove)
  • Save (remove)
  • Save As… (remove)
  • — (remove)

First locate the following lines of code within the MantleApplication.java file:

fileMenu.addItem(newMenuBar);
...
fileMenu.addSeparator();
fileMenu.addItem(saveMenuItem);
fileMenu.addItem(saveAsMenuItem);
fileMenu.addSeparator();

After commenting out the above lines of code they now look like this:

//fileMenu.addItem(newMenuBar);
...
//fileMenu.addSeparator();
//fileMenu.addItem(saveMenuItem);
//fileMenu.addItem(saveAsMenuItem);
//fileMenu.addSeparator();

If you were going to make this change permanent I would suggest you remove all instances of these menu items and sub items.

Save the file and rebuild the pentaho project, after this is complete the new menu-bar now looks like this:

Change the URL of the logo-panel

To change the URL which the logo-panel points to you will need to edit the MantleApplication.java file in Eclipse which is located under the pentaho/3.5.0-GA/mantle/org/pentaho/mantle/client/ directory (pentaho is the name of the project). First locate this line of code:

logoPanel = new LogoPanel("http://www.pentaho.com/"); //$NON-NLS-1$

At the moment it is pointing to Pentaho’s homepage, in this example I would like to have the URL point to my blog’s homepage, the line of code now looks like this:

logoPanel = new LogoPanel("http://www.prashantraju.com/"); //$NON-NLS-1$

Save the file and rebuild the pentaho project, after this is complete when a user clicks on the logo-panel they are directed to my blog’s homepage:

Add a Logout Button to the main-toolbar

To add a logout button to the main-toolbar you will need to first create a function which you will be able to call from the main_toolbar.xul file. Open the MainToolbarController.java file in Eclipse which is located under the pentaho/3.5.0-GA/mantle/org/pentaho/mantle/client/toolbars/ directory.

The next step is to import the commands/LogoutCommand.java file, to do this add the following line to the header of the MainToolbarController.java file where the other imports are located:

import org.pentaho.mantle.client.commands.LogoutCommand;

The header section of the MainToolbarController.java file now looks like this:

package org.pentaho.mantle.client.toolbars;
 
import java.util.ArrayList;
import java.util.List;
 
import org.pentaho.mantle.client.commands.ShowBrowserCommand;
import org.pentaho.mantle.client.commands.ToggleWorkspaceCommand;
import org.pentaho.mantle.client.commands.LogoutCommand;
import org.pentaho.mantle.client.perspective.solutionbrowser.SolutionBrowserPerspective;
import org.pentaho.ui.xul.EventMethod;
import org.pentaho.ui.xul.binding.BindingFactory;
import org.pentaho.ui.xul.components.XulToolbarbutton;
import org.pentaho.ui.xul.gwt.binding.GwtBindingFactory;
import org.pentaho.ui.xul.impl.AbstractXulEventHandler;
import org.pentaho.ui.xul.stereotype.Bindable;
 
import com.google.gwt.core.client.JavaScriptObject;
...

The second step is to add the following function, logoutClicked() to the AbstractXulEventHandler() function, locate the following section of code:

@Bindable
public void showBrowserClicked(){
  ShowBrowserCommand showBrowserCommand = new ShowBrowserCommand(solutionBrowser);
  showBrowserCommand.execute();
  model.setShowBrowserSelected(solutionBrowser.isExplorerViewShowing());
}

Underneath the above section of code copy and paste the following function:

@Bindable
public void logoutClicked(){
 LogoutCommand logoutCommand = new LogoutCommand();
 logoutCommand.execute();
}

Save the file and rebuild the pentaho project and copy over the new directories and files. You will now need to make changes to the main_toolbar.xul file which is located under the tomcat/webapps/pentaho/mantle/xul/ directory. Open up the file in a text editor and add the following line of code:

<toolbarspacer width="10"/>
<toolbarbutton id="logoutButton" image="mantle/images/home_back_32.png" onclick="mainToolbarHandler.logoutClicked()" tooltiptext="${logout}"/>

• toolbarspacer : Add a space of 10 pixels between the logout button and the solution browser toggle button
• id : A unique identifier for the button (optional) i.e. logoutButton
• image : The image which will be displayed for the logout button – I used this (WooFunction Icons released under GNU GPL)
• onclick : The function to call when the logout button is clicked – this is the function we created in the previous step logoutClicked(), this must be part of the mainToolbarHandler
• tooltiptext : The tooltip which is displayed when the user hovers over the logout button – in this case there is already a logout message defined so I have reused this

The main_toolbar.xul file now looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window width="400" height="275" title="Placeholder"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"  xmlns:pen="http://www.pentaho.org/2008/xul" onload="mainToolbarHandler.init()">
  <toolbar id="mainToolbar">
    <toolbarspacer width="10"/>
    <toolbarbutton id="openButton" image="mantle/images/open_32.png" onclick="mainToolbarHandler.openClicked()" tooltiptext="${openEllipsis}"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="newAdhocButton" image="mantle/images/new_report_32.png" onclick="mainToolbarHandler.newAdhocClicked()" tooltiptext="${newAdhocReport}"/>
    <toolbarbutton id="newAnalysisButton" image="mantle/images/new_analysis_32.png" disabledimage="mantle/images/new_analysis_32_disabled.png" onclick="mainToolbarHandler.newAnalysisClicked()" tooltiptext="${newAnalysisView}"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="editContentButton" image="mantle/images/editContent_32.png" disabledimage="mantle/images/editContent_32_disabled.png"  onclick="mainToolbarHandler.editContentClicked()" tooltiptext="${editContent}" disabled="true" type="toggle" pen:visible="false"/>
    <toolbarspacer id="editButtonSpacer" width="20" pen:visible="false"/>
    <toolbarbutton id="saveButton" image="mantle/images/save_32.png" disabledimage="mantle/images/save_32_disabled.png" onclick="mainToolbarHandler.saveClicked()" tooltiptext="${save}" disabled="true"/>
    <toolbarbutton id="saveAsButton" image="mantle/images/saveAs_32.png" disabledimage="mantle/images/saveAs_32_disabled.png"  onclick="mainToolbarHandler.saveAsClicked()" tooltiptext="${saveAs}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="printButton" image="mantle/images/print_32.png" disabledimage="mantle/images/print_32_disabled.png" onclick="mainToolbarHandler.printClicked()" tooltiptext="${print}" disabled="true"/>
    <toolbarspacer width="20"/>
    <toolbarbutton id="workspaceButton" image="mantle/images/workspace_32.png" type="toggle" onclick="mainToolbarHandler.workspaceClicked()" tooltiptext="${workspace}"/>
    <toolbarbutton id="showBrowserButton" image="mantle/images/browser_show_32.png" downimage="mantle/images/browser_hide_32.png" type="toggle" onclick="mainToolbarHandler.showBrowserClicked()" tooltiptext="${toggleSolutionBrowser}"/>
    <toolbarspacer width="10"/>
    <toolbarbutton id="logoutButton" image="mantle/images/logout_32.png" onclick="mainToolbarHandler.logoutClicked()" tooltiptext="${logout}"/>
  </toolbar>
</window>

Restart your Apache-Tomcat server and clear your browsers cache. The main-toolbar now looks like this:

When a User clicks on the Logout button they are logged out from the PUC.

Building the Source Code

To build the modified source code you will need to use Ant, as I mentioned early Ant comes packaged with Eclipse which makes it a lot easier to use. To start the build process right click on the build.xml file under the pentaho/3.5.0-GA/bi-platform-build/ directory and click the Run As > 1 Ant Build option:

After clicking the 1 Ant Build option Eclipse will start the build process, you can monitor the build progress from the Output tab:

The following message will be displayed in the Output tab when the build process has completed successfully:

BUILD SUCCESSFUL
Total time: 10 minutes 4 seconds

It can take over 20 minutes to build the source code for the first time and consequent builds can take between 5 to 15 minutes – this depends on your system setup, internet connection etc.

Once the build process has finished you will need to copy the following directories and file over to your Pentaho BI Server installation:

• mantle/
• mantleLogin/
• mantle-3.5.0.stable.jar

These directories and files are found under the pentaho/3.5.0-GA/mantle/dist/ directory. Before you copy these files over make sure you stop your Apache-Tomcat server and rename the current mantle/, mantleLogin/ and mantle-3.5.0.stable.jar so that they don’t cause any conflicts, in this example I renamed them to mantle.old/, mantleLogin.old/ and mantle-3.5.0.stable.old.jar.

The new mantle/, mantleLogin/ directories are inside the mantle-package-3.5-SNAPSHOT.zip file, extract the contents of this file into the tomcat/webapps/pentaho/ directory.
The new mantle.3.5.0.stable.jar file is also under the same directory but is named mantle-3.5-SNAPSHOT.jar, rename this file to mantle-3.5.0.stable.jar and copy it to the tomcat/webapps/pentaho/WEB-INF/lib/ directory.

After you have extracted and copied the new directories and file your tomcat/webapps/pentaho/ directory structure should now look like this:

• tomcat/webapps/pentaho/
  • mantle/
  • mantle.old/
  • mantleLogin/
  • mantleLogin.old/
  • WEB-INF/
    • lib/
      • mantle-3.5.0.stable.jar
      • mantle-3.5.0.stable.old.jar

Do not overwrite original directories and files!

If you are using a more recent version of Pentaho BI Server i.e. 3.5.2 the .JAR file will have a different name i.e. mantle-3.5.2.stable.jar

Start your Apache-Tomcat server, clear your browsers cache and view the modifications you have made to source code.

Final Notes

I didn’t try and go into too much detail with the “Modifying the Source Code” section as I could of have written a whole book on it! Hopefully the examples I have provided give you a bit of a kick start with any modifications you need to make to customise the PUC user interface however the best way to learn is by trial and error. This is the approach I took and I have never touched Java before I started using Pentaho!

Good luck and enjoy.

In this example I will be using the Steel Wheels sample data to create a report which will display a list of customers using two parameters: a drop down parameter which will contain a distinct list of countries which will then filter another drop down parameter which contains cities which belong to the country.

The Scenario

The current report displays customers information (includes the customer number, name, city and country). I would like to create parameters which will enable users to filter the list of customers by a country and then the cities which belong to that country.

Below is a screen shot of my initial report structure and preview screen:

Step 1. Build the Parameter Queries

I will need to build two parameter queries, the first will need to display a distinct list of countries and the second will need to display a distinct list of cities which belong to the country.

To get started I will need to add a new query to the data source which I created to connect to the sample data, from the screen shot below you can see I already have a query named customerList which the current report uses to display customer information.

To create a new query click on the icon (add a new query) and enter a SQL statement which will retrieve a distinct list of countries – make sure you don’t forget to name your query (in this example my country parameter query is named countryList):

Here is the above query in a format which you can copy and paste:

SELECT
 DISTINCT `customers`.`COUNTRY`
FROM
 `customers`

The next step is to preview the query – as you can see from the screen shot below the countryList parameter query is retrieving a distinct list of countries:

Now we will need to add the second parameter which will display a distinct list of cities based on the value of the country parameter. Close the preview window and click on the icon (add a new query) and enter a SQL statement which will retrieve a distinct list of cities – make sure you don’t forget to name your query (in this example my city parameter query is named cityList):

Here is the above query in a format which you can copy and paste:

SELECT
 DISTINCT `customers`.`CITY`

FROM
 `customers`

Preview this query. At the moment the above query is only retrieving a distinct list of every city. I need to make sure that this query retrieves a list of cities based on the country parameter:

For this query to only show a list of cities based on the value of the country parameter I will need to add the country parameter name to the WHERE clause of the cityList query. As I have not yet created the country or city parameters I will need to make note of the country parameter name I will be specifying in the cityList query – I have chosen to call the country parameter sCountryName. The new cityList query now looks like this:

Here is the above query in a format which you can copy and paste:

SELECT
 DISTINCT `customers`.`CITY`
FROM
 `customers`
WHERE
 `customers`.`COUNTRY` = ${sCountryName}

I have now created both parameter queries – I will need to revisit this area later on to modify the report query customerList but for now click on the OK button to close the JDBC Data Source window.

Step 2. Create the Parameters

I will need to create two parameters:

1. A country drop down parameter which is named sCountryName (step 1)
2. A city drop down parameter which will be named sCityName

Creating the sCountryName Parameter

To create a new parameter make sure you have the Data tab active, right click on the Parameters menu item and select the Add Parameter… option:

An Add Parameter… window will pop up. Before you make any changes to the options expand the connection folder on the left and then select the query which will populate the parameter, in this example it is the countryList query. Below is a screen shot of all the sCountryName parameter options completed:

The options above are fairly self explanatory however here are descriptions of the most important options:

• Name: This is the name we specified in step 1, this must match the value of this parameter we put in the cityList WHERE clause
• Type: The type of this parameter is a drop down
• Query: The query that will populate this parameter is the countryList query which was created in step 1
• Value and Display Name: I have set these both to the COUNTRY field as the value is the same as the output I would like displayed in the drop down parameter
• Value Type: The COUNTRY field is a string
• Mandatory: I have checked this option as a user must select a country before running the report – this also ensures that the city parameter will be populated

Click the OK button to save the sCountryName parameter.

Creating the sCityName Parameter

The second parameter I will need to create is for the city drop down. There isn’t much different from this parameter and the sCountryName parameter so I can copy and paste this parameter and then change some options.

To copy the parameter right click on the sCountryName parameter under the Data tab and select the Copy option (alternatively you can use the CTRL+C shortcut):

To paste the parameter right click on the Parameters… item and select the Paste option (alternatively you can use the CTRL+V shortcut):

This will create an identical copy of the sCountryName parameter.

Double click on the sCountryName parameter which is located at the bottom of the Parameters list, this will open the Edit Parameter… window. Before you make any changes to the options expand the connection folder on the left and then select the query which will populate this parameter, in this example it is the cityList query. Below is a screen shot of all the sCityName parameter options completed:

The options above are fairly self explanatory however here are descriptions of the most important options:

• Name: I have decided to name this parameter sCityName
• Type: The type of this parameter is a drop down
• Query: The query that will populate this parameter is the cityList query which was created in step 1
• Value and Display Name: I have set these both to the CITY field as the value is the same as the output I would like displayed in the drop down parameter
• Value Type: The CITY field is a string
• Mandatory: I have checked this option as a user must select a city before running the report

Step 3. Modify the Report Query

Now that the parameters and parameter queries have been created we are now ready to modify the report query (customerList) to use the new parameters. To modify the report query expand the data source connections under the Data tab and double click on the report query, customerList:

This will open the JDBC Data Source window and automatically highlight the customerList query:

To make the customerList query use the two new parameters created in step 2 you will need to add in two new conditions to the WHERE clause:

Here is the above query in a format which you can copy and paste:

SELECT
 `customers`.`CUSTOMERNUMBER`,
 `customers`.`CUSTOMERNAME`,
 `customers`.`CITY`,
 `customers`.`COUNTRY`

FROM
 `customers`
WHERE
 `customers`.`COUNTRY` = ${sCountryName}
AND
 `customers`.`CITY`    = ${sCityName}

Now the report query will use the values of the sCountryName and sCityName parameters in its WHERE clause. Click on the OK button to close the JDBC Data Source window.

Step 4. Preview the Report

The last step is to preview the report, to do this you can click on the (preview icon) found in the top left hand corner or alternatively click on View > Preview menu item.

By default nothing will be displayed in the report and none of the drop down parameters will be populated (if you would like a country to be set when you first run your report set a value for the Default Value option in step 2 for the sCountryName parameter).

To check if the cascading parameters are working pick a country from the first drop down for example Australia:

The city drop down parameter should automatically populate with the cities which belong to Australia (even though I’m not sure if you would classify Glen Waverly as a city):

After selecting a city i.e. Melbourne click on the UPDATE button and now the report is filtered to customers who are located in the country Australia and the city Melbourne:

Downloads

Below is a link to download the Pentaho Report file for this tutorial.

Final Notes

This was tested with PRD 3.5 and should work with PRD 3.6. If you are looking to eliminate the cascading feature you will need to remove the WHERE clause from the cityList parameter query: