How to set up a YAKINDU Traceability configuration from scratch

Information: YAKINDU Traceability Is Now itemis ANALYZE

Those of you who are following the blog posts on YAKINDU Traceability (YT) (now itemis ANALYZE) know or at least have an impression of how powerful this tool is to trace links between all kinds of different artifacts. Read further to explore what you need to do to get started and setup your YAKINDU Traceability (now itemis ANALYZE) configuration step by step.

In order to start tracing your links, you have to make a couple of preparations first. You have to:

• define the types of artifacts you are dealing with,
• specify which artifact type can link to which other artifact type and
• configure where the links you created will be stored.

All of this information goes into a so-called YAKINDU Traceability (now itemis ANALYZE) configuration.

Let’s assume you have downloaded and installed YT already, installed a YT license, and also created a new and empty workspace.

Running YT with an empty workspace means you don’t have a YT configuration yet. If you open any of the YAKINDU Traceability (now itemis ANALYZE) perspectives, for example, the YT Configuration perspective, YT will tell you about the missing configuration unmistakably by showing corresponding messages in each and every view.

 YAKINDU Traceability (now itemis ANALYZE) laments an empty configuration.

That message also recommends to use the guided wizard, which you can start via Traceability → Configuration → Start setup wizard. Or simply click on the “Start setup wizard” link in the error message, and off you go.

In the wizard, select “Create a new configuration” and click “Next”.

Using the setup wizard to create a new YT configuration

Creating a project with a YT configuration

YAKINDU Traceability (now itemis ANALYZE) is an Eclipse-based software, and in Eclipse everything is organized in so-called “projects”. An Eclipse project comprises artifacts that logically belong together in some way. In Eclipse, you can do (almost) nothing outside of a project.

Fortunately, the configuration wizard is not only able to create a new configuration, but it can establish a new project, too.

In the example below, I have entered conf.yt as the name of my configuration file and /myYTProject as the name of the project to be created. Please note the leading ‘/’ character in the project name, which is mandatory!

Entering configuration file name and project path

Clicking on Finish creates the project and the YT configuration. The latter is opened in the configuration editor, which is highlighted by a red rectangle in the screenshot below:

The YT configuration editor

The created project is visible in the Project Explorer view, which you can open by selecting the tab next to the YT Explorer view.

Please note that the configuration wizard will create a new project only within your workspace directory. If you want your project to reside somewhere else, you will have to create it in the desired location beforehand.

After that, run the configuration wizard (Traceability → Configuration → Start setup wizard) and browse for your project.

Please also note that besides using existing projects, the configuration wizard is also capable to import existing YT configurations and data, which is a common use case. However, that’s beyond the scope of this blog post.

In the configuration editor, click on the ”Set as current configuration” button:

Setting the edited configuration as the current one

This will engage the new configuration and cause the messages in the other views to disappear.

At this point, your firewall might ask whether you want to allow YT network communication.

YAKINDU Traceability (now itemis ANALYZE) includes a TCP server to interact with some external tools, like Microsoft Word. If you don’t need this, you can disable it in the preferences. (Select Window → Preferences → YAKINDU Traceability (now itemis ANALYZE), then uncheck “Enable TCP server”).

Having a look at the data

At this point we have a very basic (and very empty) YAKINDU Traceability (now itemis ANALYZE) configuration. But what about the data?

Let’s assume we want to create trace links between two types of artifacts:

• software requirements
• test specifications

A real-world traceability project would of course be much larger. It would involve many more different artifact types, like additional kinds of requirements, implementation artifacts in one or more programming languages, test cases, test results, and so on.

Artifacts could come from a wide variety of sources, be it simple Microsoft Word or Excel files or powerful and complex requirement management tools or application lifecycle tools, like IBM Rational DOORS, Atlassian Jira, Polarion ALM, etc.

The overview of YT adapters gives you an idea of what YAKINDU Traceability (now itemis ANALYZE) supports.

However, here we want to focus on how to set up the bare minimum. For this purpose, two artifact types are completely sufficient. And following the KISS principle (“Keep it simple stupid”), maintaining our requirements and specifications in simple and stupid Excel files is also acceptable.

Software requirements

Okay, so let’s have a look at the Excel file containing the software requirements:

Excel file with software requirements

