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

This section will take you through the description of the report format, help you adjust your template to certain roles or artefact types, and define which charts, tables, highlights and other data can be included in a Squore report.

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>
        <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>
        <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>
          </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 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" artefactType="JAVA_FILE" />
					<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)

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

    Warning

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

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

Modifying The Report Template

It is possible to modify the look and feel of the default report. The report functionality uses a JasperReports template, an XML file with a .jrxml extension that can be edited in Jaspersoft Studio or in a text editor. The main template file (<SQUORE_HOME>/configuration/models/Shared/Reports/templates/template.jrxml) includes most of the other files in the templates folder as subreports and allows the data sent from Squore to be turned into the final report document.

Tip

For any help with JasperReports, consult the forums at https://community.jaspersoft.com/.

The template is split into the following sections:

  • Background

  • Title

  • PageHeader

  • ColumnHeader

  • Details (the body of the report where sub-reports are inserted)

  • ColumnFooter

  • PageFooter

  • LastPageFooter

  • Summary

Squore provides values for the following variables in the template automatically:

  • $P{REPORT_DATA_SOURCE}: The full contents of the intermediate report file

  • $P{appName}: Squore

  • $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{companyName}: Squoring

  • $P{companyUrl}: https://www.squoring.com/

  • $P{logo}: The path to the logo to use in the header

  • $P{model}: The analysis model used

  • $P{poweredBy}: The path to the powered by Squore logo

  • $P{reportDate}: The date at which the report was generated

  • $P{restoreUrl}: The a URL to open the project's dashboard in Squore

  • $P{supportUrl}: https://support.squoring.com/

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

  • $P{versionDate}: The analysis date

