Getting Started Guide

This edition of the Getting Started Guide was released by Vector Informatik GmbH.

It is part of the user documentation of the Squore software product edited and distributed by Vector Informatik GmbH.

For information on how to use and configure Squore, the full suite of manuals includes:

No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner, Vector Informatik GmbH. Vector Informatik GmbH reserves the right to revise this publication and to make changes from time to time without obligation to notify authorised users of such changes. Consult Vector Informatik GmbH to determine whether any such changes have been made. The terms and conditions governing the licensing of Vector Informatik GmbH software consist solely of those set forth in the written contracts between Vector Informatik GmbH and its customers. All third-party products are trademarks or registered trademarks of their respective companies.

Vector Informatik GmbH makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Vector Informatik GmbH shall not be liable for errors contained herein nor for incidental or consequential damages in connection with the furnishing, performance or use of this material.

This edition of the Getting Started Guide applies to Squore 19.1.18 and to all subsequent releases and modifications until otherwise indicated in new editions.

Approval of this version of the document and any further updates are the responsibility of Vector Informatik GmbH.

If the information provided in this manual is erroneous or inaccurate, or if you encounter problems during your installation, contact Vector Informatik GmbH Product Support: https://support.squoring.com/

You will need a valid customer account to submit a support request. You can create an account on the support website if you do not have one already.

For any communication:

The version of this manual included in your Squore installation may have been updated. If you would like to check for updated user guides, consult the Vector Informatik GmbH documentation site to consult or download the latest Squore manuals at https://support.squoring.com/documentation/latest. Manuals are constantly updated and published as soon as they are available.

Squore ships with a collection of sample projects that we will refer to throughout this guide. Each project consists of one or several versions of the source code of an application. The code can be found in Squore Server and Squore CLI in the folder <SQUORE_HOME>/samples. If you do not have access to the sample projects, contact your Squore administrator to obtain a copy of the code.

Squore ships with a database that contains two sample users that you can use to familiarise yourself with all the functionality available:

You can use these two default users, but we recommend that you change their passwords after your first connection. The privileges and permissions assigned to these default users can be modified as needed. You can familiarise yourself with Squore permissions and privileges by referring to Understanding Profiles and Roles.

You may choose to read this manual from beginning to end or jump straight to a specific topic. Logging in as the demo user gives you access to a Tools menu that allows reproducing the examples shown in this manual. Click Tools > Build Demo Projects and select the Software Analytics - C samples to get started.

If at any moment you have doubts about how a feature works, Squore offers help in HTML and PDF formats. A Wiki and support site is also available.

Before you start working with Squore, it is essential to understand how access management works. The various permissions and privileges that can be assigned to Squore users are grouped in profiles and roles respectively. A set of default roles and profiles is available when you first start the server. You can edit them, or create more as needed.

Use this simple trick to remember the difference between a profile and a role:

A Squore user with the Administrator profile can manage users, their roles and profiles. A Squore user with the Project Manager role for a project can create a new version of this project or give access to another user to this project’s analysis results.

Your Squore installation runs on http://localhost:8180/SQuORE_Server by default. By accessing this page in your browser, you will be redirected to the Squore login page , as shown below:

Type in a username and a password and click Login to log in.

To begin using Squore, log in as the demo user with demo as username and password on the login page. Click the Login button and wait for the Home page to open.

From the Home page, you can automatically return to the last projects or favourite artefacts that you had opened in the Explorer before logging out. A timeline of executed builds and news mechanism is available as well. You can also get links to the help and other features available for your account.

As the demo user, you are an advanced user of Squore and have access to the following functionality from the toolbar :

You can log out of Squore by clicking your user name in the menu bar and selecting the Logout option. Note that if you close your browser without logging out, your session will automatically time out after two hours.

Creating a project in Squore is as easy as following a wizard that will prompt you for information about the source material to analyse, and the external Data Providers to add to the analysis results.

The example below assumes that the source code for the sample project used is available on a network share. The path to the source files to analyse is relative to the server.

In order to create a project for the sample application Neptune2, follow these steps:

When the project analysis completes, Squore shows you the list of projects. Neptune2 appears in the list, together with information about the current version and its computed rating:

To consult the results of the analysis, click on the project name to view the Squore Dashboard. More information on how to read the Dashboard is available in Where Are My Analysis Results?.

In the last column you can see the status of the last executed task. If the status is at Successful then it’s creation was completed successfully.

By clicking on the last task status you are redirected to the Project’s Tasks page :

