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.

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 → Layout and Views.
  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 link creation editor then shows all possible artifacts of both link ends in the two tree views. That can be quite a lot. To focus on „interesting” artifacts, the hierarchy can be filtered in several ways. Filters 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 supported.
  • For each custom attribute column, a pop-up menu allows to set an additional filter for attribute values. To open the pop-up menu, click-right on the column header.

Links are actually created by dragging and dropping artifacts onto other 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 onto a specific artifact. 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 links created is always the one selected in the YT Bulk link creation editor.

In the next two examples we will show you first how to use the different types of filters for the bulk link creation editor. After that, we will explain how to create links via drag and drop.

In the figure above, you can see that YT shows many artifacts, and it can be difficult to find the particular artifacts you want to link. To reduce the size of the lists, we can use different types of filters. Let’s first hide those artifacts which are already linked – provided of course that we want to create links between artifacts that are not yet linked. For this, we enable the checkboxes Hide linked artifacts on both trees. The figure below shows the result:

Hiding linked artifacts

A different approach is to filter artifacts by their names. In our example, the artifact at link end B side we want to link to is called WiperWasher. So we enter WiperWasher into the search text field. As result, we will get only those artifacts whose names match the search text. Alternatively, by ticking Regexp, we could have used a regular expression. For example, a regular expression like W.*W.* would – in this case – have returned the same result. The figure below shows the filtered artifacts:

Artifact filtering

What we can do now is filtering on a custom attribute values, i.e., restrict the result set to those artifacts where the value of a given custom attribute matches a search expression. For achieving this, we right-click on the attribute’s column header. A pop-up menu with a text field will appear, and the search expression has to go into that field. In our case, we will filter on the text custom attribute, and we want to find those artifacts where that attribute contains the text „if higher”. A column which has a filter set is marked with a filter icon. The figure below shows the custom attribute filtering just described:

Custom attribute filtering

The following example will show how to create links by dragging artifacts from the link end A side to the link end B side and dropping them on the artifact to link to.

Here we have disabled the Hide linked artifacts checkboxes, because otherwise the artifacts would immediately disappear from the view after having created the links. The remaining filters are still active. The figures below show how artifacts can be dragged and dropped to create links.

The two artifacts from the left side are selected and dragged to the right side, directly above the artifact you want to link them to.

Drag and drop artifacts

After dropping the two artifacts, two links will be created. A visual clue is the change of each involved artifact’s icon to a chain symbol, denoting a linked artifact. YT will also tell you how many links have been created, see the image below.

Links created after dropping

It is also possible to drag artifacts from a different view to the bulk link creation editor and drop them there. In the figure below, four artifacts are dragged from the YT Explorer. Links to the artifact in the right-hand tree are created once artifacts are dropped onto it.

Drag and drop from different views

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 editor, see figure "Editing all links of an artifact".

Editing all links of an artifact

Editing all links of an artifact

In this mode all links from the selected artifact are fixed in „Link end B” section. It is only possible to select a different artifact as „Link end A”. Doing so enables the „Update” button to move all the links to the new artifact. In case some of the links are already defined for the replacement a dialog asks if all the links should be moved anyhow.

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.