For each chart from the dashboard that you include in a report, the following parameters are also available:

  • $P{CHART_ID}: a unique identifier for the chart based on the chart's original ID

  • $P{CHART_URL_0} to $P{CHART_URL_X}: used to resolve the path to chart [0] to [X] (based on the chart's position in Bundle.xml

  • $P{CHART_NAME_0} to $P{CHART_NAME_X}: used to resolve the name of chart [0] to [X] (based on the chart's position in Bundle.xml

Tip

Up to 16 charts (and their comment threads) can be included without modifying the default template.

Subreports are activated based on the presence of an XML element in the data sent by Squore. The following lines checks for the presence of a highlights category in the exported data with the following dataSourceExpression to activate the highlights.jrxml subreport:

<detail>
...
	<subreport>
		...
		<dataSourceExpression><![CDATA[((net.sf.jasperreports.engine.data.JRXmlDataSource)$P{REPORT_DATA_SOURCE}).subDataSource("//Highlights")]]></dataSourceExpression>
		<subreportExpression><![CDATA["/../../../Shared/Reports/templates/highlights.jasper"]]></subreportExpression>
	</subreport>
</detail>

The following is a full sample of the data sent by Squore and fed into the report template. Note that this data is only created in memory and not saved to disk when generating a report in Squore. This sample is provided to help you understand how the JasperReports template locates data to extract and format in the final report document.

<?xml version="1.0" encoding="UTF-8"?>
<ReportModelResources appName="Squore"
                      application="Earth"
                      artefactName="Earth"
                      artefactType="Application"
                      author="demo"
                      companyName="Squoring Technologies"
                      companyUrl="http://www.squoring.com/"
                      logo="/path/to/header.image"
                      model="software_analytics"
                      poweredBy="/path/to/poweredBy.image"
                      reportDate="2018.02.27 17:55:54 CET"
                      restoreUrl="${artefactURL}?tabName=default"
                      supportUrl="http://support.squoring.com/"
                      version="V6"
                      versionDate="2017.09.05 01:00:00 CEST">
	<Charts>
		<Chart id="INDICATOR"
		       name="Key Performance Indicator"
		       path="/path/to/chart.image"/>
		<Chart ... />
	</Charts>
	<Tables>
		<Table id="COMPLEXITY_DENSITY"
		       name="Complexity">
			<Line data="10,8 %"
			      evolution="/path/to/trend.image"
			      image="/path/to/level.image"
			      isIcon="true|false"
			      isOnlyText="true|false"
			      name="Ratio of complex modules"/>
			<Line ... />
		</Table>
		<Table ... >
		...
		</Table>
	</Tables>
	<Data>
		<Findings id="VIOLATIONS"
		          total="247"
		          totalDelta="104"
		          type="Findings"
		          url="${artefactURL}?tabName=findings">
			<FindingsDefinition CHARACTERISTIC="Maintainability"
			                    SCALE_NATURE="Non Conformity"
			                    SCALE_REMEDIATION="High"
			                    SCALE_SEVERITY="Critical"
			                    <!-- scales and characteristics according to your analysis model -->
			                    delta="+1"
			                    desc="Functions shall not called themselves either directly or indirectly (see [MISRA-C:2004]: RULE 16.2)."
			                    justif="My relaxation comment"
			                    measureId="R_NORECURSION"
			                    mnemo="NORECURSION"
			                    name="Recursion are not allowed"
			                    occ="1"
			                    toolName="Squan Sources"/>
			<FindingsDefinition ... />
		</Findings>
		<Findings ... >
		...
		</Findings>
		<FindingOccurrences id="FINDINGS"
		                    relaxationState="RELAXED">
			<Artefact name="main(int,char*[])"
			          path="apps/master.c"
			          type="C Function"
			          url="${artefactURL}?tabName=FINDINGS">
				<Finding count="1"
				         id="2064416"
				         line="Ligne: 95"
				         new="true"
				         tool="Squan Sources">
					<Rule externalId="R_COMPOUND"
					      mnemonic="COMPOUND"
					      name="Missing compound statement"/>
					<Relaxation date="2018-01-31T10:08:04"
					            status="Derogation (Imported)"
					            user="demo">keeping some conciseness by avoiding using compound {}</Relaxation>
				</Finding>
				<Finding ... >
				...
				</Finding>
			</Artefact>
		</FindingOccurrences>
		<DefectReports id="AIS">
			<DefectReportsDefinition SCALE_AI_TYPE="Non Regression"
			                         SCALE_PRIORITY="High"
			                         <!-- scales according to your analysis model -->
			                         artefactName="hi_scores_disp(int)"
			                         artefactPath="apps/score.c"
			                         desc="The object hi_scores_disp(int) has a higher number of 'Blocker' or 'Critical' rules violated since the previous version."
			                         id="${ActionItemId}"
			                         measureId="${ActionItemId}"
			                         name="More 'Blocker' or 'Critical' rules violated"
			                         scope="C Function"
			                         since="V6"
			                         status="Open"
			                         url="${artefactURL}?tabName=action-items">
				<Reason desc="Code Status reveals that development is in progress (=1).&#10;"/>
				<Reason ... />
			</DefectReportsDefinition>
			<DefectReportsDefinition ... />
		</DefectReports>
		<Highlights col0="New Code Stability Index"
		            col1="Line Count"
		            filterId="TOP_10_MOST_CHANGED_ARTEFACTS"
		            id="MOST_CHANGED"
		            nbColumns="2"
		            title="Top 10 most changed artefacts">
			<TopArtefact artefactName="print_instructions_fr()"
			             artefactPath="core/write.c"
			             col0="12,5 %"
			             col1="72"
			             rating="/path/to/level.image"
			             url="${artefactURL}?tabName=highlights"/>
			<TopArtefact ... />
		</Highlights>
		<Artefacts id="RELAXED_ARTEFACT"
                   relaxationState="RELAXED">
			<Artefact name="machine.c"
                      path="apps"
                      relaxationComment="Why I relaxed this..."
                      relaxationDate="2018.02.28 16:11:29 CET"
                      relaxationUser="demo"
                      type="C File"/>
			<Artefact ... />
		</Artefacts>
	</Data>
	<SubData>
		<SubArtefacts id="COMPLEX_MODULES">
			<SubArtefact name="machine_plays()"
			             path="apps/machine.c"
			             type="C Function"
			             url="${artefactURL}">
				<!-- Each SubArtefact contains Charts and Tables sections similar to the ones at ReportModelResources level -->
				<Charts>
					<Chart ... />
				</Charts>
				<Tables>
					<Table ... />
				</Tables>
			</SubArtefact>
		</SubArtefacts>
	</SubData>
</ReportModelResources>

Note

${artefactURL} is a direct link to open the specified Explorer tab in Squore for the artefact mentioned in the report.

Prev Up Next
Chapter 9. Configuring Reports and Exports Home | ToC Configuring Exports
Squore 17.1.11
© 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.000.S.P.2013.000.10600.