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.

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:

• Screenshot and description
• How to setup your parameter query
• How to setup your report query to accept the parameter

To directly go to a parameter type you are interested in click on a link below (every example uses the Steel Wheels sample data):

• Drop Down
• Single Value List
• Multi Value List
• Radio Button
• Check Box
• Single Selection Button
• Multi Selection Button
• Text Box
• Date Picker

Drop Down

• Similar to a select box in HTML
• Displays one active option at a time unless you click on the arrow to display all options
• Can only select one option at a time

Parameter Query

This query will display a unique list of Product Lines as options inside a drop down.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the selected Product Line option from the drop down. As only one option can be selected at a time it is recommended to use a = (equal) in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE = ${enterProductLine}

Single Value List

• Similar to a list box in HTML
• Displays more than one option at once (including the active option)
• To see more than one option at once change the Visible Items count under the parameter’s options window
• Can only select one option at a time

Parameter Query

This query will display a unique list of Product Lines as options inside a single value list.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the selected Product Line option from the single value list. As only one option can be selected it is recommended to use a = (equal) in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE = ${enterProductLine}

Multi Value List

• Similar to a multi list box in HTML
• Displays more than one option at once (including active options)
• To see more than one option at once change the Visible Items count under the parameter’s options window
• Can select more than one option at a time

Parameter Query

This query will display a unique list of Product Lines as options inside a multi value list.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the selected Product Line options in the multi value list. As multiple options can be selected at a time make sure you use an IN() condition in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE IN (${enterProductLine})

Radio Button

• Similar to radio buttons in HTML
• Displays more than one option at once (including the active option)
• Can only select one option at a time

Parameter Query

This query will display a unique list of Product Lines options as radio buttons.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the checked Product Line radio button. As only one option can be selected at a time it is recommended to use a = (equal) in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE = ${enterProductLine}

Check Box

• Similar to a check box in HTML
• Displays more than one option at once (including active options)
• Can select more than one option at a time

Parameter Query

This query will display a unique list of Product Lines options as check boxes.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the checked Product Line check boxes. As multiple options can be selected at a time make sure you use an IN() condition in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE IN (${enterProductLine})

Single Selection Button

• Similar to a buttons in HTML
• Displays more than one option at once (including the active option)
• Can only select one option at a time

Parameter Query

This query will display a unique list of Product Lines as single selection buttons.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the selected Product Line button. As only one option can be selected at a time it is recommended to use a = (equal) in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE = ${enterProductLine}

Multi Selection Button

• Similar to a button in HTML
• Displays more more than one option at once (including active options)
• Can select more than one option at a time

Parameter Query

This query will display a unique list of Product Lines options as multi selection buttons.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the selected Product Line buttons. As multiple options can be selected at a time make sure you use an IN() condition in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE IN (${enterProductLine})

Text Box

• Similar to a text boxes in HTML
• Free text only
• Is case sensitive and must be exactly the same as the option

I have tried numerous ways on making the text box parameter more flexible, if you have any ideas please let me know.

Parameter Query

This query will display a unique list of Product Lines which the contents of the text box will match.

-- Name: enterProductLine
SELECT DISTINCT `products`. PRODUCTLINE
FROM   `products`

Report Query

This query will display all information for each product by the contents of the text box matching a Product Line option. As only one option can be selected at a time make sure you use a = (equal) in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `products`
WHERE  `products`.PRODUCTLINE = ${enterProductLine}

Date Picker

• Similar to standard JavaScript date pickers
• No way of formatting the date picker output, for example displays date, time and timezone

Parameter Options

As the date picker is providing the user values to input you do not need to specify a parameter query so your parameter options should look similar to the screenshot below:

Parameter Query

No parameter query is needed as the date picker is generating the parameter value.

Report Query

This query will display all information for orders which are greater than the specified Order Date from the date pickers value. As only one option can be selected at a time make sure you use a = (equal), >, >=, <= or < condition in your WHERE clause.

-- Name: stockByProductLine
SELECT *
FROM   `orders`
WHERE  `orders`.ORDERDATE > ${enterOrderDate}

Hopefully these descriptions shed more light on the parameters available in Pentaho Report Designer 3.5.

Enjoy.

If you aren’t already aware Doug Moran (Pentaho’s Community Leader) has already created a set off screen casts showing off features of Pentaho Report Designer 3.5.

The Scenario

In this tutorial I already have a report which is using the Steel Wheels sample data. My current report displays all customers by the country they are located in and I would like to create a parameter which will filter the results to a user specified country.

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

Step 1. Build the Parameter Query

The first step is to build a query which will display a unique list of countries. To get started I will need to add another query to the data source which I created to connect to the sample data, from the screenshot below you can see I already have a query named allCustomers which my current report uses to. 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 also don’t forget to name your query – in this example it is allCustomerCountries:

Make sure you give meaningful names to your queries as you will always need to reuse them through throughout your report.

Just to be sure preview the report, as you can see from the screen shot below, the allCustomerCountries query returns a unique list of countries. Close the Preview window and then click OK to save your new query and close the Data Sources window.

