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.
Several MathWorks® apps and tools use the information in the digital thread to identify traceability relationships, aggregate metric results, and perform incremental builds.
|Click Trace View in Model Design and Model Testing Dashboards
|Explore Traceability Information for Units and Components
|Metrics and Dashboards
|Explore Status and Quality of Testing Activities Using Model Testing Dashboard
|Process Advisor app (CI/CD Automation for Simulink Check support package)
|Run Tasks Locally and in CI
Digital Thread Analysis
The digital thread performs two main operations on your design: artifact tracing and the tracking of derived artifacts.
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.
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 for Units and Components.
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 one of these approaches:
In MATLAB, on the Project tab, click Startup Shutdown. In the Manage Project Startup and Shutdown dialog box, in the Environment section, select Track tool outputs to detect outdated results.
In MATLAB Online™, on the Project tab, click Settings. In the Project Settings dialog box, in the Simulink section, select Track tool outputs to detect outdated results.
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
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.
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
resultservice.dmr.old, and creates new DMR files for
the current release.
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
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.