Traceability Management into Source Code

Owned by Christoph Bergner
Jul 16, 2023
4 min read

Smartfacts is able to manage traces between requirements, test cases, work items, model artifacts on the one side and source code which is hosted in GIT on the other side.

The traceability can be established between an engineering artifact and any code object like a class, an interface or a method. Thus, a fine-granular traceability into the source code can be established and maintained.

Our Goals

We target these value propositions:

  • Support compliance with standards and regulations like ASPICE, ISO 26262 and DO-178c.

  • Align software developers and architects. Provide instant insights for software developers into architecture models.

  • Support suspect links that show software developers when relevant requirements or architecture artifacts have changed and directly guide them to the impacted source code.

This is what you can expect from the solution

  • Links are visible in the code, but show only the linked artifact IDs.

  • For IDEs like Eclipse and Visual Studio Code, we provide plug-ins that support the following use cases:

    • You load complete requirements modules (Jazz), trackers (Codebeamer), Sets (Jama Connect) or projects (Jira) into the plug-in, conveniently browse through the requirements and add links between source code and engineering artifacts.

    • Using Smartfacts, you can also establish traceability between source code objects and model based artifacts from tools like Cameo, Enterprise Architect, Innovator, PREEvision, Simulink or Rhapsody.

    • The context view in the plug-in will always list the linked artifacts in clear text in the same order as they are added into the source code.

    • Clicking a link in the source code will highlight the clear text link target in the context view.

    • Selecting a linked artifact in the context view will highlight the link in the the source code.

    • Using the local menu of a link in the context view allows to open the delegated UI of a linked engineering artifact. That can be a detailed view of a requirement, test case, model element or diagram.

  • The plugins can be downloaded from the Smartfacts platform and installed locally in your IDE.

  • Having established the links in the source code and having indexed the links via the Smartfacts source code indexer, you can see the linked source code in your engineering tools like DOORS Next and in the embedded Smartfacts plug-in in Cameo, Enterprise Architect, PREEvision, Simulink, Rhapsody, etc.

  • The links into source code that are listed in the engineering tools in context with a linked engineering artifact, provide a delegated UI of the source code object:

Architecture Principles

  • We store links as comments in the source code.

  • Links are OSLC links pointing to the concept resource of a linked artifact, e.g., a requirement.

  • We index links in and index, so the tool holding the targeted artifact can do backlink queries against the index and identify which source code objects are linked to a certain artifact.
    Smartfacts has its own link index. In a scenario where you manage traceability between source code and IBM Jazz artifacts, we index the links to LDX, the global link index of the Jazz platform.

  • We do not store the base URL of the OSLC link in the code. Instead, only this information is stored:

    • Link Type

    • Concept resource URI

    • Component name, which is the identifier for the centrally stored base URL of the OSLC link

There are two reasons why we do not store full OSLC links in the source code:

  1. OSLC URIs might be long and ugly to have in the source code. We store a much abbreviated link format.

  2. The base URL of a large number of links embedded in the source code might change. The reason might be divers. The company name might have change, etc. Even if the links are only stored as comments, it would be required to re-test and verify the whole software project after a transformation of the links to the new base URL. We avoid all this by just storing an abbreviated link format without the base URL.

The base URL is stored in Smartfacts associated with a component name that is also part of the link and can be identified to transform the abbreviated link format to the full OSLC link.

IBM Jazz

For an integration of IBM Jazz artifacts with source code this image describes how the solution works:

Codebeamer, Jama Connect, Jira and other OSLC based data sources

For tools like Codebeamer Jama Connect and others, the integration works very similar:

The Process of managing Traceability into Source Code

  1. Your define the abbreviated links format in the in the Source Code Links tab of the MWH profile in Smartfacts

    1. You define the component by providing a value for the base URL.

  2. You use the plugins for your IDE to conveniently add links to the source code.

  3. You save our source code in a GIT branch.

  4. You define an interval in which the Smartfacts parser parses the GIT branch and calculates the associations of embedded links and Source Code objects like classes, interfaces or methods.

  5. You run the parser.

  6. You check the result in the linked tool.

    1. Select an artifact the you have linked to a source code object.

    2. Check in the links tab of the Smartfacts plug-in, if the inks are listed.

    3. Open the delegated UI of the source code.

    4. Navigate into GIThub.

Â