Capra is a dedicated traceability management tool that allows the creation, management, visualization, and analysis of trace links within Eclipse. Trace links can be created between arbitrary artifacts, including all EMF model elements, all types of source code files supported by the Eclipse Platform through specialized development tools, tickets and bugs managed by Eclipse Mylyn, and all other artifacts for which an appropriate wrapper is provided. Capra is highly configurable and allows users to create their own traceability meta-model.
Compared to other similar projects which may have similar features, Capra is not a modeling tool or a tool for requirements management. All functionality is focused on providing traceability capabilities, i.e., the ability to create and visualize links between artifacts modeled in different domain-specific languages. This allows the architecture to be highly modular and the tool to be extremely customizable.
This section describes the prerequisites to run Capra and how to install the tool.
Before downloading and using Capra, first download a distribution of the Eclipse Modeling Environment (Eclipse V 4.5 (Mars)) and make sure you have the following installed:
Capra can be installed either through an update site or manually .
Capra_v.0.1.zip
(Note the location of your download)![alt text](updatesite.png =700x)
In this section, important concepts for traceability are described.
Traceability can be defined as the ability to relate different artifacts created during the development of a software system. Traceability allows creating and using links between system and software development artifacts. For instance, this allows connecting the origin of a requirement with its specification, the design elements that address its specification, the code that implements these design elements, and the acceptance tests that check if the requirement has been achieved.
The connections between different artifacts in a software development environment are called traceability links. A traceability link can connect two or more elements to imply that there is a relationship between these elements.
Depending on the requirements of a domain, traceability links can have different types. There are three different categories that can lead to different types of traceability links: the shape of a link, the semantics of a link, and the direction of a link.
Artifacts, and in particular software development artifacts refer to the resources that are either created or used as an input by a software development activity. For instance, the requirements elicitation activity produces artifacts known as requirements. Artifacts can be of different types, such as a requirement, a model element, a line of code, or a test case.
As previously mentioned, there are different types of artifacts that can exist in a software development environment. However, Capra stores the traceability links in form of an EMF model. This means that, basically only EMF artifact types can be supported. To support other artifact types, there is a need to create EMF representations of the artifacts. This is what an artifact handler does. It creates an EMF representation of non-EMF artifacts. The representations are known as “artifact wrappers”. For example to be able to link to Java Code, an artifact handler for Java needs to created. For details on how to add new artifact handlers to the tool, refer to section Adding a new artifact handler.
To demonstrate features of Capra, we take an example of the development of a Heating, Ventilation and Air Conditioning (HVAC) System. The project contains the following artifacts:
These artifacts are shown in the figure below in the context of the development environment of the HVAC system.
![alt text](hvacProjects.png =800x)
Can we provide a link to where the project can be downloaded?
Capra provides the functionality to create traceability links between different artifacts as long as artifact handlers for those artifact types are available. The current version supports tracing to EMF models, Java code (up to method level), C/C++ code (up to function level), Task tickets from ticketing systems supported by Mylyn, arbitrary files (such as PDF or word), Test executions (Hudson and Jenkins), Papyrus models, and Capella models.
To show how traceability links can be created, we continue with the HVAC example and its artifacts as described above. Our aim is to establish the following links.
The procedure to create the above links is described below.
HVAC_Requirements.reqif
file), with the “Sample Reflective Ecore Editor” view.HVAC_Variants.pld
), drag and drop the feature named “Blower” into the selection view as well as shown in the figure below.__WorkspaceTraceModels
. This folder contains your trace model which contains the trace link we just created and an artifact wrapper model which contains EMF representations of artifacts that are not in EMF format. In our case the artifact model should be empty since the artifacts we used to create the trace link are all EMF elements. The trace model (traceModel.xmi
) should contain only one trace link.BlowerCtlr
state machine and drag and drop the parent element to the selection view.__WorkspaceTraceModels
project and open the trace model (traceModel.xmi
). You will notice that a second trace link has been created.BlowerCtlr
state machine and drag and drop the parent element to the selection view.BlowerTest.java
file to reveal the BlowerTest class. Drag and drop this class to the selection view.HVAC_Requirements.reqif
file), with the “Sample Reflective Ecore Editor” view.ISO26262 Requirements.pdf
file from the Project Explorer and drag and drop it to the selection viewTask List
view, where the tasks from the Trac server are listed, select one task and drag and drop it to the selection viewCapra offers two ways in which you can visualize the traceability links that you have created. These are the Graphical view where the artifacts are shown as nodes and the links as edges in a graph and the Matrix view where artifacts are arranged in rows and column with an “x” mark in the cells to indicate a trace link between the artifact in the column and that in the specific row.
To view the traceability links related to an artifact and the connected artifacts, simply select the artifact while in the “Sample Reflective Editor” View. The “Plant UML View” needs to be open as well.
The graphical view allows you to explore directly connected elements or transitively connected elements. To use the latter functionality, click on the downward arrow on right hand corner of the Plant UML View and click on “Toggle Transitivity”. This enables you to move from viewing only directly connected elements to the selected element, to viewing all the transitively connected elements. Use the same button to return to the previously active view.
![alt text](toggleTransitivity.pdf =700x)
The traceability matrix can be created by selecting at least two model elements when the “Plant UML View” is open. This will list all the model elements as rows and columns and an “x” mark will appear show that there is a trace link between two elements. For instance, the picture below shows the resulting matrix when selecting Req3 and the artifact wrapper representing the PDF document.
Selecting more than two model elements expands the matrix into a square matrix with same elements listed in vertically and horizontally.
![alt text](matrixViewMany.png =600x)
Trace links need to be updated as the artifacts they connect evolve. Capra provides a feature to notify users when these artifacts evolve and give suggestions on how the trace links can be evolved. The suggestions are offered as quick fixes to the user and if the user wishes to make the changes suggested by the quick fix, the fix can be applied automatically by clicking on it.
The problems detected by Capra are shown in the “Problems” view with a type “Capra problem”. We demonstrate the use of the Problems view and quick fixes using our practical example of the HVAC project.
BlowerTest.java
.BlowerTest.java
, but that file has been deleted.BlowerTest.java
file.In this section, we describe scenarios in which Capra can be used to facilitate change impact analysis. Change impact analysis means being able to evaluate the effect a change to an artifact will have to other artifacts. Using the HVAC example, assume that the customer requests a change on the requirements REQ-3
. Before such a change is made, it is important for the company to know which other artefacts will be affected. With Capra, this can be done by selecting REQ-3
and then using the visualization, one can see all other artefacts that are related to REQ-3
.too.
![alt text](toggleTransitivity.pdf =700x)
For further analysis, clicking on Toggle transitivity as shown in th figure below will show all artifacts connected to REQ-3
and their connnections to other artifacts
![alt text](graphical-view-transitive.pdf =500x)
The following subsection describes the technical architecture of the tool. This information is also available in more detail in a tool demonstration paper[^fn1]. Our motivation for choosing this architecture design is based on a study on factors and guidelines that affect how a traceability tool can support traceabilityy maintenance[^fn2].
Capra is an Eclipse plugin and uses the Eclipse Modeling Framework (EMF) as its base technology. It stores the traceability model as an EMF model. The tool relies on the Eclipse Extension mechanism and provides extension points for those parts of the tool that can be customized. Based on requirements we collected from many interested parties in the industry, the tool is customizable at four points:
Additionally, Capra has an API which makes traceability data available to other tools. The current version uses the provided traceability data to visualize it graphically.
The figure below depicts the extension points. The rationale for each of them is described in the following.
![alt text](capraArchitecture.png =600x)
Depending on the company, development context, and process used, the traceability links required can differ. For example, traceability links for a company developing web-based solutions are not the same as links for companies developing embedded software. In the former case, traceability links can help connect certain entries in the server configuration files to specific requirements. The traceability links for embedded software need to relate, e.g., the hardware specification to the software design. Both concepts do not make sense in the respective other domain.
To address the different link types, the tool offers an extension point for the traceability metamodel. Here the end user (company), can define the types of links through a metamodel and supply it to the tool. Examples of link types are “verifies”, “implements”, “refines”, “related to” etc. In addition to link types, the metamodel can also define additional information to be stored with each link. It might be desirable, e.g., to store the date and time the link was created or which user created it.
Software development usually involves a number of activities such as requirements engineering, design, implementation, and testing. In most cases, each of these activities use different tools and produce artifacts of different formats. A traceability tool needs to ensure that the different formats can be traced to and from. Since different companies use different tools, it is not easy to foresee which formats a traceability tool should support. This problem of diverse artifacts existing in the development environment has been noted by several studies on traceability. Our tool offers an extension point for Artifact Handlers which allows adding artifact formats based on the needs of the end users.
As discussed, Capra stores the traceability links as an EMF model. To be able to support tracing to other formats, EMF representations of these other formats are required. Implementing an extension for a certain format means providing an EMF representation of that format to the tool using the artifact handler extension point.
The storage of traceability links is another factor that can vary depending on company policies or project set-ups. For some cases it makes sense that there is a traceability model per project while in some cases there can be one traceability model for the whole workspace. The extension point Persistence Handler allows defining such storage locations. It will also allow integrating the traceability model with versioning solutions such as EMF Store, CDO or Git.
In situations where there is more than one artifact handler that can handle the same artifact type, the tool provides an extension point for a so called Priority Handler. Here the user can define which handler should be used.
Capra provides several programming interfaces that can be used by other plugins to access the traceability data. Currently, this is in three interfaces which are the ArtifactMetaodelAdapter
, TraceMetamodelAdapter
and TracePersistenceAdapter
. The ArtifactMetaodelAdapter
has method that give you access to the artifact wrappers and their contents, the TraceMetamodelAdapter
has methods that give you access to the traceability links and the content of the links and the TracePersistenceAdapter
has methods that give access to the traceability model and the artifact wrapper model. The traceability model containing the traceability links is available to other tools this traceability data can b used for tasks such as impact analysis.
A good example on how these methods can be used is in the plugin org.eclipse.capra.ui.plantuml
. This plugin utilizes the methods to get the traceability model and its links and also to determine which artifacts are connected by the links. The plugin uses the results of these methods to create a string that can be rendered as a diagram using the PlantUML view. For example the in the file VisualizationHelper
, the method CreateMatrix()
calls a method isThereATraceBetween()
which is part of the TraceMetamodelAdapter
interface.
![alt text](interface.png =800x)
To define your own traceability metamodel follow the steps below:
org.eclipse.capra.MyTraceabilityMetaModel
model
model
folder create a new file and name it MyTraceabilityMetaModel.xcore
. A pop up window will appear asking if you want to add the Xtext nature to the project. Click “Yes”.plugin.xml
file of the new project and click on the “Extension Points” taborg.eclipse.capra.configuration.traceabilityMetaModel
org.eclipse.capra.core
to the list of plugin dependencies. Click YesTraceabilityMetaModelAdapter
. A new TraceabilityMetaModelAdapter
will be createdTraceabilityMetaModelAdapter
. On the right hand side, we need to provide a class for this extension, where we will implement all the required interfaces.src
and name your classTo define your own artifact metamodel, follow the steps below:
model
folder, create a new file and name it artifact.xcore
.plugin.xml
file of the project and click on the “Extension Points” taborg.eclipse.capra.configuration.ArtifactMetamodel
ArtifactMetamodelAdapter
. A new ArtifactMetamodelAdapter
will be createdsrc
and name your classNOTE: To test your new Traceability metamodel and artifact model, first close the project org.eclipse.capra.generic.tracemodels
. Otherwise that project will be used by Capra.
In case you want Capra to support an artifact type that is not already supported, you will need to create a new artifact handler for the particular artifact type.
As an example, we describe how the Java artifact handler was added using the following steps:
org.eclipse.capra.handler.jdt
.src
folder of the new project, create a package and name it org.eclipse.capra.handler.jdt
.META-INF
folder , Open the MANIFEST.MF
file and click on the “Extensions” taborg.eclipse.capra.configuration.ArtifactMetaModel
and click Finish.org.eclipse.capra.core
to the list of plugin dependencies. Click YesArtifactHandler
will be created.ArtifactHandler
. On the right hand side, we need to provide a class for this extension, where we will implement all the required interfaces.src
and name your classThe storage of the traceability model and the artifact handler model is not fixed and can be modified depending on the users needs and requirements. To change the storage location of the traceability model there are two options.
org.eclipse.capra.generic.persistance
.src
folder and then the org.eclipse.capra.generic.persistence
packageTracePersistenceAdapter.java
.DEFAULT_PROJECT_NAME
, DEFAULT_TRACE_MODEL_NAME
and DEFAULT_ARTIFACT_WRAPPER_MODEL_NAME
to reflect the new location and new model names for your traceability model and artifact wrapper model. ![alt text](editPersistenceHandler.png =600x)org.eclipse.capra.MyPersistenceHandler
src
folder create a package and name it org.eclipse.capra.MyPersistenceHandler
.META-INF
folder , Open the MANIFEST.MF
file and click on the “Extensions” tab.`org.eclipse.capra.configuration.persistenceHandler
and click Finish.org.eclipse.capra.core
to the list of plugin dependencies. Click Yes.persistenceHandler
. A new Persistence Handler will be created.persistenceHandler
. On the right hand side, we need to provide a class for this extension, where we will implement all the required interfaces.src
and name your class. ![alt text](newPersistenceHandlerClass.png =400x)There are cases where for one artifact type, there are several handlers available. It is important during configuration to select which handler should be given a priority for the particular artifact type. This can be done by editing the code in the Priority Handler as follows:
org.eclipse.capra.generic.priority
.org.eclipse.capra.generic.priority
package.DefaultPriorityHander.java
.hudsonHandler
when the element selected is a Test element and also a build element.![alt text](priorityHandlerCode.png =600x)
It is important to maintain the correct copyright messages, indicating the contributors of each file and that it is covered by the EPL. You can use automation to insert a correct copyright header.
Install the Eclipse Releng Tools. They contain the copyright tool. Use the following copyright header:
Copyright (c) ${date} Chalmers | University of Gothenburg, rt-labs and others. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html Contributors: Chalmers | University of Gothenburg and rt-labs - initial API and implementation and/or initial documentation
The Contributors entry can be replaced with the appropriate names. Use “Fix copyrights” from the context menu to add the copyrights to all relevant files in a project or folder.
[^fn1]: Maro, S. and Steghöfer, JP., 2016, September. Capra: A Configurable and Extendable Traceability Management Tool. In 2016 IEEE 24th International Requirements Engineering Conference (RE). IEEE.
[^fn2]: Maro, S., Anjorin A., Wohlrab R. and Steghöfer, JP., 2016, September. Traceability Maintenance: Factors and Guidelines. In Automated Software Engineering (ASE), 2016 31st IEEE/ACM International Conference. IEEE.