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

Report Configuration

Report Bundle

Each model in the Squore Configuration can define a set of reports in <SQUORE_HOME>/Configuration/models/MyModel/Reports/Bundle.xml. Availability of these reports can be restricted based on a user's role in the project.

Here is an example configuration file for one report in Bundle.xml:

<?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>
        <Indicators ids="CPXT"/>
        <Measures ids="VG;TESTS;TESTS_FAILED"/>
        <Infos ids="BUILD_DESCRIPTION" />
        <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" />
        </Data>
        <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="../../software_analytics/Dashboards/issues_distribution_pie.xml" />
              <xi:include href="../../software_analytics/Dashboards/quality_kiviat.xml" />
            </Charts>
            <Tables>
              <xi:include href="../../software_analytics/Dashboards/table_complexity_module.xml" /> 
              <xi:include href="../../software_analytics/Dashboards/table_self_descriptiveness_module.xml" /> 
              <xi:include href="../../software_analytics/Dashboards/table_rule_compliance.xml" /> 
              <xi:include href="../../software_analytics/Dashboards/issue_by_severity_table.xml" /> 
              <xi:include href="../../Shared/Analysis/product_quality/code/line_counting/line_counting_table.xml" /> 
            </Tables>
            <Measures ids="VG;TESTS;TESTS_FAILED"/>
          </SubArtefacts>
        </SubData>
      </Report>
    </Role>
  </SquoreReport>
</Bundle>

A Bundle is composed of one or more SquoreReport elements. Each SquoreReport is associated to a JasperReports template file (a file with a .jrxml extension) that defines the formatting of the final document. 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 JasperReports XML template file.

The parameters in Bundle.xml define the data that is exported and fed to the selected template file. The template used throughout this manual supports all the documented features and is located in <SQUORE_HOME>/configuration/models/Shared/Reports/templates/template.jrxml.

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" ... 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 in the default report template, 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 which users can generate the report. 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 more Report elements, each one with a type attribute that specifies for which artefact type the report can be generated.

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<SquoreReport ... >
		<Role name="DEFAULT;PROJECT_MANAGER;DEVELOPER">
			<Report type="APPLICATION;FILE">
				...
			</Report>
		</Role>
	</SquoreReport>
</Bundle>

Including Charts

The Charts element lists the dashboard charts that will be printed in the report.

The Charts element has one or more chart sub-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. Note that you can choose to include the chart's comments in the report by setting the displayComments to true.

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<SquoreReport ... >
		<Role ... >
			<Report type="APPLICATION;FILE">
				<Charts displayComments="true">
					<xi:include href="../../Analysis/key_performance_indicator.xml"/>
					<xi:include href="../../Analysis/Code/ISO9126_Maintainability/MaintainabilityKiviat.xml"/>
				</Charts>
				...
			</Report>
		</Role>
	</SquoreReport>
</Bundle>

Including Tables

Tables lists the score card tables that will be included in the report.

The Tables element has one or more table sub-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.

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<SquoreReport ... >
		<Role ... >
			<Report ... >
				...
				<Tables>
					<xi:include href="../Dashboards/tables/line_counting.xml" />
					<xi:include href="../Dashboards/tables/dates.xml" />
				</Tables>
				...
			</Report>
		</Role>
	</SquoreReport>
</Bundle>

Including measures, indicators and textual information

Using the Measures , Indicators and Infos elements (new in 18.0) in your report definition, you can ouput any metric from your model in your report. Each element takes a ids attribute which contains a semicolon-separated list of IDs for the metrics you want to include. When including an indicator, the measure associated to the indicator is also automatically included.

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<SquoreReport ... >
		<Role ... >
			<Report ... >
				...
				<Measures ids="VG;TECH_DEBT" />
				<Indicators ids="CPXT" />
				<Infos ids="NAME;BUILD_TIME" />
				...
			</Report>
		</Role>
	</SquoreReport>
</Bundle>

Tip

Using these elements at Report level exports the metrics for the current artefact. You can also extract information for child artefacts by including the Measures , Indicators and Infos in a SubArtefacts section of the report, as described in the section called “Including Information from Child Artefacts”.

Including Action Items, Findings, Highlights and Artefacts

The report bundle allows inserting other data about the artefact using the Data element to add action items (element: DefectReports ), violations and practices (element: Findings ), relaxed findings (element: FindingOccurrences ), highlights (element: Highlights ) and artefacts (element: Artefacts ).

<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
	<SquoreReport ... >
		<Role ... >
			<Report ... >
				...
				<Data>
					<DefectReports id="WORST" />
					<Findings id="VIOLATIONS" />
					<Findings id="PRACTICES" type="ALL_PRACTICE" />
					<FindingOccurrences id="RELAXED_FINDINGS" relaxationState="RELAXED" />
					<Highlights  id="TOP_10_WORST_FILE" filterId="TOP_10_WORST_ARTEFACTS" />
					<Artefacts id="RELAXED_ARTEFACTS" relaxationState="RELAXED" />
					<Artefacts id="EXCLUDED_ARTEFACTS" relaxationState="EXCLUDED" />
				</Data>
			</Report>
		</Role>
	</SquoreReport>
</Bundle>

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”.

Action Items

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.

Findings

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

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.

Highlights

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)

Artefacts

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 charts and tables from child artefacts in reports by adding a SubData node in your report Bundle (new in 18.0). 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 Home | ToC Modifying The Report Template
Squore 18.0.18
© 2019 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.001.S.P.2013.000.10600.