In this page you have access to the list of all the tasks executed on this project, as well as their logs : version builds, reapply model, cloning, etc…​

Adding a version to an already-existing project is a simple procedure that is carried out from the Projects page.

Follow these steps to create version 2 of your project:

This section covers an essential workflow feature of Squore: baselining. While it is possible to keep every version of a project created in Squore, you may want to permanently keep analysis results only for particular milestones and work with an always updating draft version.

You can decide whether a version is a draft or a baseline when you create it, or after the analysis is finished.

There are three types of changes you can make to Squore projects :

Project attributes are always editable when creating a new version of a project, except for the name of the project.

The location of the source code can always be modified. When editing a project, you can also add more source locations as needed, following the steps described in Can I Create Projects with Sources From Multiple Locations?.

Whether you can edit the settings used in the Data Providers for the project depends on their ability to support edits. This ability is defined by a Squore administrator via the configuration of the Squore wizards. For more information, refer to the Squore Configuration Guide.

Instead of creating a project from the Squore web interface, you can create a project directly from the command line using Squore CLI. Squore CLI is a client for Squore that enables you to create and analyse projects locally and send the results to Squore Server. Alternatively, you can use Squore CLI to instruct Squore Server to carry out the analysis.

If you have installed Squore CLI on your computer, you can call it using Java, passing the parameters you would have passed in the web interface to create projects. The following is an example of the command line you can use to create a project using Squore CLI on Windows:

The example above shows how to specify commands, parameters and project options to Squore CLI. This would create a project named Mars2 in version 1.0, analysing source code located in \server\share\samples\c\Mars2\V3.2.6 with the Data Provider SQuORE (the internal name for Squan Sources).

You can find more information about using Squore CLI in the Command Line Interface manual, which explains how to install the client and create projects.

If you use a Continuous Integration tool like Jenkins or CruiseControl, you can add Squore to your build process and analyse projects every time your code is compiled. This requires the installation of Squore CLI on the continuous integration server, and is therefore described in greater details in the Command Line Interface Manual.

The source code analysed by Squore does not have to be located on the same machine as Squore Server or Squore CLI. When you create a project, you get the option to choose from a range of Repository Connectors to pull source code from:

Each option requires different parameters, which can be specified from the project wizard, or via the command line. For more information, refer to Repository Connectors.

Squore provides support for analysing projects whose sources are spread over several locations or version control systems. If your source code resides in /products/common and /projects/myproject, you can specify these two locations in the Squore project wizard by clicking the Add Repository button. Similarly, if some of your code is managed by a SVN repository and the rest is handled by a Git server, you can configure both locations as part of the same project, as shown below:

Now that you have created a project, you are ready to start reviewing the analysis results in the main section of Squore, the Explorer, which consists of a set of trees for browsing through project artefacts and various dashboards to display the information associated with these artefacts.

Common icons are used throughout the explorer to indicate the rating of a component and its evolution compared to the previous version. The image below shows the meaning of the different icons used:

By default, projects are sorted out according to their analysis model in the Project Portfolios.

But it is possible to create groups and subgroups in order to organise the project list.

To do so, click on "Manage" for a given project and in the "Project Properties" tab, fill in the "Group" field :

It is possible to create subgroups as well, just type in the full path to your group : "myGroup/mySubgroup".

To remove a project from a group just delete the content of the "Group" field. If a group becomes empty after removing its last project, it will be automatically removed from the Project Portfolios.

This feature enables you to apply a new model, or an updated one, on an already existing project. This is done by using the project data in the database, without executing Repository Connectors and Data Providers.

Go to the "Projects" page, in the sandwich menu from the desired project, click "Reapply Model":

In the Reapply Model menu page, choose the desired option:

In case of a duplication the following options are available :

This feature enables you to branch a project while keeping all its version build information (relaxation states, milestones, etc…​). First version of the new branched project is the one the clone has been created from.

Go to the "Projects" page, click "Manage" on the desired project, in the "Versions" tab a new "Clone" column is available:

In the Clone project menu page, setup your project options:

In contexts where your projects reuse code from other projects that you also analyse in Squore, you can create a meta-project that will show the analysis results from the various software bricks in a single project.

When you select a wizard that allows to create a meta-project, you do not have to specify any locations for source files or any data providers to run. Instead, you are presented with a project picker that allows you to tell Squore which sub-projects compose your meta-project. In the example below, we will create a project that uses Earth (V2), Mars (v3.2.6), and Saturn (Prel) as its parts. You can choose any baseline version of any project you have access to in Squore as a component of your meta-project.

