Overview of YAKINDU Traceability

What is requirements traceability?

Traceability management is required in several industries, e.g. the automotive industry, to comply with legal requirements such as ISO 26262. Traceability deals with documenting the life of a requirement by creating bi-directional links between various associated artifacts, such as requirements, architectural components, source code, test cases, and test results. To benefit from the advantages of traceability it is necessary to be able to create traceability across all tools which are involved in the development process.

What is YAKINDU Traceability?

YAKINDU Traceability (YT) enables easy and well-arranged traceability management across all tools. It connects to the tools involved in the development process by means of custom tool adapters which are able to access the data-representing artifacts of the development process and related traceability information. These adapters do not only read or write data from those tools, they even support navigation across tools. As an example, by means of YT, an Autosar component designed in Enterprise Architect is only two clicks away from its specification in PTC Integrity (and vice versa).

YT Architecture

YT Architecture

Functional overview of YAKINDU Traceability

YT offers several possibilities to evaluate the data gathered from connected tools and the link information stored in YT itself, e.g. in the form of a coverage report or a validation of the links.

As YT unifies access to development artifacts across the whole tool chain, it supports you in various use cases of your daily work:

YT combines several approaches to manage associations between development artifacts:

  • YT supports non-invasive tracing, i.e. YT stores the trace information in its own store and does not change the original data sources.
  • Some adapters, such as the Eclipse CDT adapter, Enterprise Architect adapter or MS Excel adapter also support invasive tracing, which means that YT stores link information in the original data source, e.g. it adds a comment to a C function holding the ID of a linked requirement.
  • YT is able to adopt link information from the tools involved, e.g. a link between IBM Rational DOORS requirements or a relation between UML artifacts may be adopted as traceability links.
  • YT can also derive links from matching attributes of artifacts originating from different tools, e.g. if the test case ID of a test result provided in an XML file matches the ID of a test case specified in an Excel sheet. Dependent on development process and tools involved, YT enables you to fully configure which types of artifacts are relevant and how the links between those artifacts are managed.

For those links whose lifecycle is managed by YT (i.e. neither derived nor adopted, but stored by YT), several YT functions ease link creation: YT recognizes selections in external tools and shows the selected artifacts in a selection history; it is possible to search for specific artifacts of different tools and you can store often-used artifacts in a favorites list and then re-use them for creating links.

For those links which are derived based on attributes, it is possible to create links by manipulating the original data in their specific tools. Imagine a test case in Excel with an identifier in one column and a concatenation of identifiers of related requirements in another column. If a so-called attribute mapping is configured, YT iterates over these columns and – if the attributes match – creates links between the test cases and the requirements, independent of the tool the requirements originate from. This means that you do not have to switch to YT to create any links, but instead you can work in, say, Excel and let YT derive the links automatically. The same is possible with the Eclipse CDT adapter.

As artifacts and circumstances can change during work, it is sometimes necessary to change existing links. YT allows you to

  • delete one or more links directly,
  • change the link end(s) of a specific link,
  • replace an artifact in the traceability graph completely (i.e. replace it in all links by another artifact).

YT also provides you with different visualizations of existing links:

  • The YT Explorer shows you all existing links in a tree structure based on different groupings, e.g. based on the type of artifacts or based on link types. You can expand the various nodes to see what is linked to what.
  • The YT Overview displays all links of the artifact you selected in the different views of the tool in a graph visualization. By selecting nodes of the graph you are able to focus on other artifacts and to see its links. It is also possible to change the depth of the shown links: you can for example show only the direct links of the selected artifacts or also links of linked artifacts.

YT Explorer and YT Overview

YT Explorer and YT Overview

As it is often necessary to edit some artifacts or to check for their correctness, YT offers you an easy way to navigate artifacts: In all views displaying artifacts, you can double click on an artifact to open and select it in its native tool.

Validations: identifying project changes

Data often changes. Therefore, it is necessary to validate if they are still valid. In the context of traceability this means to validate if the links between changed artifacts are still valid. YT provides two validations to check the data validity:

As an addition, the configuration of the traceability project could have been changed. The configuration consistency validation detects potential errors and inconsistencies in the configuration of YT.

All three types of validations offer you various quick fixes that help you to re-establish the validity of the data.

Analysis: observing the traceability status

In order to analyze the current traceability status, YT provides several different means.

The YT Dashboard displays a visualization of the current traceability status including the percentage of linked artifacts and existing traces between specific artifact types. This feature provides you with an up-to-date overview of your project. In addition to the pie chart visualization, it is possible to do a drill-down from the pie chart, i.e. if you select a pie section, a table containing the affected artifacts is shown.

YT Dashboard

YT Dashboard

YT also provides you with reporting functionality. By configuring individual report templates you can find answers to your own specific questions concerning the traceability data.

Exports: creating a snapshot

Sometimes it is necessary to create a snapshot of your current data. For this purpose, you can extract the entirety of data visible to YT – the configuration, all artifacts and all links – in the form of CSV files. As these CSV files are designed with referential integrity in mind, they can easily be imported into any RDMBS (Relational Database Management System) for further evaluations. Especially for visualization purposes, it is also possible to export a graph representing the configuration of YT or a graph representing all linked artifacts. This helps you for example to discuss configurations with colleagues or to get an overview on the whole traceability project.

Tool integration: provided adapters

As explained in the start section, YT allows to access data from a multitude of tools via adapters. The adapters in the following table are supported by YT.

Domain

Adapters

Maturity level

Requirements Management

Eclipse ProR

basic

IBM DOORS

sophisticated

YAKINDU ReqIF

basic

Modeling

Eclipse Artop /AUTOSAR

basic

Eclipse Damos

basic

Eclipse Papyrus

sophisticated

Eclipse UML2

sophisticated

Enterprise Architect

sophisticated

Rational Rhapsody

advanced

YAKINDU Model Viewer

advanced

YAKINDU Statechart Tools

basic

Implementation

Eclipse C/C++ (CDT)

sophisticated

Eclipse Java (JDT)

advanced

Eclipse Xtext

advanced

Microsoft Visual Studio

basic

Test

Eclipse XML

sophisticated

SQS Test

basic

Word processing

Eclipse Text

basic

Microsoft Word

sophisticated

Spreadsheet

Microsoft Excel

sophisticated

Application Lifecycle Management

Eclipse Mylyn (e.g. HP ALM, JIRA, Microsoft Team Foundation Server, Polarion ALM)

sophisticated

PTC Integrity

sophisticated

Other

Eclipse Browser

basic

Eclipse Explorer

basic

Eclipse EMF (Sample Reflectiv Ecore Model Editor, SREME)

basic

Files

sophisticated

YAKINDU HMI

basic

First steps with YAKINDU Traceability

Installation

Installing YT from the distro file

To install YT as a stand-alone tool, unzip the distro file. A folder named YT is created on your disk. Execute YT.exe within that folder to start YT.

Setting up your YAKINDU Traceability workspace

To start working with YT, it is necessary to apply a YT license and to apply the initial YT configuration.

For a better understanding of these steps we will give you some general setup instructions in the following, including:

  1. Introducing important platform concepts
  2. Recommendations how to setup your workspace
  3. Resources for further reading

Platform concepts

The Eclipse workbench aims to manage all files relevant for your work, e.g. files that contain development artifacts like requirements, source code, and test cases. These files may be distributed over your hard disk (or several shared drives), e.g. requirements managed by Subversion and source code managed by Git may be checked out into several folders on your hard disk. The workbench bundles these files virtually, i.e. you can browse and navigate between those files as if they would reside next to each other. For further information on the Eclipse workbench, select Help → Help Contents in the main menu. The Eclipse Help window opens. You will find the „Workbench User Guide” in the navigation menu on the left-hand side.

The YT workbench

An Eclipse project groups resources that are belonging together logically and are being processed as a whole. All resources inside your workbench must reside in projects. Projects can have a type, e.g. C sources are in a „C project”, and requirements may reside in a resource project. Your workbench layout regarding resource management – how many projects you have and which resources they contain – is your own decision. Project configurations are held in „.project” files. In the default project layout, there’s a „.project” file in the project’s top-level folder. All files and directories in that folder are belonging to the project. However, you can also link folders from elsewhere into a project. The image below is showing a sample project structure.

An Eclipse workspace contains the metadata describing your workbench setup, e.g. the projects that you are working with, preference settings, and the layout of views and editors. Your workspace definition is held in a folder called „.metadata”; its parent folder is considered a workspace. Projects do not necessarily reside in the workspace folder, but can be located anywhere on your disk.

Please note: The Eclipse term project is somewhat misleading. A real-world project typically consists of not only one, but several Eclipse projects. You may want to think of your Eclipse workspace as your real-world traceability project definition and of each Eclipse project as a single module or resource.

Recommendations

  • Separate your YAKINDU Traceability resources (i.e. configuration and data) from your development artifacts (e.g. the files containing your requirements). Best practice is to create one dedicated project containing both YT configuration and data (e.g. the stored trace links), and to put your development artifacts into other projects.
  • The layout of your workbench regarding resources (e.g. how many or which projects) should best reflect your daily work process. All files relevant for one role should be in the same project.

Within the filesystem, separate your projects from your workspace. As the workspace not only stores projects, but also the user’s preferences, you might not want to put the workspace into your revision control system. Depending on whether you have common company guidelines regarding the file structure on your disk, it might be a good idea to share your project definitions by putting the .project files under revision control.

If starting with a naked workspace, you may either want to import existing YAKINDU Traceabilty projects into your workspace or create a new project on your disk. In case you set up a new project without existing config.yt and data.yt files, YT will create them as soon as you specify a project location. The path to the config.yt file can be set via the preference page. The path of the data file can be configured while creating a native file data access. If not already created, folders for both files will be created, too.

Further reading

Refer to the basic tutorial of the Eclipse platform documentation for a detailed description of how to manage the workbench, how to create or import existing projects, and more.

Entering preferences for your project

In the preferences you can do some basic configurations necessary to work with YT. The preferences can be opened by navigating to

  • Windows/Linux: Window → Preferences → YAKINDU Traceability
  • Mac: Eclipse → Preferences → YAKINDU Traceability

License

The very first thing you need to do is to install your YAKINDU Traceability license to use the product.

You can find a detailed explanation on the necessary steps in the „YAKINDU License Management” Eclipse Help chapter.

Configuration storage

The configuration storage location is set up here by defining the storage type and specific details depending on the storage type .

The most common case is that you want to point YT to an existing configuration file on your disk. To achieve this, set the field Type to FILE and the text field Details to file/projectname/foldername/filename.yt.

Hint: If you type file into the Details text field and then press [Ctrl+Space], YT offers all available .yt files in your workspace. If there are no existing .yt files, new ones will be created as soon as you set a path in the configuration editor _ or create an adapter that uses a native file storage _(data.yt).

See Configuration Storage Types for details.

The configuration itself is described in the Configuration section.

TCP server

YT includes a TCP server to interact with some external tools, like Microsoft Word. Its port can be configured here. If the server is not needed it can be disabled here.

Report templates

The location where report templates can be found is configured here.

Backup preferences

The preferences set on this YAKINDU Traceability page can be imported and exported here.

Configuring your traceability environment

In order to start using YAKINDU Traceability, you have to configure your project-specific traceability process and environment. For example, you can configure which tools YAKINDU Traceability should access data from, and you can define which artifacts are allowed to link to each other.

You can set up this configuration using the YT Configuration Editor. To start the editor, select

Traceability → Configuration → Edit Configuration

from the main menu.

General structure of the editor

The YT Configuration Editor is structured in three tabs: Data Access, Artifact Types, and Link Types.

In each of these tabs you can edit different configuration aspects for your specific project environment. The structure of the tabs is essentially the same: At the top, there is a table-based overview of the available data accesses, artifact types, or link types, respectively. You can add new elements or remove existing ones by use of the „plus” or „x” icon, respectively. Furthermore, it is possible to search for specific elements in the table: If you type a string into the search field near the top, all elements matching your input will be highlighted.

At the bottom of each of the three tabs, there is a details area where you can set up a specific configuration: If you select a row in the table at the top, the details area shows the configuration of the selected element. The configuration is done using a textual configuration language. While configuring elements, YT supports you by content assist: If you press [Ctrl+Space] YT shows proposals for suitable keywords and needed input.

If you need more space to edit one of the areas, you can fold the other one. Click on the arrow next to the area’s headline to fold or unfold it.

Activating different configurations

It is possible to have different configuration files. However, only one configuration will be active at a given point in time. If you want to activate a different configuration file, open it in the Project Explorer, and in the YT Configuration Editor press the Set as current configuration button. This button will only be active if the opened configuration is not the current one. This way you can see which configuration is the active one. Selecting Traceability → Configuration → Edit Configuration from the main menu will always open the current configuration.

Data accesses

Use the Data Access tab to configure trace data accesses. A data access is used to provide access to all kinds of trace data repositories. For example, you can configure that YT should have access to a specific Excel file located in the workspace or to a specific IBM DOORS project on a remote server.

YT can aggregate the traceability data from multiple data accesses. The tool makes all loaded links from a data access visible to the user.

You can add a new data access using the „plus” icon in the Data Access tab. This will create a new row in the data access table. Enter a name for the data access by clicking into the corresponding cell. Assign a data access type by clicking into the corresponding cell and by selecting the type from the drop-down menu. Using the Active checkbox, you choose whether the links belonging to this data access will be visible in YT or not.

When having selected a specific data access in the table you have to configure the source of the data. Depending on the type of the data access, the configuration differs. Have a look at the reference section on adapters which details data access configuration for various adapters.

Artifacts and artifact types

Artifacts, sources, and data accesses

Artifacts are the centerpieces of YT. Examples for artifacts are requirements written in Word files, Java source files, test specifications in PTC Integrity, test results in XML documents, etc.

Artifacts are part of a source. For example, if the artifact is a cell range in an Excel file, that Excel file is the artifact’s source. In principle, a file itself can represent an artifact, for example a file containing some binary data. However, an artifact does not necessarily have to reside in a file. The artifact’s source could be some server-based technology, like e.g. PTC Integrity oder IBM DOORS. In these cases the source would be the server and a so-called project.

YT reads or writes a resource by means of a data access. In order to access a particular resource an associated data access must be configured in the YT configuration.

Artifacts can be linked to other artifacts from the same or different sources.

Artifact properties

Artifacts usually have properties. For example, a file in the filesystem has a timestamp property, telling the point in time when the last modification to this file has been done.

Which properties exist for a given artifact is inherently dependent on the kind of artifact in question. For example, a bookmark in Word has document properties and a requirement in an IBM DOORS module can have a status.

Standard attributes of artifacts

Each artifact has four standard attributes.

  • name: The human-readable name of a the artifact. Example: the title of a requirement in an Excel file.
  • position: The machine-readable position of the artifact within a container. Example: the coordinates of a cell in an Excel file, i.e. the triple [worksheet; row; column].
  • source identifier: The machine-readable name of an artifact’s source. Example: the path name of an Excel file.
  • artifact type: The artifact type defined in the YT configuration. The concept of artifact types is explained below in more detail. Example: „Customer requirement”.

Custom attributes of artifacts

In addition to properties and standard attributes you can define custom attributes. Custom attributes can be derived from the underlying artifact. They are configured in an artifact type.

Artifact version

A fundamental concept of traceability is the ability to detect changes to artifacts. A change to an artifact is traced by its version. The version of an artifact is typically derived from its custom attributes and/or from properties like the timestamp. The version is not derived from the artifact’s standard attributes.

Artifact types

An artifact type is configured in the Artifact Types tab by defining a name, an adapter, a optional category and an optional color.

In the Artifact Type Configuration area at the bottom of the tab, you can create mappings for the artifact type selected in the Artifact Types table.

Each mapping defines a way to derive artifacts of the artifact type in question. You can (optionally) configure the mapping by using a textual configuration language that is specific to artifacts of the selected adapter. You can edit the mappings in the detail area in the tabs under the caption „Mapping” in the detail area. Alternatively, you can edit each mapping in a separate dialog that opens when you double-click the title of the tab. You can open several of these dialogs at the same time.

Depending on the language, you might be able to refer to custom attributes of the artifact type. You can configure the list of custom attributes on the left side of the details area. For each mapping, you can define the data access from which to derive artifacts (<implicit> assigns no data access).

The Active column in the Artifact Types table shows whether any mappings are active for the respective artifact type. This depends on the activation status of the referenced data access: If it is not active, the corresponding mappings of the artifact type will also not be available. The Active column for an artifact type shows a green check mark if all mappings of the artifact type are active. If no mapping is active it shows no check mark. In all other cases (i.e. at least one mapping is inactive and at least one mapping is active), it shows a grey check mark.

Assigning a category

In order to group artifact types and handle them collectively – e.g in reports – artifact type categories can be configured. The default category of an artifact type is „NONE”, i.e. no category. You can assign a category to an artifact type by selecting it from the Category drop-down menu in the Artifact Types table.

The elements shown in this drop-down list are individually configurable. If you wish to add categories, click on the Edit Categories button above the table in the Artifact Types tab. If no category exists yet, the Add new category dialog opens, asks for a new category name, and then you should proceed as described below.

If any categories exist already – and if it is the just-added first one only – the Edit Categories dialog lets you add, edit and remove categories.

Configuring an adapter

An adapter is a tool-specific interface. The selectable tool adapters depend on the features installed in YT. Each adapter comes with its own configuration allowing to specify how to identify valid artifacts. See the reference section on adapter configuration for details regarding the configuration of the various adapters.

Configuring custom attributes for artifact types

Some artifact types support the mapping of values derived from an artifact to custom attributes, according to the textual configuration of the artifact type. For example, you could create a custom attribute ID and map the value of a cell in an Excel sheet to this attribute. This means, every artifact of this artifact type has an additional attribute ID containing a specific value from the respective Excel sheet.

To create such a mapping, define custom attributes in the Artifact Type Configuration area of the Artifact Types tab. There are two ways to create them:

  • Manually create new attributes via the „plus” icon below the Custom attributes label. In the Mapping area, reference the added custom attributes.
  • Alternatively, reference non-existing attributes in the Mapping area as if they already existed. Then click on the „update” icon below the Custom attributes label. All mapped attributes that are not yet contained in the custom attributes list will be added to it.

Defining custom names of artifacts

For many adapters, the name of an artifact displayed in the YT views can be defined in the mapping area.

Some adapters, like Eclipse Explorer or Eclipse JDT, support custom artifact names by the keyword nameRule which is used to manipulate the name proposed by the artifact provider. The keyword ArtifactName following nameRule is a surrogate for the name proposed by the specific adapter. It can be modified by using the functions matches, trim, and replace:

  • matches: Takes two arguments. First, a regular expression and second, a reorder string that defines how the groups identified by the regular expression should be reordered.
  • trim: Parameters are a length and a trim strategy. While the first parameter specifies the length of the output string, the trimming strategy specifies whether the name should be cut at the beginning (KEEP_SUFFIX), at the end (KEEP_PREFIX), or in the middle (TRIM_MIDDLE). The removed part will be marked by ‚…’.
  • replace: The first parameter is a search string. The second parameter is a replace string. It replaces all occurrences of the search string by the replace string.

All functions can be called multiple times on one ArtifactName, e.g. ArtifactName.replace("search","find").trim(15,KEEP_PREFIX)

Attention

The artifact type configurations must be distinct. An artifact must be uniquely assignable to an artifact type. Otherwise, the first matching type will be used. The basis of assigning are the adapter and the adapter configuration. The combination of both of these must be distinct for each artifact type definition.

Ambiguous example:

Artifact Type: "Type X"
Adapter: "Tool A"
Adapter Configuration: "resource <pattern 1>"

Artifact Type "Type Y"
Adapter: "Tool A"
Adapter Configuration: "resource <pattern 1>"

Distinct example:

Artifact Type: "Type X"
Adapter: "Tool A"
Adapter Configuration: "resource <pattern 1>"

Artifact Type "Type Y"
Adapter: "Tool A"
Adapter Configuration: "resource <pattern 2>"

YT’s principal task is to maintain links between artifacts. However, that does not mean that you can link any two artifacts on the spur of the moment. Instead you first have to ponder which artifacts types you want to link to each other and specify that by way of a link type. Given a link type specifying two artifact types A and B, you can create links connecting artifacts of type A and artifacts of type B.

Example

Let’s say you want to be able to link Java source code artifacts to their corresponding test results. To do so, first create an artifact type for the Java source code artifacts and give it a name, say, Implementation Java. Additionally, create another artifact type describing test result artifacts and call it Test Result. After that, create a link type for trace links from Implementation Java artifacts to Test Result artifacts. Using this link type, you then create links from Java source artifacts to their respective test results, either automatically or by hand.

A link establishes a relationship between two artifacts. It has the following attributes:

  • link type: The link type constrains the types of artifacts link ends A and B can reference. See sections "Standard attributes of link types" and "Custom attributes of link types" for more information.
  • source: In order to maintain links they have to be stored somewhere. The source identifies that location. A link source could be a YT file, an IBM DOORS module, an Excel spreadsheet, etc.
  • position: A link source can hold a multitude of links. The position uniquely identifies a certain link. The position’s semantics highly depends on the source type. For example, the position of a link in an Enterprise Architect model is its UUID, while in a YT file it is its XMI ID.
  • end A, end B: References to the two artifacts the link connects are maintained in the properties end A and end B. The types of these artifacts must match the artifact types specified by the link type. The artifacts themselves are uniquely identified by their respective artifact properties name, position, type, and source. (Please note that link types also have properties called end A and end B. However, they denote artifact types, not artifacts.)
  • version A, version B: When a link is created, both artifacts A and B exist in a certain version at that point in time. The link can store version identifiers for A and B. However, an artifact can change over time, and it generally does not track such changes. That’s where the concept of a „version” comes in. It identifies a certain state of an artifact or relates it to a certain point in time. Please note: The version attribute is not necessarily set, but this depends of the link type configuration.

A link between two artifacts must always derive from a link type. A link type defines the artifact types whose artifacts can be linked.

Link types have the following standard properties:

  • End A, end B: These properties specify the artifact types of the artifacts that links of this link type are able to connect. (Please note that links also have properties called end A and end B. However, they denote artifacts, not artifact types.)
  • Role A, role B: These optional textual descriptions can describe the semantic meaning of the A and B artifacts. They can be used in custom queries.
  • Classification: The classification is an optional name, textual description, etc. of the link type as such. The classification does not need to be unique, i.e. different link types may have the same classification. It can be used in custom queries.

In addition to standard properties, a link type can also have custom attributes. A custom attribute’s value is the result of evaluating a function which typically takes the contents of the linked artifacts into account, extracts portions of them, possibly transforms them, combines them, and maps everything into the function’s result value. For example, a custom attribute approval_status could comprise the author’s name and last modification date of some document (artifact A) plus status and name of the person writing a review (artifact B).

