Installation and Administration Getting Started Command Line Configuration Eclipse Plugin Reference Manual
Show on single page Show on multiple pages
Configuration Guide > Configuring Reports and Exports > Configuring Reports

Configuring Reports

Understanding Reports

Each model described in the Squore Configuration defines a set of reports in the bundle file under <SQUORE_HOME>/Configuration/models/MyModel/Reports/Bundle.xml. These depend on the Analysis Model chosen, and the role of the currently logged-in user. Every report is built upon two pieces: a Jasper Report template file, that defines how the report will be organised, and its content: a set of charts and tabular data.

Here is an example configuration file for a report:

<?xml version="1.0" encoding="UTF-8"?>
<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
  <SquoreReport id="DR_DASHBOARD_REPORT" templatePath="../../Shared/Reports/templates/template.jrxml" logo="header_image.png">
    <Role name="DEFAULT;PROJECT_MANAGER;DEVELOPER">
      <Report type="APPLICATION;FILE">
        <Charts displayComments="true">
          <xi:include href="../../Analysis/key_performance_indicator.xml"/>
          <xi:include href="../../Analysis/Code/ISO9126_Maintainability/MaintainabilityKiviat.xml"/>
          <xi:include href="../../Analysis/Code/TechnicalDebt/TechnicalDebtTrend.xml"/>
          <xi:include href="../../Analysis/Code/ArtefactRating/FunctionOptimisedPie.xml"/>
        </Charts>
        <Tables>
          <xi:include href="../Dashboards/tables/line_counting.xml" />
          <xi:include href="../Dashboards/tables/dates.xml" />
          <xi:include href="../Dashboards/tables/levels.xml" />
          <xi:include href="../Dashboards/tables/displayed.xml" />
          <xi:include href="../Dashboards/tables/ArtefactsTable.xml" />
        </Tables>
        <Data>
          <Findings id="VIOLATIONS" />
          <Findings id="PRACTICES" type="ALL_PRACTICE" />
          <FindingOccurrences id="RELAXED_FINDINGS" relaxationState="RELAXED" />
          <DefectReports id="WORST" />
          <Artefacts id="RELAXED_ARTEFACTS" relaxationState="RELAXED" />
          <Artefacts id="EXCLUDED_ARTEFACTS" relaxationState="EXCLUDED" />
          <Highlights  id="TOP_10_WORST_FILE" filterId="TOP_10_WORST_ARTEFACTS" artefactType="JAVA_FILE" />
        </Data>
      </Report>
    </Role>
  </SquoreReport>
</Bundle>

A Bundle is composed of one or more SquoreReport elements. Each SquoreReport is associated to a Jasper template file (a file with a .jrxml extension). The attributes allowed for the SquoreReport element are the following:

  • id is the unique identifier of the report being defined.

  • templatePath is the path to the Jasper Report XML template file.

The following sections will take you through restricting your template to certain roles or artefact types, and define which Charts , Tables and Data (action items and findings) are included in the report.

Template Files

Squore uses Jasper Reports for its reports templates. A jasper template is an XML file with .jrxml extension. There are three levels of templates used in a Squore report:

  • The main formatting template, that defines the two main areas (charts and data), which allows to set a specific document template.

  • A template for the Action Items and Findings lists.

  • A template for displaying each row of the Action Items and Findings list.

The following generic attributes are available in a report template:

  • $P{application}: The name of the project.

  • $P{artefactName}: The name of the artefact

  • $P{artefactType}: The type of the artefact

  • $P{author}: The name of the user generating the report

  • $P{model}: The analysis model used

  • $P{version}: The name of the version

  • $P{versionDate}: The creation date of the version

The following attributes specific to charts can also be used:

  • $P{CHART_ID}: a unique identifier for the chart

  • $P{CHART_URL_0} to $P{CHART_URL_X}: used to resolve the path to chart [0] to [X]

  • $P{CHART_NAME_0} to $P{CHART_NAME_X}: used to resolve the name of chart [0] to [X]