When the analysis finishes, the meta-project is listed along with the other projects in the Project Portfolios. You can expand the Artefact Tree for your meta-project to browse the artefacts of the three sub-projects that are part of your meta-project, and consult all their Action Items, Findings and Highlights.

After completing the analysis of a new version of your project, you will probably want to investigate how it has evolved, more specifically for which artefacts the quality has decreased. Let’s look at the history of the Earth Project (which should be available if your Squore administrator has created the sample projects shipped with the Squore installation) to find out how to spot the worst-scored components in your project.

Log into Squore as the demo user using demo/demo and observe the evolution of the Earth project in the Project Portfolios:

The trend arrows before the version names in the Project Portfolios indicate that the overall rating has recently deteriorated (More information about the quality indicator icons is available in Where Are My Analysis Results?). If you take a closer look at the Technical Debt Trend chart, you can notice that the technical debt is growing for this project.

Since the trend accelerated in V6, we will focus on this version. Let’s click V6 in the tree and start our evaluation by looking at the score card, which rates Earth at E.

Let’s also look at the Code Quality dashboard, which offers more insight into coding violations. Select Code Quality in the Dashboard drop-down list:

Some values under Artefact Counting, Line Counting and Issue Distribution explain the lower score: the application contains more files and functions, more lines of code, less comments and more rules violations .

By now you probably want to find out which components in your project are responsible for increasing the technical debt the application in this version. If you want the Artefact Tree to reflect this information, you can change the sort order to show the worst scores first by clicking on the sort icon () and selecting LEVEL > Worst first to display artefacts from worst-scored to best-scored.

For some projects, you may want to collect artefacts so you can review them later. Squore enables you to build a Review Set, a list containing artefacts that you want to keep track of. Let’s log in as the demo user to review all the new artefacts added to a project, in order to evaluate their level of quality.

Isolating the new artefacts can be done in three steps:

You should see the following artefacts in the Artefact Tree:

Squore makes it easy for you to keep track of these artefacts. Click on the icon above the Artefact Tree and select Add Filtered Results to Review Set.

You can now clear your filter, the artefacts you want to review are stored in your Review Set. Click the Review Set tab in the left pane of the explorer to find the items you just saved.

At any moment, the artefact currently selected in the Artefact Tree can be sent to the Review Set as well. Simply display the context menu for an artefact and click Add to Review Set to add it to the Review Set. Clicking an item in the Review Set pane has the same effect as clicking it in the Artefact Tree: the dashboard refreshes to show the information for that artefact. You can use the left and right arrows in the Review Set pane to go to the previous and next artefact in the list.

If you want to know more about what actions you can take after reviewing artefacts, refer to Managing Your To-Do List With Squore and Communicating With Squore.

Squore provides tools to understand, verify and enhance your model under the Models menu.

* The Analysis Model Editor, which allows modifying the model’s ruleset

Users whose profile grants the "View Models" permission have access to the first two tools.

Users whose profile grants the "Modify Models" permission have access to the last two tools.

Project Managers may be interested in monitoring several projects as a whole. Squore provides a special dashboard view which compounds information about several projects into an Model/Group Dashboard, which can help you prioritise projects according to their current status.

In order to view the Model/Group Dashboard:

The dashboard refreshes to show the compounded information for all projects analysed with this model using charts and a summary table of the main indicators, the rating and the trend of each project.

In the quadrants, each project is represented as a bubble . Two indicators define the horizontal and vertical position of the bubble along the axes, while a third indicator defines the bubble size. Let’s see how you should prioritise maintenance work on your project portfolio for the sample projects. Click on the Complexity Volume Vs Cloning quadrant to view the full version:

In this chart, projects with a high code cloning ratio appear higher, while more complex projects appear more to the right. The size of each bubble indicates the size of the project in terms of source lines of code. Therefore, it may be easier to improve the quality of a project with more cloning but less complexity like Pluto (dark green) than a project with less cloning but more complexity (Mars, in red) As a project manager, you know that as a general rule you need to focus on moving projects towards the bottom-left corner of the chart for a healthy portfolio of projects.

Below the quadrants, Squore displays tables with the values used in the charts so you can refine the information read in the charts. All the information shown in the analysis model dashboard can be configured by a Squore administrator. Refer to the Squore Configuration Guide for more information.

