Linking artifacts of the development process with YT Editor

The YT Editor view is the main component used to manage trace links. You can create, edit, and delete links between artifacts by means of this editor. It provides two tabs:

  • The Link tab addresses the management of one or more links between artifacts.
  • The Artifact tab focuses on one particular artifact and on all the links from or to that artifact.

The remarkable thing is that YAKINDU Traceability can create and manage links across a lot of different tools and the artifacts therein. The blog post "Create links across your toolchain with YAKINDU Traceability" provides an introduction. It also gives a brief overview of YT Editor.

Creating links between artifacts of the trace model is a core functionality of YAKINDU Traceability. YT Editor and YT Bulk link creation editor support link creation in various cardinalities:

  • One-to-one: creating a single link from one particular artifact to one particular other artifact. For example, you can create a link from one specific requirement to the one source code fragment that implements it.
  • One-to-many: creating links from one particular artifact to several other artifacts. Consider, for example, to create links from one specific requirement to all source code fragments that are implementing that requirement in concert. Creating links the other way round is also possible, i.e., links from several different artifacts to one particular artifact. As an example, consider a set of multiple requirements that are implemented by a single source code fragment.
  • Many-to-many (YT Editor only): creating links from several artifacts to several other artifacts. Consider, for example, to create links from a set of requirements to a set of implementing source code fragments. In this case, links will be created between each requirement and each source code fragment.

If you will, you might see one-to-one and one-to-many both as special cases of many-to-many. In each case, trace links are created between one or more artifacts on one side and one or more artifacts on the other side.

Please note the following prerequisite: In order to create links between artifacts of type A and artifacts of type B, an appropriate link type for these artifact types must be defined in the YAKINDU Traceability configuration. In order to store links of this type, the link type must have a writable data access assigned. For short, we are calling this a writable link type. Please see section "YT Configuration" for details on how to create link types and on how to assign data accesses to them.

Creating links is done in the YT Editor or YT Bulk link creation editor view.

If the YT Editor view is not yet open, please do the following:

  • In the main menu, select Window → Show View → YT Editor. The YT Editor view appears.
  • In the YT Editor view, select the Link tab, if needed.

The Link tab’s heading is "Create link", showing that YT Editor is in create mode – see figure "Creating links".

Creating links

Creating links

To actually create links, perform the following steps:

  1. Insert one or more artifacts into the Artifact A field. All artifacts are usually of the same artifact type; let’s call it A.
  2. Insert one or more artifacts into the Artifact B field. All artifacts are usually of the same artifact type; let’s call it B.
  3. If your YT configuration contains only a single writable link type for artifact types A and B, YT Editor detects that situation and displays the link type in the Link type field. However, if you have several matching link types, you have to select the appropriate one from the Link type drop-down menu. – In the example shown in figure "Creating links", the link type describes links between artifact types Software architecture and Software integration test specification.
  4. Click on the Create button. As a result, YT creates the trace links. It stores these links in the writable data access that is associated with the selected link type. (If you have associated more than one writable data access with the very same link type, the link is stored redundantly.)

If the Artifact A and Artifact B fields each contain only a single artifact, i.e., the one-to-one case, YT creates a single trace link between these two artifacts.

If the Artifact A field contains a single artifact and the Artifact B field contains two or more artifacts, i.e., the one-to-many case, YT creates multiple trace links. For the artifact in Artifact A and each of the artifacts in Artifact B, a link is established. The roles of the Artifact A and Artifact B fields can be swapped, i.e., if Artifact A contains many artifacts and Artifact B contains only one, YT behaves analogously.

If the Artifact A and Artifact B fields each contain two or more artifacts, i.e., the many-to-many case, YT creates multiple trace links. For each combination of artifacts in Artifact A and Artifact B, a link is established (Cartesian product). This means that if Artifact A contains m artifacts and Artifact B contains n artifacts, m · n trace links are created. To avoid accidental creation of a large number of links, a warning will be shown if both Artifact A and Artifact B areas contain more than a single link.

In the example shown in figure "Creating links", YT creates two links:

  • from Washer [Component] to SW-ITS: Auto Wiping Evaluator Component: T101.2: turn off, and
  • from Nozzle Heater [Component] to SW-ITS: Auto Wiping Evaluator Component: T101.2: turn off.

We haven’t covered yet how you can insert artifacts into the Artifact A and Artifact B fields. Actually, you have a quite a number of different options to do so. They are described in section "Populating artifact areas".

Usually, all artifacts within the Artifact A or Artifact B area must be of the same type. However, you can remove this constraint:

  1. In the main menu, select Window → Preferences.
  2. Open YAKINDU Traceability → Customization.
  3. Check the "Allow link creation for multiple link types at once" option.

Please note: To have this work, there must be exactly one writable link type for all combinations of artifacts in the A and B artifact areas. For example, if for a certain combination of artifact types there are two link types that allow linking them in both directions, exactly one of them must be writable.

Figure "Creating links across different types" shows an example that links both an XML artifact and an Excel artifact to two C source code artifacts.

Creating links across different types

Creating links across different types

Before actually creating several links across different link types at once, YT Editor displays a confirmation dialog. This dialog intends to prevent any accidental use of this feature. It provides a detailed list of the links that will be created. It also shows the total number of links to be created and the number of different link types involved, see figure "Link creation confirmation dialog".

Link creation confirmation dialog

Link creation confirmation dialog

After clicking on the Create links button, YT confirms the successful link creation in YT Editor, see figure "Successful link creation".

Successful link creation

Successful link creation

If the YT Bulk link creation editor view is not yet open, please do the following:

  • In the main menu, select Window → Show View → YT Bulk link creation editor. The YT Bulk link creation editor view appears.

Creating links

You first have to select the type of the links to be created in the drop-down menu at the top. The bulk editor then shows all possible artifacts of both link ends in the two tree views. The hierarchy can be filtered in several ways, which can be combined:

  • You can request to show unlinked artifacts only.
  • You can enter a search text to show only matching artifacts. Regular expressions are possible.
  • For each custom attribute column, a pop-up menu allows to set an additional filter for the attribute.

Links are actually created by dragging and dropping artifacts on the artifacts in one of the hierarchies. You can select one or more artifacts on one side, drag them to the other side, and drop them there onto one artifact or onto multiple, pre-selected artifacts. Alternatively, you can select artifacts in any other view of YT and drag and drop them to the hierarchy on either the left or right side. The type of the created links is always the one selected in the YT bulk link creation editor.

A link establishes a relationship between an artifact of type A and another artifact of type B. The link also has a specific link type T AB . You can edit a link by the following operations:

  • replacing one link end by another artifact of the same type,
  • replacing one link end by another artifact of a different type C, implying a change of the link type from T AB to T AC or T CB ,
  • changing the link type from T AB to T' AB , while maintaining the artifacts at the link’s ends.

In order to edit a single link, proceed as follows:

  1. Select an artifact at one end of that particular link in YT Explorer .
  2. Right-click on the artifact. The context menu opens.
  3. In the context menu, the Edit link … submenu shows all editable links ending at the selected artifact. Select the link you want to edit.

After selecting the link to be edited in the context menu, YT Editor shows the selected artifact in the Artifact A field, the artifact at the opposite end of the link in the Artifact B field, and the link type in the Link type field. The Link tab’s heading reads "Edit link", to show it is in edit mode, see figure "Editing a single link".

Editing a single link

Editing a single link

Replacing one of the artifacts

In order to replace one link end, proceed as follows:

  1. Insert the replacement artifact into either the Artifact A or Artifact B field, replacing the artifact in that field.
  2. Click on the Update button to actually execute the replacement.

In order to insert the replacement artifact into the artifact field, you have various different options. They are described in section "Populating artifact areas".

Replacing both artifacts

You can even replace both ends of a link at the same time, which effectively replaces a link from W to X by another one from Y to Z.

  1. Insert the first replacement artifact into the Artifact A field, replacing the artifact in that field.
  2. Insert the second replacement artifact into the Artifact B field, replacing the artifact in that field.
  3. Click on the Update button to actually execute the replacement.

In order to insert the replacement artifact into the artifact field, you have various different options. They are described in section "Populating artifact areas".

In order to edit all links of an artifact, proceed as follows:

  1. Select the artifact in YT Explorer .
  2. Right-click on the artifact. The context menu opens.
  3. In the context menu, select Edit link … → Edit all. This menu entry is available only if the artifact has at least two links.

As a consequence, YT Editor displays the selected artifact and its links in the Artifact tab, see figure "Editing all links of an artifact".

Editing all links of an artifact

Editing all links of an artifact

Below its headline, the Artifact tab displays the selected artifact, i.e., the artifact whose links are to be edited. Editing all of these link means to replace the selected artifact by another one. As a result, all links to and from the selected artifact will no longer end at the latter, but at the replacement artifact instead. You can replace the artifact with respect to its links by another artifact in a single action.

The Artifact is linked with list contains all artifacts that are on the opposite sides of all links originating at the to-be-replaced artifact.

To actually replace the link, proceed as follows:

  1. Insert the replacement artifact into the Replace artifact by field. You have various different options to do so. They are described in section "Populating artifact areas".
  2. Click on the Update links button to actually replace the selected artifact by the one in the Replace artifact by field.

In order to delete a single link, proceed as follows:

  1. Select an artifact at one end of that particular link in YT Explorer .
  2. Right-click on the artifact. The context menu opens.
  3. In the context menu, the Delete link … submenu shows all links ending at the selected artifact.
  4. In the Delete link … submenu, select the link you want to delete.
  5. The selected link is deleted.

Another option to delete a link is to select a node in the YT Explorer view and hit the [Del] key. The link from the selected node to its parent node will be deleted.

Yet another option to delete a link is to click on the Delete button in YT Editor when editing a single link, see figure "Editing a single link".

In order to delete all links of an artifact, proceed as follows:

  1. Select the artifact in YT Explorer .
  2. Right-click on the artifact. The context menu opens.
  3. In the context menu, select Delete link … → Delete all. This menu entry is available only if the artifact has at least two links.

Populating artifact areas

Creating links between artifacts or editing a single link requires you to insert one or more artifacts into the Artifact A and Artifact B areas of YT Editor’s Link tab. In case you are editing all links of an artifact, you have to insert an artifact into the Replace artifact by area of YT Editor’s Artifact tab.

You have several different options to achieve this comfortably in various situations. In particular, you can

By the way, clicking on the clear icon symbol: document clear clears all YT Editor fields and resets the editor completely.

Artifact areas' behavior

The Artifact A and Artifact B areas in YT Editor’s Link tab behave differently, depending on whether YT Editor is currently operating in create mode or in edit mode. When you are creating links, both fields may contain an arbitrary number of artifacts. However, when you are editing a single link, by definition that link has a single artifact at each of its two link ends. Thus the Artifact A and Artifact B areas can hold only a single artifact each.

As long as both Artifact A and Artifact B areas are empty, you can insert any artifact into any artifact area.

After you inserted the first artifact into one of the artifact areas, that artifact’s type is displayed in the area’s heading. In create mode, you can add more artifacts to that area, but only artifacts of the same artifact type. In edit mode, you cannot add further artifacts.

If one of the artifact areas has some contents, certain constraints are applied to the opposite artifact area. Adding an artifact to the latter is allowed only if there is a link type between the type of the artifact to be added and the opposite artifact area’s artifact type.

Please note: In create mode, the above assumes that YT has not been configured to create links across different link types. Otherwise certain restrictions are lifted, allowing you to add artifacts of different types to the same artifact area.

Searching for artifacts by type

You can search for artifacts by their respective type using the Artifact Search dialog. To open that dialog, click on the magnifying glass icon symbol: magnifying glass in YT Editor. On the Link tab, it is located right from the "Create link" resp. "Edit link" heading. On the Artifact tab, you can find it right from the Replace artifact by field.

Figure "The Artifact Search dialog" shows how the dialog looks like.

The "Artifact Search" dialog

The Artifact Search dialog

  1. In the Artifact type drop-down menu, select the type of the desired artifact.
  2. Optionally, define a textual filter to find your artifacts faster in the Filter in visible tree field.
    1. If a filter is set, the dialog shows only artifacts (and hierarchies containing them) with names conforming to that filter.
    2. To clear the filter, please enter a blank (empty) text, or click on the rubber icon.
    3. The Regexp checkbox controls whether the entered text is a plain text filter or a regular expression filter:
      1. A plain text filter matches if the name of an artifact contains the given filter text. Matching is not case-sensitive.
      2. A regexp filter matches if the name of an artifact matches the given regular expression.
  3. The Matching Artifacts section displays artifacts according to the choices you made above. Select the artifact or artifacts you want to deal with.
  4. Click on the Add to favorites button to add the selected artifacts to your YT Favorites view. In YT Favorites, you can maintain a list of frequently-used artifacts for easier access.
  5. Click on the Set as A or Set as B button to add the selected artifacts to the respective artifact area of the YT Editor view.
  6. Click on the Close button to close the Artifact Search dialog.

Please note: In create mode, you can usually add artifacts via the Set as A or Set as B button only if the respective artifact area is either empty or contains artifacts of the same type already. To remove any unwanted artifact from an artifact area, click on the symbol: red "x" symbol right from the artifact, see section Removing artifacts from an artifact area.

In order to support the efficient creation of a large number of links, you can have multiple Artifact Search dialogs open simultaneously. To open them, click on the magnifying glass icon symbol: magnifying glass multiple times. These dialogs remain open after link creation; close them explicitly by clicking on their Close button, if needed.

Pasting artifacts from the clipboard

Most if not all tools offer the possibility to copy elements of whatever kind to the system-wide clipboard. You can paste the clipboard contents as artifacts to the A or B artifacts area.

  1. Select one or more artifacts in the originating tool, e.g., a portion of text in an editor, cells in a spreadsheet, entries in a requirement management tool, etc.
  2. Copy your selection to the clipboard, typically using the [Ctrl+C] key combination, a menu entry like Edit → Copy, or some tool-specific means.
  3. In YT Editor’s Artifact A or Artifact B area, click on the clipboard icon symbol: clipboard.
  4. YT reads the clipboard contents, tries to convert it into one or more artifacts, and – if successful – inserts them into the respective A or B artifacts area. If you are editing an existing link, only the first artifact on the clipboard will be added to the artifact area.

YT checks for duplicate artifacts. It won’t add an artifact to an area twice.

Adapter support for pasting from clipboard

Converting clipboard contents into artifacts requires YT …

  • to recognize the type of data that is currently on the clipboard and
  • to actually do the conversion.

Recognition and conversion are performed by YT adapters. Currently the PTC Integrity and the Microsoft Word adapters are supporting pasting from the clipboard. Please refer to the reference documentation to find out how pasting is supported.

Selecting the artifact type to be pasted

If the clipboard contents matches several different artifact types, choose the type of the artifacts to be inserted by selecting it from the drop-down menu that opens when clicking on the black triangle symbol: black triangle.

Consider, for example, you have two artifact types Requirement and Test specification. Both of them use the Microsoft Word adapter. Now let’s say you select some text in a Word document, copy it to the clipboard, and want to insert it as a Test specification into the B artifact area.

  1. Clicking simply on the clipboard icon symbol: clipboard won’t help, because YT can not decide whether it should insert the selected text as a Requirement or as a Test specification.
  2. Click on the black triangle symbol: black triangle of the artifact area you want to insert the artifact into, and select the appropriate artifact type, here: Test specification.
  3. Now click on the clipboard icon symbol: clipboard. The selected text will be inserted as a new Test specification artifact. If the same Test specification artifact is already present in the system, no new artifact will be created. Instead, the „old” artifact will appear in the artifact area.

Inserting selected artifacts

Click on the crosshair icon symbol: crosshair at the top of an artifact area to add the currently selected artifact. The currently selected artifact is an artifact that you have selected either …

  • elsewhere in YAKINDU Traceability, e.g., in YT Explorer or in YT Overview, or
  • in its „natural” editor, viewer, or other tool.

Inserting selected artifacts into an artifact area is similar to pasting artifacts from the clipboard. However, no conversion into an artifact is needed, because YT knows about the artifact already.

If you are editing an existing link, only the first selected artifact will be inserted into the respective artifact area.

Drag and drop

Use the „drag and drop” functionality to insert artifacts into the artifact areas, i.e., use the mouse to „drag” an artifact from any place within YAKINDU Traceability, e.g., from YT Explorer or YT Overview, and „drop” it into an artifact area. In create mode, you can drag and drop multiple artifacts simultaneously, in edit mode only a single one.

Picking artifacts from YT Selection History or YT Favorites

In the YT Selection History or YT Favorites view, click on an entry’s A symbol: A or B symbol: B icon to add it to the Artifact A or Artifact B area.

Removing artifacts from an artifact area

You can remove an artifact from an artifact area in the following different ways:

  • Click on the symbol: red "x" symbol right from the artifact to be removed.
  • Select the artifacts to be removed and hit the [Del] key.
  • Click on symbol: clear editor input to clear the input area of YT Editor and remove the artifacts from the artifact area.

Please note: Removing an artifact from an artifact area does not delete the artifact as such. It is just no longer displayed in the respective artifact area. If you wish, you can add it back anytime.

YT Favorites

The YT Favorites view provides a way to store artifacts that need to be linked very often. This enables you to find these artifacts quickly without searching them repeatedly via the YT Editor or the YT Explorer. Artifacts that have been added to this list will remain stored in it until they are explicitly removed, i.e., the contents of the view remain the same even after a restart of YT.

List of favorite artifacts

The list of favorite artifacts contains one row for each stored artifact. For each artifact it shows the name and the artifact type. The icon on the left of the name is the icon configured for that artifact type.

The left hand side of each row contains three icons that allow you to use the artifact within a new link or to replace another linked artifact within an existing link. In particular, you can use these icons to select one or several favorite artifacts for the Artifact A or Artifact B sections of the YT Editor or to select a favorite as replacement for an artifact edited in the YT Editor. The icons are the same as in the YT Selection History and can be used in the same way. Please refer to the description there for a more detailed explanation of their usage.

The above screenshot shows the YT Favorites, containing several artifacts of two artifact types provided by the Excel and Word adapters. Currently, „Altimeter” is in the Artifact B section of the YT Editor (not shown here). Thus, both icons are disabled for this artifact. Since „Control” has the same artifact type, it may only be added in the B role. Artifacts of other types (in this case of type „TestCases (Excel)”) can only be added in the A role. Currently, two artifacts of the same type are selected, so pressing the A-icon for any of them will add both to the Artifact A section of the YT Editor. Furthermore, an artifact of the type „TestCases (Excel)” is currently being edited in the YT Editor and can be replaced with one of the two favorites on top of the list by pressing its leftmost icon.

Adding artifacts to the list of favorites

You can add artifacts to the YT Favorites in three ways. One way is to select one or several artifacts in any other view of YT and then to press the crosshair icon in the tool bar of the YT Favorites View. Another way is to select artifacts as favorites via the Artifact Search dialog as follows. First you start the Artifact Search dialog by pressing the magnifier icon in the tool bar of the YT Favorites and select an artifact type from the drop-down list. Then you select one or several artifacts from the list and press the button „Add to favorites”. Finally, you can also add artifacts via drag-and-drop from other views of YT or from the Artifact Search dialog. New artifacts will always be added to the top of the list – except if you drag-and-drop them to a specific position within the list.

Removing artifacts from the list of favorites

You can remove artifacts from the list of favorite artifacts by selecting them in the list and then clicking on the symbol: red "x" icon in the toolbar of the YT Favorites.

Change order of favorite artifacts

It is possible to change the order of favorite artifacts by means of drag and drop. Just select one or more artifacts within the favorites list and drag them to the desired position.

Validating and updating favorite artifacts

As entries in the list of favorites might be stored for a long time and across YT sessions, the artifacts represented by these entries might be changed or deleted. You can validate and update favorite entries regarding such changes by pressing the refresh icon in the tool bar of the YT Favorites View. This validation will update the attributes of favorites entries with the latest content from the represented artifact. If the underlying artifact is missing, the entry in the favorites list is invalidated (as shown in the example above which contains invalidated "EA-"artifacts). As the artifact might have become unavailable temporarily only, e.g., if requirements from PTC Integrity are not available due to network problems, YT won’t delete favorite entries automatically.

YT Selection History

The main intention of the YT Selection History is to assist the user in the creation or modification of links. It is a supportive view for the YT Editor.

The YT Selection History provides a list of the recently selected artifacts (with the most recently selected artifact at the top). „Selection” means either the artifact representation in YT had been selected (e.g., by clicking an artifact in the YT Explorer or in the YT Overview) or the artifact had been selected outside YT in its specific editor (e.g., in MS Excel for an artifact residing in an xls file). Additionally, you can select (single click) or open (double click) artifacts directly from the YT Selection History. To avoid „flickering”, selecting an artifact inside the YT Selection History does not affect the order in the history list.

Each artifact in the list is displayed together with buttons to add an artifact to the Artifact A or Artifact B section of the YT Editor. The button de-/activation depends on the state of the YT Editor. YT will, e.g., disable the „Set as A”-button if the artifact already resides in the Artifact A section, or if the artifact type does not match the type of other artifacts residing in that section.

You can also select several artifacts and then add them at once to the Artifact A or Artifact B section of the YT Editor by pressing the corresponding icon for any one of them. This is only possible if your selection contains artifacts of just one artifact type. Artifacts in your selection which cannot be added at the moment (e.g., because they are already contained in the Artifact A or Artifact B section) will be ignored. In the case that you may only add one artifact, only the artifact for which you click the icon will be added and the others will be ignored.

The „Replace” button, the leftmost button for each artifact in the list, becomes active when you activate the „Edit all links” action in the context menu of an artifact in the YT Explorer. Additionally, the artifact type must match that of the artifact to replace. By clicking on an enabled „Replace” button next to one of the artifacts in the selection history, you can select that artifact as replacement for the edited artifact. Your selection will be reflected in the „Artifact” tab of the YT Editor where you can confirm the replacement.

In the example shown above, „R Module A:2” is already in section B of the YT Editor. Hence, its „Set as A/B”-buttons are disabled and other artifacts of the same artifact type may only be added to section B as well. Artifacts of the other artifact type, „EA Java Classes”, may be added to section A because they can be linked with artifacts of „Requirements (Excel)”. Furthermore, a „Requirements (Excel)” artifact is currently being edited. Consequently, the buttons for replacing that artifact are enabled for all other artifacts of that type in the list, but not for artifacts of different types.