Links

Squore allows you to define links between artifacts. The links are generally created by Data Providers in your model (see Addons), and are displayed automatically in tables on the dashboard, as shown below:

CFG links intro
Figure 1. Links to related requirements and tests in the scorecard of a requirement

Links in the scorecard can be clicked to navigate to the target artifact directly.

For more information about advanced display options for links, consult Scorecard tables.

Basic links are declared in the analysis model using a Links element, which accepts the following attributes:

  • id (mandatory) is the unique identifier for the link type in your model

  • srcArtefactTypes (optional, default: any) is a list of possible artifact types that can generate inbound links for this type of link.

  • dstArtefactTypes (optional, default: any) is a list of possible artifact types that this type of link can link create outbound links to.

The links shown in the picture above can be defined as follows:

<Link id="TEST" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="TEST_CASE" />
<Link id="RELATED_REQ" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="REQUIREMENT" />

It is not strictly necessary to declare all your basic link types in the analysis model, but doing so allows you to use a condition in the LINKS() function, which you can read about in Conditional and level-related functions.

You can also create advanced links in your analysis model by declaring computed links. Computed links allow you to add conditions to the source and destination artifacts and create links that follow artifacts recursively, which are a great way to implement traceability between artifacts. Here are a few examples of computed links:

  1. Provide links to all complex functions at application level:

    <ComputedLink id="COMPLEX_FUNCTIONS">
	<StartPath srcArtefactTypes="APPLICATION" scope="DESCENDANTS" dstArtefactTypes="MODULES" dstCondition="VG > 10" />
</ComputedLink>

    You can then use this link to display a treemap of all complex functions at application level in your dashboard:

    <chart type="TREEMAP" id="TREEMAP_LINK_EXAMPLE" linkType="COMPLEX_FUNCTIONS" colorFromIndicator="ROOT">
	<measure>SLOC</measure>
</chart>

  2. Provide links at application level to all complex functions in files with over 100 lines of code:

    <ComputedLink id="LARGE_FILES_WITH_COMPLEX_FUNCTIONS">
	<StartPath srcArtefactTypes="APPLICATION" scope="DESCENDANTS" dstArtefactTypes="FILE" dstCondition="SLOC > 100" />
	<NextPath scope="DESCENDANTS" dstArtefactTypes="MODULES" dstCondition="VG > 10" />
</ComputedLink>

  3. Provide links from high level requirements to tests linked to lower level requirements: A Data Provider provides a basic link between requirements and tests, and a basic link between related requirements. The model recursively traverses the hierarchy of requirements to link the highest-level requirement artifact to the test artifact attached lower-level requirements.

    <!-- Define basic link between requirement artifacts (REQUIREMENT) -->
<Link id="REQ" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="REQUIREMENT" />
<!-- Define basic links between a requirement artifact (REQUIREMENT) and a test artifact (TEST) -->
<Link id="TESTED_BY" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="TEST" />
<!-- Compute link from requirement to test recursively:
	1. Follow REQ links recursively
	2. Follow link from requirement to test
	Result:
	- A link is created from the top requirement to the test
	- Intermediate links are kept between all traversed artifacts -->
<ComputedLink id="REQ_TO_TEST">
	<StartPath links="REQ" recurse="true" keepIntermediateLinks="true" />
	<NextPath links="TESTED_BY" />
</ComputedLink>

  4. Provide links at application level to requirements with failing tests in highly complex modules: A Data Provider provides a basic link between requirements and tests and a basic link between a test and the tested code. The model dynamically computes the requirements with failing tests and provides links at application level to the unsatisfied requirements involving functions with a cyclomatic complexity greater than 10.

    <!-- Define basic links between code/test and test/requirement -->
<Link id="TESTED_BY" srcArtefactTypes="MODULES" dstArtefactTypes="TEST" />
<Link id="SATISFIES" srcArtefactTypes="TEST" dstArtefactTypes="REQUIREMENT" />