If you need more background information about the measures and indicators used in the charts and tables in the dashboard, the Indicators, Measures and Findings tabs can provide more details about the statistics recorded for the current artefact. Note that these tabs are not displayed by default. If you want to show them in Squore, click the Explorer Settings menu and then Manage Tabs to display the Tab Manager to enable these tabs, as shown below:

If you want to understand the scale used for a particular indicator, to see for example how close you are to moving up the rating scale, you can check the scale used for this indicator in the Indicators tab of the dashboard.

Log in and search for the artefact DB5_backup.c in the Neptune project, where the indicator Maintainability Non-Conformity is rated E. While this tells you about the current rating for this artefact, this does not tell you how to improve it. In order to learn how to improve this score, let’s first take a look at the scale used for this indicator. Click the Indicators tab of the Explorer. The table of indicators opens, as shown below:

The table lists all the indicators available for the artefact over several pages. The scale and levels available for an indicator can be viewed in a tooltip by placing your mouse over a rating. Using the filter above the "name" column, look for the entry named Maintainability Non-Conformity, then click its value in the rating column. The scale for the indicator indicates that the artefact is rated E because the value of the indicator is 472.09. In order to improve the score, the value would need to decrease to under 250 to be rated D, as shown below:

To understand how to improve the rating , you need to know how the indicator’s value is computed. Clicking the indicator name in the Indicator Tree shows the following explanation in the indicator popup:

The computation , i.e. the formula used to calculate the rating is 1000*(WEIGHTED_NC_MAI/ELOC), meaning that the indicator computes a ratio of broken Maintainability rules. To find out what these rules are, click the Findings tab.

Squore displays all the findings for a particular artefact in a table in the Findings tab. Next to the finding’s label is a number of occurrences followed by a colour-coded delta value (red for more occurrences, green for less) compared to a previous analysis.

If you want to find out which rules are taken into account by the Maintainability Non-Conformity indicator, expand the filter to show the advanced filtering options. Highlight Maintainability in the ISO Characteristics filter to see the corresponding rules, as shown in the picture below:

The rules BWGOTO, STDIO, NOGOTO, RETURN and COMPOUNDIF are the rules that should be fixed in order to improve the Maintainability rating of DB5_backup.c.

You can expand the BWGOTO rule to show each occurrence of the rule being broken, and also review the location in the source code that breaks the rule, as shown below:

Finally, clicking on the line number for each rule-breaking occurrence opens the source code viewer in full screen so you can carry out your code review:

The source code viewer allows comparing the code against another version of the code. Select a version name in the Compare with: list to switch to diff mode, as shown below:

Analysing findings helps to improve the quality of the code in your project. There is much more you can do with the Findings tab by using the built-in filters to detect regressions and improvements:

You can click the Export button at the bottom of the list of findings, to generate a CSV file of the findings displayed in the user interface. The contents of the file reflect your current filter selections on the page. The following is a CSV export for the Findings of the Earth project, which you can download in full here.

Squore provides a violation relaxation mechanism that is triggered via comments found in the source code itself. There are two pre-requisites for relaxation to work:

Squore interprets comments formatted in one of these three ways:

<keys> can be one of the following:

The relaxed violations are still shown in the Findings page after the next analysis, but they appear under the rule R_RELAX, showing the mnemonic of the relaxed violation and the justification text.

As an example, this is how you would relax the violations of the rule Backward goto for Maintainability Non-Conformity in Neptune:

On the Findings page, the violation now visible if you select to display derogations in the filter:

After you have relaxed findings, Squore will check for source code changes around the location of the relaxation and will alert you if a relaxed finding should be re-examined by flagging it as suspicious. The suspicious state is a flag that is automatically added to relaxed finding and does not affect their relaxation state.

To see suspicious findings in action, we will relax the Missing Break at line 40 in audio/a_bus.c in the project called Saturn. Click the Current node in the portfolio, find the artefact in the project and enter a relaxation comment for the Missing Break at line 40:

When saving the finding relaxation, the source code viewer changes the marker for the finding to a grey warning sign to indicate that the violation was relaxed.

The next version of the file included in the library does not seem to include any fix for the specific violation, but instead uses a renamed variable in the artefact where the finding is:

Since the relaxed violation is still there, analysing this code triggers the suspicious finding warning in the web interface to alert you in case you need to revise the finding status now that the code has changed. Click the banner to reveal the suspicious finding, as shown below:

Note that the violation is still relaxed with the Legacy System status, but the Suspicious flag was attached to it. Click the source code icon next to the finding to view the source code in this new version. The marker for the finding is now purple, which is the colour used to highlight suspicious findings:

