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:
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
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”).
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:
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.
Aside:
In a first version of this post, I even maintained the artifacts in XML files, which would have been a platform-independent approach that won’t require any additional tools. However, my team colleagues considered that to be too basic – and thus too complicated. They recommended I should rather use Excel files, so I did.
Dear reader, if you are working on Linux or Mac, please note that while third-party tools, like Excel, might be platform-specific, YT is platform-independent. It is available for Windows, Linux, and Mac.
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.
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.
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:
So let’s see how to configure the data accesses and the artifact types.
The first data access we create is for the software requirements:
Adding a data access for the software requirements
The configuration editor showing the created data access
Using content assist to easily specify a file resource
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
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.
Entering some basic information to create an artifact type
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.
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
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.
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:
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.
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.
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.
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.
Creating a link storage
file "/myYTProject/data/link_storage.yt"The configuration now comprises a link storage data access.
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:
Creating a link type
The new link type is shown in the configuration editor.
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.
Creating a link in the YAKINDU Traceability (now itemis ANALYZE) editor
Upon first use, the link storage file has been created.
Tip:
Use the YAKINDU Traceability (now itemis ANALYZE) Bulk link creation editor to create many links of the same type!
Selecting Window → Show view → YT Bulk link creation editor opens it.
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
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.