Chapter 11. Custom Reports

Table of Contents

The following chapter covers user defined reports. See Section 9.1.1, “The Overview Reports” on how to generate the pre-configured overview reports that are included in Klaros-Testmanagement Community Edition.

With Klaros-Testmanagement Enterprise Edition it is possible to define custom reports using the built-in de.verit.klaros.core.model. Though Klaros-Testmanagement already provides several reports, it might be helpful to design new reports that suite your and your customer's needs. Figure 11.1, “The Report Generation Process” gives an overview of the report generation process. As the report definition process is based on a Groovy or Java script and SeamPDF or SeamExcel, basic knowledge in Groovy or Java programming and XML conventions are helpful for a report designer.

Figure 11.1. The Report Generation Process

The reporting process involves two roles, the Report Designer and the Report User. While the report designer provides the structure of the report and prepares the report layout, the report user applies the reports to the data collected in Klaros-Testmanagement. The report designer has to provide a script and a template to build a report. The query script prepares the data and is implemented in Groovy or Java, while the report template describes the layout of the report. The Groovy/Java script taking care of data retrieval and preparation is provided by a class that implements the Section E.2, “KlarosScript Interface”. This interface defines a single method called execute and takes a de.verit.klaros.scripting.KlarosContext object as input parameter.

To retrieve the data from Klaros-Testmanagement, the report designer can access the de.verit.klaros.core.model via the HQL query language. The main task of the class is to provide and prepare the data for the report. The data for the report template must then be stored in the de.verit.klaros.scripting.KlarosContext object passed to the execute method. To make reports more flexible for report users, it is possible to pass parameters to the Groovy/Java script. The parameters are stored in the context and can be accessed from the script.

	Predefined objects in the context
	The de.verit.klaros.scripting.KlarosContext object already contains predefined objects. For a list please refer to Section E.1, “Context Variables”.

The report template must be implemented using SeamPDF. Section Section 11.3, “Example Report” provides an example of how to define a custom report.

11.1. Create A New Report Template

11.1.1. Supported Parameter Types
11.1.2. Dealing with Parameters

Before reports can be applied to the test data, they have to be defined. To get to the Report Templates page click on the Configure icon and select Report Templates from the menu on the left side of the screen.

Figure 11.2. The Report Templates Page

To create a new report click on the New button on the Report Templates page. Then provide the basic data for the report by entering a name in the Name field and a short description in the Description field.

Figure 11.3. The New Report Templates Page

To enter the Groovy script, which retrieves the data, use the Groovy Script text area. To unfold the template text area click on the Edit the Template link next to the Template label. The report's template code can then be entered into the unfolding text area. To unfold the Groovy script text area again click on the Edit the script link.

	Note
	For larger report templates it might be helpful to use a Java IDE e.g. Eclipse, to develop the Groovy script and an XML editor to provide the report template. The created files can then be uploaded into Klaros-Testmanagement. To avoid errors in the Groovy script, add the Klaros model libraries to the build path of your Eclipse project.

Instead of manually entering the code for each text area, the code can be imported from a file. Specify the file to be use by clicking on the Browse Button and select the file from the file system. Click OK in the file dialog and afterwards click Upload to import the selected file into the text area.

This page provides three actions to be executed. To test the code click on the Preview button to generate a report. The Save button stores the report into the Klaros repository in the file system. The changes can be discarded by pressing the Back button.

	Note
	The generated report is opened automatically in a new browser window. If this does not work for you, please check if you have a pop-up blocker active.

To provide a certain degree of freedom to the report users and to make the reports more flexible, it is possible to pass parameters to the Groovy script. This mechanism can, for example, be used to pass a time span to the Groovy script, so that only data for this time span is retrieved from Klaros-Testmanagement.

To pass arguments to the report click the New Parameter button.

A new section as shown in Figure 11.4, “Specifying Parameters” is displayed, which enables the addition of parameters. Clicking the button allows a parameter to be added to the parameter list.

Figure 11.4. Specifying Parameters

Clicking the icon removes the parameter from the list. The type of the parameters can be specified by selecting the appropriate value from combo box. Supported types are Text, Number, Date, Boolean Enumeration and Multi-enumeration.

The passed parameters can be accessed by the Groovy script by either calling the getParameterValue(String name) or the getParameter(String name) method. The methods will return null if no parameter with the specified name can be found.

11.1.1. Supported Parameter Types

The following parameter types are supported:

Report Parameter Types

Text
Number
Date
Boolean
Enumeration
Multi-enumeration

11.1.2. Dealing with Parameters

As mentioned before the passed parameters can be retrieved from the context by the methods getParameterValue(String name) and getParameter(String name).

The following code snippet shows how to access the parameters and how to use them in the Groovy script:

query.append("select tcr from KlarosTestCaseResult tcr where tcr.executionTime <");
long executionTime = context.getParameterValue("executionTime");
query.append(executionTime);
List<?> tcr = context.executeQuery(query.toString());

This query will retrieve all KlarosTestCaseResult instances that have an execution time smaller than the value passed with the parameter executionTime.

As an alternative the parameters can be directly accessed in the query as shown in the followingcode snippet.

query.append("select tcr from KlarosTestCaseResult tcr where tcr.executionTime <:executionTime");
List<?> tcr = context.executeParameterizedQuery(query.toString());

Parameters can be accessed from the report template in the following way:

<p:text value="Testresults for testruns with execution time &lt; #{executionTime} ms" />

	Note
	Make sure to escape characters like `&`, `<` or `>` when using them in XML attributes in the report template.


10.6. Backup		11.2. Applying a Report Template