After reviewing the finding, you can remove the suspicious flag by opening the Change Status…​ dialog again and change the relaxation status or comment, or just remove the suspicious flag:

When you save your changes, the suspicious warning banner disappears, as there are no more suspicious findings to review in the project.

In this section, you will learn how to relax or exclude entire artefacts directly from the Artefact Tree instead of relaxing findings. Relaxing artefacts ensures that their metrics do not impact the rating of the project, however, data providers will still generate findings for the relaxed artefacts. Excluding artefacts hides them from the project, and findings and action items are no longer created for them.

This example uses the Mars project from the samples folder. Ensure that you are a Project Manager in this project, or are part of a role with the View Drafts of Projects and Modify Artefacts privileges before you begin.

Expand the Project Portfolios to show all the versions of Mars. There are two versions in the tree (from bottom to top):

Click on Mars > V3.2.7 to see the artefacts in the Mars project as created by the demo script:

To relax an artefact and therefore tell Squore that its rating should not impact the rest of the project, display the context menu for this artefact. The relaxation options appear at the bottom of the menu if they are available for your model, as shown below:

There are two actions that can be taken to relax an artefact:

Clicking Relax…​ or Exclude…​ brings up a pop-up menu where you can type a comment to explain the reason for the relaxation. Let’s relax mars_common.c so it stops impacting the overall project rating. Click the Relax…​ option in the menu to display the relaxation popup and enter a relaxation comment:

Click Confirm to save your comment, and notice how the Artefact Tree is updated to reflect the finding’s status:

Other users can review the justification for the relaxation by clicking on the Log…​ item in the artefact context menu:

If you keep relaxing artefacts in this project and create a new draft build of the project, then you will end up seeing changes in the overall rating,

If you notice that a violation in the code or an issue in the project was not detected during an analysis, you can decide to create a finding manually from the Artefact Tree.

In this example, we add a finding to notify of a documentation issue in the Neptune project. Click on the Current version of the project, and display the context menu for the artefact where you consider that the documentation is wrong.

When you click the Add a finding…​ option, a dialog appears and lets you select the type of finding to add, as well as a description of the issue:

Click Add to save the finding. You can check that it was added successfully in the Findings tab of the Explorer:

Like regular findings, your finding also displays in the source code viewer, as shown below:

It is also possible to add a manual finding directly from the source code view. To do so, click on the code line number where you want to add the manual finding. The finding adding form is displayed. Firstly, you have to select the finding rule among the manual rules, then you have to fill the new finding description. Both fields are required. Finally, confirm the new manual finding addition thanks to the "Add a finding" button.

Squore lets you view and edit project attributes in a dedicated form tab of the explorer. You can therefore design your wizards to present checklists to a user. They can fill in the values manually after an analysis and they will be taken into account when creating the next version of the project. There are permissions associated with editing form values, so you can make them read-only for guests but read-write for project managers. The attributes displayed on the Forms tab depend on the type of the current artefact, and values are saved individually for each artefact in the project.

When you click a project in the Project Portfolios and view the Forms tab of the Explorer, all the project attributes available at application level are displayed, as shown below:

The values displayed correspond to the application attributes passed when the last version of Neptune was created. Users with the whose role grants them the Modify Artefacts Attributes privilege can edit the current value of the form for any artefact, and the value will be taken into account during the next analysis.

When you modify the values in the form, you can use the comment field to justify the change you made. A history of the modifications can be displayed by expanding the attribute field, as shown below

If you have doubts about the measures computed by Squore and their meaning, they can usually be solved by looking at the Measures tab of the Explorer. The content of the measures tab is also always refreshed to reflect the data for the current artefact, and is organised in a table displaying the measure’s mnemonic, full name, description and value for the current selection, as shown in the picture below.

Measures can be sorted by mnemonic, name, description or value, and the sorting value is remembered when selecting another artefact in the tree so you can easily compare values.

The table also tells you which Data Provider reported the metric and its status in the latest analysis, so you can determine if a metric was computed or has its default value from the analysis model. The possible status values are:

Searching for issues in your applications can be a manual process, as explained in How do I understand and Improve My Ratings?, but the analysis and decision models configured within Squore can automate this process by automatically suggesting items that require your attention after analysing the latest version of your code. This functionality can be accessed as part of the Explorer, in the Action Items tab. In this section, you will learn how to review Squore’s suggestions and incorporate them into your own issue management tool.

