Parameters allow the user to better customize the data returned by a report. The parameters available for a given report are retrieved from the report's compiled JasperReport file. The following fragment shows all the parameters available in the "Task List by Due Date" report that appears in the "My Home Page" category (from jasper_reports/task_date.xml the source file of the report):

<parameter name="userid_range_source" isForPrompting="true" class="java.lang.String">
  <parameterDescription><![CDATA[contact.source]]></parameterDescription>
  <defaultValueExpression ><![CDATA["my"]]></defaultValueExpression>
</parameter>
 <parameter name="userid_range" isForPrompting="false" class="java.lang.String">
  <defaultValueExpression ><![CDATA["1,2,32"]]></defaultValueExpression>
 </parameter>
 <parameter name="date_start" isForPrompting="true" class="java.sql.Timestamp">
  <parameterDescription><![CDATA[reports.parameter.dueDateFrom]]></parameterDescription>
  <defaultValueExpression ><![CDATA[java.sql.Timestamp.valueOf("1802-10-01 00:00:00")]]></defaultValueExpression>
 </parameter>
 <parameter name="date_end" isForPrompting="true" class="java.sql.Timestamp">
  <parameterDescription><![CDATA[reports.parameter.dueDateTo]]></parameterDescription>
  <defaultValueExpression ><![CDATA[java.sql.Timestamp.valueOf("2004-12-01 00:00:00")]]></defaultValueExpression>
 </parameter>
 <parameter name="boolean_completed" isForPrompting="true" class="java.lang.Integer">
  <parameterDescription><![CDATA[reports.parameter.completed]]></parameterDescription>
  <defaultValueExpression ><![CDATA[new Integer(-1)]]></defaultValueExpression>
 </parameter>
 <parameter name="boolean_completed_where" isForPrompting="false" class="java.lang.String">
  <parameterDescription><![CDATA[AND t.completedate IS NOT NULL]]></parameterDescription>
  <defaultValueExpression ><![CDATA["AND t.completedate IS NULL"]]></defaultValueExpression>
 </parameter>
 <parameter name="language" isForPrompting="false" class="java.lang.String">
  <defaultValueExpression ><![CDATA["en"]]></defaultValueExpression>
 </parameter>
 <parameter name="country" isForPrompting="false" class="java.lang.String">
  <defaultValueExpression ><![CDATA["US"]]></defaultValueExpression>
 </parameter>
 <parameter name="CENTRIC_DICTIONARY" isForPrompting="false" class="java.util.Map"/>
 <parameter name="SCRIPT_DB_CONNECTION" isForPrompting="false" class="java.sql.Connection"/>

The Attributes of a Parameter Element

name
After a user has selected a report to run a record is stored in the database to the "report_queue" table, and all of the parameter name and value entries are added to the "report_queue_criteria" table. This way when the ReportRunner picks up the report to process, it can read in all the parameters needed to filter the results.

isForPrompting
There are two methods for handling report parameters in ConcourseSuite, either silently by the system or by prompting the user. If the parameter should appear on the Parameter form for the user to specify, like in the case of the "date_start" and "date_end" parameters above then this should be set to "true." When isForPrompting is false the evaluation is then made behind the scenes, and the name must use one of the special prefixes, suffixes, or names to be evaluated by the system, or have a defaultValueExpression set. In most cases custom parameters will have isForPrompting set to true, since the handling of false relies on the system evaluating the result according to some predefined logic.

class
This is used for validation of input values.

Nested Elements of a Parameter

Note: the use of these elements may be altered by the presence of special strings. See "Special Strings in Parameter Names" below.

parameterDescription
This is the label of the form element that the user will see. It's optional when a parameter has isForPrompting set to false. The value must be a key in the language dictionary files that can be found in the "languages" folder, if no existing keys match the label needed a new entry will need to be added to the file.

defaultValueExpression
This an optional element that provides a default value for the parameter. The user will see this value in the corresponding input field in the Parameter Selection form when isForPrompting is true. In the case of a dropdown this will make a particular element appear at the top of the menu or in a text input this will be the pre-populated value. When isForPrompting is false this will be the value stored for that parameter name, since user input has been bypassed (unless a special name was used in which case the value may be overridden).

Special Strings in Parameter Names

Now that the purpose of each of the configurable parts of a parameter has been covered, we can take a look at the special strings for parameter names.
Please Note: These strings are treated as special only when adding reports through the form in the application. Reports created externally through the XML HTTP API or by calling the ReportQueue base classes directly will not have any special logic or meaning applied.

Names

Prefixes

Suffixes

Dynamic Filters with _where
When text_, lookup_, and boolean_ parameters are used in conjuction with a parameter with the same root name and a "_where" suffix predefined business rules will evaluate the parameter value.
_where and boolean_''

