Monitor Artifact Traceability and Detect Outdated Results with Digital Thread

When you develop software that meets industry standards and guidelines, you are responsible for creating and managing numerous artifacts. These artifacts often include requirements, models, tests, and generated results. Typically, there are dependencies among these artifacts, meaning that a change to one artifact might require you to rework or reanalyze downstream artifacts and derived artifacts. You can use information on these artifacts and their relationships to help assess the status of your development activities. For example, you can enable a digital thread for your project. A digital thread is a set of metadata that stores information about the artifacts and relationships in your project.

This page explains the benefits of a digital thread, how a digital thread works, and how to enable digital thread support for your project.

Benefits of Digital Thread

A digital thread allows you to access data on the artifacts, artifact structure, and relationships between artifacts in your project. You can analyze the information stored in the digital thread as you make changes to your project.

Having a digital thread enables you to:

Track changes to artifacts
Trace relationships between artifacts
Identify outdated results
Perform incremental updates of results

As you make changes to the artifacts in your project, the digital thread identifies these changes and incrementally updates the metadata information, providing you with a central source of traceability information and metric results that you can share across your team.

Diagram showing digital thread connecting requirements, design artifacts, tests, and test results

Several MathWorks^® apps and tools use the information in the digital thread to identify traceability relationships, aggregate metric results, and perform incremental builds.

Application	Functionality	Example
Traceability	Click Trace View in Model Design and Model Testing Dashboards	Explore Traceability Information Using Trace Views
Metrics and Dashboards	Model Maintainability Dashboard Model Testing Dashboard SIL Code Testing Dashboard PIL Code Testing Dashboard Design cost metrics (Fixed-Point Designer™) Code Quality Dashboard (MATLAB^® Test™)	Explore Status and Quality of Testing Activities Using Model Testing Dashboard
Incremental Builds	Process Advisor app (CI/CD Automation for Simulink Check support package)	Continuous Integration

Digital Thread Analysis

The digital thread performs two main operations on your design: artifact tracing and the tracking of derived artifacts.

Artifact Tracing

During artifact tracing, the digital thread:

Identifies which artifacts are in the project folder
Identifies potential software units and components
Creates universal unique identifiers (UUIDs) for each artifact
Creates an index of the design structure
Stores a representation of each artifact, their inner structure, and relationships with other artifacts

Artifact analysis allows the digital thread to convert the numerous artifacts and relationships in your design into usable artifact and traceability information.

Diagram showing files in project folder being used to create a trace view that shows the relationship between a software unit and a data dictionary file

You can view subsets of the artifact and traceability information from the digital thread by using the trace views in the dashboards. A trace view is an interactive diagram that shows a certain preset of traceability information for artifacts in a project. For example, you can view the requirement links and design artifacts that the digital thread traces to a software unit in your project. If you point to an artifact in the diagram, you can see detailed information about the artifact and directly open the artifact. For more information, see Explore Traceability Information Using Trace Views.

As you make changes to your design, the digital thread continues to monitor the files in your project folder and incrementally updates its representation of the artifacts and artifact relationships. The digital thread can detect when you move project files and maintains the same UUIDs for the artifacts and the elements inside the artifacts. If the digital thread is unable to analyze an artifact or relationship, the digital thread returns a warning or an error message. For more information, see View Artifact Issues in Project.

Tracking of Derived Artifacts

The digital thread can track the outputs from MathWorks apps, like the Requirements Editor in the Requirements Toolbox™, to help you to identify new artifacts and maintain up-to-date information on the requirements, units, tests, and results impacting your design. For example, if you modify a requirement in your design, the digital thread can detect the change and identify the impact on the downstream design artifacts that implement that requirement and tests that you might need to rerun.

For an example of how the digital thread can enable you to identify and address common traceability issues, see Fix Requirements-Based Testing Issues.

Enable Digital Thread Support

To enable digital thread support for your project, you need to enable artifact tracing for your project. If you use an app like the Model Testing Dashboard, the app automatically prompts you to enable artifact tracing for your project when you open the app for the first time.

Otherwise, you can manually enable a digital thread for your project by using the Digital Thread Settings dialog box. Open the Model Design or Model Testing Dashboard app and, in the dashboard toolstrip, click Options and then click Digital Thread Settings. In the Digital Thread Settings dialog box, select Track tool outputs.

The next time that you use an app or tool that requires a digital thread, the digital thread software performs an initial analysis of your project and creates the derived files that store the digital thread.

Digital Thread Creation

The first time that you open an app or use an API that requires a digital thread, the digital thread software performs an initial analysis where it identifies each of the artifacts in the project, their inner structure, and the traceability relationships between artifacts.

The digital thread creates a new folder (derived) in your project and stores the analysis in two files inside the derived folder.

artifacts.dmr — Stores information on the artifacts in your project, their inner structure, and the traceability relationships between artifacts
resultservice.dmr — Stores any metric results

After the initial analysis, the digital thread can track changes to the artifacts in the project and incrementally update the metadata information stored in the DMR files. The DMR files are platform-independent and persist across MATLAB sessions, which allows the digital thread to perform traceability analysis across the different artifacts without needing to locally load or access the artifacts.

Note

The digital thread is not portable across different MATLAB releases. If your project has DMR files from a previous release, the digital thread renames those DMR files to artifacts.dmr.old and resultservice.dmr.old, and creates new DMR files for the current release.

Reduce Analysis Time

You can analyze artifacts and their relationships more efficiently by using the digital thread to cache traceability information in the artifacts themselves. You can enable caching from the Digital Thread Settings dialog box.

When you open a Model Design or Model Testing Dashboard, the dashboard now shows an informational banner where you can open the Digital Thread Settings dialog box by clicking View Digital Thread Settings.

In the Digital Thread Settings dialog box, under User Settings > Trace Information, select Cache trace information to enable caching.

Digital Thread Settings showing the Cache trace information checkbox selected

Alternatively, you can view the Digital Thread Settings dialog box for a project by clicking Options in the dashboard toolstrip and clicking Digital Thread Settings.

Share Digital Thread in CI

If you use a continuous integration (CI) system, you can share the digital thread for your project across your team by treating the DMR files for the digital thread as derived artifacts. When team members clone the project from source control, they can download the latest derived files, including the existing digital thread that contains the latest analysis of the project. Team members can then perform their work on the project as usual. When team members submit changes to source control, they do not check any of the derived artifacts into source control. Instead, the CI system performs the incremental updates to the digital thread. To update the digital thread in a CI system, you can have the CI system either execute the metrics engine using the execute function or update the trace information using the updateArtifacts function. You can then use a database or repository management tool to manage the derived DMR files.

Diagram showing workflow for sharing digital thread using CI and a database or repository management tool