Note: iReport is the official visual building tool edited by JasperSoft, the company behind Jasper Reports. Since the template file is written in XML, a simple text editor like Notepad++ can be used, for advanced users at least.

Defining Your Own Logo

You can override the default header image in the report file by adding a logo attribute in Bundle.xml, as shown below:

<SquoreReport id="DR_DASHBOARD_REPORT" templatePath="../../Shared/Reports/templates/template.jrxml" logo="../../Shared/Reports/templates/header_logo.png">

The path to the header logo file is relative to the location of Bundle.xml.

Tip

For best results, use a header image with a ratio of 408 by 65 points.

Defining Roles and Artefact Types

In each SquoreReport element, one or more Role elements can be defined to specify what data is needed for this each of user. The only required attribute for the Role tag is name , with a comma-separated list of roles.

Tip

If you want your template to be available to any logged-in user, specify the role name DEFAULT.

Each role contains one or mode Report elements, each one with a type attribute that contains the target artefact type for the report template.

Including Charts

Charts describes the chart elements that the report will display, according to the template file definition.

The Charts element has one or more chart elements. The charts available for reports are the same as the charts used for dashboards. See the section called “The Charts Area” for a complete list of available charts. The ID attribute is needed to load generated images in templates. Note that you can choose to include the chart's comments in the report by setting the displayComments to true.

Including Tables

Tables describes the chart elements that the report will display, according to the template file definition.

The Tables element has one or more table elements. You can use the tables created for the dashboard or create a table that is not included in any dashboard. Refer to the section called “Scorecard Tables” for a complete reference about tables.

Including Action Items, Findings, Highlights and Artefacts

The Data element describes the action items (element: DefectReports ), practices (element: Findings ), relaxed findings (element: FindingOccurrences ), highlights (element: Highlights ) and artefacts (element: Artefacts ) that will be included in the report, according to the template file definition.

The attributes allowed for the DefectReports element are the following:

  • id (mandatory) is a unique identifier for the list of action items.

  • withReasons (optional, default: true) defines whether Action Items are reported with their reasons (true) or not (false). Note that including reasons has an impact on performance when generating the report.

The attributes allowed for the Findings element are the following:

  • id (mandatory) is a unique identifier for the list of findings.

  • type (optional, default value: NO_FILTER) is the filter to apply to the findings list. The following values are accepted, so you can generate the same lists as in the web interface:

    • NO_FILTER

    • LOST_PRACTICE

    • ACQUIRED_PRACTICE

    • DETERIORATED_PRACTICE

    • IMPROVED_PRACTICE

    • ALL_PRACTICE

Tip

Action Items and Findings are sorted in the same way as in the user interface, which you can customise for each model by following the procedure described in the section called “Sort Order for Action Items and Findings”.

The attributes allowed for the FindingOccurrences element are the following:

  • id (mandatory) is a unique identifier for the list of relaxed findings occurrences.

  • relaxationState (mandatory) is the filter to apply to the findings occurrences list. The following values are accepted, so you can generate the same lists as in the web interface:

    • RELAXED

    • RELAXED_DEROGATION

    • RELAXED_LEGACY

    • RELAXED_FALSE_POSITIVE

    Tip

    Findings occurrences are sorted by artefact path.

The attributes allowed for the Highlights element are the following:

  • id (mandatory) is a unique identifier for the highlight category.

  • filterId (mandatory) is the id of the highlight category to include in your report (as defined in the Highlights bundle in your model)

  • artefactType (mandatory) is the type of artefact to display highlights for.

    Warning

    The artefactType attribute only accepts real artefact types, not aliases.

The attributes allowed for the Artefacts element are the following:

  • id (mandatory) is a unique identifier for the list of artefacts.

  • relaxationState (mandatory) defines the relaxation status of the artefacts to include in the list. The following values are accepted:

    • RELAXED

    • EXCLUDED