Let’s assume this Excel file is stored in /myYTProject/data/software_requirements.xlsx. This is Eclipse-speak and represents the software_requirements.xlsx file, which is stored in the data folder, which resides in the myYTProject project.

On Windows, the file path would be, for example, D:\\yt\myYTProject\data\software_requirements.xlsx or wherever your workspace directory (here: D:\\yt) is located.

In the sample spreadsheet, each software requirement has been written down as a separate table row. Detailed information is available in separate columns, i.e., an ID, a name, some author information, and a description.

Test specifications

Here’s the /myYTProject/data/test_specifications.xlsx Excel file containing the test specifications:

Excel file with test specifications

Nothing spectacular here, too: Each test specification is identified by an ID in column A and a description in column B. In our example, the description is again some dummy text.

Finding the information we need

Now let’s see how we can instruct YAKINDU Traceability (now itemis ANALYZE) to access the Excel files and extract the information we are interested in. As the preceding sentence suggests, this is a two-step process:

• Accessing Excel files and other kinds of data sources is possible through so-called data accesses.
  YT provides a variety of adapters to make different data formats and tools available for traceability. In this case, we have to use the Microsoft Excel adapter and configure a data access for each of our Excel files.
• In order to extract the information we need, we have to define an artifact type for both software requirements and test specifications.
  An artifact type is based on a data access and “knows” where in the underlying data source it can find the desired data. This of course does not happen by magic, but instead requires some configuration.

So let’s see how to configure the data accesses and the artifact types.

Creating data accesses

The first data access we create is for the software requirements:

• In the configuration editor, select the Data access tab.
• Click on the  button to add a first data access. The “Add new data access” dialog appears.
  
  Type “Software requirements” into the Name field, and select “Microsoft Excel” from the Type drop-down menu.
  
  Optionally, you can select “Access specific Excel document (template)” from the other drop-down.
  
  

  Adding a data access for the software requirements

• Click on the Create button. The new data access is created.
  
  Please note that the “Data access configuration” text field contains the selected template as an example. It helps understand how to connect the data access to one or more underlying Excel files.
  
  The resource definitions have warning markers, because the specified files don’t exist.
  

  The configuration editor showing the created data access

• Okay, so let’s edit the configuration and enter our software requirements file. This is particularly easy, because we don’t have to type the complete pathname string. Just press [Ctrl+Space] after the leading quote, and select the appropriate file from the menu, as shown in this screenshot:
  

  Using content assist to easily specify a file resource

• The orange bar in the configuration editor informs us that our YT configuration is not active and contains unsaved changes (so the configuration as seen by YT is still empty).
  
  Click on the Save button in the orange bar, and the configuration will be saved and become active:
  

  The configuration editor showing the saved and active configuration

And that’s it.

We are done with creating the Software requirements data access. It expects an Excel file software_requirements.xlsx within the data folder in the myYTProject project.

Now let’s do the same for the other Excel file and create a second data access. It’s name is – surprise, surprise – Test specifications.

The YAKINDU Traceability (now itemis ANALYZE) configuration editor showing the newly-created data accesses.

By the way, instead of the  button, you can alternatively use the  and  buttons to copy and paste the Software requirements data access and then modify the copy accordingly.

Creating artifact types

Until now, we have just the data accesses. At this point, YT does not know much about them, except that they are Excel files. For example, the Software requirements data access corresponds to the file /myYTProject/data/software_requirements.xlsx, and the naming implies that it contains software requirements.

However, YT has no idea (yet!) how these software requirements look like, how they are distinguished from each other and from other contents in the Excel file, and which attributes these requirements might have.

In the next step, we will create a Software requirement artifact type. The artifact type definition clarifies the open questions just mentioned.

• In the configuration editor, select the Artifact types tab.
• Click on the  button. The “Add new artifact type” dialog appears.
• Enter the artifact type’s name into the Name field, here “Software requirement”.
• Select “Software requirements” from the Data access drop-down menu.
• Optionally, select “Recognize cells based on column header (template)” as the template to use.
  

  Entering some basic information to create an artifact type

• Click on the Create button to create the new artifact type. The result looks like this:
  

  The configuration editor showing the newly-created artifact type

This does not yet work, because we still have to adjust the template configuration, so that it suits our needs.

So, what are our needs?

In a first step, we want to set up traceable software requirement artifacts that consist of just their names as given in the Name column. We will refine and extend that definition later, but using just the name should suffice as a first approach.