• If "Any" was chosen base parameter
• filter parameter is set to "", since no filtering will be performed
• Else if "Yes" was chosen base parameter
• filter parameter is set to "parameterDescription" value
• Else "No" was chosen base parameter
• filter parameter is set to "defaultValueExpression" value

_where and others

• If "-1", "", or null was chosen base parameter
• filter parameter is set to "", since no filtering will be performed
• Otherwise
• filter parameter is set to "defaultValueExpression" value updated with the user selection

Example of Adding a Report Parameter

For this example we will create a new report out of the existing task_date.xml. First make a copy of the original and save it as task_date_loe.xml. The title will be "Task List By Deadline and Effort Type", and it will just extend the original report with a filter on level of effort types.

Two new entries will be added to the original parameters:

 <parameter name="lookup_task_loe" isForPrompting="true" class="java.lang.Integer">
  <parameterDescription><![CDATA[tasks.estimatedLOE]]></parameterDescription>
  <defaultValueExpression ><![CDATA[new Integer(-1)]]></defaultValueExpression>
 </parameter>
 <parameter name="lookup_task_loe_where' isForPrompting="false" class="java.lang.String">
  <parameterDescription><![CDATA[AND ltl.code = $P{lookup_task_loe}]]></parameterDescription>
  <defaultValueExpression ><![CDATA[" "]]></defaultValueExpression>
 </parameter>

Line By Line

<parameter name="lookup_task_loe" isForPrompting="true" class="java.lang.Integer">

Since the parameter's name is prefixed with "lookup_" the application will attempt to find a corresponding table in the database. As long as the query is successful a list of the records with their description(text) and code(int) fields will be returned. The isForPrompting attribute is set to true, since this is a special parameter that will display a dropdown menu of the records returned and add the option "Any" with value "-1" as the default. Since the code column is of type int the class is set to "java.lang.Integer."

<parameterDescription><![CDATA[tasks.estimatedLOE]]></parameterDescription>

After looking in one of the dictionary files in the "languages" folder the following entry was found:

<param name="tasks.estimatedLOE">
   <value><![CDATA[Estimated LOE]]></value>
</param>

The name is set as our parameterDescription so the label can be displayed on the form.

<defaultValueExpression ><![CDATA[new Integer(-1)]]></defaultValueExpression>

Sets the default to -1, the "Any" option

<parameter name="lookup_task_loe_where" isForPrompting="false" class="java.lang.String">

For any of the prefixes that drive form display the application will always check for a "_where" suffix next. Since this parameter name has the special "_where" suffix, the application will get the user input from the corresponding base parameter to apply against the predefined business logic. The isForPrompting attribute is set to false since the evaluation of the dynamic filter is not exposed to the user. The class is set to String since it is part of the query.

<parameterDescription><![CDATA[AND ltl.code = $P{lookup_task_loe}]]></parameterDescription>
<defaultValueExpression ><![CDATA[""]]></defaultValueExpression>

The application now applies the following rules to evaluate the parameter value:

• If "-1" was selected in the base parameter the "_where" parameter will use the defaultValueExpression
• Otherwise the parameter will update the parameter description with the "code" value submitted and save the parameter-value in the "report_queue_criteria" table.

Here is what the new query will look like:

 <queryString><![CDATA[SELECT t.task_id as task_id, 
t.description as descri, 
t.duedate as duedate,
tt.ticket_id AS ticketid,
cc.namefirst AS ofname,
cc.namelast AS olname,
c.namefirst AS cfname,
c.namelast AS clname,
c.company AS ccompany,
t.completedate as complete,
t.estimatedloe AS loe,
ltl.description AS loe_desc,
tp.description AS priority
FROM task t
LEFT JOIN tasklink_ticket tt ON (t.task_id = tt.task_id)
LEFT JOIN tasklink_contact tc ON (t.task_id = tc.task_id)
LEFT JOIN contact c ON (tc.contact_id = c.contact_id )
LEFT JOIN contact cc ON (t.owner = cc.user_id )
LEFT JOIN lookup_task_loe ltl ON (t.estimatedloetype = ltl.code)
LEFT JOIN lookup_task_priority tp ON (t.priority = tp.code)
WHERE t.task_id > -1
AND t.trashed_date IS NULL
AND t.owner IN ($P!{userid_range})
AND t.duedate >= $P{date_start}
AND t.duedate <= $P{date_end}
$P!{boolean_completed_where}
$P!{lookup_task_loe_where}
ORDER BY t.duedate, t.priority]]></queryString>

To test it out:
1. Add a record to the "report" table
2. Compile the report with ant deploy.jasper or ant deploy.
3. Login to the application and verify that the parameters and report work as expected