<!-- Compute link between complex code failing tests and associated requirement:
	1. Find all complex modules under application
	2. Follow the link to the associated test if the test is failing
	3. Follow the link to the associated requirement -->
<ComputedLink id="FAILING_REQ_RISK">
	<StartPath srcArtefactTypes="APPLICATION" scope="DESCENDANTS" dstArtefactTypes="MODULES" dstCondition="VG > 10" />
	<NextPath links="TESTED_BY" dstCondition="IF(FAILED)" />
	<NextPath links="SATISFIES" />
</ComputedLink>

  5. Provide links at application level to all change requests artifacts addressed in the git commit used for the analysis: A Data Provider parses git logs to create a basic link between a commit ID and the CR it fixes and another basic link between the commit ID and the code it impacts. The model then dynamically computes a changelog of CRs fixed in the commit ID specified for this analysis, with links to individual CR artifacts clickable at application level.

    <!-- Available artifact types:
* a GIT_COMMIT is an artifact with textual information for COMMIT_ID
* APPLICATION was provided GIT_COMMIT as textual information
* each change request was imported in the project as a CR artifact

<!-- Define basic links based on git commit information -->
<Link id="FIXES" srcArtefactTypes="GIT_COMMIT" dstArtefactTypes="CR" />
<Link id="CHANGED_FILE" srcArtefactTypes="FILES" dstArtefactTypes="GIT_COMMIT" />

<!-- Compute links between source code files and CRs:
	1. If a commit ID was specified at application level, find all file descendants
	2. If the commit ID matches the one at application level, follow the link to the commit
	3. Reach the CR and use it as the endpoint for the link from the application level -->
<ComputedLink id="CHANGELOG">
	<StartPath srcArtefactTypes="APPLICATION" srcCondition="NOT(EQUALS(COMMIT_ID, ''))" scope="DESCENDANTS" dstArtefactTypes="FILES" />
	<NextPath links="CHANGED_FILE" dstCondition="EQUALS(APP(COMMIT_ID), COMMIT_ID)" />
	<NextPath links="FIXES" />
</ComputedLink>

A ComputedLink always has a starting point defined with a StartPath element and one or more optional NextPath elements designed to keep following links as needed.

The full syntax for ComputedLink is as follows:

  • id (mandatory) is the identifier for the type of link you are declaring

The full syntax for StartPath and NextPath is as follows:

  • links or scope (mandatory) define the type of relationship between the artifacts to follow:

    • Use links="BASIC_LINK_ID1;BASIC_LINK_ID2;…​" to follow a list of relationships already defined by basic links (using a computed link inside the definition of another computed link is not supported)

    • Use scope="CHILDREN|DESCENDANTS|PARENT|ANCESTORS" to follow a relationship between an artifact and either, its children only, all its descendants, its parents only or all its ancestors

  • srcArtefactTypes and dstArtefactTypes (optional for link, mandatory for scope in StartPath) define the source and destination artifact types that should be used as endpoints for the computed link. When using links="BASIC_LINK_ID", the source and target artifact types are taken from the definition of BASIC_LINK_ID. Note that these attributes are not necessary in a NextPath definition.

  • srcCondition and dstCondition (optional, default: no condition) allow setting a condition for the source or destination artifact. You can use any computation that will be evaluated for each potential endpoint of the computed link to filter it out and skip creating a link when the condition is not met.

  • recurse (optional, default: false) allows to keep looking for destination artifacts recursively to create more links. This attribute can only be used with link relationships.

  • keepIntermediateLinks (optional, default: false) saves all links created between artifacts by following this path when set to true. By default, or when set to false, only one link is created between the source and destination artifacts. This attribute is only taken into account when recurse is set to true.

  • dstToSrc (optional, default: false) allows reversing the link direction. It is assumed by default that the link goes from the source artifact towards the target artifact. Set this attribute to true to define that the link should go from the target artifact towards source one.