Custom attribute values are evaluated when a link is created or updated. The values are then persisted within the link. This makes it possible to detect certain changes to the underlying articfacts. Consider the example above: If the last-modified date of artifact A changes, a suspicious links validation would re-evaluate the approval_status' value and detect that there’s a diffence from the value that was formerly stored in the link.

The mappings creating custom attributes are the same for all links of a given type, so the custom attributes are defined are defined on the link type level. Section "Configuring a link type" explains how you can create such mappings.

A link is stored in a link source, for example in a YT file, in an IBM DOORS module, in an Excel spreadsheet, etc.

A link provider is a software component that actually makes links available. It fetches them from a link source, retrieves the referenced artifacts from their respective sources, and evaluates the mappings to create the custom attributes defined in the link type.

Links pertaining to a single link type can be distributed over several link providers and their associated link sources.

For example, consider different individuals working on links of the same link type, but on different subsets of links. Each person could maintain his or her own link provider and source.

In another scenario, certain links of a given link type are coming from PTC Integrity. However, it is not possible to store links „from the outside” to PTC Integrity. A possible solution is to create an additional link source, say, a YT file, and configure an appropriate link provider.

In the Link Types tab, configure which artifact types are to be linked to each other in YT. To do so, please select

  • the involved artifact types, i.e. the types of the artifacts which are going to be link ends,
  • an optional classification, and
  • optional artifact roles.

In the Link Type Configuration area at the bottom of the tab, you can create mappings for the link type selected in the Link Types table. Each mapping defines a way to derive links of the given link type. For each mapping, you can define the data access from which to derive links. The value <implicit> assigns no data access.

You can optionally configure the mapping by using a textual configuration language that is specific to links of the selected data access. You can edit the mappings in the detail area in the tabs under the Mapping caption in the detail area. Alternatively, you can edit each mapping in a separate dialog that opens when you double-click the title of the tab. You can open several of these dialogs at the same time.

Depending on the language, you might be able to refer to custom attributes of the link type. You can configure the list of custom attributes on the left side of the details area.

The Active column in the Link Types table shows whether any mappings are active for the respective link type. This depends on the activation status of the referenced data access: If it is not active, the corresponding mappings of the link type will also not be available. The Active column for a link type shows a green check mark if all mappings of the link type are active. If no mapping is active it shows no check mark. In all other cases, i.e. at least one mapping is inactive and at least one mapping is active, it shows a grey check mark.

Section "Connecting YAKINDU Traceability to various tools" describes the configuration of specific link types associated with their respective adapter.

Assigning a link classification

Link classifications can be configured to make the meaning of links more clear. A sample classification is „refines”, shown in the second screenshot below. You can assign a classification to a link type by selecting it from the Classification drop-down menu in the Link Types table.

The elements shown in this drop-down list are individually configurable. If you wish to add classifications, click on the Edit Classifications button above the table in the Link Types tab. If no classification exists yet, the Add new classification dialog opens, asks for a new classification name, and then you should proceed as described below.

If any classifications exist already – and if it is the just-added first one only – the Edit Classifications dialog lets you add, edit and remove classifications.

Assigning artifact roles

In order to make the meaning of artifacts more clear if they get linked, artifact roles can be configured. You can assign a role for both artifact types, respectively, that are involved in a link type. Roles can be selected via drop-down menus in the Role A column and the Role B column.

The elements shown in this drop-down list are individually configurable. If you wish to add roles, click on the Edit Roles button above the table in the Link Types tab. If no role exists yet, the Add new role dialog opens, asks for a new role name, and then you should proceed as described below.

If you wish to add new roles press the button „Edit roles” above the table. If no role exists a simple dialog opens where you can add a new role after entering its name.

If any roles exist already – and if it is the just-added first one only – the Edit Roles dialog lets you add, edit and remove roles.

Configuring custom attributes for link types

Some link types are supporting the mapping of custom attributes to values defined in the textual configuration of the link type.

To create such a mapping, define custom attributes in the Link Type Configuration area of the Link Types tab. There are two ways to create them:

  • Manually create a new attribute via the „plus” icon below the Custom attributes label. In the Mapping area you can reference the added custom attribute.
  • Alternatively, reference non-existing attributes in the Mapping area as if they existed. Then click on the „update” icon below the Custom attributes label. All mapped attributes that are not yet contained in the custom attributes list will be added to it.

Displaying views in YAKINDU Traceability

When you have set up your project and your environment, various views help you to perform different use cases. In general, we are distinguishing between two perspectives: the Traceability perspective allowing to work with links, and the Analysis perspective allowing to analyse the traceability data. These perspectives can be opened by navigating to

Window → Open Perspective → Traceability

or

Window → Open Perspective → Other → Traceability

In the different perspectives, views help you to perform different tasks. The following YT views are available:

  • YT Dashboard
  • YT Editor
  • YT Explorer
  • YT Favorites
  • YT Issues
  • YT Overview
  • YT Selection History

They can be opened by selecting

Window → Show View → YT …

or

Window → Show View → Other → YAKINDU Traceability → YT …

in the main menu, where represents the name of the particular view.

Linking artifacts of the development process

The YT Editor is used to manage trace links. You can create, update and delete links by means of this editor. It has the two tabs, Link and Artifact. While the Link tab addresses management of links between arbitrary artifacts, the Artifact tab focuses on the set of links from or to one dedicated artifact.

In the Link tab, a specific link can be created, updated or deleted. For your convenience, it is also possible to create a plurality of links within one step.

The tab has the two areas Artifact A and Artifact B holding the artifacts to be linked (in create mode) or the artifact belonging to the link that should be changed or deleted (in update mode). The mode (create or update) is reflected in the tab heading.

In create mode, the editor supports the creation of links in various cardinalities:

  • Creation of a single link between two artifacts. In this case, both the area Artifact A and the area Artifact B contain one of the artifacts to be linked.
  • Creation of a plurality of links from one artifact to several other artifacts, i.e. the creation of links with cardinality one to many. This happens if one area contains exactly one artifact and the opposite area contains more than one artifact.
  • Creation of a plurality of links between two sets of artifacts. If both areas contain more than one artifact, YT creates the Cartesian product of links, i.e. it creates a link between each artifact in area Artifact A and each artifact in area Artifact B. This way, a large number of links can be created very easily. To prevent accidental use of this feature, a warning will be shown when both areas contain more than a single link.

Usually, all artifacts within one area must be of the same type. You can remove this constraint by checking the preference option „Allow link creation for multiple links at once”. However, this requires that for all combinations of one artifact in section A and one artifact in section B there is exactly one writeable link type. For example, when for a combination of artifacts there are two link types that allow linking them in both directions, exactly one of them must be writeable.

If you create several links of different link types at once, a dialog is displayed that shows which artifacts will be linked via which link type.

Populating the artifact areas

An artifact can be put into an area

  • by searching for it by its type in a dedicated search dialog,
  • by setting it by selection,
  • or by using „drag and drop” to drag it from another part of YT into the chosen area. You can also add several artifacts at once in this way.

To support fast and easy creation of a larger number of links, several search dialogs can be opened at once. These dialogs remain open after each link creation.

When creating or updating a link, the editor shows the appropriate link type. If the link type is not assignable clearly (e.g. because there is more than one matching link type defined in the YAKINDU Traceability configuration), the editor asks you to choose one matching type before updating or creating links.

The above image shows the link tab and its controls.

  1. Heading signals that the Editor is in create mode.
  2. The magnifier opens an artifact search dialog.
  3. The clear icon resets the editor completely.
  4. Select a link type here.
  5. It’s possible to add artifacts from the clipboard here:
    • Select the artifacts in the originate editor / tool.
    • Clicking this icon launches an implicit search within YT for the artifacts matching clipboard content. YT then adds the artifacts to the area.
      • You may want to adjust the artifact type which is a criteria for the search by selecting it from the list which shows up after a click on the black triangle symbol next to the clipboard symbol.
      • In Edit Link mode, YT will only add the first artifact from the clipboard to the area.
    • Note: Pasting of artifacts is supported by adapter types PTC Integrity and Microsoft Word. Please refer to the reference documentation to find out how pasting is supported.
    • As a general rule, Traceability avoids duplicates. The tool won’t add an item to an area twice.
    • Here’s an example: Let’s say there is an artifact type Requirement of type Microsoft Word
      1. Copy a portion of text out of a Word document
      2. In the YT Editor, choose Requirement as type to paste (by means of the black triangle)
      3. Click on the Paste button of appropriate area (i.e. the button with the clipboard icon)
      4. YT then analyzes the content of the clipboard, identifies all artifacts that had been selected and adds them to the area.
  6. The crosshair at the top of an area adds the currently selected artifact to that area.
    „Currently selected” means either the artifact representation had been selected in YAKINDU Traceability (e.g. in the YT Explorer or in the YT Overview) or the actual artifact had been selected in its „natural” editor / viewer.
  7. The red x removes an artifact from an area.
  8. Hitting this buttons creates the link(s). In the above example, two links ( from AAD to Cutter and from AAD to Altimeter ) are created.

Find below detailed descriptions of the tasks of how to create / edit / delete a link.

The Artifact tab

In this tab, all links to and from a specific artifact can be edited at once, i.e. the artifact can be replaced by another artifact in all existing links at once. This tab also supports the deletion of all links to or from that artifact at once.

The controls of the tab are

  1. The clear icon resets the editor completely.
  2. This artifact is about to be replaced in all links.
  3. The list of artifacts our replacement candidate is linked to.
  4. Select a link type here.
  5. The magnifier opens an artifact search dialog to select a replacement.
  6. Delete all links to/from the artifact (in this case: 3 links).
  7. Replace artifact in all links (in this case inactive because no replacement has been chosen yet).

To edit all trace links of an artifact at once (i.e. to open and populate the artifact tab), you can select Edit All Links in the context menu of an artifact in the Tracing Explorer.

You can also use „drag and drop” to drag an artifact with editable links from another part of YT into the corresponding area of the Artifact tab. In the same way you can choose a replacement by dragging an artifact into the replacement area.

The creation of links is possible by means of the YT Editor’s Link-tab. It is possible to create links between artifacts of the trace model in cardinalities one-to-one, one-to-many and many-to-many. In this step-by-step example, we will create links between an Architecture artifact and two Design Specification artifacts at once. For more details, refer to section The Link tab.

Prerequisite: In order to create links between artifact of types A and B ( Architecture and Design Specification in our case), there must be an appropriate Link Type defined in the YAKINDU Traceability configuration. Further, this link type must have a writeable data access assigned. The creation of link types and the assignment of data accesses is defined in chapter YT Configuration.

The overall process of link creation by means of the YT Editor is illustrated in the image below:

  1. Select artifact(s) for link end A. Please note: For your convenience, YT supports the creation of multiple links at once by adding multiple artifacts in area A or B, or both.
  2. Select artifact(s) for link end B.
  3. Choose the link type. This step is required only if there is more than one link type defined in the YT Configuration matching the type of the artifacts in area A and B.
  4. Clicking the Create button finally creates the link(s).

Selecting an artifact (steps 1 and 2) can be done in different manners

  • Find artifacts by means of the Artifact Search (click the magnifier icon to open the search dialog) of the YT Editor.

    1. Choose the type of the desired artifact.
    2. Select the artifact(s) you want to link in the Matching Artifacts section.
    3. Optionally, define a filter for the tree to find you artifacts faster.
    4. Add the selected artifacts to either area A or B.
    5. Close the dialog. Note: YT provides you extra support for rapidly creating a larger number of links:
      1. The Artifact Search dialog remains open after having added artifacts to the editor. It must be closed explicitly.
      2. It is possible to have multiple Artifact Search dialogs open at the same time.
      3. In the Artifact Search dialog, you can add all currently selected artifacts to your YT Favorites by clicking on the Add to favorites button. The YT Favorites are a list of frequently used artifacts for easier access.
  • Add the latest selected artifact to area A or B by means of the crosshair icon above the area.
  • Paste the ID of the artifact from the clipboard by means of the clipboard icon.
  • Add an artifact from the YT selection history.
  • Add artifacts via „drag and drop”, i.e. use the mouse to move one or several artifacts from other parts of YT into one of the areas of the YT Editor.

If you enable the preference option „Allow link creation for multiple links at once”, you can add artifacts of different types to both sections, provided that all can be linked according to the current configuration. The image below shows an example where an XML artifact and an Excel artifact are both linked to two C artifacts. The YT Editor displays a warning to prevent accidental use of this feature.

If you press the „Create” button to link artifacts of more than one type, YT displays the confirmation dialog shown in the below image. It provides a detailed list of the links that will be created. Also it shows you the total number of links that will be created and the number of Link Types involved.

YT confirms the successful link creation in the YT Editor.

For a detailed description of the YT Editor, refer to chapter YT Editor.

As one may expect a link to be edited has to be selected first. This is done using the YT Explorer. The way one can edit a link out of the YT Explorer depends on the chosen Group By option in the Traceability menu. In this example we use the Artifact Type Group By option to edit a link between a Test Result artifact and a Specification artifact.

In the YT Explorer each artifact can be right clicked to open a context menu. This context menu differs depending on the Group By option, but always offers actions regarding the objects related to this artifact.

For our example we’d like to edit just a single link (Note: The Edit All Links action can be used to e.g. replace an artifact in all links from/to that artifact. This task is not covered here, but in the description of the Artifact tab ).

After selecting the link to be edited in the context menu, the YT Editor is opened in Edit Link mode, showing the selected artifacts and the link type.

Editing a link usually means changing either side of the link (which also may imply a change of the link type). To relocate one side of a link to another artifact, it might be necessary to remove the former artifact first. This is done by simply clicking on the little red x. As described in section "Creating a link", there are many ways to select an artifact. This time we will use the Add Selected Artifact function of the YT Editor as it is illustrated in the image below.

  1. Select an artifact (of the correct artifact type) in the YT Explorer or YT Overview
  2. Add artifact by means of the crosshair icon in the YT Editor. (If the selected artifact is of the wrong artifact type, the icon is disabled.)
  3. Commit the changes by pressing the Update button.

Finally, YAKINDU Traceability confirms the update by a success message in the YT Editor. The editor changes back to Create Link mode.