Note that in order to change the status of the action item, you must be working with the current draft version of a project. In order to follow the steps below, ensure that you select the current version of the Earth project, click on the Action Items tab. A list of action items suggested by Squore appears in a table, as shown in the picture below:

You can filter action items if needed by using the filters above the table. The name given by Squore to the action item is the name defined in your analysis model for this alert. Priorities are also predefined, and your input is needed to validate or invalidate the reports based on your priorities.

In the action items list, 29 is critical, therefore its status should be changed to Todo.

If you are unsure about a report, you can click the action item ID to display the full details, which includes the location(s) in the source code that triggered the alert:

You can review the code in a popup window before you decide to fix or relax the action item.

Finally, you can export the action items generated by Squore and feed them into your own issue tracker: Select the export format you want to use (CSV, ClearQuest, Mantis, XML, or any other custom format you defined in your configuration) and click the Export button to download the list to a file. You can also add all artefacts that triggered an action item to your Review Set by clicking the appropriate button.

The Capitalisation base provides statistics aggregates, distribution graphics and correlation coefficients across a portfolio of projects. To begin using the Capitalisation to understand historical trends about your projects and find out if your analysis models are suited to your development style, click the Capitalisation menu item in the Squore toolbar.

In the projects tab, choose the projects that will be used to aggregate statistics. In the example below, we will look at statistics for the Earth and Mars projects, which both use the same analysis model and have similar overall ratings. Select Earth and Mars from the list and click the Statistics Aggregates.

The Statistics Aggregates tab offers an overview of all your projects' data by providing minimum, maximum, average, number of occurrences, deviation, mod, sum and median results. Results are based on all the measures of an artefact type. This means that you have to specify an artefact type before any data is displayed.

The Distribution tab offers the possibility to display any kind of distribution. The distribution is based on a measure of an artefact type. As a result, you have to select both an Artefact type and a Measure before you see any results. Note that you can change the parameters of the distribution graph by adjusting the number of bars, and the minimum and maximum values for the axes. The picture below shows the distribution of lines of code (a measure called LC) across all artefacts of type FILE for Mars and Earth.

The Correlation tab displays the matrix of correlation of any data stored in the Squore database. Correlations are computed between artefacts of the same type, so you have to select the artefact type before any data is displayed. Squore highlights cells in the table in which correlations are above the threshold defined by moving the slider or entering a correlation coefficient directly in the text box provided. You can choose to include derived data by checking the box above the matrix table.

You can choose to export the results of the correlation matrix to a CSV file. The resulting CSV file contains all metrics pairs for which a correlation exists.

The Test Effectiveness indicator is based on a ratio of passed and failed tests in your project.

It is enabled by default in your project if you use a Data Provider that imports test artefacts, like JUnit, VectorCAST, RTRT or MSTest.

The Code Coverage Compliance indicator is based on function coverage metrics imported by Data Providers like RTRT, JaCoCo, GCov or NCover among others.

In order to view test results, expand the Tests node in the Artefact Tree for the Mars and switch to the Code Coverage dashboard, which provides information specific to the test results for your project.

Expand the Tests node in the tree to uncover the hierarchy of tests. Each test is imported with its execution result, date and run time. The overall rating of the Tests node is the test effectiveness indicator, which also contributes to the overall project rating.

Clicking a test artefact displays a dashboard containing the test information, as well as a table containing links to the objects tested by the test, as shown below:

Clicking the link to the tested source code file brings up a dashboard showing the complete list of tests covering the source file, which are also clickable.

You can click the root test node (or any test suite artefact) to get a history of test execution as well as a text execution matrix showing the test results of all test cases in the project.

The Test Status Distribution chart can help you identify the failed tests immediately: click the chart thumbnail in the dashboard and click on the red pie slice to open the Data tab of the Chart Viewer. The tab shows the list of test artefacts with the Failed status. Each artefact is clickable so you can view its dashboard directly. You can additionally send the list of artefacts to the Review Set or create a highlight definition with these artefacts so you can display additional metrics for each of them.

If you click the Code node, the dashboard includes a Test Gap Analysis chart that helps you adjust your test strategy by highlighting the risky artefacts in your project based on recent code changes and test execution status.

The Highlights tab also contains predefined categories to help you analyse insufficiently tested artefacts, modified artefacts and display a summary of artefacts that comply with the code coverage threshold for the project. The screenshot below shows a list of function artefacts in the project together with their code coverage metrics:

Importing tickets related to your project activates the Ticket Completion Rate and Innovation Rate indicators in your project.

