Managing Report Templates

Applies to ReadyAPI 3.54, last modified on September 23, 2024

The ReadyAPI reporting feature uses the JasperReports engine. You can fully customize your reports both at project and global levels with JasperReports templates, since they use an XML-like syntax.

To learn more about JasperReports and its template language, visit the official website.

You can also use a free tool, iReport, to work with your report templates. The installation package is available here. Using this tool, you can edit the JRXML files, which ReadyAPI uses to store the report templates.

To learn the basics of ReadyAPI reporting, see Getting Started With Reporting.

Working With the Reporting Window

Using the Reporting window, you can work with global and project-specific report settings. To open it, select Project > Reporting from the main menu.

ReadyAPI: The Reporting window

Click the image to enlarge it.

Switch between the tabs to view reports, subreports, templates, or project level report parameters.

You can create, remove, and edit project level items in any way.

You cannot edit global items in the ReadyAPI UI. If you need to edit them, apply the changes you want in a third-party editor, then click in the Reporting window, or restart ReadyAPI.

Report Structure

ReadyAPI reports have the following structure:

  • Main Reports are the top level templates, which appear in the Create Report dialog. To view them, switch to the Available Reports tab in the Reporting window.

    The Main Report template is a standard JasperReport template. Its data source is a report-specific model item. For example, when ReadyAPI creates a load test printable report, it passes the WsdlLoadTest object to the report. You can define the properties of this object as Jasper fields in the report, and then use them.

  • Main reports include Subreports. Subreports use the standard JasperReports subreport feature with the ReadyAPI-specific URL prefix "subreport:". Subreports get data from a specific data source, which is available during report generation. On the Subreports tab, you can see all the available subreports and their data sources.

    ReadyAPI: The Subreports tab of the Reporting window

    Click the image to enlarge it.

    For example, the MetricsReport subreport gets data from the ReportMetrics data source. You can use that subreport in main reports using the following syntax:

    y="98" width="535" height="30" isRemoveLineWhenBlank="true">
    $P{IncludeResults}
    ...
    $P{TestSuiteMetrics}
    "subreport:MetricsReport"

    As you can see, subreportExpression uses a custom "subreport:" URL syntax. ReadyAPI uses it to locate the subreport template you need. The fields from the TestSuiteMetrics data source are defined in the MetricsReport template.

    ...

        <field name="name" class="java.lang.String"/>
        <field name="value" class="java.lang.String"/>
        <field name="category" class="java.lang.String"/>
        <field name="icon" class="java.lang.String"/>
    ...
         <textField isStretchWithOverflow="true">
            <reportElement x="253" y="31" width="282" height="14"/>
            <textElement/>
            <textFieldExpression class="java.lang.String">$F{value}</textFieldExpression>
         </textField>
         <textField>
            <reportElement style="ColumnHeader" isPrintRepeatedValues="false" x="0" y="0" width="535" height="24" isRemoveLineWhenBlank="true"/>
            <box bottomPadding="0">
               <pen lineStyle="Double"/>
               <topPen lineStyle="Double"/>
               <leftPen lineStyle="Double"/>
               <bottomPen lineStyle="Double"/>
               <rightPen lineStyle="Double"/>
            </box>
            <textElement verticalAlignment="Bottom"/>
            <textFieldExpression class="java.lang.String">$F{category}</textFieldExpression>
         </textField>
         <textField>
            <reportElement x="20" y="31" width="233" height="14"/>
            <textElement/>
            <textFieldExpression class="java.lang.String">$F{name}</textFieldExpression>
         </textField>
    ...

  • Templates allow managing common blocks of the template XML code.

    ReadyAPI: The Templates tab of the Reporting window

    Click the image to enlarge it.

    For example, you can use that template to add a logo to your report:

    ReadyAPI: An example report template

    Click the image to enlarge it.

    You can then insert it into a report as a property expansion.

  • Parameters allow you to apply changes to the report content without recompiling the template.

    You can find them on the Parameters tab.

    ReadyAPI: The Parameters tab

    ReadyAPI passes parameter values to JasperReports as standard Jasper parameters.

    For example, the following template defines the HeaderLogo parameter:

    JRXML

    <parameter name="HeaderLogo" class="java.lang.String" isForPrompting="false">
        <defaultValueExpression>"../../logos/header_logo.jpg"</defaultValueExpression>
    </parameter>

    Then, you can use the following code to apply the header logo:

    JRXML

    <image scaleImage="Clip" hAlign="Right" isUsingCache="false" onErrorType="Blank">
        <reportElement x="0" y="0" width="535" height="51"/>
        <imageExpression class="java.lang.String">$P{HeaderLogo}</imageExpression>
    </image>
