Identifying changes in a project

Validating your data

YT provides you different kinds of validations. They can be accessed by navigating to Traceability → Validation.

YAKINDU Traceability offers several validations:

  • Suspicious links validation
  • Duplicate links validation
  • Model consistency validation
  • Configuration consistency validation

It is even possible to define your custom validation in the form of validation queries.

The results of a validation are displayed in a dialog:

Encountered issues are displayed in YT Issues.

Links are created between artifacts. However, the artifacts these links refer to might be changed after the links were created. These artifact changes might affect links. The link itself can be changed, too, e.g., by modifying its attributes. The suspicious link validation identifies these changes.

A link is called suspicious if one or both linked artifacts have been changed in a significant way. YT uses a core model that includes all trace data. To maintain a valid model, YT checks if there are no violations regarding model consistency. As artifacts or links are changed, YT checks if these changes do not result in conflicts, e.g., the name and type of an artifact or link must be set and resolved. Otherwise a precise mapping is not possible.

Detecting suspicious artifact changes

Many, but not all, artifacts have a version . If that version changes, all links referring to that artifact version become suspicious.

However, it is up to each particular artifact type whether and how it supports the notion of a version. A few examples:

  • Each file in a filesystem has a „last-modified” timestamp which could be used to indicate the version. As long as this timestamp doesn’t change, the file’s version remains the same. However, if the file’s contents is modified – and thus the „last-modified” timestamp, too –, the suspicious link validation would consider all links referring to that file being suspicious, no matter how small the change.
  • The artifact version is mapped to a certain location in, say, a Microsoft Word file. The document’s author manually maintains a version number in that location. This way the artifact version is equal to whatever the author provided. It is up to the author’s discretion whether to update the version or not, depending on the kind of change he makes to the document.
  • Certain artifact types might offer no version information at all, like for example Java artifacts provided by the the Eclipse Java (JDT) adapter.

Anyway, it is always the link’s responsibility whether and how to take any version information into account, see below.

In order to find artifact changes resulting in suspicious links, the validator compares

  • the version information derived from the artifact itself to
  • the version information that has been stored in the link at some point in time before.

If these pieces of version information are not equal the link becomes suspicious.

While analyzing suspicious links, three different kinds of suspiciousness are checked:

  • Local links with version are links that hold their artifacts' version information. This information has been gathered before and resides in the link now. Such links are typically stored locally, e.g., in a native file, see section "Native File". Checking a link for being suspicious or not is done by retrieving the current version of an artifact and comparing it to the corresponding version stored in the link. This is done for both A and B artifacts. If at least one of the comparisons results in inequality, the link is suspicious.
  • Derived links are stored partially in the storage. The actual link data is defined by the configuration and defines which pieces of information in the linked artifacts are available for suspicious validation. The Excel storage is an example for such links. The link attributes are based on attributes of the linked element, and the values of these attributes are copied to cells in the Excel file during link creation. The link becomes suspicious if either the value of the cell changes (change in Excel), or if the value of one (or several) of the linked artifact’s attributes changes (change in the opposite artifact).
  • Externally suspicious links are fetched from a storage which supports its own meaning of suspicious links. This information can be extracted. At the moment the PTC Integrity adapter creates such derived links and PTC Integrity provides information about suspicious traces itself.

When suspicious link warnings are reported in the YT Issues view, it is possible to get detailed information about a particular link by double-clicking on its corresponding line in the view. A dialog showing the link details opens. For each changed attribute of the link and of any changed artifact A or B, the dialog displays the previous and the current value. If the changed text for an attribute is too long or consists of several lines, you can click on the Show details hypertext link to open a full-screen comparison dialog. Clicking on the Quick fix button opens a dialog showing the available options to fix the issue.

Suspicious link validation

There can be several links of the same link type between the same artifacts. We call these links duplicate links. YT warns users on creation of duplicate links, but generally allows them. Other duplicate links can be derived by the tool-specific adapters. Since duplicate links are often undesired, YT offers a validation to check for their existence. Duplicate links that are stored in different locations, have different attribute values, or different versions of their attributes are called similar links.