The Ticket Completion Rate helps you track the ratio of open and closed tickets in your project, while the Innovation Rate is an indicator of the ratio of enhancements versus defects being worked on. Both indicators are enabled when importing tickets using a Data Provider like Mantis or Jira.

The dashboard for each ticket provides details about the ticket’s activity and status history, as well as a direct link to open the ticket in your ticket management tool.

The dashboard for the Tickets node (or any ticket container artefact like each component in the Mars project) shows a summary of tickets by status and reporter, as well as a scrum board so you can keep track of task completion progress.

The ticket Data Provider are based on a common framework for importing tickets from various sources and in various file formats. To try it out in your project, you can start with a JSON or CSV file containing ticket data and define regular patterns to isolate data for the supported ticket metrics:

As an example, the following is the definition used to extract data from issues exported from Jira in JSON format:

Using a Data Provider to import requirements as artefacts in your project activate the Verified Ratio indicator. Various dashboards are available to track the volatility of your set of requirements and the evolution of single requirements.

Each of the chart thumbnails has a star () icon that you can click to mark a chart as favourite.

Clicking a star icon opens the Chart Viewer on the Favourites tab, as shown below:

The popup allows you to:

When you are satisfied with your choices, click on Save to add the chart to your favourites. You can add charts from any project you have access to.

Refer to the next section to learn how to view and manage the charts you saved as favourites.

All the charts you added from the Explorer were added to a list called Unsorted Favourites. You can delete this list and create other lists using the and icons.

When you have more than one list, you can drag and drop charts between lists.

In order to see the full size of a chart you marked as favourite, click its thumbnail on the left pane to open it in the right pane. The screenshot below shows an example of a list of favourites and a maximised chart. Note that the right pane contains links that allow you to go back to the project’s or artefact’s dashboard directly.

The list of charts you marked as favourites in Squore is the list of charts you can access via Squore Mobile

Squore Mobile is a touch-friendly interface for Squore that is accessible from http://localhost:8180/SQuORE_Server/Mobile.

When you log into Squore Mobile, you can swipe through all the charts you added to your favourite lists from your mobile device.

Not all models support milestones, but if yours does, you will see a Milestones pane on the first page of the project wizard. The Milestones pane is where you can see the existing milestones for a project, with their associated goals and dates.

In the example above, our model defines 5 milestones (SPRINT1 to SPRINT5) for the lifecycle of our project.

Each milestone has a set date and defines goals for the following key performance indicators in our project:

The Milestones pane allows you to change the dates and goals for your project. If a milestone is optional and is not relevant for your project, you can remove it by clicking the x next to its name. This is possible for all the milestones in our example above. By clicking the + icon to the right of the last milestone, you can create a new milestone for the project and define your own goals. You can also add a new goal for your project by selecting a metric from the list at the bottom of the table and clicking the \+ icon.

When you are satisfied with the milestones set for your project, click the Next button to continue with the creation of the project.

Goals and dates can be modified every time you create a new version of the project if you decide that your schedule slips. Goals and dates are versioned, so your dashboard can always show you when in the timeline of your project you decided to change your milestones.

When you consult the dashboard of a project that uses milestones, the functionality allows you to:

The following is an example of a chart that mixes objectives, projected performance and milestone date changes:

Some action items on your model can also take advantage of this feature to warn you about poor performance:

You can also visualize the milestones setup for each version of your project in the Project Portfolios :

A pop-up shows you the milestones definition at version creation :

Squore allows posting comments about charts, artefacts, action items and findings. Users in a project team can view and reply to comments when they notice that a discussion thread has received new posts since their last visit. You can also choose when a discussion no longer accepts comments or is removed from the project. In this section, you will learn the basics of commenting all around the dashboard.

There are two ways to build direct links to projects in Squore:

Each method supports different parameters to build direct links to a tab of the Explorer for the specified project, as explained below.

While you review results and comments, you can add artefacts manually to your project as needed. To add an artefact, make sure you are on the Current version of the project and click the node to which you want to add a child artefact. If this node supports adding artefacts, the Add an Artefact option will be available in the menu:

Click the menu and choose an artefact type and an artefact name to add the artefact to the tree.

Here is what the Artefact Tree looks like after manually building a test plan tree:

When you run a new analysis of the project, the new artefacts will get rated according to what is defined in your model.

You can generate reports and export data to csv with Squore so you can communicate your progress to others.