Note: You can use property expansions within any of these templates or parameter values. For example, you can show the current user name in the report. To do that, just insert the ${#System#user.name} property expansion to your report template. Keep in mind that ReadyAPI caches the report templates it has already compiled. If the property expansion value changes, ReadyAPI will compile the template again.

Summary

ReadyAPI has the Main Report** -> Subreport(*) structure. Both main reports and subreports can use multiple templates (with property expansions) or parameters (with Jasper parameters).

Report Storage

ReadyAPI stores all global report templates in the bin/reports directory (ReadyAPI_installation/bin/reports). The directory contains the following folders:

Folder Description

loadui

Templates relating to load testing reports.

logos

Contains images that use the logo: protocol reference.

reports

Contains all global main report templates. The name of each subdirectory corresponds to the appropriate value in the Report Type column on the Available Reports tab.

subreports

Contains all global subreport templates. The name of each subdirectory corresponds to the appropriate value in the Report Type column on the Subreports tab.

templates

Contains all global templates.

If you open one of these directories, you will see that ReadyAPI stores each template in two files:

  1. A .jrxml file: A clean Jasper template which you can edit in any JasperReports editor or text editor.

  2. A -config.xml file: Contains the metada of the ReadyAPI template.

To edit a global item template:

  1. Apply the changes made to the JRXML file and save them.

  2. Click in the Reporting window of ReadyAPI.

Styles and Images

ReadyAPI reports use the common styles.jrtx template. Use the following line to allow reports to use the template:

<template>"../../styles.jrtx"</template>

This file contains style definitions for various report elements, like headlines. You can edit the file to change the appearance of your reports.

As for logos and images, ReadyAPI stores them in the logos directory. You can refer to them by using the following code line:

<defaultValueExpression>"../../logos/header.png"</defaultValueExpression>

Custom Global Reports

If you want to customize the appearance of global reports without editing the default ones, you can use the Custom Global Reports feature.

  1. Create a local copy of the global reports directory.

  2. Customize the templates stored in the directory in a way you need.

  3. In ReadyAPI  Preferences, specify the path to the directory on the ReadyAPI tab:

    ReadyAPI: The ReadyAPI tab in the Preferences

    Click the image to enlarge it.

All the reports and templates in the directory you have selected will appear as global reports on the corresponding tabs of the Reporting window.

Project Level Report Storage

When you create custom project level reports, ReadyAPI stores them in the project file with the other project data. This allows you to redistribute the necessary data easily.

If you save your project as a composite project, ReadyAPI will store reports in the composite project’s directory with the structure similar to the global one. Then you can edit your reports by using external tools, as you do this when working with global reports. To reload such a report, click in the Reporting window.

Setting a Custom Report Library

You can find the path to the custom report library you saved in Preferences in the settings.xml file in your user directory.

If you have not specified the path to a custom report library, ReadyAPI will use the default report directory (<ReadyAPI Installation>/bin/reports).

When you run continuous integration, make sure you have prepared the settings.xml file and selected the correct location of the custom report library.

To specify the settings file to be used in Maven, add the following line to pom.xml:

<settingsFile>/workspace/core/settings.xml</settingsFile>

To set the location in Groovy, add the line below:

com.eviware.soapui.settings.setString( "Custom Report Library", "C:\\Work\\ ");

See Also

Configuring Report Templates

Highlight search results