Knowledge Base (Display) Knowledge Base (Display)

Birt required / facultative parameters

Birt required / facultative parameters

This article explains how the required & facultative parameters are managed in your reportlet

Overview

  • Parameters dialog automatically displayed or not?
  • Report parameters default values are very important in the reportlet engine
  • 'All values' feature in list parameters
  • Portlet preferences

Why the parameters dialog is almost never automatically displayed?

If you already tried your own reports with the reportlet, you probably noticed it is not keeping asking you the required parameters with a popup dialog. All has been done in the reportlet so that the popup parameters dialog will almost never have to be displayed automatically. Imagine you aggregate 4 reportlet windows on a unique page, it would not be very user-friendly if each of them keep displaying its parameters when the page is refreshed. A few rules are applied to decide if the popup parameters dialog must be displayed or not:

  • No default value is set up for this parameter in your report design
  • No value has already been set for this parameter in preferences mode
  • No value is found in user session (if the report has already been run in current session, parameters values are persistent even after a page refresh)

This behavior is very different from Eclipse WebViewer and Birt designer, which always display a parameters dialog when at least a report parameter is required.

When a default value is defined for each parameter in a birt report, your reportlet will never automatically display the popup parameters dialog.  The report runs with theses default values.

Birt Default values & 'All values' items

In Eclipse designer, It is possible to set each report parameter as required or facultative. Have a look on this screen:

The first list relates to a required combobox parameter, the second to a facultative one. You can notice when a such parameter is not required, a specific "All values" item is added at the end of the list.

When you set a 'not required' value for a list parameter,   "All values" item is automatically added at the last position. This label is localized and can be customized.

The value returned by this item is:

  1. The value of a specific custom property '_allvalues' if it is defined for this report parameter (see screenshot below)
  2. else the BIRT default value of the report parameter if it is defined
  3. else an empty string/null value

In Eclipse designer we should declare this user property '_allvalues'  as a string , even if the parameter has an integer type. If we declare it as integer BIRT might introduce some decimal separator ("0.0" instead of "0" for example) which could cause troubles.

For example, from final v1.0 the "interactive-table" demo report has been updated like this:

  • "Country" parameter has now a BIRT default value "USA" and a custom property "_allvalues" set to "all"
  • "Year" parameter has now a BIRT default value "2010" and a custom property "_allvalues" set to "-1"
  • The other parameters are unchanged, so their "All values" item still use their respective BIRT default value

In this example, both "all" and "-1" values are processed by the dataset query so that they return all rows.

From version 4.0, "all values" item is added to the parameter list only if the user property "_allvalues" is defined

How to handle "All values" item with a specific value in your SQL queries?

As explained in previous section, a facultative 'list' report parameter will display our "All values" item, and a good practice is to set a fictive specific value for a such parameter.
 
Most of the time, Birt developers use complex string concatenations to remove a filtering clause when a parameter must be ignored, whereas there is a much easier way to manage this.
 
Let's consider an example of a report with two parameters, productID and monthID. We suppose that productID is an "integer" facultative report parameter,  and monthID is required. Let's say the default value of productID is -1, since a real productID will always be greater than 0 in our fictive example. Here is a definition example in Birt designer:
 
 
 
And consider a BIRT query example for this report:
 
SELECT productID, sum(amount)
FROM sales
WHERE productID=?
AND monthID=?
GROUP BY productID
 
 This query returns all your sales for a specific product and a month. But when "All values" is selected for productID, this parameter is set to -1 and it won't return any row, though you want to get all products. Here is how we can update the query:
 
SELECT productID, sum(amount)
FROM sales
WHERE (productID=? OR ?=-1)
AND monthID=?
GROUP BY productID

 

This way, our query works as expected even when this productID parameter equals to -1, and we don't have to use complex javascript handlings to remove a filter clause. I hope this example makes sense, and you now understand how default values can be used to represent "All values".

Note from v0.9.4 it is possible to use a "Null" defaut value (let it blank in Birt designer), whatever the datatype is. With our example, the query would be:

SELECT productID, sum(amount)
FROM sales
WHERE (productID=? OR ? IS NULL)
AND monthID=?
GROUP BY productID
 

 

You may wonder why a constant value has not been chosen instead of default values: a such constant can't be used because a parameter may be an integer, a text, a date, etc.  Of course we could arbitrarily utilize a constant for each datatype (-9999999 for numbers, an empty string for texts, 9999-01-01 for dates etc.) , or even "Null", but it would probably be too much intrusive: for example, you may have existing stored procedures, web service datasources etc which already work with specific values, therefore it seems to be a better option to let each project manage its own fictive codes for each parameter.

Any feedback/opinion will be much appreciated! 

Report parameters in portlet preferences

If you set report parameters in "preferences" mode, as shown in the screen below, these parameters values are stored as portlet preferences in your portal database. From a user point of view, the report will run by default with these stored values, instead of BIRT default values. Here is a summary of the priority order used by the reportlet to select which value to apply when running a report:

values set by users  >  values in session  >  values in preferences  >  default values in BIRT report design

 

Tags: developers
Average (0 Votes)
Most Recent
Toolbar portlet 01 April 2015
Secured parameters 02 December 2014