Step 2. Create the Parameter

To create a parameter make sure you have the Data tab active. Right click on the Parameters menu item and select the Add Parameter… option.

This will display an Add Parameter… window with a set off options which will need to be filled out (as you can see in the screenshot below I have already filled out the options):

Here is a description of each option available from the Add Parameter… window:

• Name : The name of your parameter, this will be displayed under the Parameters menu item – this is important so make sure you give the parameter a meaningful name
• Label : The label which will be displayed to the user, for example “Select a country”
• Type : The type of parameter, for example “Drop Down”
• Query : The query which contains the contents of the parameter, for example customerCountryList
• Value : The actual value of the parameter – this isn’t displayed to the user and is used in the report query, for example Product Number instead of Product Name
• Display Name : The value which will be displayed the the user, for example Product Name
• Value Type : The data type of the parameter, for example String, Integer, Date etc.
• Default Value : The default value which is to be selected when the report is opened, this should be equivalent to the Value option, for example Australia
• Mandatory : Check this option if the parameter must be used to display results

With the options I have filled out I’m trying to create a report which:

• Uses a drop down parameter type
• Displays the text “Select a country” next to the drop down
• By default select Australia as the country in the drop down and in the report results
• Make sure that this parameter is always used to display report results

Click OK to save your new parameter.

Step 3. Modify the Report Query

Now that we have created our parameter we have to tell the report query to use the parameter’s value in its WHERE clause. To edit the report query, double click on the query under the Data tab, in this example the original report query was named customerCountries and looks like the screen shot seen below:

To make sure the report query will use our new parameter (enterCountries) add in the following piece of code to the WHERE clause:

As you can see the we have made the WHERE clause for the customer country equal to the parameter name enterCountry which is wrapped between a ${}.

At all times parameter names must be wrapper between ${}

Click OK to save and close the report query, customerCountries.

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 click on View > Preview menu item.

As you can see the parameter is set to a default value of Australia and therefore every time the report is run it will be filtered to Asutralia. To test if the report parameter is working I selected a new country Norway and clicked the Update button (if you don’t want to keep clicking Update after you choose a new parameter check the Autocomplete on selection check box).

Step 5. Publish your Report

The final step is to publish your report to Pentaho Business Intelligence Server (click here to learn how to publish reports) where you will see that the parameter looks exactly the same to when it was previewed in the designer:

Downloads

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

That is how you can create a basic parameter driven report using Pentaho Report Designer 3.5.

Enjoy.

Modify publisher_config.xml

To get started you will need to edit the publisher_config.xml file located under the /opt/biserver-ce/pentaho-solutions/ directory, once open locate the following piece of code:

<publisher-config>
<publisher-password></publisher-password>
</publisher-config>

Enter a password between the publisher-password tags (this password will be the same for all users) so that the piece of code looks similar to the example below – in this example the publisher password is publishthis:

<publisher-config>
<publisher-password><strong>publishthis</strong></publisher-password>
</publisher-config>

Save and close this file.

From now on when any users try and publish content to Pentaho BI server they will need to specify this password.

Login to Pentaho BI server

In this example I’m going to publish a report which I created in my survey scale chart tutorial to Pentaho BI server. Within PRD click on File > Publish (or use the CTRL+SHIFT+P shortcut) which will display a Login window:

You will need to specify user credentials in this window to authenticate with Pentaho BI server, the available fields and options are:

• URL : URL of Pentaho BI server (in this example it is hosted locally)
• Timeout : Amount of seconds the connection will last with the server until it times out
• Username : Username of the user publishing to the server (this is the username you use to login to Pentaho User Console (PUC))
• Password : Password of the user publishing to the server (this is the password you use to login to PUC)

The user specified above which is logging into Pentaho BI Server will inherit all access and permissions. Therefore the user will only be able to publish to folders (solutions) which the user has access to.

After filling out the required fields and clicking on OK a Login to server progress bar will appear while PRD connects to Pentaho BI Server:

Publish to Pentaho BI server

After a successful connection a Publish To Server window will appear:

Below is an explanation of all available fields and options from the Publish To Server window:

• Report Name : Name of the report being published
• Report Description : Description of the report being published
• Location : The folder (solution) on the server you would like to publish the report to
• : Open the parent folder
• : Opens up a browse window to browse through or create new folders (solutions)
• Output Type : Default output type of the report which users will see in PUC
• Lock : Lock the report format within PUC to the Output Type
• Publish Password : Publisher password (in this example it is publishthis)

For this example I would like to publish my report into a new folder (solution) named blog. To do this first click on the (browse) icon which will open up a Browse window.

Click on the (new folder) icon which will prompt you to create a new folder:

After entering a Name and Description click on OK. Now the new folder (solution) will appear in the Browse window along side other folders (solutions):

Click on the folder (solution) (which you would like to publish the report into) to make it active and click OK. To finish publishing this report complete all necessary fields and options in the Publish To Server window. In this example we will only need to complete 5 fields:

1. Name : Name of the report
2. Description : Description of the report
3. Location : The folder (solution) we are publishing the report to is /blog
4. Output Type : I have decided that my report can only be viewed as a PDF
5. Lock : I have checked this option to make sure that the report can only be viewed as a PDF and in no other formats

Click OK once your are ready to publish your report. If the report was successfully published you will be shown the following prompt:

Click on YES to run your report straight away.

Run your report

After clicking YES the PUC login screen will be launch in a new window or tab with your default browser. After logging in the report is automatically displayed as a PDF (remember I chose the output type to be a PDF and to be locked):

To launch the report within PUC first click on the folder (solution) name in the Solution Browser which contains the report which was just published – in this example it is blog:

After clicking on a folder (solution) all available reports within this folder (solution) will be displayed in the frame below it – in this example there is only one report Survey_Scale_Chart_Example, double click on the name of the report which was just published.

As you can see my report automatically ran as a PDF (remember I chose the output type to be a PDF and to be locked):

Hopefully these steps can help you in publishing content to Pentaho BI server.

This post will be added as a chapter to current Pentaho documentation.

Enjoy.

Because this book just oozes with awesomeness I have been able to shorten my review to three words “buy it now“.

Enjoy.

Below is a tutorial which I have put together on how to implement Survey Scales within a report using Pentaho’s Report Designer 3.5.

Sample Data

I have decided to create my own data set for this example which is survey responses from athletes. If you would like you can download the Excel workbook and import it into your database of choice.

Here is a quick preview of what the sample data looks like:

After importing the data into your database start PRD.

Create a New Connection

Once PRD has started create a new connection to the database which contains the sample data. In this example I have called my connection SurveyResults.

Make sure to test the new connection before we start building the query.

Build the Query

You will need to build a query to retrieve the survey results, in this example I have called the query GetAllSurveyResults.

Make sure to preview the query before we start building our report.

After clicking OK you should now see a JDBC (SurveyResults) connection, GetAllSurveyResults query and fields under the Data tab.

Report Structure

Here is how I will be structuring my report:

• Page Header
  • Athlete Name (Group)
    • Question Title and Description (Group)
      • Answer (Survey Scale Chart)
    • End of Question Title and Description (Group)
  • End of Athlete Name (Group)
• Page Footer

As you can see I’m creating a report which will group our survey results by Athlete Name and then by Question Titles and Descriptions to which the Athletes provided Answers to.

Page Header and Footer

By default I have a template which already has a default Page Header and Footer which I have modified for this tutorial.

Creating the Athlete Name group

After you have created your Page Header and Footer the next step is to create the first Group based on the Athlete Name. Right click on the first Groups option under the Structure tab and select the Edit Group option.

This will open up an Add Group dialog box, click on the ATHLETE_NAME field and then the arrow pointing to the right to add it to the Selected Fields list and click OK.

Now you need to add the ATHLETE_NAME field into the report. Make sure the Structure tab is active and expand the Groups option and select the Group Header.

To make the Group Header visible on the report canvass click on the Attributes tab and uncheck the hide-on-canvass check box.

Now you should be able to see the Group Header on the report canvass.

At the same time under the Structure tab, select the Style tab and scroll down to the page-behavior section and check the pagebreak-after option. You have now made the report create a page break after each ATHLETE_NAME group.

The next step is to drag and drop the ATHLETE_NAME field from the Data tab onto the Group Header section on the report canvass.

Creating the Question Title and Description group

To create the Question Title and Description group right click on the Groups section under the Structure tab and click on the Add Group option.

This option will open up an Add Group window. Click on the QUESTION_TITLE and QUESTION_DESCRIPTION fields and then the > button to move these fields to the selected fields list and click OK.

After clicking OK the Group Header, Details and Footer for the Question Title and Description are automatically shown on the report canvass. Drag and drop the QUESTION_TITLE, QUESTION_DESC fields from the Data tab onto the Group Header section (located under the Group Header section for the Athlete Names).

Now you are ready to add in the Survey Scale chart – before you continue make sure that your report is grouping correctly by viewing the report in the Print Preview mode.

Adding in the Survey Scale chart

For your information here is a quick overview of what elements make up a Survey Scale chart.

On the left are the elements which make up a Survey Scale chart (the labels are options which you can set up to be either a set value or an expression under the Attributes tab). On the right are the values I have put in for this tutorial, ANSWERS is a field from our GetAllSurveyResults query. In my data set:

• The lowest value can be a 0
• The highest value can be a 10
• The lower-bound value (the lowest answer Athletes should be answering) is 7
• The highest-bound value (the highest answer Athletes should be answering is 10)

You will need to drag and drop the (survey-scale) chart object onto the Details section (which sits between the Question Title and Description Group Header and Footer).

Double click on the chart object so that a drop down arrow appears and from the available list select the ANSWERS value.

To finish off click on the survey scale chart object then under the Attributes tab find the survey-scale section. As you can see I have static values but you can also create dynamic values as an expression.

To see if you have successfully created a report using Survey Scale charts view the report in the Print Preview mode.

Downloads

Below are links to download the Sample Data, Pentaho Report file or view the tutorial report generated as a PDF.

Enjoy.