Configuration consistency

Changes to the configuration influence the whole setup. Thus, changing the configuration my lead to type mismatches or wrong usage of adapters. The substitution of a data access could result in a type mismatch, e.g., a C file can not be accessed via an Excel adapter.

Custom validations by queries

It is possible to define custom validations which can be triggered by Traceability → Validation → Validation Queries.
The results of validation queries are shown as issues (warning, error or info) in the YT Issues view and as decorations of the artifacts. There are quick fixes to navigate to the artifact or the query.

Syntax of validation queries

Validation queries are mostly Queries which are described in The YT query language chapter with some special adjustments:

validation query … collect(… as Artifact, … as ErrorMessage)

Each validation query is identified by the keyword validation and has at least one column Artifact with a reference to the artifact and one column ErrorMessage with the issue text. A third column Severity for values in „Error”, „Warning” or „Info” is optional.

Example for a validation query

Validation queries can use other queries to calculate the desired result and can be executed like other queries also. in this example we calculate all system requirements which are not refinements of stakeholder requirements. The main purpose of the validation query is the definition of the artifacts which are an issue and reducing the default severity of error to warning.

// Complex calculation of business specific definitions
query "linked System requirements" source (allTraceLinks('Stakeholder requirements --> System requirements')).collect (ArtifactB as Artifact)
query "all System requirements" source (allArtifacts('System requirements')).collect (it as Artifact)
// Special validation query to produce warnings
validation query "not required word" source (reduceBy(q('all System requirements'),q('linked System requirements')))
.collect (
  column("Artifact") as Artifact,
  "System requirements should be refinements" as ErrorMessage,
  "Warning" as Severity) 

See details of validation issues

The YT Issues view shows all kind of issues (infos, warnings and errors) related to the current traceability data. Issues will be created during several processes like validations or candidate initializations. Whenever an issue occurs the user will be supported by solving an issue by so-called quick fixes. Quick fixes can be accessed via the context menu of an issue within the Issues View.

YT Issues

Quick Fixes

Working with model snapshots

To better understand the results of your validation, it is sometimes useful to compare the current artifacts and links with an older version of your traceability model. To support this use case, YAKINDU Traceability can create a model snapshot of your current trace model, which can later be loaded and explored. A model snapshot includes:

  • the configuration file that was active when the snapshot was created,
  • the traceability model, including
    • all artifacts (linked as well as unlinked ones),
    • all links, without the versions of the linked artifacts.

The blog post "Snapshots and change reports for requirements traceability data" contains a brief overview of model snapshots and what their use is.

Creating a model snapshot

To create a model snapshot, proceed as follows:

  • In the main menu, select Traceability → Snapshot → Create snapshot.
  • Enter a name for the new snapshot.
    • The chosen name must be a valid folder name, because it will be used as the name of the folder the snapshot is stored in. Therefore, you need to choose distinct names for different snapshots.
    • If you type the name of an existing snapshot, a confirmation dialog will ask you whether you really want to replace the existing snapshot by a new one.

After a few seconds – or minutes, depending on the size of your model – the snapshot folder will be created in the folder specified in your preferences. By default, it will be stored in the YT-Snapshots project. The location can be configured in the YAKINDU Traceability preference page, under „Snapshots location”.

Loading a model snapshot

To load a model snapshot, select Traceability → Snapshot → Load and manage snapshots from the main menu bar, then double-click or select the snapshot you want to load, and click on the Load snapshot button. By default, the most recent snapshot is selected.

Using the same dialog, you can also delete snapshots, see section "Deleting a model snapshot".

Loading an external model snapshot

On Windows, you can use YT to view any model snapshot file – without the need to set up or select a workspace. Such a snapshot that is not related to a workspace is called an external model snapshot. When opening an external snapshot, YT uses a temporary workspace behind the scenes.

