Artefact Links

Squore allows you to define links between artefacts. 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 artefact 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 artefact types that can generate inbound links for this type of link.

  • dstArtefactTypes (optional, default: any) is a list of possible artefact 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 artefacts and create links that follow artefacts recursively, which are a great way to implement traceability between artefacts. 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 artefact to the test artefact attached lower-level requirements.

    <!-- Define basic link between requirement artefacts (REQUIREMENT) -->
<Link id="REQ" srcArtefactTypes="REQUIREMENT" dstArtefactTypes="REQUIREMENT" />
<!-- Define basic links between a requirement artefact (REQUIREMENT) and a test artefact (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 artefacts -->
<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 artefacts 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 artefacts clickable at application level.

    <!-- Available artefact types:
* a GIT_COMMIT is an artefact 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 artefact

<!-- 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 artefacts 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 artefact 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 artefact types that should be used as endpoints for the computed link. When using links="BASIC_LINK_ID", the source and target artefact 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 artefact. 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 artefacts recursively to create more links. This attribute can only be used with link relationships.

  • keepIntermediateLinks (optional, default: false) saves all links created between artefacts 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 artefacts. 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 artefact towards the target artefact. Set this attribute to true to define that the link should go from the target artefact towards source one.