Including Information from Child Artefacts

You can include information from child artefacts in reports by adding a SubData node in your report Bundle (new in 17.1). This allows you for example to generate a report at project level that includes information about every complex function in your project, as shown below:

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
  <SquoreReport id="SubDataSample" template="...">
    <Role name="DEFAULT">
      <Report type="APPLICATION">
        <Charts>
        ...
        </Charts>
        <SubData>
          <SubArtefacts id="COMPLEX_MODULES" artefactTypes="MODULES" orderByMeasure="VG" inverted="true">
            <Where measureId="CPXT" dataBounds="[0.5;["/>
            <Charts>
              <xi:include href="../../Shared/data_provider/squan_sources/dashboard/control_flow_graph.xml" />
              <xi:include href="../Dashboards/issues_distribution_pie.xml" />
              <xi:include href="../Dashboards/quality_kiviat.xml" />
            </Charts>
            <Tables>
              <xi:include href="../Dashboards/table_complexity_module.xml" /> 
              <xi:include href="../Dashboards/table_self_descriptiveness_module.xml" /> 
              <xi:include href="../Dashboards/table_rule_compliance.xml" /> 
              <xi:include href="../Dashboards/issue_by_severity_table.xml" /> 
              <xi:include href="../../Shared/Analysis/product_quality/code/line_counting/line_counting_table.xml" /> 
            </Tables>
          </SubArtefacts>
        </SubData>
      </Report>
    </Role>
  </SquoreReport>
</Bundle>

The SubData element accepts one or more SubArtefacts elements with the following specification:

<SubData>
  <SubArtefacts id="CONTROL_GRAPH" 
      artefactTypes="FUNCTION" | [linkType="<linkId>"]
      [onlyDirectChildren="false"]
      [orderByMeasure="LC"]
      [inverted="false"]
      [artefactsLimit=""]>
    <Where measureId="VG" dataBounds="[10;["|value="10" />
    <Charts>
      <xi:include href="../Dashboards/charts/control_graph.xml" />
    </Charts>
    <Tables>
      <xi:include href="../Dashboards/tables/table.xml" />
    </Tables>
  </SubArtefacts>
</SubData>
</Bundle>

  • id (mandatory) is an ID to identify the list of child artefacts internally in the report

  • artefactTypes or linkType (mandatory) identify the type of target artefacts to include in the report. For more information about links, refer to the section called “Artefact Links”.

  • onlyDirectChildren (optional, default: false) includes artefacts that are direct children of the current artefact when set to true, or all descendants of the current artefact when set to false.

  • orderByMeasure (optional, alphabetical if omitted) allows sorting the list of artefacts according to the value of the specified measure ID.

  • inverted (optional, default: false) allows reversing the sort order defined by the orderByMeasure attribute.

  • artefactsLimit (optional, default: none) allows limiting the number of child artefacts to include.

The list of sub-artefacts can be further refined with a Where element that specifies a value or bounds for a metric, as illustrated in the two examples below.

Including functions with failing tests: 

<SubArtefacts id="WITH_FAILED_TESTS" 
  artefactTypes="FUNCTION">
	<Where measureId="TEST_FAILURES" dataBounds="[1;[" />
</SubArtefacts>

Including functions no test coverage: 

<SubArtefacts id="FULLY_COVERED" 
  artefactTypes="FUNCTION">
	<Where measureId="TEST_COVERAGE" value="0" />
</SubArtefacts>
Prev Up Next
Chapter 9. Configuring Reports and Exports Home | ToC Configuring Exports
Squore 17.1.2
© 2017 Squoring Technologies All rights reserved. This material may not be reproduced, displayed, modified or distributed without the express prior written permission of the copyright holder. Squore is protected by an Interdeposit Certification registered with Agence pour la Protection des Programmes under the Inter Deposit Digital Number IDDN.FR.001.390035.0005.000.S.P.2013.000.10600.