h1(#capra-help-contents). Capra Help Contents

h2(#user-guide). User Guide

h3(#introduction-what-is-capra). Introduction -- What is Eclipse Capra?

Eclipse Capra is a traceability management tool. It allows the creation of trace links between arbitrary artifacts, provides features to edit them and keep them consistent, and visualise the relationships between them. This includes traceability matrices and graph visualisations that are helpful for reporting and change impact analysis.

In essence, Eclipse Capra allows the creation of trace links between arbitrary artifacts, as long as an adapter for these artifacts is available. Eclipse Capra currently natively supports elements from UML, SysML, AADL, EAST-ADL, as well as ReqIF models created in, e.g., Eclipse Papyrus, Eclipse EATOP, and ProR. Furthermore, adapters for test case executions managed by a continuous integration server like Hudson or Jenkins can be traced to. There is also support for source code files supported by the Eclipse Platform (e.g., Java, C, Python) and tasks from an issue tracking system supported by Eclipse Mylyn. External artifacts for which the Eclipse Platform does not offer built-in support can also be linked if a fitting adapter is provided. Built-in capabilities allow linking to Office documents and documents hosted by Google Docs. A generic file handler and a handler for EMF models also provide capabilities for formats that currently have no native support.

Once trace links are established, Eclipse Capra offers features to manage them. If a model element that is linked to is moved, e.g., Eclipse Capra will notify the user and allow changing the link accordingly. The same support is given for model elements that are deleted or renamed. Quick fixes are available to fix most isses in a semi-automatic fashion.

Eclipse Capra also offers different visualisations of the trace links which allow developers to traverse the relationships established through the links and understand how the different artifacts are connected. This is helpful when assessing the impact a change has (e.g., which design artifacts need to be adapted when a requirement has changed?) or when trying to understand how the design artifacts in a complex development project are connected. In addition, Eclipse Capra can display traceability matrices, as requested by standards like ISO 26262.

The tool is highly extensible. The meta-model used for the traceability links can easily be adapted to a specific end-user's needs. Eclipse Capra's modular architecture allows exchanging the persistence, the visualisation, and the management modules easily. New adapters for additional artifacts can easily be added without re-compilation. This allows end-users to customise almost every aspect of the tool if needed. At the same time, we provide sensible defaults that will allow the majority of users to use Capra out of the box without extensive configuration.

h3(#getting-started). Getting Started

There are a number of resources to help you get started with Eclipse Capra:

* The "project wiki":https://wiki.eclipse.org/Capra contains information on how to install Eclipse Capra and contribute to it.
* A "video introduction":https://www.youtube.com/watch?v=jkUiYPIrutI&t=1205s to Eclipse Capra from the Eclipse Open Research Webinar Series
* The "MobSTr dataset":https://github.com/panorama-research/mobstr-dataset -- a complete systems engineering example that shows Eclipse Capra's extensibility

h3(#traceability-concepts). Traceability Concepts

In this section, important concepts of traceability are described.

h4(#definition-of-traceability). Definition of traceability

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.

h4(#what-is-a-traceability-link). What is a traceability link?

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. Traceability links are also often called _trace links_.

Eclipse Capra stores traceability links in a _trace model_. The trace model contains all important information about the traceability links themselves, about the artifacts the links connect, and about the metadata stored about a traceability link.

h4(#types-of-traceability-links). Types of traceability links

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. 

* Link Shape: A link can have a source and target which means that you can only use it to connect two artifacts, or it can be of N-nary type, meaning that you can connect more than two artifacts using the same link.
* Link Semantics: Traceability links can carry different semantics. The semantics of a link can be implied through the link name, e.g., "satisfies", "implements", "tests". It is also possible to enforce "technical" restrictions on which kind of artifacts a link can connect. For example, a "tests" link type can only allow connecting a test to a requirement. Link semantics are defined through a "traceability metamodel":#traceability-metamodel and are configurable in Capra.
* Direction of a link: A traceability link can be either a directed link or a bi-directional link. A directed link has a "source" and "target(s)" relationship where the link is from the source and points to the target(s). A directed link also means that one can navigate from "source" to target(s) but not vice versa. A bi-directional link means that the link has no semantics in the direction and one can navigate from any connected artifact to the other connected artifact(s).

h4(#what-is-an-artifact). What is an artifact?

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.

h4(#what-is-an-artifact-handler). What is an artifact handler?

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, in principle, 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 be created. For details on how to add new artifact handlers to the tool, refer to "Adding a new artifact handler":#adding-a-new-artifact-handler. 

h3(#practical-examples). Practical Examples

To demonstrate features of Capra, we take an example of the development of a Heating, Ventilation and Air Conditioning (HVAC) System. The resources can be dowloaded "here":https://www.dropbox.com/s/h6vzmca7sjpq83q/HVAC%20Projects.zip?dl=0. The project contains the following artifacts:

* A set of requirements which are written in "ReqIF":http://www.omg.org/spec/ReqIF/ format.
* A feature model describing the different features that can form several products of the HVAC system.
* State machines used to describe the behavior of the system
* Generated code from the state machines 
* Test cases defined as Java Unit tests and 
* Issues/Tasks/Tickets reported as development progresses which are stored on a "Trac":https://trac.edgewall.org/wiki/TracTickets server

These artifacts are shown in the figure below in the context of the development environment of the HVAC system.

<figure><img src="../images/hvacProjects.png" width="800"/><figcaption>Figure 2: Resources for the HVAC system</figcaption></figure>

h4(#creating-traceability-links). Creating Traceability Links

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:

# A link from a requirement to a feature representing the requirement in the feature model
# A link from a feature to the state machine that describes the behavior of the feature
# A link from a state machine to test case that tests the behavior described by the state machine
# A link from a requirement to a PDF document that describes safety issues that need to be considered
# A link from a task ticket to a requirement that is associated with the ticket

The procedure to create the above links is described below.

h5(#a-link-from-a-requirement-to-a-feature-representing-the-requirement-in-the-feature-model). A link from a requirement to a feature representing the requirement in the feature model

# To start, open the requirements (@HVAC_Requirements.reqif@ file), with the "Sample Reflective Ecore Editor" view. 
# Expand the model to see the requirements. Drag Req 3 and drop it in the Selection view. 
# Next, open the feature model (@HVAC_Variants.pld@), drag and drop the feature named "Blower" into the selection view as well as shown in the figure below. 	<figure> 		<img src="../images/selectionView1.png" width="400"/> 		<figcaption> 		Figure 3: Capra Selection View 		</figcaption> 	</figure> 
# Right click on the selection view and click on "Create Trace". 	<figure> 		<img src="../images/createTrace.png" width="400"/> 		<figcaption> 		Figure 4: Creating a traceability link 		</figcaption> 	</figure> 
# A pop up window will appear, showing the types of links that can be created based on the selected element.
# Choose a traceability link type to create (in our case "RelatedTo") and click OK. <figure> 	<img src="../images/relatedTo.png" width="400"/>	<figcaption> 	Figure 5: Creating a traceability link of type "RelatedTo" 	</figcaption> </figure> 	Since this is our first traceability link, a new folder will appear in the 	workspace with the name @__WorkspaceTraceModels@. This folder 	contains your 	trace model which contains the traceability 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 traceability link are all EMF elements. 	The trace model (@traceModel.xmi@) should contain only one traceability link. <figure> 		<img src="../images/traceLink.png" width="700"/> 		<figcaption> 		Figure 6: A traceability link of type "RelatedTo" 		</figcaption> </figure>
# To remove the elements from the selection view, there are two options: 
## Right click on an element and select "Remove from Selection". This will only remove the selected element.
## Right click anywhere on the selection view and click on "Clear selection". This will remove all elements in the selection view. 

h5(#a-link-from-a-feature-to-the-state-machine-that-describes-the-behavior-of-the-feature). A link from a feature to the state machine that describes the behavior of the feature

# From the feature model, drag and drop the feature named "Blower" into the selection view.
# Open the @BlowerCtlr@ state machine and drag and drop the parent element to the selection view.
# Right click on the selection view and click on "Create Trace".
# A pop up window will appear, showing the types of links that can be created based on the selected elements.
# Choose a traceability link type to create (in our case "RelatedTo") and click OK. 	Expand the @__WorkspaceTraceModels@ project and open the trace model 	(@traceModel.xmi@). You will notice that a second traceability link has been 	created.

h5(#a-link-from-a-state-machine-to-test-case-that-tests-the-behavior-described-by-the-state-machine). A link from a state machine to test case that tests the behavior described by the state machine

# Clear the selection view.
# Again, Open the @BlowerCtlr@ state machine and drag and drop the parent element to the selection view.
# Expand the project containing the tests, expand the @BlowerTest.java@ file to reveal the BlowerTest class. Drag and drop this class to the selection view.
# Right click on the selection view and click on "Create Trace".
# A pop up window will appear, showing the types of links that can be created based on the selected elements.
# Choose a traceability link type to create (in our case "RelatedTo") and click OK.

h5(#a-link-from-a-requirement-to-a-pdf-document-that-describes-safety-issues-that-need-to-be-considered). A link from a requirement to a PDF document that describes safety issues that need to be considered

# Clear the selection view.	
# Expand the folder containing the requirements to reveal its contents.
# Open the requirements (@HVAC_Requirements.reqif@ file), with the "Sample Reflective Ecore Editor" view.
# Expand the model to see the requirements. Drag Req 3 and drop it in the Selection view. 
# Select the @ISO26262 Requirements.png@ file from the Project Explorer and drag and drop it to the selection view
# Right click on the selection view and click on "Create Trace".
# A pop up window will appear, showing the types of links that can be created based on the selected elements and the definition of the traceability metamodel. In this example the traceability metamodel has only one traceability link type which is called "RelatedTo".
# Choose a traceability link type to create (in our case "RelatedTo") and click OK.

h5(#a-link-from-a-task-ticket-to-a-requirement-that-is-associated-with-the-ticket). A link from a task ticket to a requirement that is associated with the ticket

# Clear the selection view
# Drag Req 3 and drop it in the Selection view.
# From the @Task List@ view, where the tasks from the Trac server are listed, select one task and drag and drop it to the selection view
# Right click on the selection view and click on "Create Trace".
# A pop up window will appear, showing the types of links that can be created based on the selected elements.
# Choose a traceability link type to create (in our case "RelatedTo") and click OK.

h4(#visualizing-traceability-links). Visualizing Traceability Links

Capra 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 traceability link between the artifact in the column and that in the specific row.

h5(#graphical-view). Graphical view

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.

<figure>		<img src="../images/toggleTransitivity.png" width="600"/>		<figcaption>		Figure 7: Toggle Transitivity		</figcaption></figure>

h5(#traceability-matrix). Traceability matrix

Eclipse Capra supports two ways of showing a traceability matrix: either via the PlantUML view or via the standalone matrix view.

h6. Traceability matrix in PlantUML

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 to show that there is a traceability link between two elements. For instance, the picture below shows the resulting matrix when selecting Req3 and the artifact wrapper representing the PDF document. 

<figure>	
	<img src="../images/matrixView.png" width="400"/>
	<figcaption>	Figure 8: Matrix View as a result of selecting two elements</figcaption>
</figure>

Selecting more than two model elements expands the matrix into a square matrix with same elements listed vertically and horizontally. 

<figure>	
	<img src="../images/matrixViewMany.png" width="600"/>
	<figcaption>	Figure 9: Matrix view as a result of selecting more than two elements</figcaption>
</figure>

h6. The standalone traceability matrix view

Eclipse Capra also offers a standalone viewer for trace matrices. That standalone view has the advantage that it can handle larger trace models, that it can export the matrix to Excel, and that it offers some convenience functions, such as providing a graphical view of which artifacts are inconsistent (see also "Detecting and fixing inconsistencies":#detecting-and-fixing-inconsistencies further below). A user can doubleclick on an empty cell to create a new trace link between the two referenced artifacts. It is also possible to select an existing trace link and delete it, either by using the menu or the @Del@ button on the keyboard.

<figure>
	<img src="../images/standalone-matrix.png" width="600"/>
	<figcaption>	Figure 10: The standalone traceability matrix view.</figcaption>
</figure>

h4(#detecting-and-fixing-inconsistencies). Detecting and Fixing Inconsistencies

Traceability links need to be updated as the artifacts they connect evolve. Capra provides features that help users identify when the artifacts have changed and to resolve the issues that come with this.

On the one hand, Eclipse Capra will notify users when artifacts which are maintained inside Eclipse change. If, e.g., a user changes a requirement in a ReqIF file, Eclipse Capra will detect this change, check if any trace links to or from the requirement exist, and create a marker if that is the case. Eclipse Capra uses the Eclipse Notification Framework to detect changes and can capture rename, move, change and delete actions made on artifacts that have traceability links.

On the other hand, Eclipse Capra allows users to manually check the consistency of the entire trace model. This is useful when the trace model contains trace links to artifacts that are maintained outside of Eclipse, e.g., with an external requirements editor or an external modelling tool. To check all trace links for consistency, use the corresponding button in the Eclipse IDEs toolbar as shown below.

<figure>
	<img src="../images/check-consistency.png" width="400"/>
	<figcaption>Figure 11: The button to check for consistency of the trace model in the main Eclipse IDE toolbar.</figcaption>
</figure>

The problems detected by Capra are shown in the @Problems View@ with a type "Capra problem". In addition, the "traceability matrix view":traceability-matrix also shows which artifacts can no longer be found (in red) and which have been renamed (in yellow).

Eclipse Capra also provides quick fixes to address any issues and update traceability links accordingly. Which fixes are applicable is automatically selected by Capra. Quick fixes are either accessible via the problems view or by using the context menu on the corresponding artifact on the traceability matrix.

We demonstrate the use of the @Problems View@ and quick fixes using our practical example of the HVAC project. 

# Go to the "Project Explorer" and expand the project containing test cases. 
# Delete the file @BlowerTest.java@.
# Look at the @Problems view@ and you will see a warning with a type "Capra Problem". The issue tells you that there is a traceability link that points to a file named @BlowerTest.java@, but that file has been deleted. <figure> 		<img src="../images/problemView.png" width="700"/> 		<figcaption> 		Figure 12: Problem view showing Capra errors 		</figcaption> </figure>
# Right click on the warning and select Quick fix.
# A window will appear showing the quick fixes options available. In this case there is one option, which is to delete the traceability link related to @BlowerTest.java@ file. <figure> 		<img src="../images/quickFix.png" width="500"/> 		<figcaption> 		Figure 13: Quick Fixes 		</figcaption> </figure> 
# Click Finish.
# Notice that the traceability link has been deleted and the warning disappears.

h4(#analyzing-change-impact). Analyzing change impact

In this section, we describe scenarios in which Capra can be used to facilitate change impact analysis. Change impact analysis allows to evaluate the effect a change to an artifact will have on other artifacts. Using the HVAC example, assume that the customer requests a change on the requirement @REQ-3@. Before such a change is made, it is important for the company to know which other artifacts will be affected. With Capra, this can be achieved by selecting @REQ-3@ and, using the visualization, reviewing all other artifacts that are related to @REQ-3@ too. 

<figure>		<img src="../images/toggleTransitivity.png" width="700"/>		<figcaption>		Figure 14: Capra graphical view showing directly connected elements		</figcaption></figure> 

For further analysis, clicking on Toggle transitivity as shown in the figure below will show all artifacts connected to @REQ-3@ and their connnections to other artifacts. The end user can therefore use this information as a starting point for performing impact analysis.

<figure>		<img src="../images/graphical-view-transitive.png" width="500"/>		<figcaption>		Figure 15: Capra graphical view showing transitively connected elements		</figcaption></figure> 

h2(#developer-guide). Developer Guide

The following subsection describes the technical architecture of the tool. This information is also available in more detail in a tool demonstration paper "(1)":#references. Our motivation for choosing this architecture design is based on a study on factors and guidelines that affect how a traceability tool can support traceability maintenance "(2)":#references. 

h3(#architecture-of-capra). Architecture of Capra

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":https://wiki.eclipse.org/FAQ_What_are_extensions_and_extension_points 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: 

# The types of links to be supported;
# Which types of artifacts can be traced to;
# How the links should be stored;
# The artifact handler that should be used in case there is more than one available for one artifact type.

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.

<figure>		<img src="../images/capraArchitecture.png" width="600"/>		<figcaption>		Figure 16: The Architecture of Capra		</figcaption></figure> 

h4(#traceability-metamodel). Traceability Metamodel

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 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.

h4(#artifact-handler). Artifact Handler

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. 

h4(#persistence-handler). Persistence Handler

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.

h4(#priority-handler). Priority Handler

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. 

h3(#capra-api). Capra API

Capra provides several programming interfaces that can be used by other plugins to access the traceability data. Currently, there are three interfaces: @ArtifactMetamodelAdapter@, @TraceMetamodelAdapter@ and @TracePersistenceAdapter@. @ArtifactMetamodelAdapter@ has methods that provide access to the artifact wrappers and their contents,  @TraceMetamodelAdapter@ has methods that provide access to the traceability links and the content of the links and the @TracePersistenceAdapter@ has methods that provide access to the traceability model and the artifact wrapper model. The traceability model containing the traceability links is available to other tools. That means that traceability data can be used by other tools for specialised 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 in the file @VisualizationHelper@, the method @CreateMatrix()@ calls a method @isThereATraceBetween()@ which is part of the
@TraceMetamodelAdapter@ interface. 

<figure>		<img src="../images/interface.png" width="600"/>		<figcaption>		Figure 17: Use of the method "isThereATraceBetween()" provided by the `TraceMetamodelAdapter` interface		</figcaption></figure>

h4(#adding-a-custom-traceability-metamodel). Adding a custom Traceability Metamodel

To define your own traceability metamodel follow the steps below:

# Create a Java project and name it @org.eclipse.capra.MyTraceabilityMetaModel@
# Create a new folder and name it @model@
# In the @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".
# Define your traceability metamodel as required. In our example, we add two types of traceability links i.e "implements" and "tests" <figure> 		<img src="../images/traceMetamodelDefinition.png" width="400"/>		<figcaption> 		Figure 19: Tracemetamodel Definition 		</figcaption> </figure> 
# Open the @plugin.xml@ file of the new project and click on the "Extension Points" tab 
# Un-check the check box that says "Show only extension points from the required plugins" 
# In the text box for the "Extension point filter" type "Traceability" and select @org.eclipse.capra.configuration.traceabilityMetaModel@
# Click Finish. <figure> 		<img src="../images/addTraceExtension.png" width="500"/> 		<figcaption> 		Figure 19: Adding the Trace metamodel extension point 		</figcaption> </figure> 
# Another pop up window will appear asking if you want to add the project @org.eclipse.capra.core@ to the list of plugin dependencies. Click Yes 
# Right click on the newly added extension, and click on "New" then @TraceabilityMetaModelAdapter@. A new @TraceabilityMetaModelAdapter@ will be created 	<figure> 		<img src="../images/newTMAdapter.png" width="700"/> 		<figcaption> 		Figure 20: Adding the Trace metamodel extension point 		</figcaption> 	</figure> 	
# Click on the newly created @TraceabilityMetaModelAdapter@. On the right hand side, we need to provide a class for this extension in which we will implement all the required interfaces. 
# Click on "Class" and a pop up window for creating a new class will appear. Make sure the folder is @src@ and name your class <figure> 		<img src="../images/newClass.png" width="700"> </img>		<figcaption> 		Figure 21: Add new Class 		</figcaption> </figure> <figure> 		<img src="../images/addNewTraceAdapterClass.png" width="500"/> 		<figcaption> 		Figure 22: Add new Trace Adapter Class 		</figcaption> </figure> 
# Click Finish and a class will be created with the methods to be implemented in it. 
# Implement all the methods according to your new custom metamodel. Note that information about what each method does and its parameters can be obtained by hovering the mouse over the respective method name. 

h4(#adding-a-custom-artifact-metamodel). Adding a custom Artifact metamodel

To define your own artifact metamodel, follow the steps below:

# In the same project used to define the traceability metamodel, go to the @model@ folder, create a new file and name it @artifact.xcore@.
# Define the artifact metamodel as in the picture below. Note that you can modify this definition to fit your needs. <figure> 		<img src="../images/artifactMetamodelDefinition.png" width="400"/> 		<figcaption> 		Figure 23: Artifact Metamodel definition 		</figcaption> </figure> 
# Next, open the @plugin.xml@ file of the project and click on the "Extension Points" tab
# Un-check the checkbox that says "Show only extension points from the required plugins" 
# In the textbox for "Extension point filter" type "Artifact" and select @org.eclipse.capra.configuration.artifactMetamodel@
# Right click on the newly added extension, and click on "New" then @ArtifactMetamodelAdapter@. A new @ArtifactMetamodelAdapter@ will be created <figure> 		<img src="../images/newArtifactAdapter.png" width="600"/>		<figcaption> 		Figure 24: Artifact adapter definition 		</figcaption> </figure> 
# Click on "Class" and a pop up window for creating a new class will appear. Make sure the folder is @src@ and name your class <figure> 		<img src="../images/newArtifactAdapterClass.png" width="500"/> 		<figcaption> 		Figure 25: Artifact adapter Class definition 		</figcaption> </figure> 
# Click Finish and a class will be created with the methods to be implemented in it. 
# Implement all the methods according to your new custom metamodel. Note that information about what each method does and its parameters can be obtained by hovering the mouse over the respective method name. 

NOTE: To test your new Traceability metamodel and artifact model, first close the project @org.eclipse.capra.generic.tracemodel@. Otherwise that project will be used by Capra.

h4(#adding-a-new-artifact-handler). Adding a new artifact handler

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:

# Create a new plugin project and name it @org.eclipse.capra.handler.jdt@.
# In the @src@ folder of the new project, create a package and name it @org.eclipse.capra.handler.jdt@.
# Expand the @META-INF@ folder , open the @MANIFEST.MF@ file and click on the "Extensions" tab
# Click on Add. A pop up window will appear with a list of available extension points.
# Un-check the checkbox that says "Show only extension points from the required plugins" 
# In the textbox for "Extension point filter" type "Artifact" and select @org.eclipse.capra.configuration.artifactMetaModel@ and click Finish.
# Another pop up window will appear asking if you want to add the project @org.eclipse.capra.core@ to the list of plugin dependencies. Click Yes 
# Right click on the newly added extension, and click on "New", then "ArtifactHandler". A new @ArtifactHandler@ will be created. <figure> 		<img src="../images/newArtifactHandler.png" width="600"/>		<figcaption> 		Figure 26: New Artifact Handler definition 		</figcaption> </figure>
# Click on the newly created @ArtifactHandler@. On the right hand side, we need to provide a class for this extension, where we will implement all the required interfaces. 
# Click on "Class" and a pop up window for creating a new class will appear. Make sure the folder is @src@ and name your class <figure> 		<img src="../images/newArtifactClass.png" width="500"/>		<figcaption> 		Figure 27: New Artifact Handler Class definition 		</figcaption> </figure>
# Click Finish and a class will be created with the methods to be implemented in it. In this case there are only two methods.
# Implement all required methods. Note that information about what each method does and its parameters can be obtained by hovering the mouse over the respective method name. 

h3(#changing-the-storage-location-of-the-traceability-model). Changing the storage location of the traceability model

The 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.

# To edit the existing persistence handler project OR 
# To create a completely new persistence handler.

h4(#edit-existing-persistence-handler). Edit existing Persistence Handler

# Expand the project @org.eclipse.capra.generic.persistance@.
# Expand the @src@ folder and then the @org.eclipse.capra.generic.persistence@ package
# Open the file @TracePersistenceAdapter.java@.
# Edit the static variables @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. <figure> 		<img src="../images/editPersistenceHandler.png" width="700"/> 		<figcaption> 		Figure 28: Editing existing Persistence Handler 		</figcaption> </figure>
# Save the project and Run Capra

h4(#add-a-new-persistence-handler). Add a new Persistence Handler

# Create a new plugin project and name it @org.eclipse.capra.MyPersistenceHandler@
# In the @src@ folder create a package and name it @org.eclipse.capra.MyPersistenceHandler@.
# Expand the @META-INF@ folder , Open the @MANIFEST.MF@ file and click on the "Extensions" tab.
# Click on Add. A pop up window will appear with a list of available extension points.
# Un-check the checkbox that says "Show only extension points from the required plugins" 
# In the textbox for "Extension point filter" type "Persistence", select @org.eclipse.capra.configuration.persistenceHandler@ and click Finish. <figure> 		<img src="../images/addPersistenceHandler.png" width="500"/> 		<figcaption> 		Figure 29: Add new Persistence Handler 		</figcaption> </figure>
# Another pop up window will appear asking if you want to add the project @org.eclipse.capra.core@ to the list of plugin dependencies. Click Yes. 
# Right click on the newly added extension, and click on "New", then @persistenceHandler@. A new Persistence Handler will be created. <figure> 		<img src="../images/newPersistenceHandler.png" width="600"/>		<figcaption> 		Figure 30: New Persistence Handler 		</figcaption> </figure>
# Click on the newly created @persistenceHandler@. On the right hand side, we need to provide a class for this extension, where we will implement all the required interfaces. 
# Click on "Class" and a pop up window for creating a new class will appear. Make sure the folder is @src@ and name your class. <figure> 		<img src="../images/newPersistenceHandlerClass.png" width="500"/> 		<figcaption> 		Figure 31: New Persistence Handler Class 		</figcaption> </figure>
# Click Finish and a class will be created with the methods to be implemented in it. In this case there are only two methods.
# Implement all methods according to your needs. Note that information about what each method does and its parameters can be obtained by hovering the mouse over the respective method name.

h3(#taking-care-of-multiple-handlers-for-the-same-artifact-type). Taking care of multiple handlers for the same artifact type

There are cases in which several handlers are available for one artifact type. 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:

# Expand the project @org.eclipse.capra.generic.priority@.
# Expand the src folder and then the @org.eclipse.capra.generic.priority@ package.
# Open the file @DefaultPriorityHander.java@.
# Modify the code to select the correct handler. For instance, the code below selects a @hudsonHandler@ when the element selected is a Test element or a build element. <figure> 		<img src="../images/priorityHandlerCode.png" width="700"/> 		<figcaption> 		Figure 32: Code for the Priority Handler 		</figcaption> </figure>

h3(#adding-new-source-files). Adding new source files

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":https://wiki.eclipse.org/Development_Resources/How_to_Use_Eclipse_Copyright_Tool. They contain the copyright tool. Use the following copyright header:

bc.. 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 v2.0
which accompanies this distribution, and is available at
http://www.eclipse.org/legal/epl-v20.html

SPDX-License-Identifier: EPL-2.0
 
Contributors:
   Chalmers | University of Gothenburg and rt-labs - initial API and implementation and/or initial documentation
   Chalmers | University of Gothenburg - additional features, updated API

p. 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.

h2(#references). Rerefences

1. 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.
2. 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.