The steps to delete a link are quite similar to those to edit a link. There are two ways to delete a link:

  • Delete a link by selecting the appropriate action in the context menu of the YT Explorer

  • Choose to edit a link in the YT Editor (as described in above chapter), but instead of Update , Delete the link.

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 right 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 Enterprise Architect adapters. Currently, „R Module A:2” is in the Artifact B section of the YT Editor (not shown here). Thus, both icons are disabled for this artifact. Since „R Module A:3” has the same artifact type, it may only be added in the B role. Artifacts of other types (in this case of type „EA Java Classes”) 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 „Requirements (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 two 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. The other 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”. New artifacts will always be added to the top of 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 pressing the „X”-Icon in the tool bar 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 withing 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.

Browsing existing links

YT Explorer

The YT Explorer can be used to navigate over traces and artifacts in a tree view. It also provides access to several traceability functions like filtering and reporting over its menu. Expanding the tree shows artifacts related to the traces. The tree is pruned in order to avoid cycles. A double-click on an artifact shows it in its origin editor. By default, the YT Explorer displays only linked artifacts, but it can be configured to also display unlinked ones.

In the YT Explorer tree, you can select one or more artifacts. Selecting multiple elements is useful to populate the YT Editor or YT Favorites views quickly, or to delete multiple links at the same time.

Note: For performances reasons, the action „Select All” (Ctrl + A) will not select the entire tree when the number of expanded elements is too high. The exact behavior of this action is undetermined in this case. The only guarantee is that this action will select all items currently visible (on screen), plus a few more. The same goes for multi-selection via „Shift + Click” or „Ctrl + Click”, which may not select the entire range of elements when there are too many elements.

Show links based on different groupings

The menu provides access to several grouping modes.

  • Artifact type (undirected), default: Displays traces grouped by artifact types without regarding the link direction.
  • Artifact type (directed): Displays traces grouped by artifact types, taking the direction into account (from A to B). Each artifact that is linked as A can be expanded to show the artifacts that are linked to it as B.
  • Link type: Displays traces grouped by link types.
  • Resource: Displays traces grouped by resources.

By default, the YT Explorer shows only linked artifacts (i.e. artifacts with at least one incoming or outgoing link), regardless of the chosen grouping. By activating the toggle „Show Unlinked Artifacts” in the menu (or by pressing the corresponding tool bar icon), you can display also unlinked artifacts (i.e. artifacts without any incoming or outgoing link). Note that this can incur a significant performance penalty when there are many unlinked artifacts. Unlinked artifacts are marked with the same symbol that is used for the „Show Unlinked” toggle. For the grouping mode „Link type”, no unlinked artifacts are shown independent of the toggle state.

Filter the displayed links

The YT Explorer provides two means to filter the content:

  • A fast textual filter that considers artifact names only
  • Means to configure and save filter configurations which consider attributes of the link type and the artifact type as they are defined in the YT Configuration, e.g. link types, artifact types etc.

Textual filters

Textual filters can be defined in the text field at the top of the YT Explorer. If a textual filter is set, the Explorer shows only artifacts (and the belonging links) with a name that conforms to that filter. Note that you need to hit enter in order to confirm your filter. Entering a blank (empty) text or a click on the rubber icon clears the filter.
The Regexp checkbox controls whether the entered text works as a plain text filter or as a regular expression:

  • A plain text filter matches if the name of an artifact contains the given text. It is not case-sensitive.
  • A regexp filter matches if the identifier matches the given expression. Don’t forget the .* prefix or suffix if you expect matches not only at the beginning or ending of the name.

Configurable filters

Configurable filters provide a lot of possible filter criteria. These criteria can be easily combined by and and or. Such filters can be saved and shared.
In order to manage filters, open the Filter Editor, which is accessed by clicking Configure Filter in the YT-Explorer menu.
Here filters can be created , deleted , imported from files , and exported to files .
A configurable filter evaluates attributes of a particular artifact (similar to Textual Filters) and/or of the artifact type and the link type as they are defined in the YT-Configuration. Such filters may be combined of criteria as follows:

  • Artifact: Name, Data Source (e.g. the name of the file which contains the artifact)
  • Link Type: Classification, Role of Artifact A, Role of Artifact B
  • Artifact Type: Name, Category

If the filter SR2AD from the above example is applied to the YT-Explorer, the Explorer will only show links from artifacts of type System Requirement to artifacts of type Architectural Design.

Note that you have to re-apply a filter if you changed the filter configuration.

Synchronize selection

The YT Explorer can be put into synchronize selection mode. If the mode is activated, the YT Explorer will listen for selection events and if a artifact is selected that has trace links, only the related artifacts will be displayed. This mode can be activated by clicking in the toolbar or by selecting Synchronize Selections in the menu.

YT Overview

The YT Overview displays a live impact analysis graph by showing artifacts that are related to the current context. A double-click on an artifact-node in the graph opens the artifact in its corresponding editor.

The zooming can be adjusted by the icons Zoom in, Zoom out, Zoom to fit, Zoom to original size, Auto Zoom to fit in the toolbar of the Overview.

The menu provides means

  • to set the depth of the shown graph
  • to switch the context definition
    • Current selection: The Overview calculates a graph consisting of the latest selected artifact as „root” and all artifacts linked to this root with a distance that is not longer than the chosen depth
    • All traces: The Overview shows always the whole trace graph. Selection and depth are not considered.
  • to display only directed links (outgoing from the selection, until the specified depth), or to display all links (incoming and outgoing)
  • to define an exclusion filter. This is a blacklist of artifact types. Artifacts of these types won’t be shown in the Overview.

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 three kinds of validations:

  • suspicious links validation
  • model consistency validation
  • configuration consistency validation

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.

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 those 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. These information have been gathered before and reside in the link now. Such links are typically stored locally, e.g. in a YT file, see section "Link storage types". 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 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. Consider a link type which maps with a mapping can map attributes of both link ends to cells in the Excel file. If the content in the cell and the attribute differ the link is suspicious.
  • 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.

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.

Model consistency

YT uses a core model that includes all trace data. To maintain a valid model, YT offers an option to check 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.

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.

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

Analysing the traceability status / coverage analysis

YT offers a dedicated analysis perspective that offers a set of powerful tools to evaluate your project, determine its status, calculate the impact of change, or prepare meaningful management reports.

The perspective contains of two major parts. The YT Dashboard, which provides a graphical overview of commonly used metrics. And the YT Query View that allows to run prepared arbitrary queries against the trace model

YT Dashboard

The YT Dashboard displays information concerning traceability data for the current project. It is possible to view information about the artifacts and the links that were created so far.
By choosing an element from the combobox in the top left corner of the YT Dashboard view, it is possible to change the data for the diagram:

  • Trace links: Shows all available links sorted by the configured link type
  • Linked Artifacts: Shows all available linked artifacts and candidates sorted by the configured artifact type

If the selected option has data to show a pie chart will be displayed in the center of the view. Also there is a counter behind each option which indicates the amount of found links/artifacts.
If no data is available for the current option, a notification will be shown in the center of the view.

It is possible to show a legend or labels for each pie chart section by checking one of the checkboxes at the top right corner of the view.

The pie charts and the corresponding legend are interactive. You can click on any pie section, to explode it, or on any legend item to highlight it. A click on a pie section influences the highlighting/dimming of the corresponding legend item and vice versa.

The labels in the pie chart have the following format: {1} : {2} ({3}%)

  • 1 name of the artifact-/link type
  • 2 amount of artifacts available for the artifact-/link type
  • 3 percentage distribution of the artifact-/link type in relation to all artifact-/link types

A tooltip is available for every pie section and every legend item by hovering over an item (pie section / legend item). A tooltip has the format as mentioned above.

YT Dashboard Details

The YT Dashboard Details view is linked to the YT Dashboard. The connection between these components is visible, if elements are selected within the YT Dashboard. All selected items will be displayed in a table inside the YT Dashboard Details view. This table provides information about the selected elements (artifact- and link types) like the types of the elements, the names and the original tool of the corresponding artifacts or links.
Each of the mentioned views does also have a hint for interacting between each other. Thus, if the YT Dashboard has selected chart- or legend items, the dashboard provides a clickable hint ( show details ) displayed besides the mentioned combobox. In case the YT Dashboard Details view is closed, it will be opened to view the details for the selected dashboard item. Otherwise YT Dashboard Details view gets the focus. If the YT Dashboard has no item selected or is closed but the YT Dashboard Details view is opened, the YT Dashboard Details view provides a clickable hint ( open YT Dashboard ) to either open or set the focus to the dashboard view.

The YT Dashboard Details view provides a „copy to clipboard” button at the right side of the view. If the table is filled with content, the button provides the possibility to copy the table content (each column is separated by a tabulator) into the clipboard. The clipboard-content can also be filtered by selecting the needed table rows before pushing the button. The clipboard can also be filled by pressing Ctrl+C on the keyboard.

Query View and Query Results View

The YT Query view and the YT Query Results view provide means to create, edit and execute queries and view their results. Queries are stored in query files (extension .query). Any query file may contain multiple independent queries. The YT Query view presents them in a tree structure where each individual query is listed below the file it is defined in.

Double-clicking a query file will open the file in the query editor, while double-clicking a query will execute it immediately. Alternatively it is also possible to use the context menu or the control buttons at the top of the view to achieve the same. Note that queries have no side effects and will never manipulate the data they are executed on.

YT comes with a set of predefined queries that are read-only. In order to create a new query file, click on the green + icon at the top of the YT Query view (alternatively use the context menu). This will open a simple file creation wizard asking for name and location of the file. You may add as many queries as you need, but it is advised to maintain different queries in different files, depending on their purpose and semantics.

After executing a query, the results are shown in the YT Query Results view. Note that some queries may take some time to execute, based on their complexity and the size of your data model. A progress bar will inform you about the status of the query execution. Results are tagged with a timestamp which makes it easy to compare results of repetitive executions over time.

Queries are expressed in the YT query language.

Exporting query results to Excel

By default, query results are displayed in the YT Query Results view. However, it is also possible to export these results directly to an Excel spreadsheet. There are several ways to achieve this:

  • From the YT Queries view: In the context menu of the query, select Export query results to Excel.
  • From the YT Query Results view: Click on the toolbar button Export query results to Excel.
  • From the Traceability menu: Select Reporting → Export query results to Excel.

In any case, you will be prompted with a dialog asking for some parameters:

  • Query: The query to execute. The results of this query will be exported to an Excel document.
  • Output format: Select the Excel document format, either .xlsx or .xls. However, please see option Report name below.
  • Add sheet to existing report: If this option is selected, the report will be added as a new tab to an existing Excel document.
  • Create new file: If this option is selected, a new Excel document will be created. If the target document already exists, you will be asked for confirmation before overwriting the file.
  • Report folder: The folder a new Excel file will be created in, or the folder containing an existing Excel file to overwrite or to append a sheet to. The folder must be located in the current workspace.
  • Report name: The name of the report. This corresponds to the name of the Excel file that will be created or modified. It may optionally contain a file extension, i.e. .xls or .xlsx, in which case the Output format option will be ignored. If no file extension is specified, the value will be derived automatically from the Output format option. If you selected a valid Report folder already, the drop-down menu will show the existing Excel files in that folder. This makes it easier to select a document to replace or modify.
  • Open created report: Check this option to open the created report in Excel after the query results have been successfully exported.

Please note: If the Excel document is already open in Excel, YAKINDU Traceability may not be able to write the file. In this case, a dialog will ask you to close the file in Excel and retry.

Creating reports

The report wizard can be accessed by navigating to the menu entry

Traceability → Reporting → Create report

The default report shows simple traceability statistics only. Further reports (e.g. coverage analysis report) have to be implemented by the end users. The reporting is based on Eclipse BIRT (Business Intelligence and Reporting Tools). Reports can be designed with the BIRT WYSIWYG Designer. YT comes with data access drivers for BIRT to provide convenient access to traceability data.

In the above example a coverage report is designed that shows User Requirements without System Requirements. Coverage analyzes are calculated by joining and filtering corresponding data sets.

During the design of reports often all possible artifacts of a specific type are required. These sets are called candidates. The figure below depicts the meaning of candidates.

Creating a snapshot

YT can export the configuration and the data as a graph. The export is a GraphViz dot-file that can be rendered with GraphViz. The files are generated by navigating to the menu entry

Traceability → Export → Export Configuration

or

Traceability → Export → Export Data

Below are example conf and data exports.

GraphViz can be downloaded at http://www.graphviz.org/..

Connecting YAKINDU Traceability to various tools

The following sections are giving you a detailed overview on how to configure YAKINDU Traceability in order to connect it to a variety of specific tools. For basic concepts, please have a look at section Configuring your traceability environment.

Common concepts

The configuration of each adapter is adapter-specific, but some concepts are common.

The keyword resource is always followed by a pattern that denotes one or more files or folders in the Eclipse workspace. Generally a resource pattern is composed as follows:

/project_name_pattern/folder_name_pattern/folder_name_pattern/filename_pattern

That is, a resource pattern

  • starts with a /,
  • followed by an Eclipse project name pattern,
  • followed by zero or more folder name patterns,
  • followed by zero or one filename pattern.

The sequence of these components constitutes a resource_path, also simply called path. Adjacent path components are separated by a slash character ( /) from each other.

Each of these pattern may contain the wildcard characters * or ?. These characters are placeholders representing actual characters in project names, folder names, or filenames, respectively. The asterisk ( *) stands for a sequence of zero or more characters, a question mark ( ?) is a placeholder for exactly one character. A resource pattern may be matched by multiple actual resources, constitution a resource set. Generally a resource pattern is resolved to zero, one, or more than one actual resources.

Examples:

resource /de.itemis.pedelec.implementation.control/readme.txt
resource *.txt
resource /de.itemis*/readme.???

The first example specifies exactly one file.

The second one specifies all files (or folders or Eclipse projects) whose names are ending with the characters .txt.

The third example pertains to all projects starting with de.itemis. In these projects, the resource pattern matches all file in the top-level folder beginning with readme. followed by a three-characters extension, like e.g. doc or txt. Please note that extensions like docx or c do not match the pattern.

Attribute mapping

Data access

The attribute mapping data access derives links between artifacts based on their attributes. The metaphor is a relational database foreign key definition.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Attribute Mapping from the Type drop-down list.

Within the configuration panel no further configuration will be done. Instead, the link type provides means to map artifacts using keywords, see section Link type.

Example:

YAKINDU Traceability can derive links based on the attributes of the artifacts.

Please find below the required steps to specify such a derivation rule, followed by a detailed example.

Supported keywords:

  • in – „In” operator to use within a condition.
  • Functions: As an option, it is possible to define one (or more) functions to apply to the value of an attribute.
    • separatedby – a separator that separates identifiers in a list, e.g. requirement IDs that can be linked to IDs in a cell of an Excel document.
    • substringBefore - keeps only the part of the value before the first occurrence of a given string.
    • substringAfter - keeps only the part of the value after the first occurrence of a given string.
    • match - Specify a regular expression with exactly one group. Only the matched group will be preserved in the result.
    • replace - Specify a regular expression with any number of groups. The second parameter indicates a replacement string, in which groups matched by the regular expression can be reused.
  • where – Specifies which attributes are relevant for the identification of an artifact linked to an element.

Prerequisites:

  • Activate YT’s link derivation by specifying an attribute mapping data access.
  • Define the artifact types you want YT to derive links for. Since the link derivation derives from attributes of artifacts, these artifact types require attribute definition.

Definition of a link type which includes link derivation:

  • Define a new link type which uses the desired artifact types as artifact type A and artifact type B.
  • Assign the attribute mapping data access, i.e. the data access mentioned in the prerequisites.
  • Within the link type definition, configure the derivation rule. The syntax is similar to the definition of a database relation. The syntax is
    • where A. attribute in B. attribute or
    • where A. attribute in B. attribute.separatedBy(",")
  • If you don’t want to compare by exact value match, you can use some additional functions to modify the value of the attribute(s) of A and/or B before comparing them. For example:
    • where A. attribute.substringBefore("/") in B. attribute.substringAfter("/")
      • If A. attribute equals „Some text not relevant/Relevant part” and B. attribute equals „Relevant part/a comment that should be ignored”, a link will be created between A and B
    • where A. attribute.match("prefix to ignore(.+)suffix to ignore") in B. attribute
      • The regular expression must contain a single group (Identified by the parenthesis: (.+)). Only the substring matching this regular expression group will be retained. If the value of A. attribute is „prefix to ignore, some text to preserve, suffix to ignore”, the result of the expression will be ", some text to preserve,"
    • where A. attribute.replace("([a-zA-Z]+) ([0-9]+)", "$2_$1") in B. attribute
      • $1 and $2 are references to the matched regular expression groups (Group 1 and Group 2). If A. attribute is equal to „SomeText 332”, the value of $1 will be „SomeText” and the value of $2 will be „332”. Thus, the result of the expression will be „SomeText_332”
  • These functions can also be combined in various ways:
    • where A. attribute.substringAfter("PrefixToRemove").substringBefore("SuffixToIgnore") in [...]
      • If A. attribute is equal to „PrefixToRemove Text to preserve SuffixToIgnore”, the result will be „Text to preserve”
    • where A. attribute.separatedBy("/").substringBefore(":") in [...]
      • If A. attribute is equal to „A:1/B:2/C:3”, the result will be a list of 3 values [A, B, C]
    • where A. attribute.separatedBy(",").separatedBy(";") in [...]
      • If A. attribute is equal to „A,B,C; 1, 2, 3; X, Y, Z”, the result will be a list of 9 elements: [A, B, C, 1, 2, 3, X, Y, Z]

Example:

In this example, we will configure YT to derive links between requirements defined in a ReqIF file and requirement details defined in a Microsoft Excel file.

The derivation is based on references in Excel: Each requirement detail in Excel has a cell containing a comma-separated list of associated ReqIF requirements. To match the identifier in the list to the specific ReqIF requirement the contents in the Excel cell is traversed. The comma serves as separator to find out where the next identifier starts.

  • Activate YT’s link derivation



Find a detailed description here.

  • Definition of artifact type Requirement (incl. custom attributes)

  • Definition of artifact type Requirement Details (incl. custom attributes)

  • Definition of a link type linking Requirement and Requirement Details
    • … using the attribute mapping data access
    • … and having a derivation rule.

Links of this link type will never become suspicious.

Eclipse Artop

Artifact type

Configuration

Supported options:

  • subset metaclass – Filter elements by meta class.
  • subset namespace – Filter elements by namespace.
  • resource – File filter pattern.

Example:

resource /*.arxml
subset metaclass system.System
subset metaclass system.SystemMapping
subset namespace "Project.YourSystem_System"

A list of available meta classes can be opened by content assist (pressing [Ctrl+Space] after the space behind ‚metaclass’).

The namespace is the . delimited list of names from the root. In this example all GIdentifiable elements under the package Project in the system YourSystem_System are relevant. Each matched element has to match one of the metaclass subsets and one of the namespace subsets, if the latter are set.

For the example above and the model illustrated below, leads to the shown results in the search dialog.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Browser

Artifact type

Configuration

No configuration available yet.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse C/C++ (CDT)

Data access

The Eclipse CDT data access provides access to C and C++ artifacts such as translation units or functions. It allows to store link information invasively, i.e. within comments in C or C++ files.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Eclipse CDT from the Type drop-down list.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing the C/C++ files relevant for traceability.

Supported keyword:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions. In this case, YT takes the union of all patterns into account, i.e. the resource expressions are evaluated with a logical OR.

Independent of the definition of a resource, YT only takes files with suffixes .c, .h, or .cpp into account.

Please note that the resources have to reside in an Eclipse C/C++ project.

Example:

In this example, YT evaluates all .c and .h files in the folder named source in the com.yakindu.yt.mt.c project.

Artifact type

The C/C++ artifact type recognizes C/C++ elements such as translation units, include statements or functions in a specified set of relevant files. It does not recognize single statements within a function.

As rule-of-thumb, YT recognizes all elements that do appear in the Eclipse CDT’s outline view for C/C++ files.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Artifact Types tab.
  • Add a new Artifact Type.
  • Assign an Artifact Type Name, pick a color and a category.
  • Pick Eclipse CDT from the Adapter drop-down list.
  • Add a configuration by double-clicking on the + icon at the bottom.
  • Select your previously configured Eclipse CDT data access.

Supported keywords:

  • model elements – The list of C/C++ element types to recognize as artifacts. An explicit comma-separated list of types can be specified, or one of the following keywords can be used for a predefined list of types:
    • all – Includes all C/C++ element types
    • default – Includes this default subset of C element types: translation unit, function, function declaration. model elements default is equivalent to an empty configuration.

Examples:

model elements default
model elements all
model elements Include, Macro, TypeDef

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YAKINDU Traceability is able to recognize link information in C/C++ files, based on a portion of C or C++ code, like

/* @Req1234 */
void someOperation(Foo * param)

YT supports link maintenance both in the C/C++ code and by YT, i.e. on one hand the user can create/delete links by editing the C/C++ comments, on the other hand YT manipulates comments in the C/C++ code, as links are created/deleted in YT.

To configure the C/C++ access the configuration of both a Eclipse CDT data access and at least one link type using this data access are required.

The actual configuration of how to find the comments and how to derive the linked artifacts' identifiers from these comments is done in the link type configuration.

The configuration covers:

  • … as block|line comment – Determines whether YT creates block or line comments for new links.
  • analyze comments of … – Which artifact type represents the C/C++ artifact. Possible values are A and B.
  • create links by … – This section specifies how YT calculates the content of new comments on link creation. The specification is a concatenation of static strings and values of artifact attributes.
  • locate links by – A regular expression for the text portion in comments in C/C++ files representing a link. YT relies on Java regular expressions.
  • map { … } – As an option, it is possible to define link attributes and derive the attribute values similar to the identifier derivation specified by identified by.
  • where – Specifies which attributes are relevant for the identification of an artifact linked to a C/C++ element.
  • filtered elements – Specifies how to deal with link comments on filtered elements. Possible values are:
    • Delegate – Create a link from the first unfiltered parent element (or ignore if there is no matching parent). This is the default behavior.
    • Ignore – Always ignore link comments on filtered elements. No link will be created for such ignored comments.

In the where sections it is possible to add several rules to match groups in the regular expression specified by locate links by to attributes of the relevant artifacts. A rule is expressed by an equation of the form LeftHandSide = RightHandSide . The LeftHandSide is a concatenation of static strings and groups to the regular expression, the RightHandSide is a concatenation of static strings and values of artifact attributes and/or artifacts metadata identifier and resource. For a link, each of these expressions must match, i.e. they are linked by logical AND.

The above example shows a configuration for a data access of type Eclipse CDT. Given the comment /* @Req1234 */, YT creates a link from the C element holding the comment and Requirement Detail 1234.

YT assigns the value @Req1234, i.e. the whole match, to the wholeMarkup attribute. On link creation, YT concatenates @Req and the ID of the linked Requirement Detail, and then writes a block comment with this information.

Again, the example shows a configuration for a data access of type Eclipse CDT. Given a comment //@MYSHEET:A4, YT creates a link from the C element holding the comment to an artifact with attributes sheet="MYSHEET" and cell="A4". In this case, YT doesn’t populate any link attributes. On link creation, YT concatenates "@" + value of B.sheet + ":" + value of B.cell, and then creates a new line comment.

  • YT recognizes comments anywhere in a C/C++ file.
  • On one hand YT is able to find multiple matches in one comment, on the other hand YT creates a new comment for each new link. YT does not expand existing comments.
  • A new comment is always written in the line above the linked element.
  • YT recognizes the C/C++ elements visible in Eclipse’s outline view, i.e. files (translation units), operations, includes, macros, etc. YT does not recognize any C elements within operations, e.g. statements.
  • Comments are assigned to C/C++ elements according to the following rules (by order of priority):
    • A sequence of comments (i.e. not separated by an empty line) at the very beginning of the file (i.e. not preceded by an empty line) belongs to the translation unit.
    • End-of-line comments belong to the last element on that line.
    • A sequence of comments directly preceding an element belong to that element. The comment must be either on the same line or on the previous line, i.e. there must be no empty line between the comment and the following C/C++ element.
    • A comment inside a function belongs to the function.
    • The comment belongs to the translation unit.
  • Comments are always mapped to exactly one element. If several rules match for the same comment, the first rule has a higher priority, according to the aforementioned order. If the comment is assigned to a filtered element, the result will depend on the configuration: The comment will be assigned to the first unfiltered parent of this element if the configuration is set to „delegate”. It will be ignored otherwise (i.e. no link will be created for this comment).
  • If a link is deleted by means of YT, YT removes the link information from the C/C++ comment. If the comment is empty or includes whitespace characters only after the deletion, YT deletes the whole comment. In case the line is empty, YT deletes the line.

The following example illustrates these recognition rules:

// @Req11 - assigned to TranslationUnit
/*
 * @Req12 - assigned to TranslationUnit
 */

// @Req13 - assigned to TranslationUnit

// @Req15 - assigned to include 
/* @Req16 - assigned to include */
// If 'include' elements are filtered, these comments will be assigned to TranslationUnit instead. 
// If 'include' elements are filtered, and comments of filtered elements are ignored, these comments won't be assigned to any element. 
#include "stdafx.h"

// @Req17 - assigned to TranslationUnit

/**
 * @Req19 @Req20 - both assigned to operation _main
 */
// @Req22 @Req23 - both assigned to operation _main
int _tmain(int argc, int* argv[])
{
    return 0;
}
int _tmain2(int argc, int* argv[])
{
    //@Req28 - assigned to  _tmain2
    return 0;
    //@Req29 - assigned to  _tmain2
}

struct S1 { //@Req30 assigned to S1
    field a; //@Req31 assigned to S1::a
}

//@Req32 assigned to a
int a, /* @Req33 assigned to b */ b, c; //@Req33 assigned to c

Links of this link type will never become suspicious.

Eclipse Damos

Artifact type

Configuration

No configuration available yet.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Explorer

The Eclipse Explorer adapter is used to provide artifacts (traceable files) via views.

Artifact type

Configuration

Supported options:

Example:

resource /de.itemis.*/*

The above example specifies all resources (e.g. folders, files) that are located in projects whose names start with de.itemis..

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is its resource modification timestamp.

Eclipse Java (JDT)

The Eclipse Java data access provides access to artifacts for the Java artifact provider in Java files.

Data access

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Eclipse Java from the Type drop down list.

Within the configuration panel, you can specify file patterns consisting of Eclipse projects, folders or filename patterns describing the Java files relevant for traceability.

Supported keyword:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions. In this case, YT takes the union of all patterns into account.

Independent of any resource definitions, YT takes only files with filename extension .java into account.

Please note that the resources have to reside in an Eclipse Java project.

Example:

In this example, YT evaluates all *.java files in project com.yakindu.yt.mt.java, folder name beginning with src.

Configuration

No configuration available yet.

Artifact type

The Java artifact type recognizes Java elements such as classes, methods and properties in a specified set of relevant files, but not individual statements within a method. The relevant files are specified in the Java data access. As a rule-of-thumb, YT recognizes all elements that appear in the outline view for Java-files.

Configuration

All configuration is done in the data access. An Eclipse Java artifact type does not support any further configuration.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Papyrus

Artifact type

Configuration

Supported options:

  • resource – File filter pattern

Example:

resource *design.uml

The above example selects UML elements from files whose name ends with design.uml.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse ProR

Artifact type

Configuration

Supported options:

  • name – Specifies the name of matched artifact
  • resource – File filter pattern
  • type – ReqIF specification type long name filter.

Example:

resource /de.itemis.pedelec.requirements/requirements.reqif
type "Requirement Type"
name ID + " - " + Title

The above example specifies objects from the ReqIF file /de.itemis.pedelec.requirements/requirements.reqif of specification type Requirement Type. The name is created by concatenating the attribute ID, the string -, and the attribute Title. The used attributes must exist in the defined specification type.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

Eclipse RMF

This link type maps ReqIF links to YT trace links.

Example:

file "/de.itemis.aad.requirements/requirements.reqif"

In the above example all links from the ReqIF file /de.itemis.aad.requirements/requirements.reqif are mapped to YT trace links if corresponding artifact types and trace types exist.

Links of this link type will never become suspicious.

Eclipse Sample Reflective Ecore Model Editor (SREME)

Artifact type

Configuration

Supported options:

  • resource – File filter pattern.

Example:

resource *.uxf

The above example specifies EMF elements from files with the extension .uxf.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version. This is due to an adapter bug (YT-3430).

Eclipse Text

Artifact type

Configuration

Supported options:

  • resource – File filter pattern

Example:

resource *.txt

The above example specifies text segments from files with the extension .txt.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse UML2

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace

Example:

resource /de.itemis.pedelec.design/*.eap
subset container "de.itemis.pedelec.architecture"
subset class uml.Component
subset class uml.Interface

The above example specifies UML elements of UML meta-types Component or Interface located in the UML package de.itemis.pedelec.architecture. The corresponding files are located in the project de.itemis.pedelec.design and their names are ending with .eap.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Xtext

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace

Example:

resource *.entity
subset Entity

The above example specifies Xtext elements of meta-type Entity from files whose names end with .entity.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Enterprise Architect

The YT adapter for Enterprise Architect provides access to UML elements as traceable artifacts. More than that, it is possible to derive trace links from UML relations.

Please note: Out of the box, Enterprise Architect doesn’t provide an interface for interprocess communication. To enable selection propagation from Enterprise Architect to YAKINDU Traceability, YT ships an EA plugin which is described below.

Data access

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Enterprise Architect from the Type drop-down list.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing the .eap files relevant for traceability.

Supported keywords:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions.

Example:

In this example, YT takes all .eap files residing in project com.yakindu.yt.mt.spec, folder design into account.

Enterprise Architect plugin for selection propagation

Installing the EA plugin

In order to receive notifications about selection changes from Enterprise Architect, YT ships a plugin for Enterprise Architect.

To install this plugin, proceed as follows:

  • In a file explorer, navigate to folder /traceability/scripts/ea.
  • Run the script installAddInForEA.bat with administrator privileges.

Configuring the EA plugin

The EA plugin propagates selections from EA to YT via a TCP socket connection. Apparently, for this socket connection the same port has to be configured in both YT and EA configuration.

YT:

Select Window → Preferences → YAKINDU Traceability from the main menu. Make sure the TCP Server is not disabled. Configure a port number; the default is 1234.

EA:

Select Extensions → Yakindu Traceability → Configure Socket connection from the main menu, then set the port number.

Artifact type

The Enterprise Architect artifact type provides access to the elements of those EA models that are specified in the Enterprise Architect Data access.

It is possible to restrict the number of UML elements that are visible to YT based on their meta-type, their assigned stereotypes or their namespace. You may want to see e.g. only artifacts of type Class with the stereotype <<SafetyRelevant>> in the package safety.

This adapter supports opening the artifact in EA and showing the currently selected artifact in YT.

If Enterprise Architect is not available, it is also possible to open an EAP file with the Eclipse UML2 editor. However, the UML2 model does not support all available Enterprise Architect features. If an element is not available in the UML2 model the artifact cannot be accessed without a native Enterprise Architect instance.

If the checkbox Show artifacts within Enterprise Architect on the preferences page YAKINDU Traceability → Customization is checked, YT will open Enterprise Architect artifacts within Enterprise Architect. If that checkbox is unchecked, YT will open the artifact in the last editor you used to open an Enterprise Architect file. Selecting the artifact in an editor will work only if that editor is an Eclipse tree editor like the UML2 editor.

Currently, there is an issue regarding the selection of Enterprise Architect artifacts within the UML2 editor when error markers created by the YAKINDU EA Bridge exist for the file. In this case the selection can take very long and can fail if the editor is already open. You can prevent the YAKINDU EA Bridge from creating these markers via an option in the workspace preferences: On page YAKINDU EA-Bridge, uncheck the checkbox "Report loading errors as Resource markers for the eap-file". Now loading errors will still be shown in the editor’s Problems tab, but no markers will be created. Please note that this will not remove already existing markers.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Artifact Types tab.
  • Add a new Artifact Type.
  • Assign an Artifact Type Name, pick a Color and a Category.
  • Pick Enterprise Architect from the Adapter drop-down list.
  • Add a configuration by double-clicking the + icon at the bottom.
  • Select your previously configured Enterprise Architect data access.

Supported keywords:

  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter
  • map – Attribute mappings for custom attributes.

A list of available stereotypes and metatypes can be opened by content assist. Move the text cursor to the right of the metatype, leave at least one space, and press +[Space].

While a stereotype definition requires the fully-qualified name (i.e. including the profile as shown in the example below), a simple name is sufficient for the metatype definition. Namespace in a namespace hierarchy are delimited by the . as shown below.

Note that the configuration supports multiple usages of the same keyword. For example, using the expressions subset metatype Class and subset metatype State in the same configuration means „Class or State”.

The Enterprise Architect adapter supports mapping of artifact attributes to tagged values in Enterprise Architect. For instance, the expression map attr1 to valueOf(tagKey1) maps the attribute attr1 to the value of the tagged value with the tag tagKey1.

Example

The image above shows a configuration for the Example Model shipped with Enterprise Architect. It provides all classes with stereotype <<ERD_Entity>> and/or <<ERD_Attribute>>, residing in package Domain Specific Modeling of project Project Models.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The trace links YT derives from an Enterprise Architect model are based on the Enterprise Architect data access and the Enterprise Architect artifact types configured for the Enterprise Architect adapter. The meta class and stereotype relations in the EA Model are available for mappings.

YT can derive trace links from an Enterprise Architect model in two ways. First, UML relations within the model can directly be interpreted as trace links. Second, trace links can be derived in cases where connected elements (e.g. requirements) of some element A reference other elements B within their tagged values. In this case, trace links from A to B can be inferred.

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Link Type tab.
  • Assign artifact types for Artifact Type A and Artifact Type B.
    • These types must be of an Enterprise Architect artifact type with „Enterprise Architect” as adapter.
    • If you want to derive links from and to the same artifact type, choose this type as A and B.
  • Pick a Classification (optional) and Roles for A and B (optional).
  • Add a configuration by double-clicking the + icon at the bottom.
  • Select the very same Enterprise Architect data access that has already been assigned to the artifact types A and B.

For each mapping configuration only one of the two ways mentioned above for deriving trace links can be used. Since both cases are configured very differently, the following description considers them separately.

Supported options:

  • subset metatype – Meta-type filter
  • subset stereotype – Stereotype filter
  • link source is A|B – Optionally specifies whether the link source in EA should be artifact A or artifact B of the link type. By default it is A, which means that a link in EA from an element X to an element Y will result in a link in YT from A to B. If you define the link source to be B, the same link in EA from X to Y will result in a link in YT from B to A.

A list of available metatypes and stereotypes can be displayed by content assist (pressing +[Space] right from the space right from the metatype). The list of subsets is grouped by the subset type ( metatype and stereotype) and for each present group at least one subset has to match.

Example:

In this example, YT derives a trace link from each UML association existing in the EA model between artifacts that had been specified by type EA artifacts. Refer to this example for the Enterprise Architect artifact type to see how this type is specified.

Since the example configuration does not contain link source is ..., the default is assumed, which is link source is A. Therefore, the source of the association in EA will be artifact A of the link in YT and the target will be artifact B. If instead B was specified as link source, the source of the association would be B and the target would be A.

Supported options:

  • link where … – Defines which conditions must be fulfilled to derive trace links from the tagged values of connected elements.
  • has – Specifies which type of Enterprise Architect connector should be considered for deriving trace links.
  • to – Specifies to which type of Enterprise Architect element connectors must lead to be considered for deriving trace links.
  • with – Specifies which value the tagged value of a connected element must have such that a trace link can be derived.
  • create – Can be used to specify options for creating new links.
  • in – Specifies the package in which new Enterprise Architect elements representing new links should be created.
  • with name = – Specifies the name of newly-created Enterprise Architect elements that represent new links.
  • map – Defines a list of mappings allowing to store attribute values of linked artifacts in Enterprise Architect elements (see below).
  • … based on … to … – Defines a mapping from the values of custom attributes of B or A to a tagged value or an attribute of the Enterprise Architect element that represents the linked artifact in Enterprise Architect. Between based on and to, the string to store in Enterprise Architect can be formed by concatenating attribute values of A or B and static strings. The resulting string will be stored in a tagged value or attribute that can be defined in the to clause by using the keywords valueOf or attribute. The attribute value will be stored in the specified location when creating or updating the link. Left from based on, a custom string attribute of the configured Enterprise Architect link type must be specified. When reading a link from Enterprise Architect, this custom attribute will be set to the value that is read from the location specified in the to clause. When creating or updating a link, the custom attribute will be set to the value of the specified custom attribute of an artifact.
  • valueOf – Allows to specify the tagged value to store the specified string in.
  • attribute – Allows to specify the Enterprise Architect property to store the specified string in. The supported properties depend on the type of Enterprise Architect element that has been selected in the link expression after to. All target elements support Name, Notes and Alias. Furthermore, all elements except Operation and Attribute support Status, Author, Version, Keywords and Phase. Finally, if Requirement is selected, also Difficulty and Priority are available. Note that EA might not allow to set some properties to arbitrary strings, but only to certain values that are selectable in EA via a drop-down list. Other values are ignored for these properties.
  • join {…, …} using … – Can be used to create a composed string by concatenating several other strings with the string provided after using. The strings to concatenate are passed as a comma-separated list within the curly brackets. They can be complex strings concatenated by +, including references to artifact attributes. If any of these expressions evaluates to an empty string (usually because a referenced attribute is empty or undefined) it is ignored. The string after using must be a simple string.

The configuration for this type of configuration always begins with:

link where role has connector_type to element_type with valueOf( tag) = filter

Here, role (can be A or B) defines which of the link type’s artifact type should be considered for connected elements.

YT searches the EA model for connections with the EA connector type connector_type that lead from any EA element that is an artifact of the selected artifact type role to EA elements of element type element_type.

For all of the latter EA elements, YT checks whether the value of the tag tag is equivalent to filter. Typically, filter refers to the link type’s other artifact type. YT creates a trace link from the currently considered artifact of role to all artifacts of the second artifact type for which filter equals tag.

The expression filter is a concatenation of static strings and (meta) attributes of the link type’s second artifact type. This second artifact type is B if role is A, and vice versa. You can access an attribute attr of an artifact type B by using B.attr, the identifier of B by using B.metadata(Identifier), and the resource of B with B.metadata(Resource).

You can display a list of available meta types for connectors or elements by content assist (pressing +[Space] right from the space right from has or to, respectively). Content assist right from valueOf( will provide a list of all tags of elements in the EA model. Content assist right from attribute( will provide a list of all attributes that are supported for writing.

In YT Editor, you can manually create links from EA elements to other artifacts. These will be stored in EA in the same form as described above, i.e. as a connection to an EA element with a tagged value that references the other artifact. Whenever a new link to an artifact needs to be created, YT first searches for an existing EA element that refers to the artifact via a tagged value in the form defined in the configuration. If such an element already exists, YT only creates a connection to it – starting from the EA element that is to be linked to the artifact. Otherwise, YT also creates a new EA element with a suitable tagged value, which will then be the target of the connection.

When creating a new EA element with a tagged value to reference another artifact, YT by default creates this EA element in the same package as the EA element to be linked. The name of the new EA element will be the same as the name of the referenced artifact. Both, the name of the new element and the package, can optionally be defined explicitly in the configuration. The general form of the configuration is the same as described above, followed by , create in package with name = element_name . Here, package is the package in EA (using :: as separator) to create the new element in. The expression element_name is the name of the EA element to create. It can be defined in the same syntax as the expression filter described above. Alternatively, the name can be defined by mapping the attribute „Name”. In this case, the name (like other mapped attributes or tagged values) will be updated when the link is updated or a new link is created to the element.

You can display a list of available packages to store new EA elements by content assist (pressing +[Space] right from the space right from create in. You can also specify a new package that does not yet exist. If you do, YT will ask you whether it should create that package in EA.

Example:

In this example, YT considers for each EA artifact A of artifact type A all outgoing connectors of type Realisation that lead to a Requirement. It derives a trace link for each of these requirements with a tagged value Object Identifier that is equivalent to the expression B.ObjectIdentifier. In this case, the expression only consists of one attribute of B. If a new link is created in YT, YT will first search for an existing Requirement with a tagged value equivalent to the attribute ObjectIdentifier of the target artifact. If such a Requirement is found anywhere in the model, YT will create a Realisation connection from the EA artifact to be linked to that Requirement. Otherwise, YT will create a new Requirement in the package Project Models::Analysis and Business Modeling with a suitable tagged value Object Identifier.

The map specifies that several attributes of B are to be mapped to attributes and tagged values of the target requirement. The property Name of the new requirement will be created by composing the values of the three attributes number, heading, and ObjectIdentifier of B, separated by the static string " - ". The join keyword ensures that empty attributes are ignored in this concatenation and no superfluous " - " delimiters are inserted. The result is mapped to the link attribute Name. The property Notes of the requirement will be determined by the value of the custom attribute B.text, which is also mapped to the link attribute Description. The property Alias is mapped in a similar way. Finally, two tagged values, Variant and Created By, are set based on attributes of B.

Suspicious links validation is done by re-evaluating the link’s custom attributes and comparing these values to those stored in the link. If there are any differences, the link is suspicious.

Please note:

Enterprise Architect maintains internal and external links. For suspicious links validation, only external links are taken into account.

IBM DOORS

Data access

The IBM DOORS data access allows for a flexible configuration to exactly specify which artifacts YAKINDU Traceability should import from the IBM DOORS database.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick IBM DOORS from the Type drop-down list.

The configuration panel below allows to define which native IBM DOORS projects and baselines should be fetched. The configuration language offers content assist to guide through the different options. At least one project must be supplied.

Supported keywords:

  • baselineSet – Defines the „Baseline Set” that should be loaded.
  • baselineSetDefinition – Defines the „Baseline Set Definition” that should be loaded.
  • project – Defines a single project to be imported.
  • projects – Defines a path to multiple projects.
  • undefined attribute value – Defines a string-type value for attributes that are undefined in DOORS database.

Sample configuration for a single project :

project "/MY_PROJECT" {
    baselineSetDefinition "MY_BASELINE_SET_DEFINITION" {
        baselineSet "3.0 (MY_SUFFIX)"
    }
}
undefined attribute value = "MY_UNDEFINED_VALUE"

The example above will include the content of „/MY_PROJECT” which is present in baseline set „3.0 (MY_SUFFIX)” which is defined in baseline set definition „MY_BASELINE_SET_DEFINITION”. When the baseline set definition block is omitted, the current version of „/MY_PROJECT” is provided. In case an artifact configuration includes an attribute that is not defined in DOORS, the value „MY_UNDEFINED_VALUE” is assigned.

Sample configuration for multiple projects :

projects "/YT/*/IMPORTANT/*_PROJECT" 
undefined attribute value = "MY_UNDEFINED_VALUE"

The example above will include all projects that are located in a path that starts with „/YT/”, also includes a „/IMPORTANT/” folder and matches the pattern „*_PROJECT”. For example „/YT/REQUIREMENTS/IMPORTANT/MY_PROJECT” would be an acceptable match. Note that when defining a path instead of a single project, it is not possible to specify a baseline. The version will always be the current. The „undefined attribute value” will behave the same as in the example above.

Caching

As reading data from DOORS might be a time-consuming task, YT persists native DOORS data locally and thus avoids repeated fetching these data, especially after restarts. The native data is persisted within a folder named DOORSResponseCache within the workspace folder currently used by your running YT instance.

Invalidating the cached data can be done by using the toolbar action Update DOORS data.

In certain situations it might be useful to share the data between team members to ensure everybody is working on the same basis. If needed, this can easily be done by creating a new project within the location of the cache folder.

  • Goto New → Project…, General → Project, and click Next.
  • Choose a project name, e.g. DOORSResponseCache
  • Uncheck use default location.
  • Click on Browse.
  • Choose the cache folder DOORSResponseCache within your current workspace’s root folder.
  • Click Finish.

If everything is fine there should be a new project available in your project explorer which looks similar to the project shown in the following screenshot:

The newly-created project can be shared afterwards via Eclipse’s team functionalities.

Artifact type

The IBM DOORS adapter allows for flexible artifact configuration to specify which artifacts YAKINDU Traceability should import from the IBM DOORS data access. It also allows to define custom attributes and to map them to native DOORS module and object attributes.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Artifact Types tab.
  • Add a new Artifact Type.
  • Assign an Artifact Type Name, pick a Color and a Category.
  • Pick IBM DOORS from the Adapter drop-down list.
  • Add a configuration by double-clicking the + icon at the bottom.
  • Select your previously configured (IBM DOORS) data access.

The configuration panel below allows to define which native IBM DOORS artifacts should be included based on their type and attributes. YT artifacts can either be native Doors Projects, Modules or Objects. The configuration language offers content assist to guide through the different options. In case no explicit configuration is supplied, all artifacts for the type in the scope of the data access are included. If no type is specified ‚Objects’ is assumed.

Supported keywords:

  • != – „Not equals” operator to use within a condition
  • == – „Equals” operator to use within a condition
  • artifact type – Optional definition of the the artifact type. Possible values are Module | Project. If not specified Object is assumed.
  • contains – Constraint for substring check
  • in – „In” operator to use within a condition
  • include [projects|modules|objects] if – Starts an include expression. Artifacts will be included if they satisfy the conditions within the expression.
    • projects – Specifies that the following conditions are evaluated on project level.
    • modules – Specifies that the following conditions are evaluated on module level.
    • objects – Specifies that the following conditions are evaluated on object level.
  • map – Starts a mapping block.
  • Module – Allows to access the parent module of an object for mapping.
  • Project – Allows to access the parent project of an object for mapping.
  • to – Defines the relation of a custom attribute to the value it is mapped to
  • external links – May follow after the to keyword and defines that the attribute is mapped to external link references
  • valueOf – Starts a valueOf condition.

In Doors the artifacts have a natural hierarchy. Projects contain Modules, which contain Objects. Thus YT allows to filter the artifacts delivered by the Data Access on three levels. To do so the include projects|modules|objects if( condition ) expression is used. It causes the DOORS adapter to only consider artifacts that satisfy the specified conditions. The project conditions are evaluated first, followed by the module and finally the object conditions. Note that for artifacts of type Project only project conditions are allowed. For Modules it is possible to specify additional module conditions, while for Objects conditions on all three levels are valid.
A condition is defined by following syntax. valueOf(" attributeName") operator value with

  • operator being either a single-value operator like ==, !=, contains or the multi-value operator in
  • value being either a "single value" or and only in combination with in („a” „list” „of” „values”).

Note that multiple conditions are implicitly concatenated with a logical AND.

Simple Example(Artifact type is Object):

include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
)
include objects if(
  valueOf("Release") == "FINAL"
  valueOf("AcceptedBy") in ("ME" "OTHER")
  valueOf("Content") contains "very important"
)

The example above will only include artifacts that are defined within modules that are part of projects with the Name MY_PROJECT, have the FullName MY_NAME and are not Created By ME. The result set of this selection is further restricted by the objects conditions, allowing only objects of the FINAL Release that are also AcceptedBy ME or OTHER and have a Content that contains the string very important.

Simple Example(Artifact type is Module):

artifact type = Module 
include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
)

The example above will only include each Module as artifacts that is defined within projects with the Name MY_PROJECT, have the FullName MY_NAME and are not Created By ME. Note that no include objects if( condition ) is allowed here, since the artifact type = Module.

Simple Example(Artifact type is Project):

artifact type = Project 
include projects if(
 valueOf("Name") == "MY_PROJECT"
)

The example above will only include each Project as artifacts that has the Name MY_PROJECT. Note that no include modules|objects if( condition ) is allowed here, since the artifact type = Project.

Example with attribute mapping(Artifact type is Object):

include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
){
 include objects if(
  valueOf("Release") == "FINAL"
  valueOf("AcceptedBy") in ("ME" "OTHER")
 )
}
map {
 MY_ATTRIB to valueOf("My_attrib")
 MY_MODULE_ATTRIB to Module.valueOf("Module_attrib")
 MY_PROJECT_ATTRIB to Project.valueOf("Project_ attrib") + "_" + valueOf("My_other_attrib")
 EXTERNAL_LINKS to external links
}

In addition to a simple configuration, it is also possible to map native artifact attributes to YT attributes. To do so it is necessary to define at least one custom attribute.

Use the keyword map to begin an attribute mapping block. Within the mapping block (between { and }), content assist will suggest all defined attributes, followed by the to keyword. On the right side of the expression it is possible to define to which native attributes the YT attribute should be mapped. YT also allows to map an attribute to a list of external links.

The default scope for attribute mapping are objects. The keywords Module and Project are available to access native attributes of the parent module and project. One YT attribute can be mapped to multiple native attributes by concatenating values using +.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The IBM DOORS adapter allows for flexible link configuration to specify which links YAKINDU Traceability should import from the IBM DOORS data access. Make sure artifact types have been configured before.

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Link Type tab.
  • Assign an artifact type for Artifact Type A and Artifact Type B.
  • Pick a Classification (optional) and Roles for A and B (optional).
  • Add a configuration by double-clicking on the + icon at the bottom.
  • Select your previously configured (IBM DOORS) data access.

Please note that links that are read from the DOORS client have a direction. An artifact of the artifact type configured as Artifact Type A is the source of a native DOORS link, while artifacts of the Artifact Type B have the target role.

The configuration panel below allows to exactly define the direction of a DOORS link in YT. The configuration language offers content assist to guide you through the various options.

Supported keywords:

  • link source is A|B – Specifies the link source in DOORS. Let’s say you want to create a link type from A = "Customer Requirement" originating from DOORS module CR to B = "Software Requirement" which are defined in DOORS module SR. On specification of link source is B, YT searches for DOORS links defined in link sets from SR to CR, but creates a YT link from Customer Requirement to Software Requirement. The configuration of a link source is optional. If not specified, YT searches according to link source is A.

Example:

The expression link source is B will flip the original link direction as it is in DOORS (A → B) to B → A in YT.

Links of this link type will never become suspicious.

Microsoft Excel

Data access

The YT adapter for Microsoft Excel provides access to the contents of Excel cells as traceable artifacts.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Microsoft Excel from the Type drop-down list.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing Excel files relevant for traceability.

Supported keywords:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions.

Artifact type

The Excel adapter makes certain Excel cells available as artifacts. The recognition of such cells/artifacts depends on both cell location (file/sheet/address) and cell content, which must not be empty. Cells may be referenced by address or by value.

Configuration

Supported options:

  • addressOf – Starts an addressOf condition.
  • locate cell where – Optional regular expressions for content or address of a cell
  • identified by – The unique key for an artifact in this document
  • address matches – Regular expression for cell address in a format like $A$1
  • content matches – Regular expression for cell content
  • name – Specifies the name for the recognized artifact.
  • sheet – Regular expression for the workbook sheet name.
  • valueOf – Starts a valueOf condition.
  • column with header – Refers to a given column of an Excel sheet. May be used within a valueOf expression and within an locate cell where expression.
    • For attribute mappings, the actual header is looked for „from bottom to top”, i.e. the search direction is upwards, starting at the row containing the actual artifact.
    • For cell location restrictions, the column headers are expected in row 1 unless an optional in row is configured, see example below.
  • map – Attribute mappings for custom attributes
  • sheetName – Bound to the sheet name of the artifact
  • Document.userProperty – Map value to extended properties of the artifact’s document.
  • Document.property – Map value to default properties of the artifact’s document.

For reading the current selection of Microsoft Excel and opening an artifact, the Component Object Model (COM) API of Microsoft Windows is used. Further information is available at Microsoft COM API.

This adapter supports the XLS, XLSM, and XLSX formats.

Example:

Sample configuration:

sheet "Table_1" {
    locate cell where {
      address matches "\\$(N)\\$(\\d*)"  // Only cells in column N with any rownum
      column with header "TestCase" in row 3 // Only cells in column with Text "TestCase" in row 3
      content matches "(ID-.*)" // which contain only numbers prefixed with 'ID-'
    }
    name sheetName + ":" + valueOf {0;0}
    identified by sheetName+":" + addressOf {0;0}
    map {
      department to Document.userProperty("Department") //user property in the Excel file for department
      status to valueOf {+1;0} // custom attribute status gets the value of the cell on the right
      variant to valueOf {column with header("Variant");0} //custom attribute variant gets the value
                               //of the cell in the same row in the column with the header "Variant"
    }
  }

In the above example, the workbook sheet containing the artifacts must be named „Table_1” and the cell to link with is in column N. This column requires a header „TestCase” which is expected in row 3.

YT considers only those cells as artifacts that contain a text like ID-1000.

Please note: Although restrictions address matches and column with header are overlapping, it is possible to use them together in the same locate cell block.

Sheet name, cell address and content patterns are interpreted as regular expressions. For further information, see regular expressions. Click on the regular expression example.

The keywords name and identified by are used for presenting and identifying artifacts. In this example the artifact name might be Table_1:ID-1000, and the identifier to find the artifact could be Table_1:$N$12. You can copy and paste the example and adjust it matching your requirements.

Attribute and cell mappings

The custom attributes of artifacts can be mapped from cells relative to the artifact’s primary cell or extracted from the document properties. The example in the previous section the department is extracted from the document properties of the Excel file and the status is extracted from the cell right from the primary cell. The syntax supports two variants. The attribute value is referenced either by cell offsets or by column headers.

Example for offsets:

" valueOf( column offset ; row offset )"

Negative offsets are allowed. The attribute value is taken from row row of artifact + row offset, column column of artifact + column offset.

Example for column header:

" valueOf( column with header( " Header " ); row offset )"

YT scans from top to bottom and from left to right to look for cells with „Header” as their contents. If a cell matches, the attribute value is taken from the associated column in row row of artifact + row offset.

To use the cell address instead of the contents, the addressOf keyword supports the same offsets, but is evaluated to the address of the cell. The document properties can be accessed by Document.userProperty(" Name ") for custom properties and by Document.property( creator or title ) for the default document properties.

If your configuration tries to access a cell „preceding” the first cell or row, the value of such an non-existent cell is replaced by an information message like „Illegal cell $B$2-3”.

Value references

In the above example, the artifact named Table_1:ID-1000 is identified by the cell reference Table_1:$N$12. As a consequence, the name of the artifact will change if the text in that particular cell changes. This implies a risk of „crooked” links:

Assuming we have an Excel sheet like this:

If we delete row 2 in Excel, all trace links e.g. from/to Table_1:ID-1001 will be „bended” to link from/to Table_1:ID-1004.

This risk can obviated by using value references instead of absolute cell references. In this case, YAKINDU Traceability stores ID-1001 as reference and searches the area specified in the address matches section of the configuration for that value. Hence, the trace link stays valid.

In order to have YAKINDU Traceability use references, change the configuration from

resource *risks.xls {
  …
    identified by sheetName + ":" + addressOf {0;0}
  …
  }
}

to

resource *risks.xls {
  …
    identified by sheetName + ":" + valueOf {0;0}
  …
  }
}

Caveat: If you change the configuration from addressOf to valueOf there is a risk to corrupt existing links. Please consult the support before making such adjustments!

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

With the Excel link type, it is possible to store references from Excel artifacts to other artifacts within Excel sheets. This is achieved by populating a cell „close” to the cell representing the artifact with the ID(s) of the referenced artifact(s). The meaning of „close” is expressed in the YT configuration for the particular Excel link type. If the cardinality of the link is larger than one, the IDs of the referenced artifacts are joined in the cell.

YT supports not only to store the link by means of storing the ID, YT also supports synchronization of attributes from the linked artifact into the Excel sheet.

Let’s say test cases in Excel are linked to requirements, which, by the way, might reside in a totally different data source, e.g. PTC Integrity. If configured, on link creation YT does not only store the requirement ID in cell A, but can also copy the requirement description into another cell. This may support the person responsible for the test during specification of the test case.

Apparently, using the Microsoft Excel link type requires at least one link type mapping with a configured Microsoft Excel data access. At least one of the artifact types selected for the link type must be a configured Microsoft Excel artifact type.

To configure an Excel link type,

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Link Type tab.
  • Assign an artifact type for Artifact Type A and Artifact Type B.
  • Pick a Classification (optional) and Roles for A and B (optional).
  • Add a configuration by double-clicking the + icon at the bottom.
  • Select an Excel data access, which should have been configured in a prior step.

Supported keywords are :

  • link where … in … – Defines which condition must be fulfilled to derive trace links from cells in Excel. Left from in, a custom attribute of the target linked artifact type must be provided that identifies artifacts of this type within Excel. Right from in, a position within Excel must be provided via the valueOf keyword. This position must refer to an Excel artifact type.
  • map – Defines a list of mappings (see below).
  • … based on … to – Defines a mapping of an attribute of B or A (left from to) to a cell in Excel (right from to), i.e. the attribute value will be stored in the specified cell when creating or updating the link. Left from based on, a custom string attribute of the configured Excel link type must be specified. When reading a link from Excel, this custom attribute will be set to the value read from the specified cell. When creating or updating a link, the custom attribute will be set to the value of the specified custom attribute of an artifact.
  • valueOf – Allows to specify the position of a cell within an Excel sheet, see Microsoft Excel artifact type.

When reading or writing links of the configured Excel link type, YT will generally only consider the same Excel sheet in which the Excel artifact was found that is referred to by the in clause. All relative positions specified with valueOf are relative to the cell of this artifact, i.e. they assume {0;0} to be the position of this cell.

In general, each entry of map has the form: connectorAttr based on B. artifactAttr to A.valueOf{ xPos; yPos} . The expression connectorAttr is the name of a custom attribute defined for the link type, while the expression artifactAttr is the name of a custom attribute defined for the artifact type of B. The expression A.valueOf{ xPos; yPos} defines the position to store the attribute in, as described above.

The Excel link type supports linking from one Excel artifact to zero, one or more artifacts, the type of which is set in the link configuration:

  • If there is no link, the cell holding the link information is empty.
  • In case of one link, the cell contains the ID of the referenced artifact as specified in the link type configuration.
  • In case of more than one link, the IDs are concatenated, separated by the pipe symbol ( |).

If attributes are mapped, the same mechanism holds true for attributes. The number of items in the cell holding the IDs and the cells holding attributes must match, i.e. the n th attribute is associated with the n th link.

If in this case the links in Excel are edited manually (i.e. not by YT), the user must take care of making consistent changes: If he deletes the n th link in the cell holding the ID, he must also delete the n th attribute in each cell holding attributes.

link where B.IDX in A.valueOf{column with header("Requirement ID");0}
map {
    module based on B.ModuleName to A.valueOf{column with header ("Module");0}
    variant based on B.variant to A.valueOf{+4;0}
}

The sample configuration above describes a link type mapping from artifacts of the Excel artifact type (artifact A) to requirement (artifact B). The ID of artifact type B is configured in the custom attribute B.IDX, and artifact type B has the custom attributes B.ModuleName and B.variant.

The configuration tells YT that the IDs of the linked artifacts should be written into or read from the cell at the following position: "column labeled „Requirement ID”; same row as ID if Artifact A". YT splits the string contained in the cell by using the separator | and removes any whitespace surrounding each of the resulting parts. YT derives a link whenever one of the resulting parts is equivalent to B.IDX (i.e. the ID of the requirement).

The definition of the position has the form A.valueOf{ xPos; yPos} . The syntax is the same as for the Excel artifact type.

Via the keyword map, the configuration tells YT to store certain custom attributes of artifact B in the Excel file and to map these values to certain custom attributes of the link type. In the example, it will derive the value of the custom attribute variant of the configured Excel link type from the custom attribute variant of B and the link attribute module from B's custom attribute ModuleName. YT stores all attributes for the link in the row of the Excel sheet containing A. The column to store the value of B.ModuleName in is defined to be the column having the header „Module”. The second entry defines a similar mapping for another variable, but this time the column for storing the attribute is defined relative to the column of A: It is stored four columns to the right of A.

In the above Excel sheet, two links have been created by means of YT:

  • From test case 1 to requirement A13, which comes from module A in variant 3
  • From test case 1 to requirement A16, which comes from module G in variant 7

Suspicious links validation is done by re-evaluating the link’s custom attributes and comparing these values to those stored in the link. If there are any differences, the link is suspicious.

Microsoft Visual Studio

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.cpp
    subset "includestmt"
    subset "class"

In the above example, only class and includestmt code elements (defined in subset patterns) in all files with a .cpp extension (defined in resource pattern) can be valid for tracing. This adapter supports files with following filename extensions:

  • .h
  • .c
  • .cpp
  • .vb

and the following subsets:

  • includestmt
  • namespace
  • class
  • function
  • variable

For reading the current selection and opening an artifact in Microsoft Visual Studio 2013 Professional (or similar versions – not the Express editions), an add-in for the traceable document must be installed.

The required add-in files ( *.AddIn and *.dll) can be found in the following location after adapter installation:

  • Eclipse Installation Path/traceability/plugins/vs2013

These files should be copied to:

  • UserHome/Documents/Visual Studio 2013/Addins

Add-In installation/registration:

In the Visual Studio environment (select Extras → Add-In-Manager from the menu bar) the first and second checkbox should be checked – restart needed!

Detailed information on installation and registration can be found here:

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Microsoft Word

Data access

The YT adapter for Microsoft Word provides access to the contents of Word documents as traceable artifacts.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Microsoft Word from the Type drop down list.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing Word files relevant for YAKINDU Traceability. Supported Word formats are DOC, DOCX, and DOCM.

Supported keywords:

  • resource – A pattern for a project, folder or file in the workspace.
  • undefined attribute value – Specifies the value to be returned when an attribute can’t be resolved. This value will be returned if the cell does not exist when trying to retrieve the value from a cell in a Word table (either because the requested cell index is out of bounds or because the table does not contain the requested cell header). Possible values are strings, in which case the returned value will always be the same, or the default keyword.
  • default – For undefined attribute value, using the default value will return a String indicating the position that couldn’t be found (either by index, or by column/row header). For example, „<Not a cell: {-4; RowHeader}>”. This is especially useful to detect errors in the configuration or in a Word document

The configuration may contain several resource definitions.

Example:

resource *.docm
resource *.doc
undefined attribute value "N/A"

This configuration will match all Word documents in formats DOC or DOCM. If the Artifact Type configuration matches elements in a Word table and some attributes reference cells which can’t be found, these attributes will get the „N/A” value

Artifact type

The Word adapter recognizes three different kinds of artifacts: Bookmarks, regular expression matches, and headings. It supports DOC, DOCM, and DOCX file formats. It can extract information for the mapped attributes from the general structure (headings, paragraphs, tables), and include or exclude artifacts based on their style information (bold/italic/underline/strikethrough).

For example, it is possible to retrieve all bookmarked elements, excluding the ones with the „strikethrough” style.

When the Word change tracking mode is enabled, all modifications will be considered as „Accepted” by YAKINDU Traceability. This means that elements marked for deletion (but still visible in the document due to change tracking) will be ignored, whereas added elements will be included. This is useful to avoid duplicate matches, when a paragraph has been modified in change tracking mode, and both the old version and new version are still present in the document.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Artifact Types tab.
  • Add a new Artifact Type.
  • Assign an Artifact Type Name, pick a Color and a Category.
  • Pick Microsoft Word from the Adapter drop-down list.
  • Add a configuration by double-clicking on the + icon at the bottom.
  • Select your previously configured Microsoft Word Data access.

Supported options:

  • locate bookmark where subset – Specifies bookmark recognition(s). This can be used to filter valid bookmarks by defining a regular expression on the full label format (see detailed explanation below).
  • locate text where pattern matches – Searches in the entire document for text matching the specified regular expression. An artifact will be created for each text sequence matching this expression
  • locate heading where pattern matches – Searches in the document headings for text matching the specified regular expression. An artifact will be created for each text sequence matching this expression
  • where style is (not) – For bookmarks, text or headings, specify additional filter(s) based on font style. Supported font styles are bold, italic, underline and strikethrough. You may specify several style filters. A style is considered to be applied if at least one character has the specified style. Conversely, a style is considered to not be applied if no character has the specified style
  • name – Specifies the name for the recognized artifacts. See the list of possible values below
  • map – Starts an attribute mapping group

Possible values for name and attribute mappings:

  • Generally valid: name and map are string concatenations. Possible parts in this concatenations are:
    • String literal : a (static) string
    • hasStyle(style): evaluates the font style of the matched element and returns true if it has the specified style, false otherwise. Supported font styles are bold, italic, underline and strikethrough. Example: hasStyle(bold).
    • For artifacts found in tables:
      • valueOf {x;y} – If the artifact (text or bookmark) is found in a table cell, attributes can be mapped to values in nearby cells. Here x and y are integer coordinate values representing a relative cell position, with x being the column offset and y being the row offset. The coordinates 0;0 denote the current cell. Example:
        • {+1;0} indicates the cell that is at one column to the right from the matched artifact’s cell.
        • {-1;-3} indicates the cell one column to the left and three rows above the matched artifact’s cell.
      • column with header – In valueOf {x;y}, x can be replaced by column with header "headerName". In this case, the label of the cells in the first row (top-most) will be used to find the column.
      • row with header – In valueOf {x;y}, y can be replaced by row with header "headerName". In this case, the label of the cells in the first column (left-most) will be used to find the row.
    • For map only:
      • Document.property(title) and Document.property(creator): Accesses the Word document’s standard properties title and creator. – Please note: These are Microsoft Word’s metadata, not the metadata of the Word file, i.e. they have to be maintained inside the Word document.
      • Document.userProperty(„property_name”): Accesses the Word document’s custom property of the same name.
Use bookmarks as artifacts

The „locate bookmark” matcher can be used to create an artifact for each Word bookmark matching the specified subset (defined as a regular expression)

Minimal configuration:

locate bookmark where subset ".*" {
}

This configuration will create an artifact for each bookmark, with a default name (conforming to the full label format below) and no attributes

This matcher accepts one parameter, in the form of a regular expression, which will be evaluated against the full label of the bookmark. In the minimal example above, the regular expression „.*” matches all available bookmarks (including hidden bookmarks, such as table of contents references)

Full label format for bookmarks

When using the „locate bookmark” matcher, the bookmarks are specified by a string consisting of three sections which are separated by three hash signs:

bookmark_id ### bookmark_content ### (optional_bookmark_desc | …)

The „subset” defines a regular expression, which will be evaluated against this full label: an artifact will be created for each bookmark matching the specified expression. See Bookmark examples below for more details

Please note: The optional_bookmark_desc is deprecated, but still maintained for backward compatibility. It won’t be discussed here.

Additional supported values for bookmarks

When using a ‚locate bookmark’ matcher, you can refer to groups defined in the regular expression, using „$n”, where n is the n-th group (e.g. „$1” is the first group, as defined in the bookmark regular expression)

For example:

locate bookmark where subset "(.*)" {
	name "$1"
}

In this example, the parenthesis in the regular expression define a group. Then, the value „$1” is a reference to the text matched by the first group (which is also the only group, in this small example)

Bookmark example

locate bookmark where
	subset "([^_].*)###(.*)###(.*)"
	style is not strikethrough
	{
	name "$1 - $2"
	map {
		Author to Document.property(creator)
		Description to valueOf{column with header "Description"; 0}
	}
}
  • In the above example, bookmarks will be located in all documents specified by the Word Requirements data access.
  • The subset is a regular expression indicating that all bookmarks should be selected, except the ones prefixed with an underscore „_”. Microsoft Word uses an underscore prefix to identify „hidden bookmarks”, which means that this expression will only match visible bookmarks:
    • ([^_].*): Defines a group (identified by the parenthesis). The group will match any sequence of characters which does not start with an underscore
    • ###: The first „full label format” separator. The text before this separator represents the bookmark ID, whereas the text after this separator represents the bookmarked text
    • (.*): Defines a second group, matching any sequence of characters
    • ###: The second (and last) „full label format” separator. The text before this separator represents the bookmarked text
    • (.*): Defines a third group, matching any sequence of characters
  • The $1 and $2 expressions in the identifier refer to groups of the subset, hence YT will show matched bookmarks as concatenation of bookmark_id + " - " + bookmark_content.
  • The option style is not strikethrough will skip all bookmarks with at least one strikethrough character in the bookmarked text.
  • If the bookmarked text is located in a table cell, the description will be retrieved from a cell on the same row, namely the cell in the column named „Description”. The name of a column is the text of the first cell (top-most) in this column. If this column can’t be found, the value specified in the Word Requirements data access will be used instead.

Here is a sample Word document using bookmarks:

And here is the result in YT:

Use regular expressions as artifacts

The „locate text” matcher will create an artifact for each portion of text in the document matching the specified regular expression. This matcher gives more flexibility regarding the structure of the document (in the sense that it will search text in any part of the document, including paragraphs, headings, tables...), but the configuration is highly dependent on the contents of the document.

YAKINDU Traceability’s regular expression recognition relies on uniqueness. Hence, YT ignores text portions with identical matchedText of a regular expression, e.g. if the text REQ02 Control occurred twice in the example below. In such a case, YT will produce a single artifact (and not one per occurrence of the same text), and will attach a warning marker to this artifact (the warning will appear during Model Consistency validation)

Caveat: As some Microsoft Word functions create duplicates of text portions, such a situation is likely to occur. For your convenience, YT doesn’t match regular expressions within Word’s hyperlinks, which is one of the most commonly used functions duplicating text, e.g. when creating a table of contents. So a match in a „standard” text and in a hyperlink to that text won’t be considered as duplicates. On the other hand, if a Word document has a table of contents without the hyperlinks instead of page numbers option being set, Word creates copies of the headings instead of hyperlinks, thus YT considers matches as duplicate.
Additionally, all modifications made in „Track Changes” mode are considered to be accepted, i.e. text deleted during „Track Changes” will be ignored by YT during matching. Similarly, text added in „Track Changes” mode is always taken into account.

Minimal configuration:

locate text where pattern matches ".*" {
}

This configuration will produce one artifact for each structural element of the document (heading, consecutive list of paragraphs, or cell in a table). The name of the artifact will correspond to the entire text of this structural element

Additional supported values for regular expressions
  • function matchedText: The whole match for the regular expression
  • function textUntilNext (match | headingOrMatch) : Text portion starting from the matched text until the next match/ heading or match, resp.
  • If the match itself is inside a heading, this particular heading is considered as „the next heading”, so textUntilNext(headingOrMatch) is the text portion from the match to the end of the heading.
  • For the label (i.e. the name attribute), the textUntilNext() has a size restriction and will be truncated automatically. Custom attributes may have longer text passages.
Regular expression example

locate text where 
	pattern matches "REQ[0-9]+.*" 
	style is bold {
	name "R-" + matchedText
	map {
		Description to textUntilNext (headingOrMatch)
		Author to Document.property(creator)
	}
}

In this example, the artifacts will be located in the document and will match any occurrence of the string „REQ” immediately followed by at least one digit. The expression will also include all text following this sequence, until the next end-of-line. If at least one of the matched characters is bold, then an artifact will be produced for the matched sequence.

Each artifact will have a description, corresponding to the entire text starting immediately at the end of the matched text until the beginning of the next heading or match, whichever comes first. Note that this may include a lot of text, which may span over several tables or paragraphs.

Here is a sample Word document using regular expressions:

And here is the result in YT:

Warning regarding the use of imprecise regular expressions

If you use am imprecise regular expression while configuring the Microsoft Word adapter (for example „REQ-//d+”) more than one candidate might match.

In this example „REQ-1” and „REQ-11” would both match the expression as they both share the string „REQ-1”.

If you then double-click on the tracepoint „REQ-1” YT searches the document for the string „REQ-1” and will find the candidate „REQ-11” if it is stated above „REQ-1”!

Use headings as artifacts

The „locate heading” matcher is really similar to the „locate text” one, except that it will only search inside Word headings, instead of the entire document. Microsoft Word comes with a set of predefined headings (Heading 1 ~ 9), but this matcher will, more generally, match any paragraph with an outline level equal or greater to 1. This also corresponds to all elements visible in the Word Outline view.

Please note: by default, the main title of a Word document does not have an outline level. Consequently, it will be ignored by the „locate heading” matcher, and will not produce an artifact.

Like the „locate text” matcher, „locate heading” will accept a parameter to filter results based on a regular expression. Note that, unlike „locate text”, this parameter is optional for headings.

Minimal configuration:

locate heading {
}

Which is equivalent to:

locate heading where pattern matches ".*" {
}

Both of these configurations will produce an artifact for each heading in the Word document. The name of the artifact will correspond to the text of the heading

Additional supported values for headings

„locate heading” supports the same options as „locate text”. See Additional supported values for regular expressions above

Heading example

locate heading where pattern matches "Req[0-9]+.*" {
	name matchedText
	map {
		Description to textUntilNext (headingOrMatch)
		Author to Document.property(creator)
	}
}

This example is very similar to the regular expression example. The main difference is that artifacts will only be produced if the text „Req” immediately followed by at least one digit is found in a heading.

Here is a sample Word document using headings:

And here is the result in YT:

Example for a mix of bookmarks and expressions

YAKINDU Traceability supports using a mix of resource(s) (using different configuration mappings) and recognitions specification(s) for one artifact type, e.g. by means of an adapter configuration similar to the following:

locate bookmark where subset "([^_].*)###(.*)###(.*)"{
	//...
}

locate text where pattern matches "REQ\\d{2}.*" {
	//...
}

locate text where pattern matches "Requirement \\d{2}.*" {
	//...
}

locate heading where pattern matches "Req[0-9]+.*" {
	//...
}

Support of copy and paste from Microsoft Word to YAKINDU Traceability

In order to support fast link creation, YAKINDU Traceability supports copy and paste of artifacts from Microsoft Word to the YT Editor as described in the documentation on the YT Editor as follows:

If the clipboard contains a text portion that has been copied out of a Microsoft Word, YT analyzes the pasted text with respect to the configuration of the selected artifact type:

  • If the configuration specifies bookmarks, YAKINDU Traceability analyzes the bookmarks that are contained in the clipboard text and adds each matching artifact to the YT Editor area, i.e. each artifact that both is covered by the artifact type’s configuration and that is part of the selection.
  • The same holds true for regular expressions.
  • Caveat: The clipboard provides information on the file the selection originates from. That filename is honored by YT during the evaluation of matching artifact. As a consequence, YT will only identify artifacts if they have been selected in Microsoft Word.

Propagation of selections between YAKINDU Traceability and Microsoft Word

YT propagates the selection of artifacts from and to Microsoft Word, e.g. YT shows an artifact inside the YT Overview if a „selection” of the artifact occurs in Microsoft Word.

  • YT considers an artifact based on a bookmark as selected if the user clicks on the bookmark (label) in Microsoft Word.
  • YT considers an artifact based on a regular expressions as selected if a text portion is selected (marked) in Microsoft Word and this selection contains the matched text. If the selected text contains more than one match, YT considers the first one as selected. – Background: Regular expressions can match text portions of various sizes (even the whole document). Additionally, such matches can overlap. In order to clearly distinguish whether an artifact based on a regular expressions is selected, YT uses the algorithm described above. – Hint: A double/triple click in Microsoft Word selects (marks) the whole word/paragraph at the cursor location.

Migration advice (pre 1.1.1510 (3))

Regular expression matches had been introduced in YT version 1.1.1510 (3).

This affects the format how YT stores artifacts and links, so elder YT storage files, e.g. data.yt, need to be migrated.

A validation detecting such cases, offering quick fixes and migrating data automatically is available. Run it by selecting Traceability → Validation → Model Consistency in the main menu.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

Mylyn

Data access

The YT adapter for Mylyn provides access to Mylyn tasks as traceable artifacts. It is also used to provide the associated Mylyn relations as YT links.

To get the adapter to work, Mylyn has to be configured properly as suggested in Eclipse Mylyn Tasks. For further information have a look at the Mylyn documentation.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Mylyn from the Type drop-down list.

Within the configuration panel, no further configuration will be done.

Example:

Artifact type

Configuration

Supported options:

  • name – Specifies the name for the recognized task.
  • kinds – Filters the types of tasks to match. This corresponds to the mylyn Kind attribute. It is case-insensitive. For Mylyn/Jira, this corresponds to the Type attribute of the task (e.g. Bug).
  • valueOf – Retrieves the value from the specified Mylyn attribute

Example:

kinds "Aufgabe", "Task"
name valueOf(Key) + ": " + valueOf(Summary)

The Mylyn adapter supports all issues fetched by the Eclipse Mylyn plugin. The name of the YT artifacts can be mapped from the attribute values of the issue. In the example above all issues of kind Aufgabe or Task are made available. The name is a concatenation of the issue key, a colon and the summary of the issue.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

This link type maps links between Mylyn tasks automatically to YT trace links, if corresponding artifact types and link types exist. Selecting Mylyn as data access is mandatory for such links.

The Mylyn task repository needs to be configured in the Mylyn Eclipse plugin before YT can access Mylyn tasks. This is done by opening one of the installed Mylyn views ( Window → Show View → Other…) and starting its configuration dialog.

The link type requires links to be fetched from Mylyn. This can be achieved by activating Follow redirects for the Mylyn Task repository.

Links of this link type will never become suspicious.

Native File

Data access

The Native File data access uses a file within the workspace. Such files can be shared in source code management systems (e.g. CVS, Subversion, Git) like any other project artifacts.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Native File from the Type drop-down list.

The workspace path to the file has to be configured. Additionally, a file can be protected by applying the readOnly option. Writing operations are not allowed on such files.

Supported keywords:

  • file – Defines the file to be used for storing.

Example:

file "com.yakindu.yt.mt.yt/data.yt"

In this example the data is stored in the data.yt file which is located in the root folder of the com.yakindu.yt.mt.yt project.

If the data file does not yet exist it is automatically created. However, project and folder must already exist.

Example:

Suspicious links validation is done by comparing the artifacts' current versions to those stored in the link. If there is any difference, the link is suspicious.

PTC Integrity

Data access

The PTC Integrity data access provides access to documents being hosted by PTC Integrity as traceable artifacts. A reliable connection to the server is needed.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick PTC from the Type drop-down list.

Supported keywords:

  • server – Defines which server is to be used.
  • port – Defines which port is to be used.
  • secure true / secure false – Defines whether the connection should use a secure communications protocol – please refer to PTC Integrity documentation for details. The keyword is optional, default is secure false.
  • fields for {} – Defines the attributes of a PTC item which are taken into account to represent the item in YT. As default, PTC items are labeled in YT with ID and summary or (if summary is empty) with ID and text.
    • summary (inside fields for) – Defines the field defining the summary. Default is summary.
    • text (inside fields for) – Defines the field defining the text. Default is text.
  • projects – Defines which projects are to be imported.

Within the configuration panel further configuration is required. Below you can see a sample configuration which will be described subsequently.

Sample data access configuration:

server "ptc.itemis.de"
port 7001
secure false
fields for {
    summary "text"
    text "text"
}
projects {
  "/Pedelec"
}

The connection to the PTC Integrity server is configured here. In the above example the connection to the server is defined by the hostname ptc.itemis.de and the server port 7001. A secure connection is not configured, but the option secure can be set to true, if the server supports secure connections. PTC items are represented in YT by their text attribute.

Furthermore, the PTC Integrity projects to be considered should be listed here.

Hint: The editor supports you during the selection of projects and also during the selection of PTC item types during configuration of relevant artifacts. Entering [Ctrl+Space] in the projects section shows a list of projects that are available on the server. In order to retrieve these information, YAKINDU Traceability must be connected to PTC Integrity. The connection is established on save. Thus, we recommend an intermediate saving of the configuration after entering server and port.

Prerequisites

The PTC Integrity adapter requires the manual installation of the mksapi.jar file. By default a dialog is shown which will help installing the file. The mksapi.jar file can be found on the PTC Integrity server here:

  • /IntegrityClient10/lib/mksapi.jar
  • /IntegrityServer10/server/mks/lib/mksapi.jar

To prevent the dialog to appear or to prepare the installation, the mksapi.jar file can be copied manually into the plugin folder /plugins/com.yakindu.traceability.integrity.interface.lib_1.1.1/lib/.

Advanced data access configuration

For some PTC Integrity installations it is necessary to change the fields that are used as labels. This can be configured in the fields for section of the data access configuration. All fields have to be defined for all fetched items, including documents. At first, the summary field is used, and if not set the value of the text field is used.

server "ptc.itemis.de"
port 7001
secure false
fields for {
    summary "summary"
    text "text"
}
projects {
  "/Pedelec"
}


Artifact type

The PTC adapter provides requirements hosted by PTC as artifacts. A sample configuration shows how the mapping works.

Configuration

Supported options:

  • map to{…} – A block that defines which PTC items are relevant for traceability and how they are mapped to YT artifact types.
  • if( … and … ) (inside map to) – Defines a boolean expression which is evaluated on PTC items. If the evaluation result is true YT considers the PTC item as a traceable artifact of the given artifact type. The expression may contain several attribute evaluations concatenated by the keyword and.
  • … to … (inside map to ) – Defines how attributs of YT artifacts should be populated with values from PTC items' attributes.

Example:

map to "Requirement"
    if ("Category" = "User Requirement") {
        "text" to "Text"
 }

In the above example, the YT artifact type is mapped to the PTC Integrity type Requirement if the Category attribute of the PTC item is set to User Requirement. The if condition is optional. Furthermore the PTC Integrity attribute Text is mapped to the YT type custom attribute text. The attribute mapping is optional.

The if clause supports the operators =, !=, >, <, <=, >=, contains, doesNotContain.

Please note that depending on the attribute type some operators are not allowed by PTC Integrity, e.g. text fields (i.e. fields of type longtext, shorttext, fva, etc.) support contains and doesNotContain but not = or !=.

Please also note that contains is a heuristic operator – refer to the PTC Forum for more information.

Loading the document structure

For artifacts which are structured in a document in Integrity, it is also possible to show the document structure in the search dialog. The document structure is not loaded by default, but must be requested for each project separately. This can be achieved via context menu of a document in the search dialog.

In this example, the artifacts of type User Requirement are saved in a document in Integrity. The first image shows the default hierarchy after initial load where artifacts are grouped by document. In the second image the hierarchy was loaded and the artifacts were re-ordered after the document structure was fetched.

Support of copy and paste from PTC Integrity to YAKINDU Traceability

In order to support fast link creation, YAKINDU Traceability supports copy and paste of artifacts from PTC Integrity to the YT Editor as described in the YT-Editor chapter as follows:

In the PTC Client, mark and copy a set of items. On paste, YT analyzes the clipboard content with respect to the configuration of the selected artifact type. If the ID of an item in the clipboard matches an item that is covered by artifact type configuration then YAKINDU Traceability adds this item to the YT Editor area.

Please note:
Not all versions of PTC Integrity support copying of items. If you cannot copy items with your PTC Integrity version we recommend to apply the support of YAKINDU Traceability within PTC Integrity.

Please also note:
If the clipboard contains artifacts that are not covered by the configuration of the artifact type (to put it crudely: The selection is „too large”), YAKINDU Traceability notifies the user about such items. The user can turn off this notification.

Support of YAKINDU Traceability editor within PTC Integrity client

Especially for users who are primarily working with the PTC Integrity client, YAKINDU Traceability supports an integration of YT Editor functionalities into the PTC Integrity client using custom actions.

Configuration

To configure the PTC Integrity client to work with a running YAKINDU Traceability instance you have to configure a custom action within the view set of your current PTC Integrity client installation. Technically, a custom action is a program which is executed by the PTC Integrity client.

This program which will be configured in the following steps and can be found in the traceability\integrity folder included in the root folder of your YAKINDU Traceability installation.

Copy the files IntegrityClientIntegration.jar, Set_A.gif and Set_B.gif to any location you prefer, e.g. C:\IntegrityClientIntegration.jar etc. Open your PTC Integrity client, select ViewSet → Customize… from the menu bar, and choose the Actions tab. Within the tree on the left side choose Custom.

After the custom item is selected a list of possible custom actions becomes visible on the right side of the details view. Custom actions are bound to predefined keyboard shortcuts and you can configure whether the custom action should also be visible in the menu or in the toolbar. If you wish to use custom buttons, the drop-down must be set to Visible, on Toolbar.

By clicking Edit next to a free action, you will get to a custom action configuration dialog where at least the parameters mentioned below should be configured.

Please note:
To use the full YT Editor integration it is necessary to configure two custom actions, one for Set A and another one for Set B.

  • Name: the name of the action, e.g. Add to A
  • Program: the full path to your local Java executable, e.g. C:\Program Files\Java\jdk1.8.0_45\bin\javaw.exe
  • Parameters: the following parameters are passed to the executed Java program:
    • -jar PATH_TO_YT_CLIENT_JAR
    • -s A|B : select the section of YT Editor where artifacts are added
    • Sample -jar „C:\IntegrityClientIntegration.jar” -s A
  • Optional
    • Icon File: custom action icon, absolute path on local machine

Optionally the following parameters are available:

  • -h HOST : host YT is running on
  • -p PORT : port YT is listening on
  • -ce: keeps the command-line window open; makes sense if java.exe is used instead of javaw.exe
  • -logLvl OFF|FATAL|ERROR|WARN|INFO|DEBUG|TRACE|ALL|DEV : log output level
  • -logFile ABSOLUTE_FILE : log file

If the actions are configured it is necessary to ensure that YAKINDU Traceability is enabled. Find more information in section TCP Server.

Usage

Once the two custom actions are configured and the TCP Server is enabled as described in the previous section, it is possible to add issues selected in the PTC Integrity client to the A and B section of the YT Editor by just clicking the toolbar buttons or menu actions in the PTC Integrity client. The link creation will be done within the YT Editor itself.

If there are any issues selected in the PTC Integrity client which can not be associated with any artifacts by YAKINDU Traceability, the following notification will be shown. This happens just in case YT can not determine any artifact based on the current selection.

Prerequisites

The PTC Integrity adapter requires the installation of API files from the Integrity Server installation. See Prerequisites for details.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is the item’s modified date_.

The trace links YT derives from PTC Integrity are based on the PTC data access. If PTC Integrity relations should be mapped to YT trace links, a mapping must be defined at the corresponding YT link types.

Supported keywords:

  • map – Starts a mapping block.

Example:

map to "Validated By"

In the above example, trace links from PTC Integrity are mapped to YT links using the PTC Integrity attribute Validated By. It is defined at the PTC item type which is mapped to the YT artifact type of link end A.

Links of this type are suspicious if the corresponding suspicious flag on the PTC Integrity server is true.

Rational Rhapsody

Artifact type

The Rhapsody adapter supports artifacts in models from Rational Rhapsody. The supported model elements are Classes, UseCases and Requirements.

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.rpy
subset IRequirement

In the above example, requirements from files ending on .rpy are taken into account.

Prerequisites

The Rhapsody adapter requires the manual installation of the rhapsody.jar and rhapsody.dll into the folder INSTALL_PATH /plugins/com.yakindu.traceability.port.rhapsody.lib_1.1.1516/lib/_. The files can be found on the Rhapsody server under Rhapsody Installation Path\Rational\Rhapsody\8.1.1\Share\JavaAPI\rhapsody.jar and Rhapsody Installation Path\Rational\Rhapsody\8.1.1\Share\JavaAPI\rhapsody.dll .

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

SQS Test

Artifact type

Configuration

There are no configuration options for this adapter, but it requires some additional set-up in the YT preferences.

Example:

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YAKINDU HMI

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.hmi
subset sgraph.State

In the above example, elements of meta-type sgraph.State from files with names ending on .hmi are taken into account.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YAKINDU Model Viewer

YAKINDU Model Viewer is a tool to visualize Simulink models. YAKINDU Traceability is able to extract Blocks from these models as traceable artifacts. It can also read block parameters, including the Name, Path and Type of each block.

Data Access

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick YAKINDU Model Viewer files from the Type drop–down list.

Configuration

Supported options:

  • resource – A pattern for a project, folder or file in the workspace. Supported formats are *.mdl and *.slx
  • undefined attribute value – Optional: specify the value to use when trying to read the parameter of a Block, when the parameter doesn’t exist. (See Artifact type below)

The configuration may contain several resource definitions.

Example:

resource "*.mdl"
undefined attribute value = "<N/A>"

In the above example, blocks from files with names ending on .mdl are taken into account.

Artifact type

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Artifact Types tab.
  • Add a new Artifact Type.
  • Assign an Artifact Type Name, pick a Color and a Category.
  • Pick YAKINDU Model Viewer from the Adapter drop–down list.
  • Add a configuration by double–clicking the + icon at the bottom.
  • Select your previously configured (Model Viewer) data access.

Supported options:

  • include blocks if – Starts an include expression. An artifact will be created for each block satisfying the expression. This option is optional: if not specified, all blocks will be matched. If several conditions are specified, an artifact will be created only if the block matches all conditions.
  • valueOf – Starts a valueOf condition.
  • != – „Not equals” operator to use within a condition. The operator will match if the left and right operands have different values.
  • == – „Equals” operator to use within a condition. The operator will match if the left and right operands have the same value.
  • in – „In” operator to use within a condition. The operator will match if the value of the left operand is equal to one of the values in the right operand.
  • contains – „Contains” operator to use within a condition. The operator will match if the value of the right operand is a substring of the value of the left operand.
  • map – Starts a mapping block.
  • to – Defines the relation of a custom attribute to the value it is mapped to.
  • Block – Allows to access the matched block for mapping.
Please note: an empty configuration is valid. In this case, one artifact will be created for each block found in the model. The name of the artifact will correspond to the name of the block. 

Example:

include blocks if (
	valueOf(path) contains "collision avoidance"
)
name Block.valueOf(name)
map {
	"path" to Block.valueOf(path)
	"type" to Block.valueOf("BlockType") 
	IconDisplay to Block.valueOf("IconDisplay")
}

In the above example:

  • All blocks with „collision avoidance” in their path (e.g. the block named „collision avoidance” and all its children, recursively) will be matched.
  • The name of the YT Artifact will be the name of the Simulink Block.
  • The predefined path and type attributes will be mapped to the corresponding attributes of the YT artifact
  • The „Icon display” property will have the value of the block’s „IconDisplay” parameter (Or „<N/A>” if the parameter doesn’t exist for this block – As specified in the Data access configuration)
Please note: YAKINDU Traceability will only extract Blocks from the model. Thus, while similar, the tree hierarchy presented in the YT search dialog may be slightly different from the hierarchy visible in the YAKINDU Model Viewer editor

We use the following model from YAKINDU Model Viewer:

And here are the resulting artifacts in YAKINDU Traceability:

Version

The status of the version of artifacts of this type is not clear at the moment. This will change.

YAKINDU ReqIF

Artifact type

Configuration

Supported options:

  • map to type – ReqIF type long name filter
  • name – Specifies the name for matching artifacts
  • resource – File filter pattern
  • type – ReqIF specification type long name filter

The configuration can be based on a spec type from the ReqIF schema definition in the resource or on attributes of the objects. The resource must name the ReqIF file in the workspace.

Defining the type is optional and can be done directly below resource without constraints, or by map to type having constraints for the objects, or attribute mappings for custom attributes.

The identifier is used for artifact representation and should be recognizable by the user.

Example:

resource /de.itemis.aad.requirements/requirements.reqif
type "Requirement Type"
map {
    ReqID to valueOf(Description)
}
name valueOf(ID) + " - " +  valueOf(Title)

In the above example specification, objects of type Requirement Type from the ReqIF file /de.itemis.aad.requirements/requirements.reqif are taken into account.

The name is created by concatenation of the value of the attribute ID, the string -, and the the value of the attribute Title. The attributes used must exist in the defined specification type.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

YAKINDU Statechart Tools

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.sct
subset sgraph.State

In the above example, elements of meta-type sgraph.State from files with names ending with .sct are taken into account.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YT Query based link extraction

Data access

The query based data access derives links between artifacts based on queries of the query language.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick Query based from the Type drop-down list.

Within the configuration panel no further configuration will be done. Instead, the link type provides means to define the query, see section Link type.

Example:

YAKINDU Traceability can derive links based on the query language.

Please find below the required steps to specify such a derivation rule.

The configuration consists of a query. The query result columns have to contain one column named ArtifactA and one column ArtifactB with artifacts of the same type as the link type in which this mapping is defined. Columns with the same name as an custom attribute are mapped to this attribute.

Example:

Links of this link type will never become suspicious.

XML

Data access

The YT adapter for XML files provides access to any nodes in the XML Document Object Model.

Configuration

  • Open the YT configuration with the YT Configuration Editor.
  • Select the Data Access tab.
  • Add a new Data Access.
  • Assign a Data Access Name.
  • Pick XML from the Type drop-down list.

Within the configuration panel, you may specify file patterns consisting of projects, folders or file name patterns which describe the XML files relevant for traceability.

Supported keywords:

  • resource – A pattern for an XML file path.
  • zipped in – A pattern for a zipped file in the workspace.

The configuration may contain several resource definitions. If zipped in is appended to the resource definition, the resource is the path inside the ZIP file and the pattern following zipped in denotes the archive file in the workspace.

Please note: If an XML file resides in a ZIP archive, selection propagation from YT to an XML editor is not supported. If you double-click an artifact originating from an XML file in a ZIP archive, YT will neither open the XML document in an editor nor will YT select the ZIP file e.g. in any file explorer.

Example:

resource "TESSY_OverviewReport.xml"
zipped in "/com.yakindu.yt.mt.spec/test/TESSY_OverviewReport.zip"

Artifact type

This adapter supports the selection of XML nodes and opening and selecting artifacts within the Eclipse XML Editor, unless the XML file resides in a ZIP archive. The XML files have to be defined in the XML data access.

Configuration

Supported options in the configuration:

  • artifact source ID where – The unique ID for this artifact source. Multiple element sources can be used in the configuration, allowing to use different element matches conditions or mapping configurations.
  • element matches – XPath expression for selecting artifacts
  • name – Name for the matched artifact
  • identified by – The unique key for an artifact in this document, it is optional.
  • map – Attribute mappings for custom attributes
  • valueOf – XPath expression
  • joined – Follows a valueOf( XPath Expression) statement and allows to join (concatenate) the elements of a list into a single string, separated by the default separator ,.
  • joined with separator – Follows a valueOf( XPath Expression) statement and allows to join (concatenate) the elements of a list into a single string, separated by the specified separator.

Example:

Adapter configuration:

artifact source Node where (
    element matches "/testrun/testsuite/testcase"
)
{
    name valueOf("@classname") + "." + valueOf("@name")
    identified by valueOf("@classname") + "." + valueOf("@name")
    map {
        fqn to valueOf("../../@project|../@name|@name")
                joined with separator "/"
    }
}

In the above example, the artifacts will be all XML nodes named testcase contained in the specified path, i.e.:

<testrun> <!-- Root element of the document (/testrun) -->
  <testsuite>
    <testcase classname="testClassName" name="matchedTestName"/> <!-- Matched artifact -->
  </testsuite>
</testrun>

The XPath expressions for name, identified by and mapped attributes will be evaluated against the XML node for each artifact. So, the expression @classname will correspond to the attribute classname of the <testcase> node.

Element matcher

Selectable XML nodes are specified by an XPath expression following the element matches keywords.

Given the following XML document, the above XPath expression /testrun/testsuite/testcase will select a single <testcase> … <testcase>. If the testcase node has siblings, all of them would be selected.

Sample JUnit result:

<?xml version="1.0" encoding="UTF-8"?><testrun name="EmergencyHandlerTest" project="de.itemis.aad.implementation.java" tests="1" started="1" failures="1" errors="0" ignored="0">
  <testsuite name="de.itemis.aad.EmergencyHandlerTest" time="0.001">
    <testcase name="testActivateEmergencyState" classname="de.itemis.aad.EmergencyHandlerTest" time="0.001">
      <failure>java.lang.AssertionError: Failed as expected!
    at org.junit.Assert.fail(Assert.java:88)
    at de.itemis.aad.EmergencyHandlerTest.testActivateEmergencyState(EmergencyHandlerTest.java:11)
      </failure>
    </testcase>
  </testsuite>
</testrun>

See XML Path Language (XPath) Version 1.0 for a complete XPath documentation.

Value references

The name and identified by properties from the previous example are expressed as concatenation of value references:

name valueOf("@classname") + "." + valueOf("@name")

The valueOf keyword introduces a value reference containing an XPath expression. The context of the nested XPath expressions is the matched node from artifact source. For instance the full XPath expression for name valueOf("@classname") is "/testrun/testsuite/testcase/@classname", given that only a single testcase node is contained in the XML document.

If the evaluation of the XPath expression returns a list of elements, it is possible to concatenate the results of this list to obtain a single string attribute. This is achieved using the joined with separator keyword. For instance:

map {
    time to valueOf("//testcase/@time") joined with separator ';'
}

The resulting string will be the concatenation of the time for each testcase contained in the document, separated by semicolon, e.g. 0.001;0.023;0.358. If the separator is not specified, it defaults to a comma ,.

Miscellaneous

This chapter contains configuration adapter-specific details for configuration storage types and data access types.

Configurations can be made in the configuration editor or on the preferences page.

Configuration storage types

NONE

The NONE storage deactivates YT.

FILE

The FILE storage uses a file within the workspace. Such files can be shared in a source code management repository (e.g. CVS, Subversion, Git) like any other project artifacts. The configuration requires the workspace path to the file to be specified.

Example:

file "/de.itemis.pedelec.tracing/model/conf.yt"

In this case the configuration is stored in the conf.yt file, which is located in the model folder within the de.itemis.pedelec.tracing project.

The configuration file is automatically created if it does not already exist. The project and the folder must exist in this case.

YT can store links in the following different types of link storage:

Links are stored in a native file when you assign a Native File data access to a link type. The configuration supports one option: links can be protected using the readOnly option. No write operations (create/update/delete) will be allowed for such links.

Example:

readOnly

This link type monitors a configured folder and loads all data access files in that folder automatically. Removed files are also unloaded automatically. The loaded files are read only.

Example:

folder "/de.itemis.pedelec.tracing/generated/"

As an example, this link type can be used if trace data is generated automatically while generating code. It is recommended to handle such trace data in a separate file instead of adding the data to the main data access.

Keywords, options, configurations

Keywords

  • == – „Equals” operator to use within a condition
  • != – „Not equals” operator to use within a condition
  • addressOf – Starts an addressOf condition.
  • baselineSetDefinition – Defines the „Baseline Set Definition” that is to be loaded.
  • baselineSet – Defines the „Baseline Set” that is to be loaded.
  • contains – Constraint for substring check
  • if – Third keyword of an include expression. Starts a block of conditions.
  • in – „In” operator to use within a condition
  • include – Starts an include expression. Artifacts satisfying the expression right from the include keyword will be included in the result set.
  • map – Starts a mapping block.
  • Module – Allows to access the parent module of an object for mapping.
  • modules – Second keyword of an include expression. Defines that the following conditions are evaluated on module level.
  • objects – Second keyword of an include expression. Defines that the following conditions are evaluated on object level.
  • project – Defines which project is to be imported.
  • Project – Allows to access the parent project of an object for mapping.
  • resource – A pattern for a project, folder or file in the workspace.
  • to – Defines the relation of a custom attribute to the value it is mapped to.
  • valueOf – Starts a valueOf condition.
  • server – Defines the server to be used.
  • port – Defines the port to be used.
  • file – Defines the file to be used for storing.

Options

  • cell – Optional regular expressions for content or address of a cell
  • element matches – XPath expression for the selection of artifacts
  • identified by – Unique key for an artifact in this document.
  • column with header – Defines within a valueOf expression in a configuration of the Excel adapter that the value is contained in a column with a certain column header provided right from the keyword.
  • locate bookmark where subset – Bookmark recognition(s). This can be used to filter valid bookmarks by defining a regular expression on the full label format, see detailed explanation below.
  • locate text where pattern – Regular expression recognition(s)
  • map – Attribute mappings for custom attributes
  • map to type – ReqIF type long name filter
  • name – Name for the matched artifact
  • resource – File filter pattern
  • sheet – Regular expression for the workbook sheet name
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter
  • type – ReqIF specification type long name filter

Configurations

  • … as block|line comment – Specifies whether YT creates block or line comments for new links.
  • analyze comments of … – Which artifact type represents the C artifact. Possible Values are A and B.
  • create links by … – Specifies how YT calculates the content of new comments on link creation. The specification is a concatenation of static strings and values of artifact attributes.
  • in – „In” operator to use within a condition
  • locate links by – A regular expression for the text portion in the comment of the C files representing a link. YT relies on Java regular expressions.
  • map { … } – As an option, it is possible to define link attributes and derive the attribute values similar to the identifier derivation specified by identified by.
  • separatedby – As an option, it is possible to define a separator, that separates identifiers in a list, e.g. requirement ids that can be linked with ids in one cell of an Excel document.
  • where – Specifies the relevant attributes for the identification of an artifact linked to a C element.

YT query language

The YT query language enables dedicated analysis of and specific information from the whole trace model (i.e. the graph of artifacts and links, including unlinked artifacts, attributes of artifacts, and attributes of links) which has been created by YT based on the configuration and the information that has been extracted from the various data sources.

Queries are processed by the YT query engine in three steps:

  1. Extract relevant data. Based on the definition of the query, YT evaluates the trace model and collects all matching result elements in a result model set that is specific for the given query. In contrast to an SQL result set, the result model set is not a tabular, flat sequence of data rows, but an object-oriented data model with entities of possibly different types and with relations between those entities.
  2. Flatten the result model set. This step transforms the result model set into a tabular result set with „data rows” of a homogeneous structure.
  3. Filter, aggregate, and sort data. Process the result set. This is similar to SQL.

YT query language elements

A YT query consists of up to six elements which are listed in the table below and are described in more detail in the subsequent sections.

Language Element Syntax Description Optionality
Query meta data query "name" description "description" Defines the display name of the query and an optional description. mandatory (description is optional)
Data source source(expression) Defines the algorithm a.k.a. query function which evaluates the trace model and returns a model set of result model set, i.e. the elements of the result set are not records, but objects, i.e. entities with attributes and relations. The expression may also contain parameters passed to the algorithm. This part can be roughly compared to the FROM clause of an SQL query mandatory
Data transformation collect(comma-separated feature selections) Defines the transformation of the result model set into a result set. This part can be roughly compared to the SELECT clause of an SQL query. Similar to an SQL SELECT clause it is possible to assign a name to the column of the result set by an optional AS customName as a suffix to one feature selection. With a prefix of @, it is also possible to use aggregator functions such as @sum. mandatory
Filter where(expression) An expression restricting the rows of the result set optional
Aggregation groupBy(comma-separated feature selections) Defines how the query results should be aggregated or projected. optional
Ordering orderBy(comma-separated feature selections) Defines the order of the rows of the query result. optional

Elements of a YT query are separated by a . (dot), possibly with blank space left or right from the dot. An exception are query meta data and data source: These query elements are separated by blank space. This is illustrated by the following example which utilizes all language elements.

query "name" description "description of the query"
 source(someQueryFunction(parameter1, parameter2))
 .collect(attribute1 as A1, @sum(attribute2) as A2)
 .groupBy(attribute1)
 .orderBy(A2)


Source clause

The expression specified in a source(expression) clause links to an algorithm which processes the trace model and returns a set of result models. The algorithm itself is a so-called query function implemented in Java. The expression can pass parameters to the query function. YT does not restrict the types of the model elements of the result model set in any way.

A crucial characteristic of a query function is its return type. While YT does not restrict the element types of a result model set, all elements in the result model set of a given query are of the query function’s return type.

As an example, YT provides the following query function:

Iterable<TVMDArtifact> allArtifacts(TVMCArtifactType type)

The allArtifacts function is one of YT’s built-in query functions. The definition above shows that allArtifacts takes a single parameter of type TVMCArtifactType, which represents any artifact type. The result model set returned by allArtifacts contains all artifacts of the specified artifact type. It comes in the form of an Iterable of TVMDArtifact, i.e. as a sequence of zero or more TVMDArtifact objects, each of them representing an artifact of the specified type.

Consequently, a YT query using the allArtifacts function in a source clause, as in e.g. source(allArtifacts('TestCase')), populates the result model set with matching TVMDArtifact elements, in this case with elements of type TestCase.

YT query clauses right from the source(allArtifacts(type)) clause operate on these elements. Like all TVMDArtifact, a TestCase has a name and a version. So a query like

query "simple example" source(allArtifacts('TestCase').collect(name as n, version as v)

creates a result set with columns n and v containing the name and the version of the TestCase artifacts.

Generally speaking, query clauses right from the source clause like collect, where, etc. are based on the element type of the result model set and consequently on the query function’s return type. If, for example, you replace the query function expression allArtifacts('TestCase') by a different query function, say foobar('TestCase') with a different return type, the whole query might become invalid.

Apparently, being versed in the YT query language requires knowledge not only of the query language syntax, but also of available query functions, their return types, the specifics of these types, and the data model as a whole.

Please find a complete overview of the built-in query funtions and their return types in section YT built-in query functions.

Extending the YT query language by custom query functions

Since YT recognizes query functions dynamically during runtime, it is easy to add custom query functions to YT and in this way extend the YT query language with evaluations that are specific to your development process.

Collect clause

A collect clause defines which attributes of the model elements returned by the query functions are taken over as a result set row of the YT query. A collect clause defines rules for the relevant attributes column by column, the rules being separated by comma. Each individual attribute is defined by navigating the attributes of an element of the result model set. The syntax is a dot-separated expression defining the access to attributes and getter functions, similar to e.g. the C# programming language.

As an example, the query function tracesFromTo returns a set of traces.

  • A trace has a start (of type Artifact)
  • … which has a data source, representing e.g. the file for a requirement extracted from a Microsoft Word document,
  • … and an identifier, e.g. the name of the file.

So, a query like:

query "Requirements covered by test cases"
    source(tracesFromTo('Requirement', 'TestCase'))
    .collect(Start.DataSource.Identifier as FileName, Start.Name as ID)

returns a result set containing FileName and ID of Requirements which are (not necessary directly) linked to TestCases. A Requirement which has n TestCases assigned is listed n times in the result set.

Within a collect clause, you can not only access attributes, but also apply aggregator functions. As aggregator functions are making sense with an aggregation only, a groupBy clause is mandatory if using such functions. Available aggregator functions are:

Aggregator function Description
@avg(expression), @max(expression), @min(expression), @sum(expression) Calculates the average, maximum, minimum, or sum, respectively, in an aggregation. The specified expression must evaluate to a numeric value.
@count(expression) Counts the number of elements. The expression is irrelevant for counting the elements, but it must be specified and valid. For example, @count(1) would be perfectly sufficient for counting the elements.
@first, @last Returns the first resp. last element of an aggregation.

Example: The query

query "Requirements covered by test cases"
    source(tracesFromTo('Requirement', 'TestCase' ))
    .collect(Start.Name as ID, @count(End) as Coverage)
    .groupBy(Start.Name)

returns a result set containing the IDs of Requirements and the number of (not necessary directly) linked TestCases.

Where clause

Values of a result set are matched against the boolean expression specified by a where clause. Within a where clause, boolean expressions can be combined using or or and logic. Grouping them by parenthesis (…) is supported. The available operators are as follows, in the order of highest to lowest precedence:

Type Operator Description
Primary expression (...) Grouping
Primary expression attribute Attribute evaluation, see Collect clause
Primary expression literal false, true, null, number, string (between double quotes, e.g. "This is a string.")
Unary operators !, -, + Logical NOT, negative number, positive number
Multiplicative operators *, /, % Multiply, divide, modulo
Additive operators +, - Add, subtract
Relational operators >=, <=, > , < Larger than or equal, smaller than or equal, larger than, smaller than
Equality operators ==, != Equal, unequal
Logical AND operator && Combines two boolean expressions by a logical AND. The resulting expression evaluates to true if the combined conditions both evaluate to true, else false.
Logical OR operator || Combines two boolean expressions by a logical OR. The resulting expression evaluates to true if at least one of the combined conditions evaluated to true, else false.

Example: The query

query "Requirements covered by manual test cases"
    source(tracesFromTo('Requirement', 'TestCase'))
    .collect(Start.Name as Id, @count(End) as Coverage)
    .where(Start.AttributeValue("Status") == "Verified" && End.AttributeValue("Execution Kind") == "Manual")
    .groupBy(Start.Name)
    .orderBy(Coverage)

finds all verified Requirements with their respective number of linked manual TestCases. The requirements are grouped by the name of their sources. Within each group they are ordered by their coverage, i.e. by the number of test cases assigned.

GroupBy clause

Every so often you are more interested in certain higher-level characteristics of a result set than in the individual members of a query result. A basic example would be to return the total number of requirements that are associated with at least one test case and the total number of those that don’t.

This requires to first group the result set elements by an attribute like, say, hasTestCases, and then count the members of both groups using the @count aggregator function. Such a group is called an aggregation.

Another example is shown near the end of the Collect clause section above. The query function tracesFromTo('Requirement', 'TestCase') returns all traces from requirements to directly or indirectly associated test cases. Requirements having multiple test cases appear multiple times in the resulting traces. Now essentially two things happen:

  • The groupBy(Start.Name) puts all trace elements with identical requirement names into a group of their own, respectively. That is, if a requirement has, say, five test cases, then five of the trace elements returned by the query function will contain that requirement as their start attribute. These trace elements will be grouped into an aggregate of their own, just like other trace elements with identical requirement names.
  • In the collect(Start.Name as Id, @count(End) as Coverage) clause, the @count(End) aggregator function is particularly interesting, because it counts the elements in each aggregation. The sample collect clause creates a result set with two columns: Column Id holds the requirement names, and column Coverage holds the number of test cases for each of those requirements.

Aggregator functions work on aggregations and thus require a groupBy clause to be present in the YT query.

It is possible to group a result set by more than just one criterion. Multiple feature selections are specified as a comma-separated list, e.g. groupBy(A, B, C).

OrderBy clause

The orderBy clause is used to sort the result set by one or more columns. An example is given in section Where clause.

YT built-in query functions

YT comes with a lot of built-in query functions. As foreshadowed in section YT query language elements, these functions do not return plain data records, but a set of result models, e.g. models containing instances of artifacts and links. The result models returned by the built-in YT query functions are all based on the same meta-model. The returned models are complete; if e.g. a function returns a set of links, it is possible to navigate from such a link first to the artifact at end A and then from there to the artifact type.

List of built-in query functions

Function Description Parameters Return type, i.e. set of … Example
allArtifacts Finds all artifacts of a given type. Type: ArtifactType Artifact source(allArtifacts('TestCase')).collect(Name)

Returns all names of all test cases.
allArtifactTypes Lists all artifact types specified in the YT configuration. ArtifactType source(allArtifactTypes()).collect(Name)

Returns all names of all artifact types.
allLinkTypes Lists all link types specified in the YT configuration. LinkType source(allLinkTypes()).collect(Name)

Returns all names of all link types.
allTraceLinks Lists all links for a given type Type: LinkType Link source(allTraceLinks('Requirement --> Test')).collect(ArtifactA.Name as Req, ArtifactB.Name as verifiedBy)

Returns both ends of all links between requirements and tests.
artifactsWithoutTraceFromTo Finds all artifacts of one type that have no traces to any artifact of a second type. TypeA: ArtifactType
TypeB: ArtifactType
Artifact source(artifactsWithoutTraceFromTo('Customer Requirement', 'Test Result')).collect(Name)

Returns all customer requirements without any assigned test results. „Assigned” in this case means „reachable via a chain of links”, e.g. from Customer Requirement to System Requirement to System Test Case to Test Result.
join Joins two query results (i.e. from q). Query1: QueryResult
column1: ColumnName
Query2: QueryResult
column2: ColumnName
QueryResult source(join(q('q1'), "artifact", q(q2), "start")).collect(left("Name") as name, right("End") as end)

Returns the „Name” of „q1” and all "End"s for these artifacts in „q2”.
linkedArtifacts Finds all artifacts of a given type that have at least one link. Type: ArtifactType Artifact source(linkedArtifacts('TestCase')).collect(Name)

Returns all names of all linked test cases.
notLinkedArtifacts Finds all artifacts of a given type that have no link. Type: ArtifactType Artifact source(notLinkedArtifacts('TestCase')).collect(Name)

Returns all names of all test cases which are not linked.
q Get the result of one query as input for another one like join or union. Query: Query QueryResult source(q('AnotherQuery')).collect(column("Name") as name)

Returns the column „Name” from „AnotherQuery”.
tracesFromTo Finds all traces (i.e. chained trace links) between two artifact types. TypeA: ArtifactType
TypeB: ArtifactType
Trace source(tracesFromTo('Customer Requirement', 'Test Result')).collect(Start.Name, @count(End)).groupBy(Start.Name)

Returns all customer requirements with at least one assigned test result and the number of these assigned test results. „Assigned” in this case is defined as above.
traceMatrixFor Calculates all possible traces between two artifact types, while also considering incomplete, or interrupted traces. TypeA: ArtifactType
TypeB: ArtifactType
Trace source(traceMatrixFor('Customer Requirement', 'Test Result')).collect(ByType("Customer Requirement"), ByType("Software Requirement"), ByType("Implementation"), ByType("Test Case"), ByType("Test Result")).groupBy(Start.Name)

Assuming that the trace model looks as follows: „Customer Requirement” -> „Software Requirement” -> „Implementation” -> „Test Case” -> „Test Result”. The result will contain all distinguished traces between each and every artifact in the chain. Also unlinked artifacts are included.

Query result meta model

For the results of the built-in YT query functions the most important domain objects and their relations are illustrated and described below.

DataSource: Represents the origin from which artifacts or links have been extracted. E.g. for the Microsoft Word Adapter, a DataSource represents the Microsoft Word Document. For the IBM DOORS adapter, the DataSource represents the DOORS module.

Attributes:

  • identifier: The name of the DataSource

Link: A single trace link between two artifacts.

Relations:

  • artifactA: The „A” end of the link
  • artifactB: The „B” end of the link
  • configElement: The defining link type from the YT configuration
  • dataSource: The origin or storage medium of the link

Attributes:

  • Attributes: A map containing the attributes of the link (as defined in the YT configuration of the link type). The values of this map are accessible by means of function AttributeValue(key) in the query language, e.g. collect(… AttributeValue("my custom Attribute") as MyCustomAttribute).
  • versionA: The version of artifactA at the time of link creation / last link update
  • versionB: The version of artifactB at the time of link creation / last link update

Artifact: Represents a traceable artifact that may or may not have links.

Relations:

  • configElement: The defining link type from the YT configuration
  • dataSource: The origin or storage medium of the link
  • linksAsA: All links where the given artifact has the role ArtifactA
  • linksAsB: All links where the given artifact has the role ArtifactB

Attributes:

  • Attributes: A map containing the attributes of the link (as defined in the YT configuration of the link type). The values of this map are accessible by means of function AttributeValue(„key”) in the query language, e.g. collect(… AttributeValue("my custom Attribute") as MyCustomAttribute ).
  • name: The name of the artifact
  • position: The information where the artifact is located in its data source. For example, for IBM DOORS, the position of a requirement is the absolute number.
  • version: The current version of the artifact. The algorithm for version calculation depends on the technology of the adapter, e.g. for Microsoft Excel, the version is a snapshot of all configured attributes. For PTC Integrity, the version is the modifiedDate of the item being represented by the artifact.

Trace: Represents a chain of linked artifacts, i.e. the n th artifact in the chain has a direct link from the artifact at position n-1 and a direct link to the artifact at postion n+1.

Relations:

  • start: The first artifact of the chain
  • end: The last artifact of the chain

Attributes:

  • traceLength: The number of links in the chain
  • artifactAtIndex(int n): The n th artifact in the chain. The index is zero-based, i.e. artifactAtIndex(0) equals start.

LinkType: Reflects an artifact type specified in the YT configuration.

Relations:

  • typeA: The artifact type specified as artifact type A
  • typeA: The artifact type specified as artifact type B

Attributes:

  • classification.name: The classification as specified in the YT configuration
  • name: A string representation of the linked type (which in the main part consists of the names of the linked artifact types)
  • roleA.name: The role of end A as specified in the YT configuration
  • roleB.name: The role of end B as specified in the YT configuration

Note: From a technical point of view, the above-listed attributes of a link type are not shallow attributes, but attributes of related objects, e.g. the attribute classification.name is the name of the classification the link type is related to. Nevertheless, from a domain point of view, „attribtutes of related objects” can be viewed as attributes of the link type.

ArtifactType: Reflects an artifact type specified in the YT configuration.

Relations:

  • linksAsA: All link types where the given artifact type has the role typeA
  • linksAsB: All link types where the given artifact type has the role typeB

Attributes_

  • category: The category as specified in the YT configuration
  • providerName: The name as specified in the YT configuration

Release notes

FM2 (1.1.1705)

New – MS Word adapter recognizes „headings” as candidates

We extended the MS Word adapter to recognize headings as candidates. The configuration language now supports the „heading” keyword as in the example below.

locate heading where pattern matches ".*" {
}

This will find any heading as candidate that matches the regular expression „.*”. Find all details in the Microsoft Word – Artifact Type documentation.

New – quick fix remove all duplicate links at once.

A new quick fix was added to remove all duplicate links in one step. This means that all, but one link is removed. The user can not influence which link survives the clean up. „Read-only” links can not be deleted, therefore the result of the quick fix is one of the following:

  • YT will keep all „read-only” links.
  • YT will keep exactly one „editable” link.

Improvement – Error handling for the batch export.

When running the YT batch export application on a continues integration server, the job will now be marked as failure when an error occurs during YT execution.

Improvement – Name validation for configuration editor.

The configuration editor will now validate that there are no name clashes for data access and artifact types.

Improvement – Error handling for the batch export.

When running the YT batch export application on a continues integration server, the job will now be marked as failure when an error occurs during YT execution.

Improvement – Name validation for configuration editor.

The configuration editor will now validate that there are no name clashes for data access, artifact types, artifact categories, artifact attributes, link classification and link roles.

Improvement – Performance tweak for suspicious link validation.

We increased the performance of suspicious link validation for large link numbers.

Improvements of YT Issues

Improvement – YT Issues view allows limiting the number of displayed issues.

The YT Issues view now allows to limit the number of issues displayed to a user defined number.

Improvement – YT Issues view – YT Issues view allows filtering and grouping issues by type.

The YT Issues view now allows to filter and group the shown issues by type displayed.

Improvement – YT Issues view „Previous” and „Next” issue buttons behave more intuitive.

When opening the YT issues details view the „Previous” and „Next” issue buttons will jump to issues respecting the order of the issues list.

Improvement – Visual overhaul of YT Overview.

The artifact representations in the YT Overview are now drawn with a color gradient and will cast a shadow.

Bug fix – Overlapping artifact configuration cause bad performance of IBM Doors adapter

When configuring multiple artifact types that point to the same objects in Doors, under certain circumstances the Doors adapter did not fetch all relevant attributes in one swing. This results in poor performance since the adapter has to reload missing attributes lazily.

Bug fix – Wrong tool tips in YT Overview

The tool tip for the link direction evaluation switch now change their text based on the state of the switch.

Bug fix – Native YT data not correctly reloaded

Fixed an issue that prevents YT from recognizing changes in the native data storage outside YT. When the data.yt file changed outside YT, e.g. by the version control system YT will now reload the file correctly.

Bug fix – Column order and size lost after restart

The columns can now be reordered and resized. The changes will not be reset after closing the dialog or restarting YT.

Bug fix – The role label for artifacts in YT Editor were not updated correctly

Bug fix - „Active” indicator in the configuration editor did not reflect the correct state of artifact and link types.

The „active” check mark is now updated correctly for artifact and link types even when multiple mappings are defined.

FM1 (1.1.1701)

Improvements of XML adapter

We updated the XML and XPath framework which is used under the hood of YT. This does not only improve the performance of the XML adapter, it also faciliates the evaluation of substrings. Think of an XML such as

  <testcase id="12">
	  <Req data="id=r44,status=approved"/>
	  <Req data="id=r47,status=approved"/>
	  ...
  </testcase>

In this case, YT can extract the requirement IDs r44 and r47 based on a configuration similar to

... 
map{
 reqIDs to valueOf("Req/substring-before(substring-after(@data,'id='),',')")joined with separator ";"
}
...

Improvement of Enterprise Architect adapter

Link types mapped with the EA data access can now be configured to recognize an UML relation as a trace link in opposite direction.

Let’s say we have a dependency in UML from DesignDetail to Design (i.e. DesignDetail is dependent, Design is supplier). In this case, YT can be configured to recognize this relation as trace link from DesignDetail to Design or in opposite direction. Before, YT always recognized such relations as being directed from the owner to the related element (i.e. from DesignDetail to Design ). A link type configuration of

link source is B 

configures YT to recognize the relation in opposite direction.

Better error handling if DOORS cache is corrupt

When the DOORS cache was corrupt, you had either had to delete it manually from disk or by means of YT. The latter required entering a sequence of commands

  1. Deactivate data access "DOORS"
  2. Choose Update DOORS data
  3. Reactivate data access "DOORS"

We improved the usability in such cases by means of a notification dialog which encapsulates the above sequence.

Improvements of YT Overview

It is now possible to choose whether the graph in the YT Overview is calculated by evaluating links in direction „from A to B” or bidirectional.

Improvements of YT Configuration Editor

  • We made the auto-completion in the mapping area for data access, artifact types and link types a little smarter: When entering strings, the recognition of the closing double quote has been improved so that the auto completion does no longer insert two double quotes at the end of Strings.
  • Issues that were found during the validation of configuration consistency are now not only listed in the YT Issues view, but also marked in the YT Configuration editor.

YT prevents evaluation or validation during data load

When triggering a validation or a report creation, YT notifies the user that the result of the current operation may be based in incomplete data and offers the choice to validate immediately or to wait until data are loaded completely.

Order of columns of Artifact Search Dialog can be adjusted by the user

You can now order columns or change the width of columns. The changes are specific for the chosen artifact type which means that you can define different layouts for different types. Once adjusted, the layout is stored as a preference on your disk so that your adjustments are applied valid if YT is closed and re-opened.

Query language supports AND and OR

The expressions in the where clause of the query language now support the combination of conditions by && (and), || (or) and () (brackets specifying precedence), e.g.

query "All Test Results with exactly three incoming links"
source (linkedArtifacts('Test Result'))
	.collect(Name as ArtifactName)
	.where(LinksAsB.size > 2 && LinksAsB.size < 4)

Bug fixes

Fix in YT Editor

We fixed a bug in the YT Editor regarding the labels of sections Artifact A and Artifact B:

In multiple types mode, i.e. when a section is populated with artifacts of more than one artifact type, the label does no longer append the role configured for one of the associated link types. Instead, it simply states multiple types.

Fix regarding YT Favorites view

We also now prevent the YT Favorites view from pushing to the front.

Before, the view was pushed to the front during startup of YT even if you put another view in front of the YT Favorites view within a prior session.

EM6 (1.1.1649)

The YT Explorer now supports multi-select and drag and drop

It is now possible to select multiple artifacts in the YT Explorer at once and to drag and drop the whole selection directly into the YT Editor. You may select ranges of artifacts (by means of the [SHIFT] key) or more distributed artifacts (by means of the [CTRL] key)

YT visualizes the attributes of artifacts in the YT Explorer

You may already know the hover showing the attributes of a trace artifact in the YT Overview. This has been applied to YT Explorer as well.

Bug fixes

DOORS adapter

We fixed several minor bugs regarding the connection of YT and DOORS, e.g. that the selection from DOORS to YT has not been propagated if DOORS had been closed and re-opened while YT was running. We also tweaked the generator that creates – based on the YT configuration – the DXL script which extracts the relevant data from DOORS. Time and memory consumption have been reduced by about five percent. Not that much; but it’s noticeable as YT is used in projects with more than 80,000 DOORS objects.

YT Editor

We fixed a bug in the YT Editor where the Set As A and Set As B buttons were sometimes deactivated for no reason.

EM5 (1.1.1647)

Creation of m:n links of different types

It is now possible to create a plurality of trace links in a single step. The YT Editor supports the creation of trace links for the cartesian product of artifacts in sections A and B – even for a combination of trace links of multiple link types.

As this method carries the risk of creating unintended links, it is guarded several times in YT.

  • First of all, the feature is disabled by default. Before first usage, it has to be activated manually in the YT preferences. (Window → Preferences → …)
  • Furthermore, YT requires a user confirmation if creating trace links of different types in a single step.

    This confirmation cannot be deactivated.
  • And of course, YAKINDU Traceability will never link artifacts without a valid link type definition provided by the YT Configuration.

The YT Configuration now supports attribute names with special characters

YT now supports attribute names with special characters for the definition of trace artifact types or trace links types. In the mapping definition, they have to be quoted.

EM4 (1.1.1643)

  • New features
    • The license management is now unified for all YAKINDU products. The YAKINDU license management supports file and floating licenses.
    • For CDT artifacts , it is now possible to configure which artifacts are relevant based on their type (e.g. YT should recognize only TranslationUnits). If no configuration is given, YT recognizes translation units, functions and function declarations.
    • YT visualizes the attributes of artifacts now in the properties view and in the YT Overview (in an hover).
    • It is now possible two create „m:n” links by means of the YT Editor. YT links the cartesian product of artifacts in sections A and B.
    • The coverage report is now better configurable: It is possible to add more than one link type and to choose whether unlinked Artifacts should be integrated in the report.
    • YT offers a validation that reveals duplicate links . As quick fix, the duplicate can be removed.
  • Improvements
    • YT does no longer trim the name of candidates.
    • When creating a new artifact type, YT now assigns colors with more contrast (rainbow color scheme).
    • MS Word Adapter
      • For configured regular expressions with more than one match, YT now creates one linkable artifact instead of ignoring duplicates completely.
      • Word does ignore matches of regular expressions in text sections that are marked as deleted.
    • The dialog showing suspicious link Ends now uses a table and a Diff Viewer to show deltas in longer texts.
    • The YT Explorer can be configured to also show unlinked artifacts.
  • Bug fixes
    • Fixed a resource leak (memory and performance) when quickfixing hundreds of suspicious Excel links at once.
    • The local cache for DOORS data had been deleted on any error during read (e.g. in case of an out-of-memory error). This has been fixed; YT deletes the cache only if it recognizes the file as corrupt.
    • The layout of tables in the YT Favorites view and in the YT Selection History was sometimes broken after YT restart. This has been fixed. YT also applies a smarter layout algorithm.
    • Sometimes, YT considered the local storage „data.yt” as read-only, when the file was empty and the first link had been saved.
    • Fixed a bug when editing an YT Configuration that is write protected. YT notifies the user and offers a „save as” option.
    • YT considers multiple mappings for the same DOORS artifact type correctly.

EM3 (1.1.1639)

  • New features
    • YT’s data management layer has been reworked completely. This affects mainly the mechanics and scheduling of how YT loads and updates data for the different data accesses, artifact types and link types. For example, YT now reloads links and artifacts automatically if a document changes. As a consequence, the buttons which triggered a reload of Excel, Enterprise Architect and attribute mapping links have been removed.
  • Improvements
    • Word adapter can be configured to use the font style as a filter, e.g. requirements will be recognized only if style is not strikethrough.
    • Excel adapter can use cell headers for artifact localization, e.g. locate cell where { … column with header „Requirement ID” }.
    • Better usabilty for context menu of YT Explorer. The /[Entf] button now deletes the link from the currently selected artifact to its parent.
    • Better user information if a search does not find any artifacts of a given type, e.g. because the data access had been disabled by the user.
  • Bug fixes
    • A potential inconsistency in the configuration of the Word adapter has been removed. The adapter does no longer accept more that one subset definition if locating bookmarks.

EM2 (1.1.1635)

  • Improvements
    • Word adapter supports these new features:
      • Finding headings as artifacts
      • Finding attributes in nearby cells, when the artifact is in a Table
      • More accurate results for *.doc files (Word 97-2003): special (hidden) characters are properly removed. Note that this may cause a version change for existing artifacts. This may affect attributes for artifacts located in tables, or containing special fields (such as references).
    • Usability of configuration editor has been improved.
      • Editing values requires a double-click instead of a single click.
      • It is now possible to delete table entries by hitting the /[Entf] key.
      • Better synchronization of editor content if the underlying file is updated.
    • YT Explorer
      • We added a new grouping. It is now possible to show the tree „in direction from A to B, but not from B to A” by means of Group by → Artifact Type (directed).

EM1 (1.1.1631)

  • Improvements
    • Mylyn artifact type: To be consitent with other adapters, keyword ‚valueOf’ is now mandatory
    • Data Extract: Improved the editor for mapping defintions from YT data to custom RDBMS schema
    • Several minor usabilty improvements (error messages, field labels, etc.)

DM4 (1.1.1627)

  • Improvements
    • YT Configuration editor has been redesigned
        • Improved usability
        • Better visualization of configuration items data access, artifact types, link types
        • A configuration can be activated directly from the editor
    • Excel adapter: Improved performance of link derivation
    • DOORS adapter: Better management of connection to DOORS
    • XML adapter
        • It’s now possible to read XML files in ZIP archives.
    • Adapter can now be configured to join attributes of multiple XML nodes into one single YT attribute
  • Bug fixes
    • DOORS adapter: Fixed a bug when querying a project baseline

1.1.1625

  • New features
    • Added a new default report showing unlinked artifacts
  • Improvements
    • Better information message if user tries to copy ‚nothing’ into YT Editor
    • YT now supports custom queries in YT data extract
    • YT now remembers user’s adjustments to the size of the Artifact Search dialog
    • DOORS adapter:
      • Added code completion for data access configuration (values of project, baselineSet, baselineSetDefinition)
      • YT allows the configuration of default values if an attribute of a requirement does not exist in DOORS.
      • YT puts DOORS in foreground if a requirement is opened
    • Improved information message if user saves a YT configuration with errors.
    • Removed support for „unnamed” link attributes for EA and Excel links.
    • Configuration Editor: Added means to synchronize (i.e. update) declaration of attributes with attribute’s value assignments.
  • Bug fixes
    • C adapter does no longer mix files if more than one data access defined
    • Fixed a bug in Quickfix-Action „Delete all links” for missing artifacts
    • If a user fast deletes multiple artifacts from YT Editor, YT does not open these artifacts (fast clicks no longer perceived as double-click)
    • PTC Integrity adapter: data access no longer disabled if user installs the mksapi.jar
    • YT does no longer loose connection to DOORS if user refreshes DOORS data during load
    • Fixed a bug in dialog for Report Generation: YT „forgot” parameter values if a parameter had been selected and de-selected immediately.
    • YT now is robust regarding „links to self” if executing a query on the traceability graph.

1.1.1623

  • Improvements
    • Several Usability improvements for the Favorites View and Selection History
    • Removed YT Observer functionality (outdated)
    • Add custom queries to YT batch data extract
    • The DOORS data load now honors user cancellation
    • Invasive Excel storage: YT always suffixes the link information with the separator symbol (i.e. Vertical bar a.k.a Pipe-Symbol)
  • Bug fixes
    • Refresh file after close in Excel does no longer block out YT
    • „All validations” now includes configuration consistency validation
    • Progress bar is shown when updating DOORS data
    • YT is now more robust regarding race conditions occurring if the Eclipse UI decides to decorate nodes in the YT Explorer during restart of YT
    • Fixed a bug when processing selection from Enterprise Architect. Updated user documentation as well.

1.1.1621

  • Improvements
    • Reduced memory consumption when reading links stored in a plurality of files (which is the case e.g. for Eclipse CDT)
    • Made „names” (i.e. YT the representation) of DOORS requirements configurable
  • Bug fixes
    • Enterprise Architect adapter can update also EA replica models

1.1.1619

  • New features
    • Added Suspicious Validation for Excel and Enterprise Architect invasive storages
    • YT is able to store links in Enterprise Architect invasively
  • Improvements
    • Improved performance when reading data from DOORS
  • Bug fixes
    • Key-based link derivation for invasive storages and Attribute Mapping is more robust regarding missing keys
    • Re-enabled code completion during configuration of artifact types for PTC Integrity

1.1.1617

  • New features
    • YT is able to store links in Excel invasively
    • YT is able to store links in Enterprise Architect invasively
  • Improvements
    • DOORS adapter: Query all data in one request instead of sending several smaller requests
    • Removed password protection from Configuration Editor
    • Improved Logging for several link types (Excel, Attribute Mapping, DOORS)
    • Improved capabilities to update data for dedicated data accesses (Excel, Attribute Mapping, DOORS, PCT Integrity) and YT as a whole
    • Improved performance for adding C artifacts to YT Editor
    • Smarter content assist for file resources
    • Excel artifacts: Mapping of attributes can now be defined based on column with header
    • YT Editor gives a warning if a user is about to create link duplicates
    • Suspicious Validation: Better performance when doing a quickfix for a plurality of issues
    • Bug fixes
    • Textual filter in YT Explorer now works also if grouped by link type
    • Attribute Mapping does no longer consider a match if attributes are missing on both sides

1.1.1613

  • Improvements
    • Consolidated YT Configuration Editor: roles, classification and categories can be defined "in place"
    • Improved performance when deleting multiple links at once
    • DOORS adapter: Added performance logging
  • Bug fixes
    • If the active configuration is already opened in an editor, „Opening” the active configuration by means of menu does not open a second editor, but activate the one which is already open
    • Fixed a bug regarding User Interface blocks when editing two YT configurations in parallel
    • YT Reporting: Fixed a bug when appending new Excel-Sheets to xlsm files
    • Removed unnecessary restriction regarding artifact types that could by linked from CDT adapter

1.1.1611

  • New features
    • link type for Enterprise Architect stores links as Requirements in EA
  • Improvements
    • DOORS adapter & Word adapter
      • the „version” of an Artifact in YT is computed by a snapshot of the attributes mapped the artifact type definition
    • CDT adapter
      • Fixed a bug when deleting multiple links within the same comment at once
    • PTC Integrity adapter
      • YT ensures that an artifact type definition for „PTC Integrity” must be mapped to a data access for "PTC Integrity"
  • Bug fixes
    • Closing YT does no longer cause a launch of the DOORS client
    • Fixed a bug regarding white spaces in the path to DOORS cache
    • Quick fixing a plurality of suspicious links at once works
    • CDT adapter filters duplicates of comments (this is a compensation for a bug in CDT)
    • When reading the currently selected requirement in DOORS, YT is no longer blocked by modal dialog in DOORS.
    • Fixed a bug in the evaluation of the configuration of Excel / Word adapters with more than one resource definitions

1.1.1609

  • New features
    • Introduced Traceability menu
    • link type for Enterprise Architect derives links based on tagged values of EA Requirements
  • Improvements
    • DOORS adapter
      • Link recognition supports either Artifact A or Artifact B as „source” of a link
      • Improved representation of enumeration values in YT attributes (honors not only „string”, but also „value”)
    • CDT adapter
      • Improved performance for link derivation
      • Added expressive logging
  • Bug fixes
    • Report creation dialog recognizes templates in linked projects (i.e. projects not residing physically in workspace)
    • Removed duplicate initialization of DOORS Data access

1.1.1607

  • Improvements
    • EA adapter retrieves Tagged Values as attributes of artifacts
    • Stronger validation for PTC adapter (only one data access is supported)
    • Improved performance when creating multiple links at once
  • Bug fixes
    • Fixed wrong assignment of stereotypes in graphviz export
    • Report creation now honors report parameters (they were ignored before)

1.1.1605

  • Improvements
    • Improved usability of „Create Report” Dialog
  • Bug fixes
    • Fixed a bug regarding artifact recognition when copying artifacts from Excel to the YT Editor
    • DOORS adapter now considers only assigned (not all) data accesses during evaluation of baseline configuration
    • Fixed inconsistencies in YT Configuration Editor when creating new artifact and link types in one modification

1.1.1603

  • Improvements
    • Suspicious Validation shows Attribute values ‚before’ and 'after'
    • Excel adapter: Provides access to Excel metadata such as ‚title’ or custom metadata attributes
    • CDT adapter: Improved performance for link evaluation
    • Improved progress bar messages when waiting for a DOORS login
    • Updated base technology EMF Compare from 3.0 to 3.1
  • Bug fixes
    • Fixed a bug which disabled quickfixes for Suspicious Validation
    • Search in YT Explorer now works when grouped by 'link type'
    • DOORS adapter: Fixed a bug affecting link recognition in baselines
    • Fixed inconsistencies in YT Configuration Editor when creating new artifact and link types in one transaction

1.1.1552

  • New features
    • YT supports invasive linking to C-Artifacts (based on Eclipse CDT)
    • Introduced native DOORS adapter which reads requirements and links from IBM DOORS
  • Improvements
    • Rhapsody adapter: configuration language supports filters for relevant artifacts (e.g. Class, State, UseCase, …)
    • YT warns if a new report overrides an existing file
    • Improved two-way-compare of YT data files
    • YT Configuration Editor
      • Edit any configuration file (not only the active configuration)
      • Improved warnings on save of configuration
  • Bug fixes
    • Rhapsody adapter
      • Fixed bug in selection propagation from YT to Rhapsody
      • YT now traverses Rhapsody models which are spread over several modules correctly
    • YT Selection History: Icon for „Set As A” does no longer overlay the whole application
    • Attribute Mapping Storage: Fixed race conditions if several Attribute Mappings are configured at once

1.1.1540

  • New features
    • Added means to cancel the load of PTC Integrity artifacts
    • As an option, a report now can be amended to an existing Excel file
    • Support of paste for a multiplicity of artifacts for MS Word and PTC Integrity
    • For Word artifacts, YT supports access to document’s metadata for attribute mappings
  • Improvements
    • YT Explorer
    • Improved rendering performance
    • Better support for textual filters containing a SPACE
    • Context-menu item „Delete All Links” is now inactive if links are read-only
    • Context-menu item „Specific Link Actions” contains also read-only links
    • Added sorting the the list of artifacts in the YT Editor
    • MS Excel adapter notifies the user if references to non-existing cells are specified
    • Better proposals for the configuration of the Enterprise Architect adapter
  • Bug fixes
    • YT Explorer now highlights a selected filter
    • YT Overview is now synchronized on "Delete All Links"
    • YT now handles operator „!=” (not equal) for PTC Integrity correctly
    • Attribute-mapping access: Fixed a bug in the recognition of artifacts with cardinality one-to-many

1.1.1532

  • New features
    • Added Rhapsody 8 support
    • Added generic XML adapter
    • MS Word adapter supports regular expression
  • Improvements
    • Refactoring of internal data model to improve performance
    • PTC Integrity
      • A link type is no longer mandatory for a data access
      • introduces operators „contains” and „doesNotContain” in the artifact type configuration
      • Default fields summary and text used for labels can be changed by configuration
    • If not active, YT shows a status message in all views, instead of complaining about the status in a dialogue.
  • Bug fixes
    • Fixed several typos in User Guide, several amendments
    • Fixed an error in the Error Dialog
    • Avoid Exception in installation dialog of mksapi.jar
    • Corrected the completion proposal within YT Configuration Editor for MS Excel artifact types
    • Enabled deletion of trace links with inconsistent link types
    • A hidden or closed YT Overview does no longer complain about the fact that it cannot render
    • YT doesn’t try anymore to validate the connection to PTC Integrity if server and port are not yet specified
    • It is now possible to activate the password protection for a YT configuration that just had been saved.
    • YT does no longer notify the user that „searching for candidates is not supported” if the search revealed an error or if simply no artifacts had been found.

1.1.1510

  • New features
    • Native Enterprise Architect Storage
    • Additional supported types for Rhapsody adapter
    • Non modal YT Search dialog for search artifacts by type
  • Improvements
    • Core
    • proper reporting if configured adapters aren’t installed
    • EA adapter
    • supports Enterprise Architect 10
    • filter/subset by namespace
    • Performance of Excel adapter in files with macros improved
    • Word adapter
    • Support for artifacts based on regular expressions
    • Existing configuration has to be changed (see Microsoft Word adapter for details).
  • Bug fixes
    • Hide artifact tab in properties view, if trace is selected
    • Subset evaluation consistently use ‚AND’ for different kinds and ‚OR’ for subset of the same kind
    • Errors during JAR installation (especially PTCs MKS-API)
    • avoid NPE during selections in Eclipse general 'Problems View'
    • Dependencies of UML2 adapter changed to complete UML2 editor
    • Fixed typos in User Guide

1.1.1508

  • Improvements
    • ReqIF-Compare shows images embedded in XHtml
    • ReqIF-Editor shows progress monitor when opening larger files
    • YT Editor: Fixed bug regarding button state
    • EA adapter: Configuration honors UML meta-types and stereotypes
    • Added Welcome Screen
    • Improved performance in the UI (faster issue decorator)
    • Suspicious Validation does no longer cover derived links
    • Artop adapter honors subset namespace
  • Bug fixes
    • YT Editor: Fixed bug regarding button state
    • Excel adapter
    • YT does no longer prevent Excel’s save
    • Adapter does no longer create processes on non-Windows-OSs

1.1.1506

  • New features
    • Suspicious Validation: Versioning of trace-links from and to ReqIF and Excel honors the mapped attributes of the trace type.
    • Excel adapter: Cells are referenced by value (i.e. a cell reference is still valid if for instance a prior row in Excel is deleted).
    • Jira adapter: Added more Jira-Attributes that one may address, esp. status
  • Improvements
    • ReqIF Editor
    • Editor can show deleted elements
    • Improved "Group by"
    • Improved Filtering
    • Improved XHTML display
    • Harmonized font types
    • YT Editor
    • Better user support in Link Edit mode
    • Buttons Search and Add won’t fade if editor’s display size shrinks
    • Suspicious Validation: Renamed menu item to Suspicious Links
    • Quick-Filter in YT Explorer shows used filter criteria
    • Improved synchronization of selection in YT Explorer and YT Overview
    • Improved usability of filter import
    • Improved performance of YT Explorer
    • A note within YT licenses is no longer mandatory
    • Licenses search covers union of licenses in user-home and/or installation directory
    • Splash Screen appears also on windows
    • Improved coupling with MS Word and Excel

1.1.1

  • Several improvements and bug fixes
  • Quick Search in Explorer
  • Search for Artifacts supports hierarchical presentation and artifact attributes
  • Integrity connection is more defensive to avoid wrong login attempts
  • Delete in context-menu
  • View contexts
  • Copy & Paste artifacts

1.1.0

  • Several improvements and bug fixes
  • Suspicious links
  • Trace data validations
  • New Tool adapter
    • Eclipse Browser
    • SQS Test
    • YAKINDU Simulink Viewer

1.0.2

  • Several improvements and bug fixes
  • Type filter for overview
  • Read only trace types
  • Tool adapter for MS Word
  • Tool adapter for MS Excel – Improvements
  • Tool adapter for AUTOSAR – Configuration
  • Tool adapter for IBM Rhapsody
  • Storage for PTC – PTC/MKS API installation support

1.0.1

  • Several improvements and bug fixes
  • Derived custom attributes that are only available for reporting
  • Quick fix to update invalid name and custom attributes of a trace point
  • Storage for PTC – Conditional mapping

1.0.0

  • Several improvements and bug fixes
  • License management
  • Improved filter options (contains, contains not and match by regular expression)
  • Tool adapter for Eclipse Explorer – Project Explorer, Package Explorer & Navigator can be used simultaneously
  • YT Explorer shows trace point type colors for trace points
  • Storage for Mylyn
  • ODA driver supports custom attributes fetching for trace point candidates
  • YT preferences can be imported/exported
  • File extension for trace configuration and trace data changed from „.xmi” to ".crema"
  • (Migration have to be done manually by renaming both files and replacing the textual occurrences in the <data>.xmi to <conf>.xmi by <conf>.crema)
  • Configurable coloring for trace point types which is visualized in the graphical overview view
  • Compare (diff/merge) support for trace data files
  • YT Editor can be synchronized with trace or trace point selection
  • YT Editor can edit trace points
  • YT Editor supports fast trace creation (automatic mode)
  • Custom attributes of traces and trace points can be edited in the Eclipse Properties view
  • ODA driver can fetch candidates
  • Storage for PTC – Initialization of PTC data runs asynchronous and provides better user feedback
  • Storage for PTC – Supports custom attributes mapping