To open an external snapshot, drag the corresponding .ytsnapshotzip file in the Windows explorer onto the YT_Snapshot_Viewer.bat file, which resides in the YT installation directory besides the YT.exe executable.

Exploring a model snapshot

Once a model snapshot is loaded, it mostly behaves like a standard YAKINDU Traceability configuration, although in read-only mode. The main difference is that data is retrieved from the snapshot, not via enabled adapters. This means that in order to browse a snapshot you do not need any tool or adapter to be installed.

The following views, features, and perspectives are supported in snapshot mode in the same way as they are in conventional mode:

  • YT Explorer
  • YT Overview
  • Search Dialog
  • YT Analysis (including queries, query results, and the YT Dashboard)
  • YT Favorite
  • YT Selection History
  • Report creation
  • Configuration editor (read-only)

Since the model snapshot is read-only and shows potentially outdated data which may not exist in your current documents or code, the following features are disabled:

  • YT Editor (except for the search dialog)
  • All editing menus in the YT Explorer (delete/edit link)
  • Validation

Snapshot mode

Snapshot mode


Adapter-related features may or may not work. As the model snapshot mode does not manipulate any source data directly, information required for navigation from/to external tools may not be available. For example, if you create a snapshot for a model containing a Word document and then delete this document, you can still load the snapshot and find the artifacts. However, you won’t be able to navigate to the original document.

In another scenario, the original document has been changed since taking the model snapshot. Navigating from the snapshot to the document will show the latter in its current state, however, which might be very different from its state at the time the snapshot was created.

Since model snapshots do not directly rely on adapters, you can load a snapshot containing artifacts for which you don’t have the proper adapters installed. This will work, though with some limitations: The adapter icon will be missing and navigation will be entirely disabled.

Deleting a model snapshot

To delete a model snapshot, select Traceability → Snapshot → Load and manage snapshots from the main menu, then select the snapshot(s) you want to delete, and press the [Del] key or click on the symbol: red "x" icon.

Alternatively, if the snapshot mode is active you can also delete model snapshot(s) in the YT Snapshot List view via the symbol: red "x" icon or the [Del] key.

You can also delete the model snapshot that you are currently exploring. However, you will need to acknowledge this in a confirmation dialog. Acknowledging the deletion will end the snapshot mode.

Snapshot bar and the YT snapshot list

As long as you are in snapshot mode, the snapshot bar will be displayed. It allows for several functions:

  • showing the name of the model snapshot currently being explored,
  • allowing to show/hide the snapshot list view via the Show/Hide snapshot list link,
  • allowing to create a delta report via the Create delta report button, see section Reporting model snapshot differences,
  • allowing to end the snapshot mode via the End snapshot mode button,
  • adding external snapshots (files with the .ytsnapshotzip filename extension) via drag and drop to the snapshot list.

The snapshot bar is automatically opened when loading a model snapshot, and it is automatically closed when ending the snapshot mode. The YT snapshot list contains all available model snapshots, allowing quick navigation by simply double-clicking on a snapshot to load it as well as deleting snapshots via the [Del] key or the symbol: red "x" icon. External snapshots dropped into the list can be activated in the same way. On deletion of such snapshots, only the link is removed from the list while the snapshot file itself is left untouched. External snapshots are not kept in the list after closing YT.

Please note: By default, snapshot bar and snapshot list are opened on the top and on the left of the screen, respectively, in the YT perspectives, see figure "Snapshot mode". If you can’t see them when in snapshot mode, you can reset the perspective via Window → Perspective → Reset Perspective….

Reporting model snapshot differences

Having two trace models conserved as model snapshots, it is possible to create a report that contains the differences between the two snapshots. This delta report lists removed or added artifacts and links as well as changed custom attributes in existing ones. The wizard to create a delta report is available

  • from the snapshot bar,
  • via the main menu as Traceability → Snapshot → Create delta report, or
  • via the context menu in snapshot list.

In the dialog, select the two model snapshots that you want to compare. Similar to other report dialogs, please also select an output folder and a filename for the report.