The following artifact type configuration does just that. It has to go into the Mapping text field:

// Process "Sheet1" only and ignore any other sheets.
sheet "Sheet1" {
    // Select all cells in the column(s) that has a header
    // in row 1 with the text "Name". However, exclude row 1:
    locate cell where {
        // The columns header must be "Name" in row 1:
        column with header "Name" in row 1
        // Exclude row 1 (by using an ugly regular expression):
        address matches "\\$.*\\$([2-9]|..+)"
    }
    // The value of the cell becomes the artifact's name:
    name valueOf {0;0}
}

This configuration instructs YT to go to the Sheet1 worksheet in the Excel file, select certain cells, and create a software requirement artifact from each of them.

The “locate cell where” statement specifies which cells we are interested in: It’s the cells that have a header cell with the text “Name” in row 1. The “column with header” condition specifies that.

In our example, all cells in column B are matching this condition. However, the header cell in row 1 is also a match, which is not desired. To mask it out, we add an “address matches” condition. It specifies the addresses of the cells we are interested in by a regular expression.

An address specifies a cell in the well-known Excel way. For example, $U$238 specifies the cell at the intersection of column U and row 238.

Unfortunately, we cannot say something like “any cells except those in row 1”, but instead we have to express it positively, i.e., “all cells in row 2 and higher”. And unfortunately we cannot use an arithmetic expression like “row number >= 2”, but instead we have to use a regular expression.

Well, “\\$.*\\$([2-9]|..+)” is admittedly ugly, but it does what is needed. It matches all cells that are in any column (the “.*” right from the first $ character) and in any row with a row number that is either in the range 2…9 (the “[2-9]” character class) or has at least two digits (specified by “..+”).

In other words: That’s all cells in the worksheet except for those in row 1.

YAKINDU Traceability (now itemis ANALYZE) constructs the intersection of the cells that the “column with header condition” returns and the cells the “address matches” condition returns. And as needed, this is all (populated) cells in column B, except for the cell in row 1, i.e., $B$1.

Okay, now we have the cells, how can we turn them into software requirement artifacts?

In YT, name is a mandatory artifact attribute, so we will have to configure how to set up this attribute. We can do this by mapping the textual value of the selected cells to the respective artifact’s name.

That’s what the “name valueOf {0;0}” statement does: It assigns the value of “our” cell to the name attribute. The notation {0;0} stands for the current cell. The numbers actually specify a relative offset to the current cell.

For example, {2;5} specifies the cell that is two columns right and 5 rows below the current cell. Negative values are also allowed. We will use relative cell addressing below.

With the changes above, click on Save. After having defined and saved the Software requirement artifact type, the configuration editor looks like this:

The Software requirement artifact type has been defined.

Displaying artifacts

Now let’s see whether YT can extract and display the artifacts. That’s what the YT Explorer view is good for.

However, even after defining our first artifact type that view is empty. It doesn’t show anything at all. The reason is simple: By default, the YAKINDU Traceability (now itemis ANALYZE) explorer only displays artifacts that are linked to other artifacts, and we have neither links nor link type definitions yet, so nothing is shown.

Clicking on the  button instructs YT to also display artifacts that are not linked.

Et voilà: Now the software requirements appear.

YT Explorer showing artifacts

Hovering the mouse over an entry shows the latter's attributes in a pop-up window, i.e., the entry’s name, its resource (the file the entry is coming from), and its type.

Defining a custom attribute

Let’s go a step further and add the software requirement’s description from the Excel file as a custom attribute to the artifact.

First, we have to define the custom attribute:

• In the Custom attributes section of the Artifact type configuration, click on the  button.
• In the Attribute name list, replace the name of the new entry, “NEW”, by the name of your custom attribute, “reqDescription” in our case.

The second step is to configure where to find the requirement description or, in YT lingo, to add a mapping from the artifact’s reqDescription custom attribute to the spreadsheet data.

The following change adds a map block that does exactly that (highlighted in bold):

// Process "Sheet1" only and ignore any other sheets.
sheet "Sheet1" {
  // Select all cells in the column(s) that has a header
  // in row 1 with the text "Name". However, exclude row 1:
  locate cell where {
    // The columns header must be "Name" in row 1:
    column with header "Name" in row 1
    // Exclude row 1 (by using an ugly regular expression):
    address matches "\\$.*\\$([2-9]|..+)"
  }
  // The cell's value becomes the artifact's name:
  name valueOf {0;0}
  map {
    // Get the requirement’s description from the cell that is
    // in the current row and has a “Description” header:
    reqDescription to
      valueOf {column with header("Description");0}
  }
}

