To install YAKINDU Traceability (YT) as a stand-alone tool, unzip the distro file. A folder named YT is created on your disk. The YAKINDU Tranceability executable is residing in that directory. It is called YT.exe on Windows and YT on Linux or macOS. Execute it to start YAKINDU Tranceability.
YAKINDU Traceability is shipped as one archive, where the YT application can be extracte manually. If the Download is extracted in the same folder as it was downloaded, Mac OS X puts it into a sandbox mode until you move the folder somewhere else or rename it. In the sandbox mode the default workspace path and other settings are stored in a temporary location which is removed on exit, and some required extractions can not be done, which leads to a strange behavior.
After moving the YT.app to another folder, YT can be started like other applications and asks for the workspace.
For Linux some additional requirements needs to be installed for YT to run.
Depending on your Linux distribution and version, you might need to install additional packages for Webkit GTK and Java from your distribution’s repository (or elsewhere).
If the welcome page looks broken and asks you to configure webkitgtk, refer to Webkit GTK.
The easiest way to get a suitable installation and all dependencies installed, is by installing an eclipse by your distributions package manager. This will in general install Webkit, Java and other requirements.
On Linux, you might encounter certain user interface problems or display irregularities when working with Eclipse-based software, e.g., when viewing the welcome page. This is a general problem that can also affect YAKINDU Traceability. It is due to Eclipse on Linux needing specific versions of the libwebkitgtk library to function properly. Depending on your Linux distribution and version, you already have a suitable libwebkitgtk library installed or not.
For a better understanding of these steps we will give you some general setup instructions in the following, including:
YT is based on the Eclipse platform and inherits its concepts. The most important of them are briefly explained below.
The Eclipse workbench is your desktop working environment, i.e., YAKINDU Traceability’s main window and its contents. The workbench typically consists of one editor and a number of views and editors. Take, for example, figure "The YT workbench": This workbench is divided into four different parts. Starting at the top left, there is the YT Explorer view, together with the YT Selection History on another tab. At the top right, there is the YT Overview. Below it, there is the YT Bulk link creation editor, together with the YT Issues. Last not least, you will see the YT Editor at the bottom left.
You can rearrange and resize editors and views as you like, and you can also open further views and close those you don’t need. A certain arrangement of views and editors is called a perspective. YT comes with a few pre-defined perspectives. However, you can create and save your own perspectives or even overwrite the pre-defined ones. To save a perspective, select Window → Save Perspective As.
Detailed information on the Eclipse workbench, targeted especially to software developers, is available in the Eclipse "Workbench User Guide". Alternatively, select Help → Open Help in the main menu to open the Eclipse Help window. 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. Figure "The project explorer" shows a sample project structure in the project explorer view.
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 (see below) as your real-world traceability project definition and of each Eclipse project as a single module or resource.
The project explorer
The Eclipse workspace aims to manage all the files relevant to your work, e.g., files that contain development artifacts like requirements, source code, and test cases. Physically, these files may be located anywhere, say, in various locations on your hard disk or on several shared drives. Artifacts like requirements that are managed by Subversion and source code maintained in a Git repository may be checked out into several folders on your hard disk. Files are organized virtually in projects (see above) , and the workspace bundles all your projects under one hood. That is, you can browse and navigate between projects and the files contained therein as if they would reside next to each other.
Technically, the workspace is a directory on your disk. It contains project subfolders and the .metadata directory. The latter contains everything needed to describe your workbench setup, e.g., the projects that you are working with, preference settings, and the layout of views and editors. Projects do not necessarily reside in the workspace folder; they can be located anywhere on your disk.
You can have multiple workspaces, but only one workspace can be opened at a time.
Within the file system, 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.
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 much more.
In the preferences you can do some basic configurations necessary to work with YT. The preferences can be opened by navigating to
The YAKINDU Traceability trial version comes with an evaluation license that is valid for 30 days. If you want to continue working with YAKINDU Traceability beyond that period of time, you have to acquire a license.
The license manager documentation describes how you can install a license file or configure a license server for floating licenses. To access that documentation, select Help → Help Contents from YAKINDU Traceability’s main menu, then open the YAKINDU License Management documentation.
The configuration storage preferences allow you to select a configuration file in your workspace. If you do not yet have a configuration file, you can create one in the Add new configuration wizard that you can open by clicking on the link below the selection list.
The configuration itself is described in the Configuration section.
You can start or disable YAKINDU Traceability by selecting or unselecting the checkbox and then press the button for applying the preferences. You need to select a configuration file to be able to start YT.
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.
The location where report templates can be found is configured here.
This preference setting allows you to select the folder in which YT should store model snapshots.
The preferences set on this YAKINDU Traceability page can be imported and exported here.
YT offers additional configuration options for specific views and also some global settings. To inspect and possibly change these preferences, select Window → Preferences → YAKINDU Traceability → Layout & Views in the main menu.
Several YT dialogs offer a „Don't show again” checkbox which prevents them from reappearing when they usually would. The button in the „Dialogs” group resets this setting for all dialogs at once, i.e., all dialogs will show up again. You can then selectively hide them again as before.
The remaining options are described by their label or by a short text below the setting.
Some adapters support their own specific preferences settings. You can see and edit these preferences by selecting Window → Preferences → YAKINDU Traceability → Adapters in the main menu. These preferences will be explained in the adapter-specific subsections in the section Connecting YAKINDU Traceability to various tools. The page will show preferences only of those adapters that are installed in your YT.
In order to start using YAKINDU Traceability, you have to configure your project-specific traceability process and environment. For example, you can configure which tool adapters YAKINDU Traceability should use to access data, how artifacts are recognized and how links between them can be created.
This information resides in a configuration file, typically, but not necessarily, named conf.yt. The following sections explain how to use the configuration editor to create or modify a configuration and how to toggle between different configurations.
If you are starting up YAKINDU Traceability for the first time or on a new project, you won’t have a configuration yet. You might not even have any Eclipse projects at all yet, let alone the data for your traceability project available in Eclipse projects.
The setup wizard is here to help you get up to speed quickly. It offers three major ways to go in order to get a YT configuration:
We will explore all of these options one by one subsequently. However, let’s first have a look at how to start the setup wizard.
To start the setup wizard, carry out one of these two options:
The setup wizard looks like this:
The setup wizard
The typical use case for this option is that you already have an existing YT configuration. However, it is not in your workspace, but in a project somewhere else. To import such a project, including its configuration, perform the following steps:
This will bring up the Eclipse import wizard, which generally allows you to import various kinds of resources into your workspace. In this case, however, only three or four of them deserve our attention. Figure “Importing an existing configuration” shows these options being unfolded, i.e., their respective parent „folders” being opened.
Importing an existing configuration
Please choose the variant that suits your needs, then click on the Next button. Depending on your choice, further dialogs will open and guide you through the import process.
Please note: When importing a project from a local directory, you can choose whether you want to copy the existing project into your workspace or to directly work with the existing project. In the latter case, any changes will be made to the already existing project. In the former case, you have to check the "Copy projects into workspace" option in the Import projects wizard. Any changes you will make later will be done to the copy and will leave the already existing project untouched.
After importing a project, a YT configuration contained therein will not automatically be activated. Thus the setup wizard proceeds to activating an existing configuration, please see below for details.
The setup wizard’s "Create a new configuration" option is especially useful if you don’t have an existing YT configuration anywhere and possibly don’t even have an Eclipse project yet. So this is the „real” starting-from-scratch scenario.
/project/folder_1/folder_2, i.e., it starts with a slash (/) and the project’s name and is optionally followed by a slash and an arbitrary number of folder names separated by slashes.
The example shown in figure "Creating a new configuration" will create the configuration file config_1.yt (the .yt will be added automatically). The file will be created in a project named my_project. If that project does not yet exist, YT will create it, after asking the user for confirmation. The configuration file will be placed into the a/configurations folder, which is located in the project my_project. If any of these folders do not yet exist, YT will create them.
Creating a new configuration
If you want to import any data into your workspace in the same step – typically data you want to extract traceable artifacts from –, check the "I also want to import existing data into my workspace" checkbox and click on the Next button. The Eclipse import wizard will open and let you import whatever you want to import.
Clicking Finish in the import wizard will start the actual import. After that, the wizard will close and leave you with the newly-created configuration file in the configuration editor.
YAKINDU Traceability will not automatically activate any imported configuration. This is a step you will have to make explicitly.
While the configuration editor allows you to activate the configuration you are currently editing by clicking on the "Set as current configuration" button, the setup wizard searches your whole workspace for YT configuration files and lets you choose one for being activated.
Activating an existing configuration
If you want to import any data into your workspace in the same step – typically data you want to extract traceable artifacts from –, check the "I also want to import existing data into my workspace" checkbox and click on the Next button. The Eclipse import wizard will open and let you import whatever you want to import.
Clicking Finish in the import wizard will start the actual import. After that, the wizard will close and leave you with the activated configuration file in the configuration editor.
If you have not yet set up or created a current configuration, you should consider starting from scratch using the setup wizard.
In order to edit your traceability configuration, open the YT Configuration Editor by selecting
Traceability → Configuration → Open current configuration
from the main menu.
To add a new configuration, select
Traceability → Configuration → Add new configuration
instead. The latter is the only operation you can perform if you don’t have a configuration yet. It will open the dialog for creating a new configuration.
The YT configuration editor is structured into 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 or 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.
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 → Open current configuration from the main menu will always open the current configuration.
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 icon in the Data access tab. This will open the Add new data access dialog. Enter a name into the Name field. Assign a type for the data access by selecting it from the Type drop-down menu. You can (optionally) indicate a template to be used for the data access configuration by selecting it from the other drop-down menu. When you click on the Create button the new data access will be added to the list of data accesses. Using the Active checkbox in that list, you choose whether the links belonging to the respective data access will be visible in YT or not.
After 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 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.
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.
Each artifact has four standard attributes.
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.
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.
You can add a new artifact type using the icon in the Artifact type tab. This will open the Add new artifact type dialog. Enter a name into the Name field. Assign the corresponding data access by selecting it from the Data access drop-down menu. You can (optionally) indicate a template to be used for the artifact type configuration by selecting it from the other drop-down menu. When you click on the Create button the new artifact type will be added to the list of artifact types.
In the Artifact Type Configuration area at the bottom of the tab, you can create so-called 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:
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:
All functions can be called multiple times on one ArtifactName, e.g., ArtifactName.replace("search","find").trim(15,KEEP_PREFIX)
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.
Artifact Type: "Type X" Adapter: "Tool A" Adapter Configuration: "resource <pattern 1>" Artifact Type "Type Y" Adapter: "Tool A" Adapter Configuration: "resource <pattern 1>"
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.
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:
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:
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 edited. The values are then persisted within the link. This makes it possible to detect certain changes to the underlying artifacts. 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, you can configure which artifact types can be linked to each other in YT. To do so, please click on the icon. The Add new link type dialog will appear where you have to select the following items:
Click on the Create button to add the new link type to the list of link types.
In the list of link types, you can optionally define per link type:
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:
Sometimes it is necessary to maintain traceability for different variants or versions of the same project. To support this use case, YAKINDU Traceability allows users to define parameters that can be referenced in the configuration language of most adapters. Instead of maintaining different versions of an otherwise identical configuration, you can create one parameterized configuration and then switch between different parameter values.
Imagine you want to re-use the same configuration with only slight adjustments, e.g., analyze the traceability of your project for different releases with associated release numbers.
In such cases, the release number has to be configured for several data accesses, artifact types or link types. Now you don’t want to adjust the release number in all these definitions individually, which would be ather tedious and error-prone. Instead, you can introduce the release number as a parameter. It will have to be adjusted only once, and then its new value will be applied everywhere the parameter is used.
Each occurrence of the parameter reference $important_type is replaced by the actual value of the important_type parameter, here „LK_ContentType”.
The Parameters tab in the YT Configuration editor
The parameter configuration is considered an advanced feature that might not be relevant for every user. Therefore, by default, the Parameters tab is hidden. However, it can be activated easily by a click on the icon in the status bar of the configuration editor.
In order to create a new parameter, open the parameters tab, click on the icon in the upper left corner, and enter the name of the parameter. To add new parameter values, click on the icon in the lower half of the tab. Deletion of parameters and their values works in the same way as for configuration elements in the other tabs. Parameters can be copied and pasted within and across YT configurations.
You can select the active value of a parameter from the drop-down list in its Active value column. You may only select values that you defined previously. This is to prevent typos when switching back-and-forth between parameter values. When you add the first value for a parameter, it will automatically be selected as the active value.
A parameter’s cell in the Referenced column contains a green checkmark if that parameter is referenced in any configuration text for a data access, a link type mapping, or an artifact type mapping. If you place the mouse cursor over this checkmark, a message box appears that lists the data accesses, artifact types, or link types which reference the parameter.
Referencing parameters in YT Configuration
You can reference a parameter in a configuration by prepending a
$ (dollar sign) left from its name. For instance, you can reference a parameter with the name
parametername by writing
Parameters are supported in all cases where you can create complex strings by concatenating substrings using the
+ operator. Most YT configuration languages are also supporting parameters in other cases. You can use them as replacements for concrete strings, e.g., in comparisons. Wherever parameters are supported, YT will offer them to you, if you trigger content assist by pressing
[Ctrl] + [Space].
Parameter references in a configuration are highlighted in a different font style and color to distinguish them from the rest of the configuration text. If you place the mouse cursor over them, you can see their currently selected value. You can also see a parameter’s current value if you select it in the list of suggestions, which you get by triggering content assist.
After you have set up your project and your environment, various views help you to perform different tasks. Depending on the task at hand, you need a suitable set of views. To support the most common use cases, YT provides a couple of default views in different perspectives:
These perspectives can be opened in any of three ways:
Within YT perspectives, the third option will show a list of all YT perspectives. Otherwise you can select the perspectives in a dialog opened with Window → Open Perspective → Other.
Depending on the selected perspective, some views will be opened by default. You can open other views by selecting
in the main menu, where YT … represents the name of the particular view.YT provides the following views:
The individual views will be explained in the subsequent sections in the context of the functionalities they are supporting.
The YT Configuration perspective and most other Eclipse perspectives will open editors in the center area of the Eclipse workbench window. In the YT Tracing and YT Analysis perspectives, the editor area is minimized by default. It will be restored automatically if you open an editor in Eclipse, e.g., by double-clicking on an artifact in the YT Explorer that has an Eclipse editor associated with it. The editor area usually remains visible even if no editor is currently open. However, the YT Tracing and YT Analysis perspectives will automatically minimize the editor area whenever there is no open editor.
It is possible to execute YT without requiring any user interactions as a so-called batch command. This allows YT to run automatically, e.g., on a continuous integration (CI) server, like Jenkins. This way you can automatically perform certain tasks on a regular basis, e.g., creating reports, documenting the current project state, or archiving it.
When starting YT in batch mode, it is necessary to provide the appropriate configuration and the workspace as command-line parameters. While running, YT will load artifacts and links according to the configuration, and it will export its entire knowledge into a generic CSV schema. When that export is finished, the application terminates successfully.
There is a multitude of command-line options available, which you can use to change YT’s behavior in batch-mode execution. The batch mode should always be called with the parameters
-application com.yakindu.traceability.batch.application -nosplash --launcher.suppressErrors. Additional command-line options are optional, unless mentioned otherwise below. The following options are supported:
||Tells YT to run in batch mode and terminate after finished. This option is mandatory.|
||Sets the workspace for YT execution to the given absolute file system path. This option is mandatory.|
||Workspace-relative path to the YT configuration file. If the containing project is in the workspace folder, it will be imported. This option is mandatory. Can be abbreviated as
||Absolute file system path to a properties file with parameter values for the configuration. All parameters and values have to be defined in the configuration.|
||Explicitly sets the active value of a parameter in the configuration to a specific value. The value has to be one of the possible parameter values that have been defined for the given parameter.|
||How long to wait for the YT core to initialize and adapters to become ready (seconds). If the timeout expires and YT has not yet finished loading all data, no data will be extracted, except if the
||This option forces YT to export its data, even if a timeout occurred, see the
||Imports additional projects into the workspace. If this option is set, all projects in the workspace directory will be imported. If a folder is given, all projects in this folder and direct children are imported. Multiple folders can be provided by separating them using the system’s filepath separator, which is
||Keeps the application open after the export has been finished. The user needs to close the application explicitly. This option is useful for debugging. After exporting, the user can browse workspace and traceability data to verify whether the correct data is included in the export or not.|
||Name of the output file relative to the workspace root that was provided by the
||Shows dialogs in the UI thread instead of printing console messages.|
||Executes all queries in the query file that is referenced by the path queryFile. It writes the result for each query into a separate CSV file. The CSV file has the same name as the corresponding query, followed by the .csv filename extension. You can use --queries repeatedly to execute queries in more than one file.|
||Creates a snapshot in the given folder.|
||Path to a properties file containing Java system properties.|
||Lists all available options and their description. Can be abbreviated as
Based on the adapters in use, additional parameters may be required, e.g., to provide credentials to server-based data sources etc.
Please note: It is possible to set Java system properties from a file in order to simplify the usage of the command line. To do so, please use the
--propertiesoption to provide the path to the file.
The batch application terminates with exit code 0 when no error was detected. In case of errors, we return other codes depending on the error type, as summarized in the following table:
|1||Incomplete or invalid parameters from command line|
|2||An exception occurred, but YT was shut down|
|3||An error occurred that avoids clean shutdown (like VirtualMachineError or OutOfMemoryError)|
In case of severe errors reported by the virtual machine which would avoid any handling by YT, we directly return the corresponding error codes.
Batch export CSV schema