In order to create a report, for the currently selected artefact in the tree, click the Reports tab in the Explorer. The Reports page opens as shown in the picture below:

The Reports tab offers a choice of report and export types in various output formats. Reports are primarily used to present information visually including charts and data about action items, findings and relaxed artefacts. The output formats currently supported are .pdf, .pptx, .docx.

Reports can be created in full or synthetic view. The synthetic view omits details about the exact location of violations in the code in the report, but provide a link to read the full details in the Squore web interface. The screenshots below show the difference between a synthetic report and a full report. The availability of the full report depends on your licence.

Exports can be used to extract information in various formats in order to import it into another tool. Clicking the Create button generates and downloads the file in your browser. Note that the availability of the export feature depends on your licence.

The following is an example of CSV export file obtained by launching the Project Portfolio export at model-level to get details:

Other exports ask you to choose a list of highlights. In this case, the exported data contains the artefacts and metrics defined by the selected highlights.

The following is an example of a file generated by the

Highlights to Excel export with the HIS: All Metrics and Code Coverage: All Modules highlights selected for the Mars project:

Reports and Exports are highly customisable, consult your Squore administrator or refer to the Squore Configuration Guide to learn more about how to tweak the report contents or format.

When you create a project, you become its owner, and remain the only user who can view it in Squore by default. In order to make it visible to more users, the project owner has to create a project team of users and groups and assign them roles. This is done in the Manage page of a project in the Team tab, as shown below:

In order to give visibility to the user admin over the projects created by the user demo, follow these steps:

The admin user can now log in and will see the Earth project in their Explorer.

If you want to configure the rest of the sample projects the way you configured Earth, you can copy the project team to another project:

A Squore administrator may allow you browse a list of projects created by other users so you can contact them and request to be added to their project’s team. When this feature is enabled, you can click the Ask access to Project Owners button on the Projects page to view a list of projects that other users have created, as shown below:

If you want to become a team member of one of the projects listed, click the project owner’s e-mail address to send them a message and request to be added to their project’s team.

You can configure each project in Squore so that an e-mail notification is sent out after a new version is created. This functionality is available for users who can create and manage projects, either in the General Information section of the project wizard, or the in the Project Properties tab of the Manage Project page:

The conditions on which you can to trigger an e-mail are:

The e-mail contains a description of the version, the number of new artefacts, the number of action items, a list of the new action items and the number of new findings.

You can get information on how your collaborators are viewing the projects you manage or the models you develop by using the statistics features of Squore. This section describes the information available to project managers and model developers via Models > Statistics and the Manage Project page.

As a project manager, you can use project statistics to investigate the popularity of your project by going to Manage > Statistics.

When you select a reporting period, the following information is displayed:

You can learn more about the usage of particular features of a model by clicking Models > Statistics. For each analysis model, find out how many users consult results, which projects are the most popular and which regions and charts of the dashboard are the most useful for users.

You can delete or rename one or more of the last versions of a project if needed. This can be done from the Projects page if you are the project creator or are a member of a role that allows managing the project.

If you want to manage the previous analyses of the Earth project, log in as the demo user and click Projects. Click the Manage icon () and open the Versions tab to view the list of versions created for this project:

By clicking the pen icon next to the version name, you can rename this analysis. Your changes will immediately be reflected in the Project Portfolios.

In order to delete an analysis, check the box next to the version you want to delete. All versions created after the version you selected will also be checked. Click the Delete button to reach a summary page where you can confirm which versions will be deleted, and click Confirm to launch the delete process.

Projects can be deleted by their creator or members of a role that allows to manage projects. In order to delete a project, click Projects and click the delete icon () next to the project you want to delete. After confirming the operation, the project is deleted from the Squore database and cannot be restored.

A Squore Administrator can access functionality that does not involve working with projects directly. You can access the Administration menu if you need to perform any of the following tasks:

For more information about administration functionality, consult the Online Help.

Server maintenance, including database backups need to be carried out by a system administrator directly on Squore Server. If you need to know more about the backup options offered by Squore, refer to the Squore Installation and Administration Guide.

Squore allows using multiple repositories in the same analysis. If your project consists of some code that is spread over two distinct servers or SVN repositories, you can set up your project so that it includes both locations in the project analysis. This is done by labelling each source code node before specifying parameters, as shown below

Note that only alpha-numeric characters are allowed to be used as labels. In the artefact tree, each node will appear as a separate top-level folder with the label provided at project creation.

Using multiple nodes, you can also analyse sources using different Repository Connectors in the same analysis: