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:
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:
The Link tab’s heading is "Create link", showing that YT Editor is in create mode – see figure "Creating links".
To actually create links, perform the following steps:
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:
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:
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
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
After clicking on the Create links button, YT confirms the successful link creation in YT Editor, see figure "Successful link creation".
Successful link creation
If the YT Bulk link creation editor view is not yet open, please do the following:
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.
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:
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:
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:
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.
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.
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.
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:
In order to edit a single link, proceed as follows:
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
In order to replace one link end, proceed as follows:
In order to insert the replacement artifact into the artifact field, you have various different options. They are described in section "Populating artifact areas".
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.
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:
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
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:
Another option to delete a link is to select a node in the
view and hit the
[Del] key. The link from the selected node to its parent node will be deleted.
In order to delete all links of an artifact, proceed as follows:
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 clears all YT Editor fields and resets the editor completely.
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.
You can search for artifacts by their respective type using the Artifact Search dialog. To open that dialog, click on the magnifying glass icon 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
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 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 multiple times. These dialogs remain open after link creation; close them explicitly by clicking on their Close button, if needed.
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.
[Ctrl+C]key combination, a menu entry like Edit → Copy, or some tool-specific means.
YT checks for duplicate artifacts. It won’t add an artifact to an area twice.
Converting clipboard contents into artifacts requires YT …
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.
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 .
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.
Click on the crosshair icon 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 …
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.
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.
You can remove an artifact from an artifact area in the following different ways:
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.
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.
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.
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.
You can remove artifacts from the list of favorite artifacts by selecting them in the list and then clicking on the icon in the toolbar of the YT Favorites.
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.
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.
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.