Hovering the mouse over the entries in the YT explorer again – after having clicked on the Save button – now also shows the reqDescription custom attribute and its value.

Creating an artifact type for test specifications

We also need the Test specification artifact type. Its configuration is similar to that of the Software requirement artifact, so it’s sufficient to just have a look at the result:

The Test specification artifact type has been defined.

Creating a link type

Okay, so we have defined our two artifact types, and we even have YT populated with some concrete artifacts. Now let’s create trace links from software requirements to their corresponding test specifications.

Setting up a link storage

Links have to be stored somewhere, and before we can create any links, we will have to set up some storage for them. Data accesses of certain types can be used as link storages. One of these types is the native file data access, which stores links in a proprietary format.

In our example, it would be particularly appealing to store the links directly in another column of the software_requirements.xlsx Excel file. YAKINDU Traceability (now itemis ANALYZE) supports this kind of invasive link storage.

However, in this article simplicity is the prime directive, thus we will use the native file data access. You might even consider it an advantage that the Excel files are left as they are and the links are stored non-invasively.

• In the configuration editor, go to the Data access tab.
• Create a new data access, call it “Link storage”, select the Native file type, and click on the Create button.
  
  

  Creating a link storage

• The data access configuration should contain the following line, specifying where to store the links: file "/myYTProject/data/link_storage.yt"
• Warning markers appears, because the file does not yet exist. Don’t worry, that’s okay. YT will create the file when the first link is to be stored.
  
  

  The configuration now comprises a link storage data access.

Establishing the link type

Now we are ready to create the link type.

A link is always of a certain type, which is characterized by its A and B artifact types. In our case, the link type will be Software requirement → Test specification.

To create that link type, proceed as follows:

• In the configuration editor, select the Link types tab.
• Click on the  button. The “Add new link type” dialog will appear.
• From the drop-down menus, select Link storage as the data access, Software requirements as artifact type A, and Test specification as artifact type B.
  
  

  Creating a link type

• Click on the Create button. Now YAKINDU Traceability (now itemis ANALYZE) establishes that link type. Click on Save to save the configuration.
  
  

  The new link type is shown in the configuration editor.

Creating a link

After all these preparations, we can finally create our first links.

For example, to express that test specifications 4711 and 4712 pertain to software requirement IN-NE, we have to create a link from IN-NE to 4711 and another one from IN-NE to 4712.

We can create both links in a single step; and the tool we need is the YT Editor view in the lower-left corner of the YT main window.

• Drag software requirement IN-NE from the YT explorer to the “Link end A” field of the YT editor.
• Drag test specifications 4711 and 4712 from the YT explorer to the “Link end B” field of the YT editor. The YT editor now looks like this:
  
  

  Creating a link in the YAKINDU Traceability (now itemis ANALYZE) editor

• Click on the Create button. YT creates the links, stores them in the link storage file, and let’s you know that it has created that file.
  
  

  Upon first use, the link storage file has been created.

  
  
  

Displaying links

To display links, change to the YT Tracing perspective (Windows → Perspective → Open Perspective → YT Tracing).

In the YT Explorer view, you can now “open” artifacts that are constituents of a link. Artifacts that can be reached via direct links are shown as child nodes.

A graphical representation can be seen in the YT Overview: It highlights the currently selected artifact and displays how it is connected to other artifacts.

YT Overview showing a graph of related artifacts

Conclusion

In this article, we have laid the foundations for starting the implementation of traceability projects. We have seen how to create a YAKINDU Traceability (now itemis ANALYZE) configuration and how to specify, in the form of data accesses, where the traceability data come from.

The definition of artifact types describes how to create traceability artifacts from data (here: from Excel tables). Finally, we have linked certain artifacts. For that purpose, we have created a link type and a link storage.

Now you can start your own traceability project.

Analyze what your artifact types are, in which tools or formats they are available, then create a suitable YT configuration.

YT supports a wide range of different data accesses and storage options, so the multitude of available configuration options and making the most of them can be challenging.

Don't hesitate to call us for professional support, if you need help.