Connecting YAKINDU Traceability to various tools

The following sections are giving you a detailed overview on how to configure YAKINDU Traceability in order to connect it to a variety of specific tools. For basic concepts, please have a look at section Configuring your traceability environment.

Tools are connected to YAKINDU Traceability via adapters. A complete list of available adapters, sorted by tool name, is available here: "Overview of YAKINDU Traceability adapters".

Common concepts

The „resource” keyword

The configuration of each adapter is adapter-specific, but some concepts are common.

The keyword resource is always followed by a pattern that denotes one or more files or folders in the Eclipse workspace. Generally a resource pattern is composed as follows:

/project_name_pattern/folder_name_pattern/folder_name_pattern/filename_pattern

That is, a resource pattern

  • starts with a /,
  • followed by an Eclipse project name pattern,
  • followed by zero or more folder name patterns,
  • followed by zero or one filename pattern.

The sequence of these components constitutes a resource_path, also simply called path. Adjacent path components are separated by a slash character ( /) from each other.

Each of these pattern may contain the wildcard characters * or ?. These characters are placeholders representing actual characters in project names, folder names, or filenames, respectively. The asterisk ( *) stands for a sequence of zero or more characters, a question mark ( ?) is a placeholder for exactly one character. A resource pattern may be matched by multiple actual resources, constitution a resource set. Generally a resource pattern is resolved to zero, one, or more than one actual resources.

Examples:

resource /de.itemis.pedelec.implementation.control/readme.txt
resource *.txt
resource /de.itemis*/readme.???

The first example specifies exactly one file.

The second one specifies all files (or folders or Eclipse projects) whose names are ending on the .txt filename extension.

The third example pertains to all projects starting with de.itemis. In these projects, the resource pattern matches all file in the top-level folder beginning with readme. followed by a three-characters extension, like, e.g., doc or txt. Please note that extensions like docx or c do not match the pattern.

String functions

For all adapters that support the name keyword or attribute mapping, a set of string functions is available. These allow to manipulate the original value that is read from the data source, before it is written into an artifact name or attribute.

Supported functions are:

  • trim – Called without parameters, the trim function removes leading and trailing whitespace. In addition, it is possible to provide two optional parameters to specify a trimming strategy and the length of the trimmed value.
  • substringBefore – Keeps only the part of the value left from the first occurrence of a given string.
  • substringAfter – Keeps only the part of the value right from the first occurrence of a given string.
  • match – Specify a regular expression with exactly one group. Only the matched group will be preserved in the result. An optional second parameter allows to replace the matched group by an arbitrary string.
  • replace – Replaces any occurrence of a string by a replacement string.

Examples:

Sample call Result
"SomeSplitAttribute".substringBefore("Split") "Some"
"SomeSplitAttribute".substringAfter("split") "Attribute"
"Some\Attribute".replace("\", "/") "Some/Attribute"
"SomeAttributeValue".trim(8, KEEP_PREFIX) "SomeAtt..."
"SomeAttributeValue".trim(8, KEEP_SUFFIX) "...teValue"
"SomeAttributeValue".trim(8, TRIM_MIDDLE) "Some...lue"
"SomeSomeGroupInAttribute".match(".*(SomeGroup).*") "SomeGroup"
"SomeSomeGroupInAttribute".match(".*(SomeGroupIn).*", "-") "Some-Attribute"

Regular expressions

Regular expressions are a powerful means for find or find and replace operations on character strings. A regular expression, also known as regex or regexp, is a sequence of characters that defines a search pattern. For example, the regex aaa.*bbb specifies a search pattern matching strings consisting of the letters „aaa”, followed by a (possibly empty) sequence of arbitrary characters, followed by the letters „bbb”.

You can use regular expression in many places when setting up your YAKINDU Traceability configuration. YT supports regular expressions as defined by the Java programming language or, to be more exact, by the java.util.regex.Pattern class.

Java regular expressions are very similar to Perl regular expressions. However, please note that there are a few differences!

Attribute mapping

Using the attribute mapping adapter, YAKINDU Traceability can automatically derive links based on the attributes of the artifacts. Trace links are created between each artifact of a type A and each artifact of a type B that have matching attributes.

Consider, for example, an artifact type Requirement with an attribute reqId and another artifact type Implementation that has an attribute implementsReqId. Using the attribute mapping adapter, you can automatically create links between the Requirements and their corresponding Implementation counterparts, respectively. The mapping between Requirements and Implementations is done using the requirement ID, a piece of information that is available on both sides. For each Requirement artifact, the adapter considers all Implementation artifacts and creates a link for those pairs where the reqId attribute of the Requirement equals the implementsReqId of the Implementation.

Actually, the example above is a special case only, and the attribute mapping adapter has much broader capabilities. The values to find matches for are not restricted to the mere attribute values, although they are still based on them, and matching is not restricted to string equality.

  • The mapping values are evaluated as follows:
    • For each artifact a of an artifact type A, the adapter evaluates a function fA(a, i) on the attribute i of artifact type A, resulting in a set of values Va1, Va2, …, Vak. The result set may be empty (k = 0) or have a single element (k = 1).
    • For each artifact b of an artifact type B, the adapter evaluates a function fB(b, j) on the attribute j of artifact type B, resulting in a set of values Vb1, Vb2, …, Vbl. The result set may be empty (l = 0) or have a single element (l = 1).
  • Link creation is done as follows:
    • Matching can be based on string equality and various sorts of substring containment.
    • For all pairs (a; b) of A and B artifacts, the attribute mapping adapter checks whether at least one of the Va1, Va2, …, Vak matches at least one of the Vb1, Vb2, …, Vbk. If there is a match, the adapter creates a trace link between a and b.

The functions fA(a, i) and fB(b, j) as well as the matching conditions have to be formulated as a derivation rule in a link type configuration.

Please note: A derivation rule considers only a single attribute on each side. If you want to take multiple attributes into account, you can do this by defining a new custom attribute in the artifact type and deriving this attribute’s value by combining the values of the attributes you are actually interested in. Then use the new custom attribute in the attribute mapping’s derivation rule.

For setting up everything, you have to define

The configuration effort, including the definition of the derivation rule, goes into the latter.

Of course you also need the artifact types A and B. They must have appropriately-defined attributes for matching.

Data access

The attribute mapping data access does all the work to derive links between A and B artifacts.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Attribute Mapping as data access type.

For the data access, name and type are sufficient. The configuration panel remains empty. The actual configuration for mapping artifacts using keywords goes into the link type configuration, which will reference this data access.

Example:

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • Select artifact types A and B. Since the link derivation is based on attributes of artifacts, these artifact types require appropriate attribute definitions.
  • As data access, select the attribute mapping data access defined above.
  • In the configuration panel, specify the derivation rule.
  • Optionally add attributes:#attribute_mapping_adapter_link_type_attributes to the links.

The derivation rule is the core of link creation. It goes into the link type configuration panel, see below for an example.

Let’s have a look at the syntax of the derivation rule by considering some examples. In the subsequent text, a represents an artifact of type A, and b represents an artifact of type B.

The most simple case is attribute equality:

  • where A.attribute in B.attribute
    • Creates links between all artifacts a and b where the specified attributes have the same value.

You can split an attribute value on a separator character, resulting in a list of strings on one side (or even on both sides):

  • where A.attribute in B.attribute.separatedBy(",")
    • Creates links between all artifacts a and b where the specified A attribute’s value is equal to at least one of the strings that result from splitting the B attribute’s value using the specified separatedBy string, here: a comma („,”).

If you don’t want to compare by exact matches of attribute values, you can use certain functions to first do something with the attribute values of the a and/or b artifacts before comparing the results:

  • where A.attribute.substringBefore(" – ") in B.attribute.substringAfter(": ")
    • If A.attribute equals „0815 – this is the requirement ID” and B.attribute equals „Requirement ID: 0815”, a link will be created between a and b.
  • where A.attribute.match(".*FOO(.+)BAR") in B.attribute
    • If the value of A.attribute is, say, „aaaFOO0815BAR”, it matches the regular expression specified as the match operator’s parameter. In particular, the group (.+) within the regular expression matches „0815”, and this is the value the match operator returns. The match operator must always have a regular expression containing a single group as its parameter. The substring matching this group is the operator’s result. If there is no match, the empty string is returned.
  • where A.attribute.replace("([a-zA-Z]+) ([0-9]+)", "$2_$1") in B.attribute
    • If the value of A.attribute matches the regular expression specified as the replace operator’s first parameter, the latter replaces that match by its second parameter. This parameter may contain placeholders for the regular expression’s groups: The notation „$1” is a placeholder for the text matching the first group, „$2” represents the second group, and so on. For example, if A.attribute is „SomeText 332”, it matches the ([a-zA-Z]+) ([0-9]+) regular expression. In particular, „SomeText” matches the first group, and „332” matches the second group. The replacement text „$2_$1” will thus be substituted by „332_SomeText”.

Functions can be combined in various ways:

  • where A.attribute.substringAfter("PrefixToRemove").substringBefore("SuffixToIgnore") in B.attribute
    • If A.attribute is equal to „PrefixToRemove Text to preserve SuffixToIgnore”, the result will be „Text to preserve”
  • where A.attribute.separatedBy("/").substringBefore(":") in B.attribute
    • If A.attribute is equal to „A:1/B:2/C:3”, the result will be a list of 3 values [A, B, C]
  • where A.attribute.separatedBy(",").separatedBy(";") in B.attribute
    • If A.attribute is equal to „A,B,C; 1, 2, 3; X, Y, Z”, the result will be a list of 9 elements: [A, B, C, 1, 2, 3, X, Y, Z]

The derivation rule supports the following keywords.

  • where – This keyword starts the derivation rule.
  • Link-creating operators: A link-creating operator evaluates the expression on its left-hand side for all artifacts a of artifact type A, and it also evaluates the expression on its right-hand side for all artifacts b of artifact type B.
    • in – For each pair (a; b), a trace link is created between a and b, if at least one of the string values on the left equals at least one of the string values on the right.
    • contains – For each pair (a; b), a trace link is created between a and b, if at least one of the string values on the left contains at least one of the string values on the right as a substring.
    • startWith – For each pair (a; b), a trace link is created between a and b, if at least one of the string values on the left starts with at least of the string values on the right.
  • Functions: The following functions can be used in the expressions on the left-hand and right-hand side of the link-creating operators.
    • separatedBy – splits a string by using the specified string parameter as a separator. For example, use it to break up a comma-separated list of requirement IDs, stored in a cell of an Excel document, into a list of individual strings.
    • substringBefore – keeps only the part of the value before the first occurrence of the given string parameter.
    • substringAfter – keeps only the part of the value after the first occurrence of the given string parameter.
    • match – Specifies a regular expression with exactly one group. The operator’s result is the string matching that group.
    • replace – Specifies a regular expression with any number of groups. The second parameter indicates a replacement string, in which placeholders $1, $2, etc. are substituted by the strings matching the regular expression’s groups.

Please note: Instead of A or B attributes, you can alternatively use their built-in properties. This is done via the metadata keyword. A.metadata(Identifier) returns the position of a, A.metadata(Name) returns its name, and A.metadata(Resource) returns its resource.

Please also note: In order to speed up the process of link derivation, YAKINDU Traceability creates an associative array (a.k.a. map or dictionary) using the values of the configured attributes as keys. This approach is optimized for mappings using the in operator; the usage of contains or startWith might consume more time.

For reporting purposes, artifact attributes of the linked artifacts can be mapped and transformed to link attributes. The mappings are defined within the optional map { … } clause and refer to custom attributes defined for the link type. The value which is assigned to the attribute can be defined by string functions and can access all attributes of A and B.

In this example, we will configure YT to derive links between requirements defined in a ReqIF file and requirement details defined in a Microsoft Excel file.

The derivation is based on references in Excel: Each requirement detail in Excel has a cell containing a comma-separated list of associated ReqIF requirements. To match the identifier in the list to the specific ReqIF requirement the contents in the Excel cell is traversed. The comma serves as separator to find out where the next identifier starts.

  • Activate YT’s link derivation by defining an attribute mapping data access:

  • Define the Requirement artifact type, including custom attributes:

  • Define the Requirement Details artifact type, including custom attributes:

  • Define a link type linking Requirement and Requirement Details using the attribute mapping data access defined above and specifying a derivation rule.
  • As a result, the attribute mapping adapter automatically creates links between each requirement and all requirement detail artifacts mentioning it.

Please note: If A is identified within B.ReqID by its name, resource or position, instead of A.ReqID you can use A.metadata(Name), A.metadata(Resource), or A.metadata(Identifier). This way you don’t have to define and map a custom variable for A.

Links of this link type will never become suspicious.

Eclipse Artop

Artifact type

Configuration

Supported options:

  • subset metaclass – Filter elements by meta class.
  • subset namespace – Filter elements by namespace.
  • resource – File filter pattern.

Example:

resource /*.arxml
subset metaclass system.System
subset metaclass system.SystemMapping
subset namespace "Project.YourSystem_System"

A list of available meta classes can be opened by content assist (pressing [Ctrl]+[Space] after the space following metaclass).

The namespace is the . delimited list of names from the root. In this example all GIdentifiable elements under the package Project in the system YourSystem_System are relevant. Each matched element has to match one of the metaclass subsets and one of the namespace subsets, if the latter are set.

For the example above and the model illustrated below, leads to the shown results in the search dialog.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Browser

Artifact type

Configuration

No configuration available yet.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse C/C++ (CDT)

Data access

The Eclipse CDT data access provides access to C and C++ artifacts such as translation units or functions. It allows to store link information invasively, i.e., within comments in C or C++ files.

The blog post "Tracing requirements and source code" gives a general overview of identifying source code elements as traceable artifacts and linking them to other artifact types, e.g., requirements.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Eclipse CDT as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing the C/C++ files relevant for traceability.

Supported keyword:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions. In this case, YT takes the union of all patterns into account, i.e., the resource expressions are evaluated with a logical OR.

Independent of the definition of a resource, YT only takes files with suffixes .c, .h, or .cpp into account.

Please note that the resources have to reside in an Eclipse C/C++ project.

Example:

In this example, YT evaluates all .c and .h files in the folder named source in the com.yakindu.yt.mt.c project.

Indexer caveat

The CDT index supports searching and fast navigation in C files. This is achieved by resolving all links between files and caching them, aside from macros and active defines.

Initialization and maintenance of the index is not for free, and the CDT adapter finds artifacts even if the index is disabled. If the index is enabled, the option "Allow heuristic resolution of includes" can lead to problems with macros and other included references required to determine artifacts in the source code. In this case – or to prevent other problems –, this option should be disabled.

Artifact type

The C/C++ artifact type recognizes C/C++ elements such as translation units, include statements or functions in a specified set of relevant files. It does not recognize single statements within a function.

As rule-of-thumb, YT recognizes all elements that do appear in the Eclipse CDT’s outline view for C/C++ files.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Eclipse CDT data access in the Data access drop-down list.

Supported keywords:

  • model elements – The list of C/C++ element types to recognize as artifacts. An explicit comma-separated list of types can be specified, or one of the following keywords can be used for a predefined list of types:
    • all – Includes all C/C++ element types
    • default – Includes this default subset of C element types: translation unit, function, function declaration. model elements default is equivalent to an empty configuration.

Examples:

model elements default
model elements all
model elements Include, Macro, TypeDef

Caveat

Some names are not unique

The artifact names for CDT artifacts can’t be configured. YAKINDU Traceability uses the name provided by CDT for each element. However, in some cases, this name is not unique. This is especially the case if two similar elements have the same name, for example if you have two C functions both named doSomething().

If YT detects such cases, it will append a count to the second and subsequent occurrences, e.g., doSomething and doSomething (1). However, if two functions have the same name but a different signature, like, e.g., void doSomething() and void doSomething(int param)), YT will not provide a distinct name for each of them. Both will appear as doSomething [Function], which may be confusing. Please note that this will only affect the way artifacts are displayed: YT will be able to properly distinguish them and to create links to each of them.

Non-unique names may also occur in some structured elements (struct, class, …) if there are parent elements with the same name. CDT should report them as errors, but YT can still handle them. In the following example the name of field a is not unique:

struct Example { //Name is Example [Structure]
	int a; //Name is Example::a [Field]
	int b;
};

struct Example { //Name is Example (1) [Structure]
	int a; //Name is Example::a [Field]
	int b;
};

Some positions are not unique

Some (few) C elements may not be distinguishable from each other if they occur several times in the same file and have the same name. CDT provides an index to distinguish most elements occurring multiple times, but this is not the case for all elements. For example, two functions with the same signature can be distinguished, but two #include statements cannot. If two include statements import the same file, e.g., in two distinct #ifndef blocks, they will have the same name and position. YT will only create one artifact for both of them. This may cause side-effects in link management. For example, it might not be possible to delete a CDT traceability link defined on the second occurrence of the #include statement from the YT Editor – you would have to delete such a link manually by removing the C comment. This should however be a rare case, as it only affects a few types of elements, #include being the only one that is known at this point.

To avoid this issue, it is recommended to avoid creating YT links to #include statements when using the CDT link type.

For example:

#ifdef A
//@link libA
#include "lib.h"
#endif

#ifdef B
//@link libB
#include "lib.h"
#endif

YT will find a single lib.h [Include] artifact, with two links to libA and libB, respectively. Creating a new link to lib.h [Include] will always add new C comments to the first #include occurrence, i.e., below @link libA. The YT Editor will not be able to delete the link to libB.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YAKINDU Traceability is able to recognize link information in C/C++ files, based on a portion of C or C++ code, like

/* @Req1234 */
void someOperation(Foo * param)

YT supports link maintenance both in the C/C++ code and by YT, i.e., on one hand the user can create/delete links by editing the C/C++ comments, on the other hand YT manipulates comments in the C/C++ code, as links are created/deleted in YT.

To configure the C/C++ access, the configuration of both a Eclipse CDT data access and at least one link type using this data access are required.

The actual configuration of how to find the comments and how to derive the linked artifacts' identifiers from these comments is done in the link type configuration.

The configuration covers:

  • … as block|line comment – Determines whether YT creates block or line comments for new links.
  • analyze comments of … – Which artifact type represents the C/C++ artifact. Possible values are A and B.
  • create links by … – This section specifies how YT calculates the content of new comments on link creation. The specification is a concatenation of static strings and values of artifact attributes.
  • locate links by – A regular expression for the text portion in comments in C/C++ files representing a link.
  • map { … } – As an option, it is possible to define link attributes and derive the attribute values similar to the identifier derivation specified by identified by.
  • where – Specifies which attributes are relevant for the identification of an artifact linked to a C/C++ element.
  • filtered elements – Specifies how to deal with link comments on filtered elements. Possible values are:
    • Delegate – Create a link from the first unfiltered parent element (or ignore if there is no matching parent). This is the default behavior.
    • Ignore – Always ignore link comments on filtered elements. No link will be created for such ignored comments.

In the where sections it is possible to add several rules to match groups in the regular expression specified by locate links by to attributes of the relevant artifacts. A rule is expressed by an equation of the form LeftHandSide = RightHandSide . The LeftHandSide is a concatenation of static strings and groups to the regular expression, the RightHandSide is a concatenation of static strings and values of artifact attributes and/or artifacts metadata identifier and resource. For a link, each of these expressions must match, i.e., they are linked by logical AND.

The above example shows a configuration for a data access of type Eclipse CDT. Given the comment /* @Req1234 */, YT creates a link from the C element holding the comment and Requirement Detail 1234.

YT assigns the value @Req1234, i.e., the whole match, to the wholeMarkup attribute. On link creation, YT concatenates @Req and the ID of the linked Requirement Detail, and then writes a block comment with this information.

Again, the example shows a configuration for a data access of type Eclipse CDT. Given a comment //@MYSHEET:A4, YT creates a link from the C element holding the comment to an artifact with attributes sheet="MYSHEET" and cell="A4". In this case, YT doesn’t populate any link attributes. On link creation, YT concatenates "@" + value of B.sheet + ":" + value of B.cell, and then creates a new line comment.

  • YT recognizes comments anywhere in a C/C++ file.
  • On one hand YT is able to find multiple matches in one comment, on the other hand YT creates a new comment for each new link. YT does not expand existing comments.
  • A new comment is always written in the line above the linked element.
  • YT recognizes the C/C++ elements visible in Eclipse’s outline view, i.e., files (translation units), operations, includes, macros, etc. YT does not recognize any C elements within operations, e.g., statements.
  • Comments are assigned to C/C++ elements according to the following rules (by order of priority):
    • A sequence of comments (i.e., not separated by an empty line) at the very beginning of the file (i.e., not preceded by an empty line) belongs to the translation unit.
    • End-of-line comments belong to the last element on that line.
    • A sequence of comments directly preceding an element belong to that element. The comment must be either on the same line or on the previous line, i.e., there must be no empty line between the comment and the following C/C++ element.
    • A comment inside a function belongs to the function.
    • The comment belongs to the translation unit.
  • Comments are always mapped to exactly one element. If several rules match for the same comment, the first rule has a higher priority, according to the aforementioned order. If the comment is assigned to a filtered element, the result will depend on the configuration: The comment will be assigned to the first unfiltered parent of this element if the configuration is set to „delegate”. It will be ignored otherwise (i.e., no link will be created for this comment).
  • If a link is deleted by means of YT, YT removes the link information from the C/C++ comment. If the comment is empty or includes whitespace characters only after the deletion, YT deletes the whole comment. In case the line is empty, YT deletes the line.

The following example illustrates these recognition rules:

// @Req11 - assigned to TranslationUnit
/*
 * @Req12 - assigned to TranslationUnit
 */

// @Req13 - assigned to TranslationUnit

// @Req15 - assigned to include 
/* @Req16 - assigned to include */
// If 'include' elements are filtered, these comments will be assigned to TranslationUnit instead. 
// If 'include' elements are filtered, and comments of filtered elements are ignored, these comments won't be assigned to any element. 
#include "stdafx.h"

// @Req17 - assigned to TranslationUnit

/**
 * @Req19 @Req20 - both assigned to operation _main
 */
// @Req22 @Req23 - both assigned to operation _main
int _tmain(int argc, int* argv[])
{
    return 0;
}
int _tmain2(int argc, int* argv[])
{
    //@Req28 - assigned to  _tmain2
    return 0;
    //@Req29 - assigned to  _tmain2
}

struct S1 { //@Req30 assigned to S1
    field a; //@Req31 assigned to S1::a
}

//@Req32 assigned to a
int a, /* @Req33 assigned to b */ b, c; //@Req33 assigned to c


Links of this link type will never become suspicious.

Eclipse editor drag-and-drop linking functionality

YT supports the creation of links by dragging elements from various YT views and dropping them into a C editor.

This functionality requires the following:

  • A unique link type needs to be configured between the artifact type of the elements being dragged to the C editor and the artifact type of target elements in the C editor.
  • There must be only one mapping of type „C” for this link type. Additionally, this mapping needs to support the creation of links by insertion of comments in C files.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the C editor. A comment is inserted at the beginning of the line where the drop is performed, the source code being edited in the C editor is saved to disk, and a link is created automatically. If one of the conditions required for this functionality is not fulfilled, dropping is prevented and a message is shown that indicates the reason.

Eclipse Java (JDT)

The Eclipse Java data access provides access to artifacts for the Java artifact provider in Java files.

The blog post "Tracing requirements and source code" gives a general overview of identifying source code elements as traceable artifacts and linking them to other artifact types, e.g., requirements.

Data access

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Eclipse Java as data access type.

Within the configuration panel, you can specify file patterns consisting of Eclipse projects, folders or filename patterns describing the Java files relevant for traceability.

Supported keyword:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions. In this case, YT takes the union of all patterns into account.

Independent of any resource definitions, YT takes only files with filename extension .java into account.

Please note that the resources have to reside in an Eclipse Java project.

Example:

In this example, YT evaluates all *.java files in project com.yakindu.yt.mt.java, folder name beginning with src.

Configuration

No configuration available yet.

Artifact type

The Java artifact type recognizes Java elements such as classes, methods and properties in a specified set of relevant files, but not individual statements within a method. The relevant files are specified in the Java data access. As a rule-of-thumb, YT recognizes all elements that appear in the outline view for Java-files.

Configuration

All configuration is done in the data access. An Eclipse Java artifact type does not support any further configuration.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Eclipse Papyrus

Eclipse Papyrus is a modeling environment that allows for graphical modeling according to a large number of standards including UML 2. The adapter allows to trace into such models and extract artifacts and links.

The configuration of the Eclipse Papyrus adapter is nearly identical to that of the Eclipse UML2 adapter. Therefore, please refer to section Eclipse UML2 for information about how to configure data access, artifact type, and link type. Basically, you need to select the desired Papyrus variant in the drop-down list instead of the UML2 ones.

The only major difference between the Eclipse Papyrus adapter and the Eclipse UML2 adapter is that if you double-click on a Papyrus artifact, it will open in Papyrus and not in the UML2 model editor.

Currently YT supports decorations in order to indicate whether an element opened in the Papyrus editor is linked to other elements. Accordingly, once an element has been opened in the Papyrus editor, it is decorated with a YAKINDU logo if it is linked. Additionally, If this decoration icon is hovered upon, a tooltip appears indicating the number of elements this element is linked to. This is shown in figure "Linked elements are marked in Papyrus".

Linked elements are marked in Papyrus

Linked elements are marked in Papyrus

Once the decoration icon is clicked, a context menu listing the linked artifacts opens, see figure "Listing linked artifacts in Papyrus". If you click the context menu item of one of these elements, a tooltip appears showing a small summary of this element. Double clicking one of the linked elements in the context menu opens this element.

Listing linked artifacts in Papyrus

Listing linked artifacts in Papyrus

Eclipse Project Explorer

The Eclipse Project Explorer adapter identifies workspace resources in Eclipse as traceable artifacts. It also provides access to various properties of these resources.

Data access

The Eclipse Project Explorer data access can be configured to access arbitrary files, folders and projects within the Eclipse workspace. You can define patterns to specify the locations and filenames that will be taken into account.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Eclipse Project Explorer as data access type.

Supported keywords:

  • resource – Resource filter pattern.

Example:

resource /de.itemis.*/*

The above example specifies all resources (i.e., folders, files, and projects) that are located in projects whose names start with de.itemis..

Artifact type

The Eclipse Project Explorer artifact type identifies each of the resources that match the patterns defined in the associated Eclipse Project Explorer data access as an artifact. It supports selection propagation from artifacts in YT to resources in the Project Explorer view in Eclipse and vice versa.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Eclipse Project Explorer data access in the Data access drop-down list.

The Eclipse Project Explorer artifact type can be configured to access several properties of these resources, e.g., the type of resource, the date of the last modification, or whether the resource is read-only. You can concatenate these properties with static strings and with each other and assign them to custom attributes of the artifact. You can also define the name of artifacts in the same way. By default, the name of the artifact will be the name of the resource.

For an example, consider that you want the name of each artifact to be the full name of the resource, followed by the type of resource (file, folder, or project) in parentheses. You can concatenate strings as usual with the + operator, and you can access properties with the valueOf keyword, followed by the name of the property in parentheses. For the sake of this example, you can define the artifact name using the following line in the artifact type configuration:

name valueOf(fullName) + " (" + valueOf(type) + ")"

Let us consider that you also want to assign the values of some properties to some custom attributes. You want to have custom attributes containing the path of the resource, the date of the last modification, and – in a single attribute – whether the resource is read-only and whether it is hidden or not. For files, you also want to maintain the file size in an attribute. The following lines in the artifact configuration accomplish this:

map{
	Path to valueOf(path)
	LastModification to valueOf(lastModified)
	State to "read-only: " + valueOf(isReadOnly)+ ", hidden: " + valueOf(isHidden)
	FileSize to valueOf(fileSize) + " bytes"
}
Configuration keywords

The Eclipse Project Explorer artifact type configuration supports the following keywords:

  • map – Maps artifact properties to custom attributes. For each attribute it contains an expression of the form attribute to expression, where attribute is the attribute name and expression defines how the assigned value is computed.
  • name expr – Specifies the name of the artifact as the value the expression expr evaluates to. By default, an artifact’s name is the name of the corresponding resource.
  • valueOf( property) – Refers to the value of the resource property whose name is specified by property. The adapter supports access to the following properties:
    • extension – The filename extension of the resource. This is only relevant for files.
    • fileSize – The size of the resource in bytes, if the resource is a file. Otherwise, the result will be the empty string.
    • fullName – The (full) name oft the resource. In case of files, this includes the filename extension.
    • isArchive – A boolean flag, indicating whether or not the resource is marked as an archive.
    • isDirectory – A boolean flag, indicating whether or not the resource is a directory.
    • isExecutable – A boolean flag, indicating whether or not the resource is marked as an executable file in the file system. Note that Microsoft Windows does not support this flag.
    • isHidden – A boolean flag, indicating whether or not the resource is hidden on the file system level.
    • isReadOnly – A boolean flag, indicating whether or not the resource is read-only.
    • lastModified – The date and time of the last modification of this resource.
    • lastModifiedDate – The date of the last modification of this resource.
    • lastModifiedTime – The time of the last modification of this resource.
    • modificationStamp – The internal resource modification timestamp of the resource in Eclipse.
    • numberOfContents – The number of elements contained in the resource, if the resource is a folder. Otherwise, the result will be the empty string.
    • OSPath – The path to the resource in the format specific to the user’s operating system.
    • path – The platform-independent path to the resource.
    • shortName – The name of the resource without any filename extension.
    • type – The type of the resource. It is either „file”, „folder”, or „project”.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is its resource modification timestamp.

Eclipse ProR

The ProR adapter identifies traceable artifacts based on requirements that are stored in the ReqIF (Requirements Interchange Format) file format. More precisely, the adapter creates artifacts for ReqIF specification objects that fulfill certain conditions. These conditions are configurable. The adapter propagates the selection of artifacts from YT to the ProR requirements engineering platform and vice versa.

ProR is the graphical component of the open-source RMF (Requirements Modeling Framework) software framework. It allows for creating and editing ReqIF models. Requirements in these models are defined as „specification objects”, each of which has a user-defined type and a user-defined set of attributes. Based on these types and attributes, the ProR adapter supports filtering of those specification objects that should be recognized as traceable artifacts.

ProR displays specification objects and their attributes in tables. It also displays specification objects in Eclipse’s Overview view. The ProR adapter recognizes selections both in tables and in the overview.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Eclipse ProR as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource *.reqif

This configuration rule specifies that YT should load ReqIF models from all files in the workspace whose filename extension is .reqif.

Artifact type

The ProR artifact type identifies specification objects in ReqIF models as traceable artifacts. The set of identified artifacts can be constrained, based on their types and the values of their attributes. These constraints can be configured.

For each combination of constraints to derive artifacts for, you can define how the artifact name and the values of custom attributes should be computed. In both cases, you can specify expressions that refer to the attributes of the specification objects that were identified as artifacts.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Eclipse ProR data access in the Data access drop-down list.

Identifying specification elements as artifacts

We will now introduce the configuration language, including its syntax, by an example. You can find the complete list of keywords below.

Let’s consider a specification Functional Requirements that contains specification objects, some of which have the type Functional Requirement. This type defines the attributes ID, Title, Description and Status.

To identify artifacts, we need to create a mapping and configure it. The following mapping configuration for a ProR artifact type derives artifacts for specification objects of type Functional Requirement and assigns values to their custom attributes. These values depend on conditions on the artifacts themselves. The configuration will be explained in more detail below.

name valueOf(ID) + "-" + valueOf(Title)
map to type "Functional Requirement" if (valueOf("Status") != "REJECTED" and isSet("Status")==true) {
	Description to valueOf(Description)
	Status to valueOf("Status")
	SpecificationDescription to Specification.valueOf("Description")
}
map to type "Functional Requirement" if (isNotSet("Status")== true) {
	Description to valueOf(Description)
	Status to "(unknown)"
	SpecificationDescription to Specification.valueOf("Description")
}

Let us assume that we want to identify artifacts for any specification objects of type Functional Requirement. We can express this by writing map to type "Functional Requirement". If we additionally want to restrict these functional requirements to those that don’t have the status „REJECTED”, we can do this by adding the condition if (valueOf("Status") != "REJECTED"). By adding and isSet("Status")==true to the if condition, we can exclude those requirements that have no known status. Combining these three conditions, we get the second line of the example above.

In general, the keyword map introduces a set of conditions for specification objects. If a specification object fulfills these conditions, it will be identified as an artifact. The to type keyword simply excludes all specification objects that don’t have the type with the indicated name. The if keyword opens a boolean expression that must evaluate to true for a given specification object to fulfill the constraint. Via valueOf, we can access the value of a specification object’s attribute, like Status in the above example. The keyword isSet allows us to check whether a given attribute has any value at all.

Now we want the artifacts identified for functional requirements to have names that consist of the respective requirement’s ID and its title. We can define this by adding name valueOf(ID) + "-" + valueOf(Title) to the top of the configuration. Here, a minus character is used to separate ID and title.

If we want to assign attribute values of functional requirements to custom attributes of the corresponding artifacts, we can do this in a separate block of statements, included between curly braces ( {, }) and appended to the map statement.

Let’s say we want to assign the values of the Description and Status attributes to custom attributes of the same name. We can do this by using the statements Description to valueOf(Description) and Status to valueOf("Status").

In ReqIF, specifications can be used to structure specification objects hierarchically. Like specification objects, specifications have their own sets of attributes. We can access these attributes by using the command Specification.valueOf instead of valueOf. Please note that this always refers to the specification of the specification object that valueOf refers to. We now want to assign the Description attribute of this specification to the variable SpecificationDescription. We can do this using the expression SpecificationDescription to Specification.valueOf("Description").

In conclusion, these variable assignments make up the following block, which completes the first map statement in the example above:

{
 	Description to valueOf("Description")
	Status to valueOf("Status")
	SpecificationDescription to Specification.valueOf("Description")
}

Now we also want to consider functional requirements that have an undefined status. We could include them by removing the condition isSet("Status")==true. However, here we also want to assign a special value to the custom attribute Status. Usually we would get an empty string for the undefined value, but instead we want the string to be „(unknown)”. We can do this by adding a second map statement with the condition isNotSet("Status")== true. The keyword isNotSet is true whenever an attribute is not set, i.e., isNotSet is the opposite of isSet. We will now identify an artifact for a specification object if it fulfills the conditions of either of the two map statements. However, we assign different attribute values depending on which one matches.

Configuration keywords

The ProR artifact type configuration supports the following keywords:

  • if( constr) – Defines a constraint to filter specification objects by attributes. Artifacts will only be created for those specification objects for which constr evaluates to true. The latter is a boolean expression that consists of either a single comparison or of several comparisons, combined by the boolean operators and or or. The left-hand side of the comparison is a string expression that may include the keywords isNotSet, isSet, Specification.valueOf or valueOf. The right-hand side is always a static string. You may choose between the comparison operators == (checks for equality), != (checks for inequality) and contains. The latter checks for an occurrence of the string on the right-hand side within the string computed for the left-hand side.
  • isNotSet( attr) – Evaluates to the negation of isSet( attr) (see there).
  • isSet( attr) – Evaluates to true if the attribute attr of the „current” specification object is set. Otherwise it evaluates to false. See below for what the „current” specification object is.
  • map constraints – Starts a block associated with constraints defined by the expression constraints. These constraints select the specification objects for which to identify artifacts. Within the block, you can assign custom attributes of artifacts identified for this block. The expression constraints may be empty, in which case all specification objects in the configured resources will match. Otherwise, the expression can consist of one of the keywords to type, if or both (see there). An artifact is identified if it matches all constraints of the block. Within the optional block in curly braces following map, you can map attributes of specification objects to custom attributes of matching artifacts. For each attribute, it contains an expression of the form attribute to expression, where attribute is the custom attribute’s name and expression defines how the assigned value is computed.
  • name expr – Specifies the name of the artifact as the value the expression expr evaluates to. By default, the artifact name is equal to the identifier of the corresponding specification object.
  • Specification.valueOf( attr) – Evaluates to the value of a specification attribute with the name attr. The expression always relates to the specification that contains the „current” (see below) specification object. If more than one specification contains the current object, the expression refers to the first one in the list.
  • to type type – Defines a constraint to filter specification objects by type. Artifacts will only be created for those specification objects which are of type type.
  • valueOf( attr) – Evaluates to the value of a specification object’s attribute with the name attr. The expression always relates to the „current” (see below) specification object.

The keywords isNotSet, isSet, Specification.valueOf and valueOf refer to the „current” specification object. In case of the if expression, this is the specification object that is currently being checked for whether it should be identified as an artifact or not. Otherwise (attribute assignment, name expression) the „current” specification object is one that has already been qualified as a traceable artifact.

The configuration may include one or several map statements – or none at all. If no map statement is specified, all specification objects will be identified as artifacts. The same is true if one of the map statements has no constraints. In case of several map statements, an artifact will be created for a given specification object if it fulfills the constraints of any statement.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

Eclipse Sample Reflective Ecore Model Editor (SREME)

Artifact type

Configuration

Supported options:

  • resource – File filter pattern.

Example:

resource *.uxf

The above example specifies EMF elements from files with the extension .uxf.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version. This is due to an adapter bug (YT-3430).

Eclipse UML2

The UML2 adapter identifies elements of UML models as traceable artifacts. UML models are configured as UML2 data access. UML elements are identified based on their metatypes, their assigned stereotypes, or their namespaces. For example, you might want to recognize only artifacts of type Class with stereotype «SafetyRelevant» that are in the safety package.

This adapter supports selection propagation: If you select an element in YT, the selected artifact will be opened in Eclipse’s UML model editor, and if you select an element in the UML model editor, it will be opened in YT.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select UML2 as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource *.uml

This configuration specifies that YT should load all files residing in the workspace whose filename extension is .uml.

Please note that this adapter supports files with .uml filename extension only.

Artifact type

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Eclipse UML2 data access in the Data access drop-down list.

Example:

name valueOf("qualifiedName") 
subset namespace model
subset metatype uml.Operation
subset metatype uml.Class
map {
	attr to valueOf("isLeaf")
}

This example shows an artifact type configuration for the UML2 adapter. It provides all classes and operations in the model namespace that are residing in the uml package. Extracted artifacts are named according to their respective qualifiedName attribute. The custom attribute attr is mapped to the value of the isLeaf attribute of the matched element.

Keywords

The Eclipse UML2 artifact type configuration supports the following keywords:

  • name expr – Specifies the name of the artifact as the value of the expression expr. By default, this is the FQN, if defined. Otherwise, the element’s URI is used.
  • subset namespace – Filters elements by namespace.
  • subset metatype – Filters elements by metaclass.
  • subset stereotype – Filters elements by stereotype.
  • map – Maps artifact properties to custom attributes. For each attribute, this clause contains an expression of the form attribute to expression, where attribute is the attribute name, and expression defines how the assigned value is computed.
  • valueOf( elem) – Retrieves the value of the specified attribute elem for the current element. The attribute can be the name of any parameter defined for this element. The Name attribute is predefined and returns the name of the element. However, the configuration may specify any other value.

Content assist will show you a list of available stereotypes and metatypes, where appropriate. Place the text cursor right from subset metatype or subset stereotype, leave at least one space, and press [Ctrl]+[Space].

Please note that the configuration supports using the same keyword multiple times. For example, the expressions subset metatype uml.Class and subset metatype uml.Operation in the same configuration means "all Class or Operation elements in the uml package".

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is the URI of the element.

Relationships within a UML model can be interpreted directly as trace links. YT derives trace links based on UML relationships and their navigability.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select an UML2 artifact type with Eclipse UML as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • As data access, select the very same UML2 data access that has already been assigned to the artifact types A and B.

Mapping example:

subset metatype uml.Association
subset metatype uml.DirectedRelationship
map {
	attr to valueOf("Navigable")
}

This example shows a link type configuration for the UML2 adapter. It extracts all Association and DirectedRelationship elements that are residing in package uml as trace links. The custom attribute attr of these links is mapped to the value of the Navigable attribute of the matched element.

The Eclipse UML2 link type configuration supports the following keywords:

  • subset metatype – Filters links by their metatype.
  • map – Maps link properties to custom attributes. For each attribute, this clause contains an expression of the form attribute to expression, where attribute is the attribute name and expression defines how the assigned value is computed.
  • valueOf( elem) – Retrieves the value of the specified attribute elem for the current element. The attribute can be the name of any parameter defined for this element. The Name attribute is predefined and returns the name of the element. However, the configuration may specify any other value.

Content assist will show you a list of available metatypes, where appropriate. Place the text cursor right from subset metatype, leave at least one space, and press [Ctrl]+[Space].

Please note that the configuration supports using the same keyword multiple times. For example, the expressions subset metatype uml.Association and subset metatype uml.DirectedRelationship in the same configuration means "all Association or DirectedRelationship in package uml.

A link’s version is used for suspicious links validation. The version of a UML2 link contains the relationship’s URI in the UML model, but we have to differentiate between two cases:

  • In the UML model, there’s a bidirectional or undirected relationship between elements E1 and E2. In this case, YT derives two trace links from the UML relationship: one from E1 to E2 and a second one from E2 to E1. Using the UML relationship’s URI as the version of both trace links would be ambiguous. In order to avoid that, the trace link’s version evaluates to the string concatenation of the relationship’s URI and the respective source element’s URI.
  • In the UML model, there’s a unidirectional relationship from element E1 to E2. In this case, the UML relationship’s URI would be unambiguous as the trace link’s version. However, in order to be consistent with the first case, the trace link’s version here also evaluates to the string concatenation of the relationship’s URI and the source element’s URI.

Eclipse Xtext

The Xtext adapter identifies elements of Xtext documents as traceable artifacts. The adapter can be configured based on the grammar rules of a domain-specific language (DSL) that has been defined with Xtext. The adapter propagates selected artifacts to and from Xtext files using the DSL-specific editor generated by Xtext.

Xtext allows for defining grammars for textual domain-specific languages (DSL) . In this section, the following definitions apply:

  • If D is a DSL defined by Xtext, a D document is a textual document that conforms to the grammar rules of language D.
  • An Xtext document is a textual document that conforms to any of the languages defined by Xtext. For example, if A, B, and C are DSLs defined by Xtext, A documents, B documents, and C documents are jointly called Xtext documents. Typically, when we are talking about Xtext documents, we are talking about general principles pertaining to all Xtext-defined languages, not about the peculiarities of a specific DSL.
  • An Xtext document element is a syntactical unit of an Xtext document, as defined by the grammar rules of the particular Xtext language. An Xtext document element might simply be called document element or element, as long as the context is unambiguous.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Xtext files as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource A*.entity
resource *b.entity

These configuration rules specify that YT should load Xtext documents from files whose filenames – disregarding filename extensions – start with the letter A or end with the letter b, and whose filename extension is .entity.

Please note that the filename extension is mandatory. The Xtext adapter will only work if the Xtext grammar can be inferred from the filename extension. If you want to configure different several file filters for the same data access, all of them must have the same filename extension. Then again, if you want to trace artifacts of several different DSLs, you will have to define a separate data access for each Xtext grammar.

Artifact type

The Xtext artifact type identifies Xtext document elements as artifacts. These elements are identified based on which Xtext grammar rules they correspond to. Every document element corresponds to at least one rule that defines the context in which the element may occur.

Assume, for example, that your DSL D contains the following rules R, R1 and R2:

R: R1 | R2;

R1: 'X' x=STRING;

R2: 'Y' y=STRING;

If YT is configured to identify artifacts matching the rule R1, it will identify a document element X "text" as an artifact. If it is configured for R2, it will instead identify Y "text" as artifact. YT will recognize both as artifacts if it is configured for R, because it references R1 and R2 in unassigned rule calls (please refer to the Xtext documentation for this special Xtext construct).

For each rule of the Xtext grammar you want to derive document elements as artifacts from, you can define how the artifact name and the values of custom attributes should be computed. In both cases, you can specify expressions that refer to assignments, e.g., x=STRING in case of rule R in the sample grammar above. These assignments correspond to attributes or refer to document elements. For example, given the document element artifact X "text", matching the rule R1: 'X' x=STRING;, the value of attribute x is "text").

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Xtext data access in the Data access drop-down list.

We will introduce the configuration language, including its syntax, by using an extensive example. You can find the complete list of keywords following the example.

A sample Xtext grammar

Let’s consider the following two rules of the (actually much larger) Xtext grammar for the YT query language:

Query:
	('query' name = STRING)?
	('description' description = STRING)?
	source=QSource
	collect=QCollect?
	where=QWhere?
	groupBy=QGroupBy?
	orderBy=QOrderBy?
;

QCollect:
	{QCollect}
	'.' 'collect' '(' features+=QFeatureSelectionWithAggregation (',' features+=QFeatureSelectionWithAggregation)* ')'
;

In this sample grammar, the rule Query represents a query. It references – among other things – the rule QCollect, which represents the optional collect statement. For this example, let’s consider the case that we want to examine query files and identify individual queries within them as artifacts.

We are using the following query file, comprising two queries, as a sample document of this grammar:

query "name" description "description of the query"
 source(someQueryFunction(parameter1, parameter2))
 .collect(attribute1 as A1, @sum(attribute2) as A2)
 .groupBy(attribute1)
 .orderBy(A2)

query "Requirements covered by test cases"
    source(tracesFromTo('Requirement', 'TestCase'))
    .collect(Start.DataSource.Identifier as FileName, Start.Name as ID)

The first steps are to

  • define a data access definition for the query files,
  • create an artifact type, and
  • assign the data access definition to it.

Here we want to search for queries in all files with the filename extension .query. This leads us to the following simple data access configuration:

*.query
Identifying artifacts by grammar rule

Next, we need to create a mapping and configure it. The following mapping configuration for an Xtext artifact type derives artifacts for the rule Query. In case of the query file above, two artifacts will be derived, one for each query. The configuration will be explained in more detail below.

rule Query {
    name "Query "+fqnOf(this)
    map {
        description to valueOf(description)
        collectedFeatures to valueOf(collect.features) joined with separator " / "
        startLine to startLineOf(this)
        endLine to endLineOf(this)
    }
}

The rule statement can refer to any rule defined by the grammar. In the example, it references the Query rule of the query grammar, however, it could for instance also reference the QCollect or the QSource rule. Press [Ctrl]+[Space] after rule to have the content assist propose all available grammar rules.

Let us assume that we require all artifacts to be named in a specific way. Furthermore, we need to extract some additional properties from each query and map them to the custom attributes of the corresponding artifact. We can specify the artifact name and the attribute mappings in the block within braces, following rule Query. Both, the mappings and the name definition, are optional. For this example, however, we need both.

While this example includes a single rule statement only, in general an Xtext artifact type configuration may contain several of them. This way, artifacts for different rules can be identified within the same configuration. Each of them has its own block with its own mappings that are specific to the corresponding rule. Note that there is only one set of custom attributes for each artifact type. Hence, all of an attribute type configuration’s rule blocks are sharing these attributes. Custom attributes, for which there is no mapping in a given block, will remain empty for all artifacts identified by its rule.

For this example, we want each artifact’s name to start with the character string „Query ”, followed by the fully-qualified name (FQN) of the corresponding query. We define this by using a name statement that appends the result of fqnOf(this) to the above-mentioned string. Here, this references the current query, and the function fqnOf(this) yields its FQN. The content assist proposals for the parameters of fqnOf also include all attributes of a query. These are defined by the assignments within the Query grammar rule, e.g., name, description, or source. For the sample query file above, the names of the derived artifacts are „Query name” and „Query Requirements covered by test cases”, because in this case the FQN is equivalent to the value of the attribute name.

Mapping document properties to artifact attributes

Now let’s consider mapping certain properties of each query to custom attributes of the artifact derived from it. We can do this similarly to many other artifact types: by using a map block. The following paragraph describes the individual properties and the mappings that we need for them.

First, we want to extract the description of the query, as defined by the description assignment in the grammar rule, and map it to a custom attribute of the same name. We do this in the first line of the map block by assigning valueOf(description) to the description attribute. Since description is not a document element that has nested children, the valueOf operator returns a string representation of the query’s description attribute value. In this case, however, the attribute type is STRING, which means that the attribute value is already a character string. For the sample query file, the first description is empty and the second is „description of the query”.

Next, we want to determine the list of features contained in the query’s collect statement and assign a string representation of this list to the custom attribute collectedFeatures. As you can see in the corresponding second line of the map block, there are several differences between this case and the above-mentioned mapping for description. We will discuss them in detail below.

Instead of directly reading an attribute of the current query, we need to access the features attribute of the query’s collect statement. It is defined by assignments to features in the QCollect rule. We can access this attribute using the expression collect.features. This expression first references the query attribute collect, which is an instance of QCollect, and then traverses to the features attribute, which contains a list of features. Then, the valueOf operator is applied to the features attribute in order to provide a character string.

As we just pointed out and contrary to description above, the features attribute is a list. Hence, valueOf determines a string for each element of this list and concatenates these strings. We want the list elements to be separated by the string " / " and achieve this by using the expression joined with separator " / ".

Each element of the list features is an instance of QFeatureSelectionWithAggregation, which is also defined in the query grammar, but not shown in the excerpt above. In the sample query document there are document elements matching the QFeatureSelectionWithAggregation rule. Here valueOf will not create a string based on the attribute value (i.e., the document element), but will instead yield the text representation of the document element within the query document. These texts will be concatenated as explained above.

In the sample query document, this works as follows. The collect statements we are going to process are:

  • collect(attribute1 as A1, @sum(attribute2) as A2)
  • collect(Start.DataSource.Identifier as FileName, Start.Name as ID)

The relevant expression in the artifact type configuration is:

  • valueOf(collect.features) joined with separator " / "

Applying this configuration, the collectedFeatures attributes of the query artifacts in the sample document have to following values:

  • attribute1 as A1 / @sum(attribute2) as A2
  • Start.DataSource.Identifier as FileName / Start.Name as ID

Finally, we also want to know the numbers of the first and the last lines of the queries, respectively, within the query document. The last two statements of the map block assign these line numbers to corresponding custom attributes. The keywords startLineOf and endLineOf find the first and the last line, respectively, of the document element given as their respective parameter. We again use the keyword this to refer to the query object itself. For the sample query document, the line numbers assigned are 1 and 5 for the first query and 7 and 9 for the second one.

Configuration keywords

The Xtext artifact type configuration supports the following keywords:

  • endLineOf( elem) – Refers to the last line of the textual representation of an element within an Xtext document. The document element is addressed by the parameter elem as explained below.
  • fqnOf( elem) – Refers to the fully-qualified name (FQN) of a document element. The document element is addressed by the parameter elem as explained below.
  • joined with separator sep – Follows one of the ...Of expressions and allows to join (concatenate) the elements of a list into a single string, separated by the specified separator sep. Without this keyword, the separator ", " will be used. Document elements are part of a list if they correspond to assignments of the form variable += expression in the Xtext grammar. Here variable is the list and its elements are determined by expression.
  • map – Maps artifact properties to custom attributes. For each attribute it contains an expression of the form attribute to expression, where attribute is the attribute name and expression defines how the assigned value is computed.
  • name expr – Specifies the name of the artifact as the value the expression expr evaluates to. By default, the FQN is used, if defined. Otherwise, the fragment of the element’s URI is used. The fragment identifies the element locally within the document. In case of the queries example above, the fragment of the second feature in the collect statement of the first query would be „//@queries.0/@collect/@features.1”.
  • rule rulename – The Xtext rule, identified by rulename, for which document elements should be identified as artifacts (see above for examples). You can configure YT to derive elements for rules of the Xtext grammar that you have configured using the Xtext data access. Additionally, you can also refer to rules inherited from other Xtext grammars.
  • startLineOf( elem) – Refers to the first line of the textual representation of a document element. The document element is addressed by the parameter elem as explained below.
  • this – Refers to the current document element, which corresponds to the Xtext rule referenced by the rule block in which this is used. YT evaluates the rule block for every such element to create an artifact for it. In a given evaluation, this refers to the element that is considered in that evaluation. For example, in rule R { name valueOf(this) }, the keyword this can be any document element corresponding to the Xtext rule R.
  • valueOf( elem) – Refers to the textual representation of a document element. The document element is addressed by the parameter elem as explained below. If the attribute is a plain type, e.g., a string or number, or if it is defined externally to the document, e.g., in a document of another language, the object’s string value will be used.
The elem parameter

The keywords valueOf, fqnOf, startLineOf, and endLineOf each have one parameter that denotes a document element. It can be this to reference the document element that is matching the current grammar rule. Alternatively, it can be an object navigational expression of the form object_1. object_2.. object_n. object , where object_1 is an attribute of this, object_2 is an attribute of object_1 and so on.

If the last object is a list, the respective keyword will be applied to each element individually, and the results will be concatenated by ", " or as indicated by joined with separator. For example, a list ("one", "two", "three") would be concatenated to "one.two.three" when using "." as a separator.

In case of valueOf, the final object can be any object, while the other …Of keywords only work for document elements (or lists of document elements) and will otherwise evaluate to an empty string. The keyword fqnOf only works for document elements that actually have an FQN. The other keywords only work for elements defined in the Xtext document.

Content assist supports you in the selection of Xtext rules. Its proposals are based on the Xtext grammar of the language that is configured for the respective data access. You can also use content assist to select attributes or references within valueOf. The proposals include attributes and references that are defined by any of the assignments defined for the given Xtext rule. For example, if the rule contains x=STRING and y=STRING, then the proposals contain x and y. If these assignments also correspond to further rules, you can recursively navigate through the assignments by chaining them with the dot operator ( .).

Referencing elements from external languages and models

Please note that the content assist’s proposals won’t include attributes or references of other Xtext grammars, except for those that are inherited from Xtext grammars which are (directly or indirectly) included using the Xtext keyword „with”. Content assist for other EMF models – see Eclipse Modeling Framework – will only work if the configured Xtext grammar references elements of a specific type defined in the EMF model.

If there is no content assist for certain attributes or references you can reference them by manually typing their respective names without the help of the content assist. For example, if you know that an attribute object of type SuperType always contains an object of type SubType and that this type defines an attribute called name, then you can access this attribute by object."name". The quotation marks are needed here, because name is a keyword.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Enterprise Architect

The YT adapter for Enterprise Architect provides access to UML elements as traceable artifacts. More than that, it is possible to derive trace links from UML relations.

Please note: Out of the box, Enterprise Architect doesn’t provide an interface for interprocess communication. To enable selection propagation from Enterprise Architect to YAKINDU Traceability, YT ships an EA plugin which is described below.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Enterprise Architect as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders, or file name patterns describing the .eap files relevant for traceability.

Supported keywords:

  • resource – A pattern for a project, folder, or file in the workspace.

The configuration may contain several resource definitions.

Example:

In this example, YT takes all .eap files residing in project com.yakindu.yt.mt.spec, folder design into account.

Enterprise Architect plugin for selection propagation

Installing the EA plugin

In order to receive notifications about selection changes from Enterprise Architect, YT ships a plugin for Enterprise Architect. Please note that for Enterprise Architect version 10 or lower, there is a restriction preventing selection propagation for .eap files that actually reference a database.

To install this plugin, proceed as follows:

  • In a file explorer, navigate to folder /traceability/scripts/ea.
  • Run the script installAddInForEA.bat with administrator privileges.

Configuring the EA plugin

The EA plugin propagates selections from EA to YT via a TCP socket connection. To establish a socket connection, the same port has to be configured in both YT and EA.

YT:

Select Window → Preferences → YAKINDU Traceability from the main menu. Make sure the TCP Server is enabled. Configure a port number; the default is 1234.

EA:

Select Extensions → Yakindu Traceability → Configure Socket connection from the main menu, then set the port number.

Artifact type

The Enterprise Architect artifact type provides access to the elements of those EA models that are specified in the Enterprise Architect Data access.

It is possible to restrict the number of UML elements that are visible to YT based on their meta-type, their assigned stereotypes, or their namespace. You may want to see, e.g., only artifacts of type Class with the stereotype <<SafetyRelevant>> in the package safety.

This adapter supports opening the artifact in EA and showing the currently selected artifact in YT.

If Enterprise Architect is not available, it is also possible to open an EAP file with the Eclipse UML2 editor. However, the UML2 model does not support all available Enterprise Architect features. If an element is not available in the UML2 model the artifact cannot be accessed without a native Enterprise Architect instance.

If the checkbox Show artifacts within Enterprise Architect on the preferences page YAKINDU Traceability → Customization is checked, YT will open Enterprise Architect artifacts within Enterprise Architect. If that checkbox is unchecked, YT will open the artifact in the last editor you used to open an Enterprise Architect file. Selecting the artifact in an editor will work only if that editor is an Eclipse tree editor like the UML2 editor.

Currently, there is an issue regarding the selection of Enterprise Architect artifacts within the UML2 editor when error markers created by the YAKINDU EA Bridge exist for the file. In this case the selection can take very long and can fail if the editor is already open. You can prevent the YAKINDU EA Bridge from creating these markers via an option in the workspace preferences: On page YAKINDU EA-Bridge, uncheck the checkbox "Report loading errors as Resource markers for the eap-file". Now loading errors will still be shown in the editor’s Problems tab, but no markers will be created. Please note that this will not remove already existing markers.

Additionally, if such errors exist and if the UML2 editor is used to open EA artifacts, the editor will by default open on the Problems tab. This is the default behavior of the UML2 editor, but it may be confusing since it may look as if the file has failed to load. However, in order to properly display the model, you can manually switch to the editor’s Selection tab.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Enterprise Architect data access in the Data access drop-down list.

Supported keywords:

  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter
  • map – Attribute mappings for custom attributes.

A list of available stereotypes and metatypes can be opened by content assist. Move the text cursor to the right of the metatype, leave at least one space, and press [Ctrl]+[Space].

While a stereotype definition requires the fully-qualified name (i.e., including the profile as shown in the example below), a simple name is sufficient for the metatype definition. When using the namespace filter, the individual names in a namespace hierarchy can be delimited either by ., as shown below, or by ::. The second variant is mandatory if any name in the fully-qualified name contains a ..

Note that the configuration supports multiple usages of the same keyword. For example, using the expressions subset metatype Class and subset metatype State in the same configuration means „Class or State”.

The Enterprise Architect adapter supports mapping of artifact attributes to tagged values in Enterprise Architect. For instance, the expression map attr1 to valueOf(tagKey1) maps the attribute attr1 to the value of the tagged value with the tag tagKey1.

Example

The image above shows a configuration for the Example Model shipped with Enterprise Architect. It provides all classes with stereotype <<ERD_Entity>> and/or <<ERD_Attribute>>, residing in package Domain Specific Modeling of project Project Models.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The trace links YT derives from an Enterprise Architect model are based on the Enterprise Architect data access and the Enterprise Architect artifact types configured for the Enterprise Architect adapter. The meta class and stereotype relations in the EA Model are available for mappings.

YT can derive trace links from an Enterprise Architect model in two ways. First, UML relations within the model can directly be interpreted as trace links. Second, trace links can be derived in cases where connected elements (e.g., requirements) of some element A reference other elements B within their tagged values. In this case, trace links from A to B can be inferred.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select an Enterprise Architect artifact type with Enterprise Architect as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • As data access, select the very same Enterprise Architect data access that has already been assigned to the artifact types A and B.

For each mapping configuration only one of the two ways mentioned above for deriving trace links can be used. Since both cases are configured very differently, the following description considers them separately.

Supported options:

  • subset metatype – Meta-type filter
  • subset stereotype – Stereotype filter
  • link source is A|B – Optionally specifies whether the link source in EA should be artifact A or artifact B of the link type. By default it is A, which means that a link in EA from an element X to an element Y will result in a link in YT from A to B. If you define the link source to be B, the same link in EA from X to Y will result in a link in YT from B to A.

A list of available metatypes and stereotypes can be displayed by content assist (pressing [Ctrl]+[Space] right from the space right from the metatype). The list of subsets is grouped by the subset type ( metatype and stereotype) and for each present group at least one subset has to match.

Example:

In this example, YT derives a trace link from each UML association existing in the EA model between artifacts that had been specified by type EA artifacts. Refer to this example for the Enterprise Architect artifact type to see how this type is specified.

Since the example configuration does not contain link source is ..., the default is assumed, which is link source is A. Therefore, the source of the association in EA will be artifact A of the link in YT and the target will be artifact B. If instead B was specified as link source, the source of the association would be B and the target would be A.

Supported options:

  • link where … – Defines which conditions must be fulfilled to derive trace links from the tagged values of connected elements.
  • has – Specifies which type of Enterprise Architect connector should be considered for deriving trace links.
  • to – Specifies to which type of Enterprise Architect element connectors must lead to be considered for deriving trace links.
  • with – Specifies which value the tagged value of a connected element must have such that a trace link can be derived.
  • create – Can be used to specify options for creating new links.
  • in – Specifies the package in which new Enterprise Architect elements representing new links should be created.
  • with name = – Specifies the name of newly-created Enterprise Architect elements that represent new links.
  • map – Defines a list of mappings allowing to store attribute values of linked artifacts in Enterprise Architect elements (see below).
  • … based on … to … – Defines a mapping from the values of custom attributes of B or A to a tagged value or an attribute of the Enterprise Architect element that represents the linked artifact in Enterprise Architect. Between based on and to, the string to store in Enterprise Architect can be formed by concatenating attribute values of A or B and static strings. The resulting string will be stored in a tagged value or attribute that can be defined in the to clause by using the keywords valueOf or attribute. The attribute value will be stored in the specified location when creating or updating the link. Left from based on, a custom string attribute of the configured Enterprise Architect link type must be specified. When reading a link from Enterprise Architect, this custom attribute will be set to the value that is read from the location specified in the to clause. When creating or updating a link, the custom attribute will be set to the value of the specified custom attribute of an artifact.
  • valueOf – Allows to specify the tagged value to store the specified string in.
  • attribute – Allows to specify the Enterprise Architect property to store the specified string in. The supported properties depend on the type of Enterprise Architect element that has been selected in the link expression after to. All target elements support Name, Notes and Alias. Furthermore, all elements except Operation and Attribute support Status, Author, Version, Keywords and Phase. Finally, if Requirement is selected, also Difficulty and Priority are available. Note that EA might not allow to set some properties to arbitrary strings, but only to certain values that are selectable in EA via a drop-down list. Other values are ignored for these properties.
  • join {…, …} using … – Can be used to create a composed string by concatenating several other strings with the string provided after using. The strings to concatenate are passed as a comma-separated list within the curly brackets. They can be complex strings concatenated by +, including references to artifact attributes. If any of these expressions evaluates to an empty string (usually because a referenced attribute is empty or undefined) it is ignored. The string after using must be a simple string.

The configuration for this type of configuration always begins with:

link where role has connector_type to element_type with valueOf( tag) = filter

Here, role (can be A or B) defines which of the link type’s artifact type should be considered for connected elements.

YT searches the EA model for connections with the EA connector type connector_type that lead from any EA element that is an artifact of the selected artifact type role to EA elements of element type element_type.

For all of the latter EA elements, YT checks whether the value of the tag tag is equivalent to filter. Typically, filter refers to the link type’s other artifact type. YT creates a trace link from the currently considered artifact of role to all artifacts of the second artifact type for which filter equals tag.

The expression filter is a concatenation of static strings and (meta) attributes of the link type’s second artifact type. This second artifact type is B if role is A, and vice versa. You can access an attribute attr of an artifact type B by using B.attr, the identifier of B by using B.metadata(Identifier), and the resource of B with B.metadata(Resource).

You can display a list of available meta types for connectors or elements by content assist (pressing [Ctrl]+[Space] right from the space right from has or to, respectively). Content assist right from valueOf( will provide a list of all tags of elements in the EA model. Content assist right from attribute( will provide a list of all attributes that are supported for writing.

In YT Editor, you can manually create links from EA elements to other artifacts. These will be stored in EA in the same form as described above, i.e., as a connection to an EA element with a tagged value that references the other artifact. Whenever a new link to an artifact needs to be created, YT first searches for an existing EA element that refers to the artifact via a tagged value in the form defined in the configuration. If such an element already exists, YT only creates a connection to it – starting from the EA element that is to be linked to the artifact. Otherwise, YT also creates a new EA element with a suitable tagged value, which will then be the target of the connection.

When creating a new EA element with a tagged value to reference another artifact, YT by default creates this EA element in the same package as the EA element to be linked. The name of the new EA element will be the same as the name of the referenced artifact. Both, the name of the new element and the package, can optionally be defined explicitly in the configuration. The general form of the configuration is the same as described above, followed by , create in package with name = element_name . Here, package is the package in EA (using :: as separator) to create the new element in. The expression element_name is the name of the EA element to create. It can be defined in the same syntax as the expression filter described above. Alternatively, the name can be defined by mapping the attribute „Name”. In this case, the name (like other mapped attributes or tagged values) will be updated when the link is updated or a new link is created to the element.

You can display a list of available packages to store new EA elements by content assist (pressing [Ctrl]+[Space] right from the space right from create in. You can also specify a new package that does not yet exist. If you do, YT will ask you whether it should create that package in EA.

Example:

In this example, YT considers for each EA artifact A of artifact type A all outgoing connectors of type Realisation that lead to a Requirement. It derives a trace link for each of these requirements with a tagged value Object Identifier that is equivalent to the expression B.ObjectIdentifier. In this case, the expression only consists of one attribute of B. If a new link is created in YT, YT will first search for an existing Requirement with a tagged value equivalent to the attribute ObjectIdentifier of the target artifact. If such a Requirement is found anywhere in the model, YT will create a Realisation connection from the EA artifact to be linked to that Requirement. Otherwise, YT will create a new Requirement in the package Project Models::Analysis and Business Modeling with a suitable tagged value Object Identifier.

The map specifies that several attributes of B are to be mapped to attributes and tagged values of the target requirement. The property Name of the new requirement will be created by composing the values of the three attributes number, heading, and ObjectIdentifier of B, separated by the static string " - ". The join keyword ensures that empty attributes are ignored in this concatenation and no superfluous " - " delimiters are inserted. The result is mapped to the link attribute Name. The property Notes of the requirement will be determined by the value of the custom attribute B.text, which is also mapped to the link attribute Description. The property Alias is mapped in a similar way. Finally, two tagged values, Variant and Created By, are set based on attributes of B.

Suspicious links validation is done by re-evaluating the link’s custom attributes and comparing these values to those stored in the link. If there are any differences, the link is suspicious.

Please note:

Enterprise Architect maintains internal and external links. For suspicious links validation, only external links are taken into account.

IBM DOORS

The IBM DOORS adapter allows to extract objects, modules and projects from a running 9.x IBM DOORS client and provides means to propagate selections in both directions.

To decrease loading time, the adapter allows to operate on cached data. The cache is either valid until the configuration (see below) changes or until the user manually invalidates the cache. There is also the possibility to automatically invalidate the cache on YT startup by means of a custom preference. Navigate to Window → Preferences → YAKINDU Traceability → Customization. Check Always reload Doors artifacts on startup? to invalidate the cache automatically.

Data access

The IBM DOORS data access allows for a flexible configuration to exactly specify which artifacts YAKINDU Traceability should import from the IBM DOORS database.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select IBM DOORS as data access type.

The configuration panel allows to define which native IBM DOORS projects and baselines should be fetched. The configuration language offers content assist to guide through the different options. At least one project must be supplied.

Supported keywords:

  • baselineSet – Defines the „Baseline Set” that should be loaded.
  • baselineSetDefinition – Defines the „Baseline Set Definition” that should be loaded.
  • project – Defines a single project to be imported.
  • projects – Defines a path to multiple projects. Or define a white list by adding in.
  • in - Starts a white list of project names.
  • undefined attribute value – Defines a string-type value for attributes that are undefined in DOORS database.

Sample configuration for a single project :

project "/MY_PROJECT" {
    baselineSetDefinition "MY_BASELINE_SET_DEFINITION" {
        baselineSet "3.0 (MY_SUFFIX)"
    }
}
undefined attribute value = "MY_UNDEFINED_VALUE"

The example above will include the content of „/MY_PROJECT” which is present in baseline set „3.0 (MY_SUFFIX)” which is defined in baseline set definition „MY_BASELINE_SET_DEFINITION”. When the baseline set definition block is omitted, the current version of „/MY_PROJECT” is provided. In case an artifact configuration includes an attribute that is not defined in DOORS, the value „MY_UNDEFINED_VALUE” is assigned.

Sample configuration for multiple projects :

projects "/YT/*/IMPORTANT/*_PROJECT" 
undefined attribute value = "MY_UNDEFINED_VALUE"
projects in ("/PROJECT_A" "/PROJECT_B") 

The first example above will include all projects that are located in a path that starts with „/YT/”, also includes a „/IMPORTANT/” folder and matches the pattern „*_PROJECT”. For example, „/YT/REQUIREMENTS/IMPORTANT/MY_PROJECT” would be an acceptable match. Note that when defining a path instead of a single project, it is not possible to specify a baseline. The version will always be the current. The „undefined attribute value” will behave the same as in the example above.

The second example will consider all projects contained in the explicitly given list, the so-called white list. In this case the white list consists of „/PROJECT_A” and „/PROJECT_B”.

Caching

As reading data from DOORS might be a time-consuming task, YT persists native DOORS data locally and thus avoids repeated fetching these data, especially after restarts. The native data is persisted within a folder named DOORSResponseCache within the workspace folder that is currently used by your running YT instance.

Invalidating the cached data can be done by using the toolbar action Update DOORS data.

In certain situations it might be useful to share the data between team members to ensure everybody is working on the same basis. If needed, this can easily be done by creating a new project within the location of the cache folder.

  • Goto New → Project…, General → Project, and click Next.
  • Choose a project name, e.g., DOORSResponseCache
  • Uncheck use default location.
  • Click on Browse.
  • Choose the cache folder DOORSResponseCache within your current workspace’s root folder.
  • Click Finish.

If everything is fine there should be a new project available in your project explorer which looks similar to the project shown in the following screenshot:

The newly-created project can be shared afterwards via Eclipse’s team functionalities.

Artifact type

The IBM DOORS adapter allows for flexible artifact configuration to specify which artifacts YAKINDU Traceability should import from the IBM DOORS data access. It also allows to define custom attributes and to map them to native DOORS module and object attributes.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured IBM DOORS data access in the Data access drop-down list.

The configuration panel allows to define which native IBM DOORS artifacts should be included, based on their type and attributes. YT artifacts can either be native DOORS projects, modules or objects. The configuration language offers content assist to guide through the different options. In case no explicit configuration is supplied, all artifacts for the type in the scope of the data access are included. If no type is specified ‚Objects’ is assumed.

Supported keywords:

  • != – „Not equals” operator to use within a condition
  • == – „Equals” operator to use within a condition
  • artifact type – Optional definition of the artifact type. Possible values are Module | Project. If not specified Object is assumed.
  • contains – Constraint for substring check
  • in – „In” operator to use within a condition
  • include [projects|modules|objects] if – Starts an include expression. Artifacts will be included if they satisfy the conditions within the expression.
    • projects – Specifies that the following conditions are evaluated on project level.
    • modules – Specifies that the following conditions are evaluated on module level.
    • objects – Specifies that the following conditions are evaluated on object level.
  • map – Starts a mapping block.
  • Module – Allows to access the parent module of an object for mapping.
  • Project – Allows to access the parent project of an object for mapping.
  • to – Defines the relation of a custom attribute to the value it is mapped to.
  • external links – May follow after the to keyword and defines that the attribute is mapped to external link references. YT extracts the external links of the given object in their entirety into a single attribute, separated by comma.
  • separated by – Specifies an arbitrary separator for external links and multi-value enums.
  • valueOf – Starts a valueOf condition.

In DOORS, artifacts have a natural hierarchy. Projects contain modules, which contain objects. Thus, YT allows to filter the artifacts delivered by the data access on three levels. To do so, the include projects|modules|objects if( condition ) expression is used. It causes the DOORS adapter to only consider artifacts that satisfy the specified conditions. The project conditions are evaluated first, followed by the module and eventually the object conditions. Please note that for artifacts of type project only project conditions are allowed. For modules, it is possible to specify additional module conditions, while for objects, conditions on all three levels are valid.

A condition is defined by the following syntax: valueOf(" attributeName") operator value with

  • operator being either a single-value operator like ==, !=, contains or the multi-value operator in
  • value being either a single "literal" or, and only in combination with the in operator, a list of literals, e.g., („This” „is” „a” „list” „of” „values”).

Please note that multiple conditions are implicitly linked by a logical AND.

Example (artifact type is Object):

include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
)
include objects if(
  valueOf("Release") == "FINAL"
  valueOf("AcceptedBy") in ("ME" "OTHER")
  valueOf("Content") contains "very important"
)

This example will only include artifacts that are defined within modules that are part of projects with the Name MY_PROJECT, have the FullName MY_NAME and are not Created By ME. The result set of this selection is further restricted by the objects conditions, allowing only objects of the FINAL Release that are also AcceptedBy ME or OTHER and have a Content that contains the string very important.

Example (artifact type is Module):

artifact type = Module 
include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
)

The example above will only include a Module as an artifact that is defined within projects with the Name MY_PROJECT, have the FullName MY_NAME and are not Created By ME. Please note that no include objects if( condition ) is allowed here since the artifact type = Module.

Example (artifact type is Project):

artifact type = Project 
include projects if(
 valueOf("Name") == "MY_PROJECT"
)

The example above will only include a Project as an artifact that has the Name MY_PROJECT. Please note that no include modules|objects if( condition ) is allowed here since the artifact type = Project.

Example with attribute mapping (artifact type is Object):

include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("FullName") == "MY_NAME"
 valueOf("Created By") != "ME"
){
 include objects if(
  valueOf("Release") == "FINAL"
  valueOf("AcceptedBy") in ("ME" "OTHER")
 )
}
map {
 MY_ATTRIB to valueOf("My_attrib")
 MY_MODULE_ATTRIB to Module.valueOf("Module_attrib")
 MY_PROJECT_ATTRIB to Project.valueOf("Project_ attrib") + "_" + valueOf("My_other_attrib")
 EXTERNAL_LINKS to external links separated by ","
 MULTI_VALUE_ENUM to valueOf("MultiValueEnumAttribute") separated by ";"
}

In addition to a simple configuration, it is also possible to map native artifact attributes to YT attributes. To do so it is necessary to define at least one custom attribute.

Use the keyword map to begin an attribute mapping block. Within the mapping block (between { and }), content assist will suggest all defined attributes, followed by the to keyword. On the right side of the expression it is possible to define to which native attributes the YT attribute should be mapped. YT also allows to map an attribute to a list of external links. Multi-valued enums can be mapped using a custom separator. If no separator is specified, the values are concatenated without any separator or whitespace. This mimics the default behavior of the DOORS client.

The default scope for attribute mapping are objects. The keywords Module and Project are available to access native attributes of the parent module and project. One YT attribute can be mapped to multiple native attributes by concatenating values using +.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

The IBM DOORS adapter allows for flexible link configuration to specify which links YAKINDU Traceability should import from the IBM DOORS data access. Make sure artifact types have been configured before.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

Please note: Links that are read from the DOORS client have a direction. An artifact of the Artifact Type A type is the source of a native DOORS link while artifacts of the Artifact Type B type have the target role.

The configuration panel allows to exactly define the direction of a DOORS link in YT. The configuration language offers content assist to guide you through the various options.

It is possible to restrict the consideration of native DOORS links, based on project and (link) module attributes. The configuration language is similar to the artifact type configuration.

Supported keywords:

  • link source is A|B – Specifies the link source in DOORS. Let’s say you want to create a link type from A = "Customer Requirement" originating from DOORS module CR to B = "Software Requirement" which is defined in DOORS module SR. On specification of link source is B, YT searches for DOORS links defined in link sets from SR to CR, but creates a YT link from Customer Requirement to Software Requirement. The configuration of a link source is optional. If not specified, YT searches according to link source is A.
  • != – „Not equals” operator to use within a condition
  • == – „Equals” operator to use within a condition
  • contains – Constraint for substring checking
  • in – „In” operator to use within a condition
  • include [projects|modules] if – Starts an include expression. Links will be included only if their containing link module satisfies the conditions given in the expression.
    • projects – Specifies that the following conditions are evaluated on project level.
    • modules – Specifies that the following conditions are evaluated on (link) module level.
  • valueOf – Starts a valueOf condition.

Example:

Example with an additional link filter:

link source is B
include projects if(
 valueOf("Name") == "MY_PROJECT"
)
include modules if(
 valueOf("Name") == "MY_NAME"
 valueOf("Created By") != "ME"
) 

The expression link source is B will flip the original link direction as it is in DOORS (A → B) to B → A in YT.

The filters defined above are evaluated on link module level. In this example, only links are considered that are defined in a link module that a) is contained in „MY_PROJECT”, b) has the name „MY_NAME”, and c) has not been created by „ME”.

Links of this link type will never become suspicious.

Microsoft Excel

Data access

The YT adapter for Microsoft Excel provides access to the contents of Excel cells as traceable artifacts.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Microsoft Excel as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing Excel files relevant for traceability.

Supported keywords:

  • resource – A pattern for a project, folder or file in the workspace.

The configuration may contain several resource definitions.

Artifact type

The Excel adapter makes certain Excel cells available as artifacts. The recognition of such cells/artifacts depends on both cell location (file/sheet/address) and cell content, which must not be empty. Cells may be referenced by address or by value.

Configuration

Supported options:

  • addressOf – Starts an addressOf condition.
  • locate cell where – Optional regular expression for content or address of a cell
  • identified by – The unique key for an artifact in this document
  • address matchesRegular expression for cell address in a format like $A$1
  • content matchesRegular expression for cell content
  • name – Specifies the name for the recognized artifact.
  • sheetRegular expression for the workbook sheet name.
  • valueOf – Starts a valueOf condition.
  • column with header – Refers to a given column of an Excel sheet. May be used within a valueOf expression and within an locate cell where expression.
    • For attribute mappings, the actual header is looked for „from bottom to top”, i.e., the search direction is upwards, starting at the row containing the actual artifact.
    • For cell location restrictions, the column headers are expected in row 1 unless an optional in row is configured, see example below.
  • map – Attribute mappings for custom attributes
  • sheetName – Bound to the sheet name of the artifact
  • Document.userProperty – Map value to extended properties of the artifact’s document.
  • Document.property – Map value to default properties of the artifact’s document.

For reading the current selection of Microsoft Excel and opening an artifact, the Component Object Model (COM) API of Microsoft Windows is used. Further information on COM is available on the Microsoft website.

This adapter supports the XLS, XLSM, XLSX, XLT, XLTM and XLTX formats. It provides selection propagation from YT to Excel for all formats. However, selection propagation from Excel to YT is only possible for non-template files, i.e., XLS, XLSM, and XLSX.

Example:

Sample configuration:

sheet "Table_1" {
    locate cell where {
      address matches "\\$(N)\\$(\\d*)"  // Only cells in column N with any rownum
      column with header "TestCase" in row 3 // Only cells in column with Text "TestCase" in row 3
      content matches "(ID-.*)" // which contain only numbers prefixed with 'ID-'
    }
    name sheetName + ":" + valueOf {0;0}
    identified by sheetName+":" + addressOf {0;0}
    map {
      department to Document.userProperty("Department") //user property in the Excel file for department
      status to valueOf {+1;0} // custom attribute status gets the value of the cell on the right
      variant to valueOf {column with header("Variant");0} //custom attribute variant gets the value
                               //of the cell in the same row in the column with the header "Variant"
      author to Document.property(creator) //Predefined property for the creator of the Excel document
    }
  }

In the above example, the workbook sheet containing the artifacts must be named „Table_1” and the cell to link with is in column N. This column requires a header „TestCase” which is expected in row 3.

YT considers only those cells as artifacts that contain a text like ID-1000.

Please note: Although restrictions address matches and column with header are overlapping, it is possible to use them together in the same locate cell block.

Sheet name, cell address and content patterns are interpreted as regular expression, see section "Regular expressions". You can find a regular expressions example in the Microsoft Word adapter documentation.

The keywords name and identified by are used for presenting and identifying artifacts. In this example the artifact name might be Table_1:ID-1000, and the identifier to find the artifact could be Table_1:$N$12. You can copy and paste the example and adjust it matching your requirements.

Attribute and cell mappings

The custom attributes of artifacts can be mapped from cells relative to the artifact’s primary cell or extracted from the document properties. The example in the previous section the department is extracted from the document properties of the Excel file and the status is extracted from the cell right from the primary cell. The syntax supports two variants. The attribute value is referenced either by cell offsets or by column headers.

Example for offsets:

" valueOf( column offset ; row offset )"

Negative offsets are allowed. The attribute value is taken from row row of artifact + row offset, column column of artifact + column offset.

Example for column header:

" valueOf( column with header( " Header " ); row offset )"

YT scans from top to bottom and from left to right to look for cells with „Header” as their contents. If a cell matches, the attribute value is taken from the associated column in row row of artifact + row offset.

To use the cell address instead of the contents, the addressOf keyword supports the same offsets, but is evaluated to the address of the cell. The document properties can be accessed by Document.userProperty(" Name ") for custom properties and by Document.property( creator or title ) for the default document properties.

If your configuration tries to access a cell „preceding” the first cell or row, the value of such an non-existent cell is replaced by an information message like „Illegal cell $B$2-3”.

Value references

In the above example, the artifact named Table_1:ID-1000 is identified by the cell reference Table_1:$N$12. As a consequence, the name of the artifact will change if the text in that particular cell changes. This implies a risk of „crooked” links:

Assuming we have an Excel sheet like this:

If we delete row 2 in Excel, all trace links, e.g., from/to Table_1:ID-1001 will be „bended” to link from/to Table_1:ID-1004.

This risk can obviated by using value references instead of absolute cell references. In this case, YAKINDU Traceability stores ID-1001 as reference and searches the area specified in the address matches section of the configuration for that value. Hence, the trace link stays valid.

In order to have YAKINDU Traceability use references, change the configuration from

resource *risks.xls {
  …
    identified by sheetName + ":" + addressOf {0;0}
  …
  }
}

to

resource *risks.xls {
  …
    identified by sheetName + ":" + valueOf {0;0}
  …
  }
}

Caveat: If you change the configuration from addressOf to valueOf there is a risk to corrupt existing links. Please consult the support before making such adjustments!

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

With the Excel link type, it is possible to store references from Excel artifacts to other artifacts within Excel sheets. This is achieved by populating a cell „close” to the cell representing the artifact with the ID(s) of the referenced artifact(s). The meaning of „close” is expressed in the YT configuration for the particular Excel link type. If the cardinality of the link is larger than one, the IDs of the referenced artifacts are joined in the cell.

YT supports not only to store the link by means of storing the ID, YT also supports synchronization of attributes from the linked artifact into the Excel sheet.

Let’s say test cases in Excel are linked to requirements, which, by the way, might reside in a totally different data source, e.g., PTC Integrity. You can configure YT such that on link creation it does not only store the requirement ID in cell A, but can also copy the requirement description into another cell. This may support the person responsible for the test during specification of the test case.

Using the Microsoft Excel link type requires at least one link type mapping with a configured Microsoft Excel data access. At least one of the artifact types selected for the link type must be a configured Microsoft Excel artifact type.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select a Microsoft Excel artifact type with Microsoft Excel as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • As data access, select an Excel data access, which should have been configured in a prior step.

Supported keywords are :

  • link where … in … – Defines which condition must be fulfilled to derive trace links from cells in Excel. Left from in, a custom attribute of the target linked artifact type must be provided that identifies artifacts of this type within Excel. Right from in, a position within Excel must be provided via the valueOf keyword. This position must refer to an Excel artifact type.
  • map – Defines a list of mappings (see below).
  • … based on … to – Defines a mapping of an attribute of B or A (left from to) to a cell in Excel (right from to), i.e., the attribute value will be stored in the specified cell when creating or updating the link. Left from based on, a custom string attribute of the configured Excel link type must be specified. When reading a link from Excel, this custom attribute will be set to the value read from the specified cell. When creating or updating a link, the custom attribute will be set to the value of the specified custom attribute of an artifact.
  • valueOf – Allows to specify the position of a cell within an Excel sheet, see Microsoft Excel artifact type.

When reading or writing links of the configured Excel link type, YT will generally only consider the same Excel sheet in which the Excel artifact was found that is referred to by the in clause. All relative positions specified with valueOf are relative to the cell of this artifact, i.e., they assume {0;0} to be the position of this cell.

In general, each entry of map has the form: connectorAttr based on B. artifactAttr to A.valueOf{ xPos; yPos} . The expression connectorAttr is the name of a custom attribute defined for the link type, while the expression artifactAttr is the name of a custom attribute defined for the artifact type of B. The expression A.valueOf{ xPos; yPos} defines the position to store the attribute in, as described above.

The Excel link type supports linking from one Excel artifact to zero, one or more artifacts, the type of which is set in the link configuration:

  • If there is no link, the cell holding the link information is empty.
  • In case of one link, the cell contains the ID of the referenced artifact as specified in the link type configuration.
  • In case of more than one link, the IDs are concatenated, separated by the pipe symbol ( |). If the pipe symbol is used within an ID, it must be encoded as \|, i.e., there must be preceeded by a backslash. A backslash within an ID must be encoded as \\. YT automatically performs these conversions when storing links, but users who manually change these Excel cells need to make sure that the encoding is as described above.

If attributes are mapped, the same mechanism holds true for attributes. The number of items in the cell holding the IDs and the cells holding attributes must match, i.e., the n th attribute is associated with the n th link.

If in this case the links in Excel are edited manually (i.e., not by YT), the user must take care of making consistent changes: If he deletes the n th link in the cell holding the ID, he must also delete the n th attribute in each cell holding attributes.

link where B.IDX in A.valueOf{column with header("Requirement ID");0}
map {
    module based on B.ModuleName to A.valueOf{column with header ("Module");0}
    variant based on B.variant to A.valueOf{+4;0}
}

The sample configuration above describes a link type mapping from artifacts of the Excel artifact type (artifact A) to requirement (artifact B). The ID of artifact type B is configured in the custom attribute B.IDX, and artifact type B has the custom attributes B.ModuleName and B.variant.

The configuration tells YT that the IDs of the linked artifacts should be written into or read from the cell at the following position: "column labeled „Requirement ID”; same row as ID of Artifact A". YT splits the string contained in the cell by using the separator | and removes any whitespace surrounding each of the resulting parts. YT derives a link whenever one of the resulting parts is equivalent to B.IDX (i.e., the ID of the requirement).

The definition of the position has the form A.valueOf{ xPos; yPos} . The syntax is the same as for the Excel artifact type.

Via the keyword map, the configuration tells YT to store certain custom attributes of artifact B in the Excel file and to map these values to certain custom attributes of the link type. In the example, it will derive the value of the custom attribute variant of the configured Excel link type from the custom attribute variant of B and the link attribute module from B's custom attribute ModuleName. YT stores all attributes for the link in the row of the Excel sheet containing A. The column to store the value of B.ModuleName in is defined to be the column having the header „Module”. The second entry defines a similar mapping for another variable, but this time the column for storing the attribute is defined relative to the column of A: It is stored four columns to the right of A.

In the above Excel sheet, two links have been created by means of YT:

  • From test case 1 to requirement A13, which comes from module A in variant 3
  • From test case 1 to requirement A16, which comes from module G in variant 7

Suspicious links validation is done by re-evaluating the link’s custom attributes and comparing these values to those stored in the link. If there are any differences, the link is suspicious.

Microsoft Visual Studio

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.cpp
    subset "includestmt"
    subset "class"

In the above example, only class and includestmt code elements (defined in subset patterns) in all files with a .cpp extension (defined in resource pattern) can be valid for tracing. This adapter supports files with following filename extensions:

  • .h
  • .c
  • .cpp
  • .vb

and the following subsets:

  • includestmt
  • namespace
  • class
  • function
  • variable

For reading the current selection and opening an artifact in Microsoft Visual Studio 2013 Professional (or similar versions – not the Express editions), an add-in for the traceable document must be installed.

The required add-in files ( *.AddIn and *.dll) can be found in the following location after adapter installation:

  • Eclipse Installation Path/traceability/plugins/vs2013

These files should be copied to:

  • UserHome/Documents/Visual Studio 2013/Addins

Add-In installation/registration:

In the Visual Studio environment (select Extras → Add-In-Manager from the menu bar) the first and second checkbox should be checked – restart needed!

Detailed information on installation and registration can be found here:

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Microsoft Word

Data access

The YT adapter for Microsoft Word provides access to the contents of Word documents as traceable artifacts.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Microsoft Word as data access type.

Within the configuration panel, you may specify file patterns consisting of Eclipse projects, folders or file name patterns describing Word files relevant for YAKINDU Traceability. Supported Word formats are DOC, DOCX, and DOCM.

Supported keywords:

  • resource – A pattern for a project, folder or file in the workspace.
  • undefined attribute value – Specifies the value to be returned when an attribute can’t be resolved. This value will be returned if the cell does not exist when trying to retrieve the value from a cell in a Word table (either because the requested cell index is out of bounds or because the table does not contain the requested cell header). Possible values are strings, in which case the returned value will always be the same, or the default keyword.
  • default – For undefined attribute value, using the default value will return a String indicating the position that couldn’t be found (either by index, or by column/row header). For example, „<Not a cell: {-4; RowHeader}>”. This is especially useful to detect errors in the configuration or in a Word document

The configuration may contain several resource definitions.

Example:

resource *.docm
resource *.doc
undefined attribute value "N/A"

This configuration will match all Word documents in formats DOC or DOCM. If the artifact type configuration matches elements in a Word table and some attributes reference cells that can’t be found, these attributes will receive the „N/A” value.

Artifact type

The Word adapter recognizes three different kinds of artifacts: Bookmarks, regular expression matches, and headings. It supports DOC, DOCM, and DOCX file formats. It can extract information for the mapped attributes from the general structure (headings, paragraphs, tables), and include or exclude artifacts based on their style information (bold/italic/underline/strikethrough).

For example, it is possible to retrieve all bookmarked elements, excluding the ones with the „strikethrough” style.

When the Word change tracking mode is enabled, all modifications will be considered as „Accepted” by YAKINDU Traceability. This means that elements marked for deletion (but still visible in the document due to change tracking) will be ignored, whereas added elements will be included. This is useful to avoid duplicate matches, when a paragraph has been modified in change tracking mode, and both the old version and new version are still present in the document.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Microsoft Word data access in the Data access drop-down list.

Supported options:

  • locate bookmark where subset – Specifies bookmark recognition(s). This can be used to filter valid bookmarks by defining a regular expression on the full label format (see detailed explanation below).
  • locate text where pattern matches – Searches in the entire document for text matching the specified regular expression. An artifact will be created for each text sequence matching this expression
  • locate heading where pattern matches – Searches in the document headings for text matching the specified regular expression. An artifact will be created for each text sequence matching this expression
  • where style is (not) – For bookmarks, text or headings, specify additional filter(s) based on font style. Supported font styles are bold, italic, underline and strikethrough. You may specify several style filters. A style is considered to be applied if at least one character has the specified style. Conversely, a style is considered to not be applied if no character has the specified style
  • name – Specifies the name for the recognized artifacts. See the list of possible values below
  • map – Starts an attribute mapping group

Possible values for name and attribute mappings:

  • Generally valid: name and map are string concatenations. Possible parts in this concatenations are:
    • String literal : a (static) string
    • hasStyle(style): evaluates the font style of the matched element and returns true if it has the specified style, false otherwise. Supported font styles are bold, italic, underline and strikethrough. Example: hasStyle(bold).
    • For artifacts found in tables:
      • valueOf {x;y} – If the artifact (text or bookmark) is found in a table cell, attributes can be mapped to values in nearby cells. Here x and y are integer coordinate values representing a relative cell position, with x being the column offset and y being the row offset. The coordinates 0;0 denote the current cell. Example:
        • {+1;0} indicates the cell that is at one column to the right from the matched artifact’s cell.
        • {-1;-3} indicates the cell one column to the left and three rows above the matched artifact’s cell.
      • column with header – In valueOf {x;y}, x can be replaced by column with header "headerName". In this case, the label of the cells in the first row (top-most) will be used to find the column.
      • row with header – In valueOf {x;y}, y can be replaced by row with header "headerName". In this case, the label of the cells in the first column (left-most) will be used to find the row.
    • For map only:
      • Document.property(title) and Document.property(creator): Accesses the Word document’s standard properties title and creator. – Please note: These are Microsoft Word’s metadata, not the metadata of the Word file, i.e., they have to be maintained inside the Word document.
      • Document.userProperty(„property_name”): Accesses the Word document’s custom property of the same name.
Use bookmarks as artifacts

The „locate bookmark” matcher can be used to create an artifact for each Word bookmark matching the specified subset (defined as a regular expression)

Minimal configuration:

locate bookmark where subset ".*" {
}

This configuration will create an artifact for each bookmark, with a default name (conforming to the full label format below) and no attributes

This matcher accepts one parameter, in the form of a regular expression, which will be evaluated against the full label of the bookmark. In the minimal example above, the regular expression „.*” matches all available bookmarks (including hidden bookmarks, such as table of contents references)

Full label format for bookmarks

When using the „locate bookmark” matcher, the bookmarks are specified by a string consisting of three sections which are separated by three hash signs:

bookmark_id ### bookmark_content ### (optional_bookmark_desc | …)

The „subset” defines a regular expression, which will be evaluated against this full label: an artifact will be created for each bookmark matching the specified expression. See Bookmark examples below for more details

Please note: The optional_bookmark_desc is deprecated, but still maintained for backward compatibility. It won’t be discussed here.

Additional supported values for bookmarks

When using a ‚locate bookmark’ matcher, you can refer to groups defined in the regular expression, using „$n”, where n is the n-th group (e.g., „$1” is the first group, as defined in the bookmark regular expression)

For example:

locate bookmark where subset "(.*)" {
	name "$1"
}

In this example, the parentheses in the regular expression define a group. Then, the value „$1” is a reference to the text matched by the first group (which is also the only group, in this small example)

Bookmark example

locate bookmark where
	subset "([^_].*)###(.*)###(.*)"
	style is not strikethrough
	{
	name "$1 - $2"
	map {
		Author to Document.property(creator)
		Description to valueOf{column with header "Description"; 0}
	}
}
  • In the above example, bookmarks will be located in all documents specified by the Word Requirements data access.
  • The subset is a regular expression indicating that all bookmarks should be selected, except the ones prefixed with an underscore „_”. Microsoft Word uses an underscore prefix to identify „hidden bookmarks”, which means that this expression will only match visible bookmarks:
    • ([^_].*): Defines a group (identified by the parentheses). The group will match any sequence of characters which does not start with an underscore
    • ###: The first „full label format” separator. The text before this separator represents the bookmark ID, whereas the text after this separator represents the bookmarked text
    • (.*): Defines a second group, matching any sequence of characters
    • ###: The second (and last) „full label format” separator. The text before this separator represents the bookmarked text
    • (.*): Defines a third group, matching any sequence of characters
  • The $1 and $2 expressions in the identifier refer to groups of the subset, hence YT will show matched bookmarks as concatenation of bookmark_id + " - " + bookmark_content.
  • The option style is not strikethrough will skip all bookmarks with at least one strikethrough character in the bookmarked text.
  • If the bookmarked text is located in a table cell, the description will be retrieved from a cell on the same row, namely the cell in the column named „Description”. The name of a column is the text of the first cell (top-most) in this column. If this column can’t be found, the value specified in the Word Requirements data access will be used instead.

Here is a sample Word document using bookmarks:

And here is the result in YT:

Use regular expressions as artifacts

The „locate text” matcher will create an artifact for each portion of text in the document matching the specified regular expression. This matcher gives more flexibility regarding the structure of the document (in the sense that it will search text in any part of the document, including paragraphs, headings, tables...), but the configuration is highly dependent on the contents of the document.

YAKINDU Traceability’s regular expression recognition relies on uniqueness. Hence, YT ignores text portions with identical matchedText of a regular expression, e.g., if the text REQ02 Control occurred twice in the example below. In such a case, YT will produce a single artifact (and not one per occurrence of the same text), and will attach a warning marker to this artifact (the warning will appear during Model Consistency validation)

Caveat: As some Microsoft Word functions create duplicates of text portions, such a situation is likely to occur. For your convenience, YT doesn’t match regular expressions within Word’s hyperlinks, which is one of the most commonly used functions duplicating text, e.g., when creating a table of contents. So a match in a „standard” text and in a hyperlink to that text won’t be considered as duplicates. On the other hand, if a Word document has a table of contents without the hyperlinks instead of page numbers option being set, Word creates copies of the headings instead of hyperlinks, thus YT considers matches as duplicate.
Additionally, all modifications made in „Track Changes” mode are considered to be accepted, i.e., text deleted during „Track Changes” will be ignored by YT during matching. Similarly, text added in „Track Changes” mode is always taken into account.

Minimal configuration:

locate text where pattern matches ".*" {
}

This configuration will produce one artifact for each structural element of the document (heading, consecutive list of paragraphs, or cell in a table). The name of the artifact will correspond to the entire text of this structural element

Additional supported values for regular expressions
  • function matchedText: The whole match for the regular expression, the bookmarked text, or the heading.
  • function textUntilNext (match | headingOrMatch) : Text portion starting from the matched text until the next match/ heading or match, resp.
  • If the match itself is inside a heading, this particular heading is considered as „the next heading”, so textUntilNext(headingOrMatch) is the text portion from the match to the end of the heading.
  • For the label (i.e., the name attribute), the textUntilNext() has a size restriction and will be truncated automatically. Custom attributes may have longer text passages.
Regular expression example

locate text where 
	pattern matches "REQ[0-9]+.*" 
	style is bold {
	name "R-" + matchedText
	map {
		Description to textUntilNext (headingOrMatch)
		Author to Document.property(creator)
	}
}

In this example, the artifacts will be located in the document and will match any occurrence of the string „REQ” immediately followed by at least one digit. The expression will also include all text following this sequence, until the next end-of-line. If at least one of the matched characters is bold, then an artifact will be produced for the matched sequence.

Each artifact will have a description, corresponding to the entire text starting immediately at the end of the matched text until the beginning of the next heading or match, whichever comes first. Note that this may include a lot of text, which may span over several tables or paragraphs.

Here is a sample Word document using regular expressions:

And here is the result in YT:

Warning regarding the use of imprecise regular expressions

If you use an imprecise regular expression while configuring the Microsoft Word adapter (for example „REQ-//d+”) more than one candidate might match.

In this example „REQ-1” and „REQ-11” would both match the expression as they both share the string „REQ-1”.

If you then double-click on the tracepoint „REQ-1” YT searches the document for the string „REQ-1” and will find the candidate „REQ-11” if it is stated above „REQ-1”!

Use headings as artifacts

The „locate heading” matcher is really similar to the „locate text” one, except that it will only search inside Word headings, instead of the entire document. Microsoft Word comes with a set of predefined headings (Heading 1 ~ 9), but this matcher will, more generally, match any paragraph with an outline level equal or greater to 1. This also corresponds to all elements visible in the Word Outline view.

Please note: by default, the main title of a Word document does not have an outline level. Consequently, it will be ignored by the „locate heading” matcher, and will not produce an artifact.

Like the „locate text” matcher, „locate heading” will accept a parameter to filter results based on a regular expression. Note that, unlike „locate text”, this parameter is optional for headings.

Minimal configuration:

locate heading {
}

Which is equivalent to:

locate heading where pattern matches ".*" {
}

Both of these configurations will produce an artifact for each heading in the Word document. The name of the artifact will correspond to the text of the heading

Additional supported values for headings

„locate heading” supports the same options as „locate text”. See Additional supported values for regular expressions above

Heading example

locate heading where pattern matches "Req[0-9]+.*" {
	name matchedText
	map {
		Description to textUntilNext (headingOrMatch)
		Author to Document.property(creator)
	}
}

This example is very similar to the regular expression example. The main difference is that artifacts will only be produced if the text „Req” immediately followed by at least one digit is found in a heading.

Here is a sample Word document using headings:

And here is the result in YT:

Example for a mix of bookmarks and expressions

YAKINDU Traceability supports using a mix of resource(s) (using different configuration mappings) and recognitions specification(s) for one artifact type, e.g., by means of an adapter configuration similar to the following:

locate bookmark where subset "([^_].*)###(.*)###(.*)"{
	//...
}

locate text where pattern matches "REQ\\d{2}.*" {
	//...
}

locate text where pattern matches "Requirement \\d{2}.*" {
	//...
}

locate heading where pattern matches "Req[0-9]+.*" {
	//...
}

Support of copy and paste from Microsoft Word to YAKINDU Traceability

In order to support fast link creation, YAKINDU Traceability supports copy and paste of artifacts from Microsoft Word to the YT Editor as described in the documentation on the YT Editor as follows:

If the clipboard contains a text portion that has been copied out of a Microsoft Word, YT analyzes the pasted text with respect to the configuration of the selected artifact type:

  • If the configuration specifies bookmarks, YAKINDU Traceability analyzes the bookmarks that are contained in the clipboard text and adds each matching artifact to the YT Editor area, i.e., each artifact that both is covered by the artifact type’s configuration and that is part of the selection.
  • The same holds true for regular expressions.
  • Caveat: The clipboard provides information on the file the selection originates from. That filename is honored by YT during the evaluation of matching artifact. As a consequence, YT will only identify artifacts if they have been copied to the clipboard in Microsoft Word.

Propagation of selections between YAKINDU Traceability and Microsoft Word

YT propagates the selection of artifacts from and to Microsoft Word, e.g., YT shows an artifact inside the YT Overview if a „selection” of the artifact occurs in Microsoft Word.

  • YT considers an artifact based on a bookmark as selected if the user clicks on the bookmark (label) in Microsoft Word.
  • YT considers an artifact based on a regular expressions as selected if a text portion is selected (marked) in Microsoft Word and this selection contains the matched text. If the selected text contains more than one match, YT considers the first one as selected. – Background: Regular expressions can match text portions of various sizes (even the whole document). Additionally, such matches can overlap. In order to clearly distinguish whether an artifact based on a regular expressions is selected, YT uses the algorithm described above. – Hint: A double/triple click in Microsoft Word selects (marks) the whole word/paragraph at the cursor location.

Migration advice (pre 1.1.1510 (3))

Regular expression matches had been introduced in YT version 1.1.1510 (3).

This affects the format how YT stores artifacts and links, so elder YT storage files, e.g., data.yt, need to be migrated.

A validation detecting such cases, offering quick fixes and migrating data automatically is available. Run it by selecting Traceability → Validation → Model Consistency in the main menu.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

Mylyn

Data access

The YT adapter for Mylyn provides access to Mylyn tasks as traceable artifacts. It is also able to derive a link in YT for every relation between tasks within Mylyn.

To get the adapter to work, Mylyn has to be configured properly as suggested in Eclipse Mylyn Tasks. For further information have a look at the Mylyn documentation.

For setting up and using Mylyn in the batch mode of YT, the adapter can be configured to load an existing Mylyn task list that has been exported by the user before. Otherwise, no configuration is required. Please note that there can be only one active Mylyn data access at a time.

Since the exported configuration does not include any passwords for any repositories, YT supports setting the login credentials via the command line by using Java system properties. These properties are MYLYN_LOGIN_USER_NAME for the user name and MYLYN_LOGIN_PASSWORD for the password. The same credentials will be used for all of the repositories.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Mylyn as data access type.

Supported options:

  • if empty import file – If the task list is empty, imports a Mylyn task list from the .zip file. The file must be in the format that Mylyn uses for exporting task lists. The imported task list will overwrite the current one. If the credentials have already been provided by parameters or by secure storage, this option will also trigger task synchronization.

Example:

if empty import file "/com.yakindu.yt.mt.spec/example.zip"

This configuration specifies that YT should check whether the Mylyn task list currently contains no tasks. If this is the case, YT will import a task list from the specified file example.zip. Subsequently, YT will trigger a synchronization for all existing repositories.

No further configuration will be done on the configuration panel.

Exporting Mylyn configuration data

The Mylyn configuration itself can be exported via the Eclipse menu entry File → Export… → Tasks/Task List and Contexts.

Please note: Exported configuration data also contains tasks which are currently being synchronized while exporting. To avoid any confusion after import, the local copy of tasks in the task list should be removed before restart.

Caveat: The export wizard does not always respect the latest changes made just before starting the export. To be sure that the configuration is up-to-date, we recommend to (re-)start YT before exporting.

Artifact type

Configuration

Supported options:

  • name – Specifies the name for the recognized task.
  • kinds – Filters the types of tasks to match. It is case-insensitive. For Mylyn, this corresponds to the Type attribute of the task (e.g., Bug). This is also true for Jira, which Mylyn can connect to.
  • map – Attribute mappings for custom attributes.
  • valueOf – Retrieves the value of a specified Mylyn metadata property
  • customAttribute – Retrieves the value of a specified Mylyn custom attribute

Example:

kinds "Aufgabe", "Task"
name valueOf(Key) + ": " + valueOf(Summary)
map {
	ID to valueOf(Key)
	relatesTo to customAttribute("Relates to:")
	isMentionedBy to customAttribute("Is mentioned by:")
}

The Mylyn adapter supports all issues fetched by the Eclipse Mylyn plugin. The name of an YT artifact can be mapped from the attribute values of the corresponding issue. In the example above all issues of kind Aufgabe or Task are made available. The name is a concatenation of the issue’s key, a colon and the summary of the issue. The custom attribute ID is mapped to the issue’s Key value. The custom attributes relatesTo and isMentionedBy are mapped to corresponding Mylyn custom attributes of the issue. These are called Relates to: and Is mentioned by:, respectively.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

This link type maps links between Mylyn tasks automatically to YT trace links, if corresponding artifact types and link types exist. Selecting Mylyn as data access is mandatory for such links.

The Mylyn task repository needs to be configured in the Mylyn Eclipse plugin before YT can access Mylyn tasks. This is done by opening one of the installed Mylyn views ( Window → Show View → Other…) and starting its configuration dialog.


You can configure the repository settings by double-clicking the Jira (supports [...]) entry. The link type requires links to be fetched from Mylyn. This can be achieved by activating Follow redirects for the Mylyn Task repository.

Links of this link type will never become suspicious.

Native File

Data access

The „native file” data access is a link storage. It uses a file in the workspace to store and maintain links created by YT.

Files used by the native file data access are in a proprietary XML format and can be maintained in source code management systems like CVS, Subversion, or Git – just like any other project artifacts.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Native File as data access type.

The workspace path to the file has to be configured. Additionally, a file can be protected by applying the readOnly option. Writing operations are not allowed on such files, which means that it is not possible to create, update, or delete any links in a read-only file.

Supported keywords:

  • file – Defines the file to be used as a link storage. The filename extension must be .yt.
  • readOnly – Specifies to use the file in read-only mode.

Example:

file "/my_project/conf/data.yt"

In this example, link data are stored in the data.yt file, which is located in the conf folder of the my_project project.

If the data file does not yet exist, it will be created automatically. The same holds for the folder path, if any. However, the specified project must already exist.

The following example shows a read-only link storage file:

Links are stored in a native file if you assign a Native File data access to a link type.

Suspicious links validation is done by comparing the artifacts' current versions to those stored in the link. If there is any difference, the link is suspicious.

PDF files

YAKINDU Traceability’s PDF adapter identifies fragments of a PDF document as traceable artifacts. These artifacts can be identified by either their textual contents or by comments in the PDF document. Tracing is possible in both directions between an artifact in YT and the corresponding location in a PDF document, be it a comment or a text fragment.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select PDF files as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource "*.pdf"

This configuration specifies that YT should load and analyze all files residing in the workspace whose filename extension is .pdf.

Artifact type

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured PDF files data access in the Data access drop-down list.

Keywords

The PDF artifact type configuration supports the following keywords:

  • analyze comments – Analyzes the comments in the PDF document and creates artifacts from them.
  • locate text where pattern matches – Looks up textual contents matching the specified regular expression in the configured files. For each text sequence matching the regular expression an artifact will be created.
  • name expr – Specifies the name of the artifact as the value of the expr expression. By default, this is the text fragment matched by the pattern.
  • group( name) – Retrieves the match of the capture named name in the pattern.
  • identified by – An optional key for the matched artifact. If specified, it should be a value uniquely identifying the artifact. If the same value is specified for multiple matching text elements, YT will create only a single artifact nevertheless.
  • map – Starts a mapping block for specifying custom attributes.

Example for analyzing comments:

analyze comments

Example for text parsing and artifact extraction:

locate text where pattern matches "(?sm)(?<id>\\[A:.*?])(?<txt>([^\\[])*)" { 
	name group("id")
	identified by group("$1")
	map{
	   attr to group ("txt").substringBefore("HEADER")+group("txt").substringAfter("FOOTER")
	}	
}

The pattern uses multiline-mode search ( ?sm) to find all occurrences of specific text elements. Such a text element starts with „[A:” ( [A:), followed by none or multiple characters ( .*?) and ends with a square bracket ( ]).

The group txt will contain the text until the next square bracket ( *)).

Extracted artifacts are named according to the value of the captured group named id. Artifacts are identified by the value of the first matching group, here id. The custom attribute attr is mapped to the txt group.

If a txt element stretches more than one page, the attr will include the page’s header and footer texts. If you want strip them off, you can use the substringBefore and substringAfter methods as shown. To actually use the example’s code snippet, please replace HEADER by the header’s first characters and FOOTER by the footer’s last characters. These character sequences should be unique in order to match only in the header and in the footer, respectively, and nowhere else.

Polarion

The Polarion adapter allows to extract table items from a Polarion database server and to open Polarion artifacts from YT.

Instead of connecting to the Polarion application server, YAKINDU Traceability connects directly to the Polarion database. To make this possible, you have to allow external access to the database. Polarion provides a description of how to do so: https://almdemo.polarion.com/polarion/sdk/doc/database/ExternalDatabaseConnection.pdf. You can use any SQL client to check whether you can successfully connect to the database.

Data access

The Polarion data access configuration specifies the Polarion database server to connect to.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Polarion as data access type.

Supported keywords:

  • server - The Polarion server’s IP address and port number
  • user - The user name for logging into the Polarion server
  • password - The password for logging into the Polarion server
  • webURLPrefix - The URL prefix for accessing Polarion work items through a web browser (e.g., http://almdemo.polarion.com)

Sample configuration:

server "192.168.3.160:5433" user "external" password "secret007"

The example above will connect to the Polarion database server which is available at the IP address 192.168.3.160 and listening on port 5433. The user name for logging in is „external” with the password „secret007”.

server "192.168.3.160:5433" user "external" password "secret007" webURLPrefix "http://almdemo.polarion.com"

In addition to connecting to the database server, the above configuration also specifies a URL prefix (webURLPrefix) that YT uses for opening a Polarion artifact in a web browser. Double-clicking on a Polarion artifact in YT navigates to this URL and to the specific work item in the web browser.

Artifact type

The Polarion adapter allows for flexible artifact configuration to specify which artifacts YAKINDU Traceability should import from the Polarion data access.

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Polarion data access in the Data access drop-down list.

Supported keywords:

  • != – „Not equals” operator to use within a condition
  • == – „Equals” operator to use within a condition
  • contains – Constraint for substring check
  • include objects if - Starts an include expression. Artifacts will be included if they satisfy the following conditions expression.
  • map - Starts an mapping block. This is optional.
  • name - Defines the name of the artifacts.
  • valueOf – Starts a valueOf condition.

To filter artifacts delivered by the data access the include objects if( condition ) expression is used. It instructs the Polarion adapter to only consider artifacts that satisfy the specified condition.

A condition is defined by the following syntax:

valueOf(attributeName) operator value
as attributeName, you can use any one of the predefined constants shown in the following list. At the moment, it is not possible to define your own attributeName.

  • author
  • autosuspect
  • created
  • deleted
  • description
  • duedate
  • id
  • initialEstimate
  • location
  • module
  • outlinenumber
  • plannendEnd
  • plannendStart
  • previousStatus
  • priority
  • project
  • remainingEstimate
  • resolution
  • resolvedOn
  • revision
  • severity
  • status
  • timeSpent
  • title
  • type
  • updated
  • uri

with

  • operator being a boolean operator like ==, !=, or contains
  • value being a "literal"

Please note that multiple conditions are implicitly concatenated with a logical AND.

Example:

include objects if(
	valueOf(type)=="userstory"
)
name valueOf(id)

The example above will include only artifacts whose type attribute’s value is userstory. The name of these artifacts will be set to the id attribute’s value.

You can map attributes, too. Example:

include objects if(
	valueOf(type)=="userstory"
)
map{
	attribute to valueOf(author)
	^severity to valueOf(severity)
}
name valueOf(id)

This example expands the previous example. Here we are mapping two attributes to the values of a Polarion work item.

The Polarion adapter allows to specify which links YAKINDU Traceability should import from the Polarion data access. Make sure artifact types have been configured before.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

  • As at least one of A and B, select a Polarion artifact type with Polarion as its adapter. If you want to derive links from and to the same artifact type, choose this type both as A and as B.
  • The data access to be selected depends on your A and B artifact types, which should have been configured in a prior step:
    • If A and B are both Polarion artifact types with the same Polarion data access, select that data access. No further configuration is necessary, because YT will link matching types automatically.
    • If either A or B is not a Polarion artifact type, select the Native File.

Example:

PTC Integrity

Data access

The PTC Integrity data access provides access to documents being hosted by PTC Integrity as traceable artifacts. A reliable connection to the server is needed.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select PTC as data access type.

Supported keywords:

  • server – Defines which server is to be used.
  • port – Defines which port is to be used.
  • secure true / secure false – Defines whether the connection should use a secure communications protocol – please refer to PTC Integrity documentation for details. The keyword is optional, default is secure false.
  • fields for {} – Defines the attributes of a PTC item which are taken into account to represent the item in YT. As default, PTC items are labeled in YT with ID and summary or (if summary is empty) with ID and text.
    • summary (inside fields for) – Defines the field defining the summary. Default is summary.
    • text (inside fields for) – Defines the field defining the text. Default is text.
  • projects – Defines which projects are to be imported.

Within the configuration panel further configuration is required. Below you can see a sample configuration which will be described subsequently.

Sample data access configuration:

server "ptc.itemis.de"
port 7001
secure false
fields for {
    summary "text"
    text "text"
}
projects {
  "/Pedelec"
}

The connection to the PTC Integrity server is configured here. In the above example the connection to the server is defined by the hostname ptc.itemis.de and the server port 7001. A secure connection is not configured, but the option secure can be set to true, if the server supports secure connections. PTC items are represented in YT by their text attribute.

Furthermore, the PTC Integrity projects to be considered should be listed here.

Hint: The editor supports you during the selection of projects and also during the selection of PTC item types during configuration of relevant artifacts. Entering [Ctrl]+[Space] in the projects section shows a list of projects that are available on the server. In order to retrieve this information, YAKINDU Traceability must be connected to PTC Integrity. The connection is established on save. Thus, we recommend an intermediate saving of the configuration after entering server and port.

Prerequisites

The PTC Integrity adapter requires the manual installation of the mksapi.jar file. By default a dialog is shown which will help installing the file. The mksapi.jar file can be found on the PTC Integrity server here:

  • /IntegrityClient10/lib/mksapi.jar
  • /IntegrityServer10/server/mks/lib/mksapi.jar

To prevent the dialog to appear or to prepare the installation, the mksapi.jar file can be copied manually into the plugin folder /plugins/com.yakindu.traceability.integrity.interface.lib_1.1.1/lib/.

Advanced data access configuration

For some PTC Integrity installations it is necessary to change the fields that are used as labels. This can be configured in the fields for section of the data access configuration. All fields have to be defined for all fetched items, including documents. At first, the summary field is used, and if not set the value of the text field is used.

server "ptc.itemis.de"
port 7001
secure false
fields for {
    summary "summary"
    text "text"
}
projects {
  "/Pedelec"
}



Artifact type

The PTC adapter provides requirements hosted by PTC as artifacts. A sample configuration shows how the mapping works.

Configuration

Supported options:

  • map to{…} – A block that defines which PTC items are relevant for traceability and how they are mapped to YT artifact types.
  • if( … and … ) (inside map to) – Defines a boolean expression which is evaluated on PTC items. If the evaluation result is true YT considers the PTC item as a traceable artifact of the given artifact type. The expression may contain several attribute evaluations concatenated by the keyword and.
  • … to … (inside map to ) – Defines how attributs of YT artifacts should be populated with values from PTC items' attributes.

Example:

map to "Requirement"
    if ("Category" = "User Requirement") {
        "text" to "Text"
 }

In the above example, the YT artifact type is mapped to the PTC Integrity type Requirement if the Category attribute of the PTC item is set to User Requirement. The if condition is optional. Furthermore the PTC Integrity attribute Text is mapped to the YT type custom attribute text. The attribute mapping is optional.

The if clause supports the operators =, !=, >, <, <=, >=, contains, doesNotContain.

Please note that depending on the attribute type some operators are not allowed by PTC Integrity, e.g., text fields (i.e., fields of type longtext, shorttext, fva, etc.) support contains and doesNotContain but not = or !=.

Please also note that contains is a heuristic operator – refer to the PTC Forum for more information.

Loading the document structure

For artifacts which are structured in a document in Integrity, it is also possible to show the document structure in the search dialog. The document structure is not loaded by default, but must be requested for each project separately. This can be achieved via context menu of a document in the search dialog.

In this example, the artifacts of type User Requirement are saved in a document in Integrity. The first image shows the default hierarchy after initial load where artifacts are grouped by document. In the second image the hierarchy was loaded and the artifacts were re-ordered after the document structure was fetched.

Support of copy and paste from PTC Integrity to YAKINDU Traceability

In order to support fast link creation, YAKINDU Traceability supports copy and paste of artifacts from PTC Integrity to the YT Editor as described in the YT Editor chapter as follows:

In the PTC Client, mark and copy a set of items. On paste, YT analyzes the clipboard content with respect to the configuration of the selected artifact type. If the ID of an item in the clipboard matches an item that is covered by artifact type configuration then YAKINDU Traceability adds this item to the YT Editor area.

Please note:
Not all versions of PTC Integrity support copying of items. If you cannot copy items with your PTC Integrity version we recommend to apply the support of YAKINDU Traceability within PTC Integrity.

Please also note:
If the clipboard contains artifacts that are not covered by the configuration of the artifact type (to put it crudely: The selection is „too large”), YAKINDU Traceability notifies the user about such items. The user can turn off this notification.

Support of YAKINDU Traceability editor within PTC Integrity client

Especially for users who are primarily working with the PTC Integrity client, YAKINDU Traceability supports an integration of YT Editor functionalities into the PTC Integrity client using custom actions.

Configuration

To configure the PTC Integrity client to work with a running YAKINDU Traceability instance, you have to configure a custom action within the view set of your current PTC Integrity client installation. Technically, a custom action is a program which is executed by the PTC Integrity client.

This program which will be configured in the following steps and can be found in the traceability\integrity folder included in the root folder of your YAKINDU Traceability installation.

Copy the files IntegrityClientIntegration.jar, Set_A.gif and Set_B.gif to any location you prefer, e.g., C:\IntegrityClientIntegration.jar etc. Open your PTC Integrity client, select ViewSet → Customize… from the menu bar, and choose the Actions tab. Within the tree on the left side choose Custom.

After the custom item is selected a list of possible custom actions becomes visible on the right side of the details view. Custom actions are bound to predefined keyboard shortcuts and you can configure whether the custom action should also be visible in the menu or in the toolbar. If you wish to use custom buttons, the drop-down must be set to Visible, on Toolbar.

By clicking Edit next to a free action, you will get to a custom action configuration dialog where at least the parameters mentioned below should be configured.

Please note:
To use the full YT Editor integration it is necessary to configure two custom actions, one for Set A and another one for Set B.

  • Name: the name of the action, e.g., Add to A
  • Program: the full path to your local Java executable, e.g., C:\Program Files\Java\jdk1.8.0_45\bin\javaw.exe
  • Parameters: the following parameters are passed to the executed Java program:
    • -jar PATH_TO_YT_CLIENT_JAR
    • -s A|B : select the section of YT Editor where artifacts are added
    • Sample -jar „C:\IntegrityClientIntegration.jar” -s A
  • Optional
    • Icon File: custom action icon, absolute path on local machine

Optionally the following parameters are available:

  • -h HOST : host YT is running on
  • -p PORT : port YT is listening on
  • -ce: keeps the command-line window open; makes sense if java.exe is used instead of javaw.exe
  • -logLvl OFF|FATAL|ERROR|WARN|INFO|DEBUG|TRACE|ALL|DEV : log output level
  • -logFile ABSOLUTE_FILE : log file

If the actions are configured it is necessary to ensure that YAKINDU Traceability is enabled. Find more information in section TCP Server.

Usage

Once the two custom actions are configured and the TCP Server is enabled as described in the previous section, it is possible to add issues selected in the PTC Integrity client to the A and B section of the YT Editor by just clicking the toolbar buttons or menu actions in the PTC Integrity client. The link creation will be done within the YT Editor itself.

If there are any issues selected in the PTC Integrity client which can not be associated with any artifacts by YAKINDU Traceability, the following notification will be shown. This happens just in case YT can not determine any artifact based on the current selection.

Prerequisites

The PTC Integrity adapter requires the installation of API files from the Integrity Server installation. See Prerequisites for details.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is the item’s modified date.

The trace links YT derives from PTC Integrity are based on the PTC data access. If PTC Integrity relations should be mapped to YT trace links, a mapping must be defined at the corresponding YT link types.

Supported keywords:

  • map – Starts a mapping block.

Example:

map to "Validated By"

In the above example, trace links from PTC Integrity are mapped to YT links using the PTC Integrity attribute Validated By. It is defined at the PTC item type which is mapped to the YT artifact type of link end A.

Links of this type are suspicious if the corresponding suspicious flag on the PTC Integrity server is true.

Working without view admin rights

If a user has no viewAdmin rights in Integrity, some commands need to be restricted to visible data only. This can lead to incomplete data, like fields not available for attributes or missing links or artifacts. If you have no viewAdmin rights in Integrity you need to disable „Integrity: Work with view admin rights” in the customization preferences.

Rational Rhapsody

Artifact type

The Rhapsody adapter supports artifacts in models from Rational Rhapsody. The supported model elements are Classes, UseCases and Requirements.

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.rpy
subset IRequirement

In the above example, requirements from files ending on .rpy are taken into account.

Prerequisites

The Rhapsody adapter requires the manual installation of the rhapsody.jar and rhapsody.dll into the folder INSTALL_PATH /plugins/com.yakindu.traceability.port.rhapsody.lib_1.1.1516/lib/_. The files can be found on the Rhapsody server under Rhapsody Installation Path\Rational\Rhapsody\8.1.1\Share\JavaAPI\rhapsody.jar and Rhapsody Installation Path\Rational\Rhapsody\8.1.1\Share\JavaAPI\rhapsody.dll .

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

SQS Test

Artifact type

Configuration

There are no configuration options for this adapter, but it requires some additional set-up in the YT preferences.

Example:

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

Syntext Serna

Syntext Serna is a „what you see is what you get” XML editor for Windows. YT’s Serna adapter is a specialized version of the XML adapter, so please refer to the XML adapter documentation to learn about its configuation. YT is able to propagate selections directly from and to Serna, but it is necessary to install a small Serna plug-in and to configure the path to the Serna executable.

Plug-in installation

The Serna plug-in can be installed by copying the directory traceability/scripts/YTSernaPlugin_py from your YT installation directory to the plugins directory of your Serna installation. To check the installation, open Tools → Preferences… → Plug-Ins within Serna, and check if the YT plug-in is activated.

The default port used by the plug-in to connect to the YT TCP server is 1234. To choose a different port, modify the variable TCP_PORT in the file main.py in Serna’s plug-in directory appropriately.

Please note: As the multiprocessing module is not available in the Python version of Serna, logging of multiprocessing information is disabled by the plug-in by setting the logging.logMultiprocessing to 0.

Configuring the Serna path

It is also necessary to configure the location of serna.exe in YT. This can be achieved by going to Window → Preferences → YAKINDU Traceability → Customization and then providing the path to serna.exe in the "Location where Serna editor (serna.exe) is installed" preference.

Text file

YAKINDU Traceability’s text file adapter identifies fragments within plain text files as traceable artifacts, using configurable regular expressions. In a similar way, the adapter also recognizes link information in the very same text files. It operates invasively and is thus not only able to read links from text files, but it can also insert, modify, and delete them.

Elements are identified based on regular expressions:

  • The artifact type configuration specifies which text fragments should be recognized as artifacts.
  • The link type configuration specifies which text fragments should be recognized as links and how they are mapped to artifacts on the opposite side of the link.
  • Implicit rules define which artifact belongs to which link and thus to the artifact on the opposite side of the link.

The text file adapter supports selection propagation: If you select an element in YT, the selected artifact will be opened in Eclipse’s default text editor, and if you select an element in Eclipse’s default text editor, it will be also selected in YT.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Text File as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource *.txt

This configuration specifies that YT should load all files residing in the workspace whose filename extension is .txt.

Artifact type

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Text File data access in the Data access drop-down list.

Example:

locate text where pattern matches "(?m)(REQ)(?<id>\\d{2})(\\s+)(?<txt>\\w+)" { 
	name group("$1") + "_ID_" + group("id") 
	identified by group("$2") 
	map { 
		attr to group("txt") 
	} 
}

This example shows an artifact type configuration for the Text File adapter. The pattern uses multi-line mode search ( ?m) to find all occurrences of specific text elements. Such a text element start with „REQ” ( REQ), followed by two digits ( ?<id>\\d{2}), followed by one or more spaces ( \\s+). The text element ends with a word consisting of several characters ( ?<txt>\\w+). Extracted artifacts are named according to the result of the first capture in the pattern ( $1), followed by a constant value which is the result of the capture named „id”. Artifacts are identified by the result of the second capture in the pattern. The custom attribute attr is mapped to the result of the capture named „txt”.

Keywords

The Text File artifact type configuration supports the following keywords:

  • locate text where pattern matches pattern – Looks up text matching the specified regular expression in the configured files. An artifact will be created for each text sequence matching the regular expression.
  • name expr – Specifies the name of the artifact as the value of the expression expr. By default, this is the text fragment matched by the pattern.
  • group( name) – Retrieves the match of the capture named name in the pattern.
  • identified by – An optional key for the matched artifact. If specified, it should return a value which uniquely identifies the artifact. If the same value is returned for more than one matching text elements, YT will create only a single artifact.
  • map – Starts a mapping block for specifying custom attributes.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

YAKINDU Traceability is able to recognize link information in text files in the same way as it can recognize text artifacts: a configurable regular expression defines which parts of the text correspond to links. These links define to which other artifacts the text artifacts in the same file are linked.

YT supports link maintenance in two ways. On the one hand the user can create, delete, or update links by manually adding, removing, or changing the corresponding texts in the file. On the other hand, YT automatically updates the file as links are created, deleted, or updated in YT.

We will now introduce the configuration language, including its syntax, by an example. You can find a more detailed description of the configuration below.

Let’s assume that we want to identify links for artifacts in text files of a „text file” artifact type that we have configured previously. We have selected this artifact type as link end A of the link type. Now we also have to flesh this out in the link type configuration. We are doing so by starting the configuration with the line analyze files of A.

Let’s assume further that we want to identify artifacts in a text file according to the sample artifact type configuration that we used for the text file artifact type, with artifact texts like REQ10 SampleRequirement. Now we want to link these to tests that are represented by artifacts of the second artifact type. Let us assume that these artifacts are identified by an arbitrary sequence of words, separated by spaces, that ends with a number. An example would be My test 123.

Of course we somehow have to identify the start of such a sequence of words in the text file. So let’s add some unique „marker text” left from each such artifact identifier, for example, @Test. Thus, the text making up a link to an artifact with the above-mentioned identifier would be @TestMy test 123. This way, we don’t need to consider too much unrelated text left from a number as potential artifact identifiers.

To identify links as suggested above, we extend the configuration as follows:

analyze files of A
locate links by "(@Test(?<id>[a-zA-Z\\s]+[0-9]+))"{
    where { 
        group("id") = B.metadata(Identifier)
    }
} create links by { "@Test" + B.metadata(Identifier) }

The expression locate links by is followed by a regular expression specifying which patterns in the text should be regarded as links. The where block defines additional constraints that must be fulfilled such that a link is recognized. In this case, the where block contains one constraint: It requires that the part of the match that is right from @Test must match the identifier of any artifact for link end B.

We find this identifier within the matching text by using the matching group ?<id> in the regular expression and by later referencing it via group("id").

The block starting with create links by defines how new link texts are created. In this case the expression is straightforward: The newly-linked artifact’s identifier is appended to the above-mentioned prefix.

Let’s now assume that we want to map the text part and the numeric part of the requirement ID to different custom attributes of the link. We can achieve this by extending the configuration as follows:

analyze files of A
locate links by "(@Test(?<id>(?<text>[a-zA-Z\\s]+)(?<number>[0-9]+)))"{
	where { 
		group("id") = B.metadata(Identifier)
	}
} map {
	 testNumber to group("number") 
	 testText to group("text") 
} create links by {
	"@Test" + B.metadata(Identifier)
}

We are using the additional groups number and text to identify the desired parts of the matching text. The map block assigns the corresponding values to the link’s custom attributes.

Now we know which parts of the text correspond to links and which parts correspond to artifacts. However, which links do belong to which artifacts? The link text only specifies the artifact on the B side of the link; the artifact on the A side, i.e., „this” side, is one of the text fragments that have been recognized by the regular expression spelled out in the artifact configuration.

Considering all pairs of

  • text matches recognized as links and
  • text matches recognized as artifacts,

the text file adapter assumes that a link and an artifact belong to each other in any of the following cases:

  • Artifact text and link text overlap.
  • The artifact text follows the link text somewhere on the same or the next line, possibly interspersed with some text that neither matches any link nor artifact regular expression.
  • An artifact can be preceded by multiple links and belong to all of them. These links must be arranged on consecutive lines, possibly interspersed with some text that neither matches any link nor artifact regular expression.

Please note: A consequence of these rules is that you can have an arbitrary sequence of links, interspersed by arbitrary text, and followed by an artifact. Links and artifacts can be distributed over several consecutive lines – with one restriction: Each of the lines must contain at least (part of) one link or (part of) the artifact. Any other line interrupts the sequence of links. Link texts preceding such a line are „lost”, i.e., they don’t belong to an artifact and thus don’t establish any links.

Consider the following example:

@TestMy Result 1
REQ01 SecondRequirement
@TestMy Result 2
Some Text
@TestMy Result 3
@TestMy Result 4 Some other text
@TestMy Result 5 REQ02 ThirdRequirement

In this example, the REQ01 artifact will be linked to My Result 1, REQ02 will be linked to My Result 3, My Result 4, and My Result 5. However, My Result 2 will not be linked to anything, because the line Some Text neither matches an artifact nor a link regular expression. However, it separates the block of link texts preceding it from the following link and artifact texts.

Eclipse editor drag-and-drop linking functionality

When you create links in YT by using drag and drop or by using the YT Editor, the link texts will be added in the lines above the artifact. Each link text will have its own line. Note that YT can delete a link only if its text is either contained in an artifact or it is the only text (except for whitespace) in the same line. This applies to all links created by YT itself, so only manual modifications of the text file can create read-only links. In the sample code provided above, YT can delete just the links to My Result 1 and My Result 3. This example also illustrates the reason for this restriction: if YT were to remove the text @TestMy Result 4 in order to delete the link to My Result 4, this would mean that My Result 3 wouldn’t be linked anymore. Removal of the complete line would also remove Some other text, i.e., other text which might contain valuable information.

This functionality requires the following:

  • A unique link type needs to be configured between the artifact type of the elements being dragged to the text editor and the artifact type of target elements in the text editor.
  • There must be only one writable mapping of type Text Editor for this link type, i.e., one with a create links by expression.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the text editor. If one of the conditions required for this functionality is not fulfilled, dropping is prevented and a message is shown that indicates the reason.

The configuration has the following structure:

  • analyze files of … – Defines which text file artifact type selected as link end should be used when searching for links. Possible values are A and B. The adapter will link artifacts of the selected type according to link text matches that are found in files of the corresponding data access.
  • locate links by – A regular expression that defines the portions in text files representing links.
  • map { … } – As an option, it is possible to define link attributes and derive their values, similar to the identifier derivation specified by identified by in the of an artifact type configuration.
  • create links by … – This expression specifies how YT evaluates the text that represents a new link, which is to be created. The specification is a concatenation of static strings and artifact attribute values. Please make sure that links created according to this expression can be recognized by the pattern specified in the locate links by expression. YT itself does neither check nor guarantee this.
  • where – Specifies attributes that are relevant for identification of artifacts on the „other” side to be linked to a text file artifact.

In where sections, it is possible to add several rules to match groups in the regular expression specified by locate links by to attributes of the relevant artifacts. A rule is expressed by an equation of the form LeftHandSide = RightHandSide . The LeftHandSide is a concatenation of static strings and groups (accessed via the keyword group( name) in the same way as in the artifact type configuration) referring to the regular expression. The RightHandSide is a concatenation of static strings and values of artifact attributes and/or the artifacts metadata Identifier and Resource. For link creation, each of these expressions must match, i.e., they are linked by logical AND.

Links of this link type will never become suspicious.

Eclipse text editor drag-and-drop linking functionality

YT supports the creation of links by dragging elements from various YT views and dropping them into the Eclipse text editor.

This functionality requires the following:

  • A unique link type needs to be configured between the type of artifacts being dragged to the text editor and the type of target artifacts in the text editor.
  • There must be only a single mapping of type Text file for this link type. Additionally, this mapping needs to support link creation by inserting text into text files.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the text editor. Link text is inserted at the beginning of the line that the element is dropped at, the modified contents of the text editor is saved to disk, and a link is created automatically. If one of the conditions required for this functionality is not met, a dialog indicating the failure reason is shown.

YAKINDU HMI

Artifact type

Configuration

Supported options:

  • resource – File filter pattern
  • subset metaclass – Filter elements by meta class
  • subset namespace – Filter elements by namespace
  • subset stereotype – Stereotype filter

Example:

resource *.hmi
subset sgraph.State

In the above example, elements of meta-type sgraph.State from files with names ending on .hmi are taken into account.

Version

An artifact’s version is used for suspicious links validation. Artifacts of this type do not provide a version.

YAKINDU Model Viewer

YAKINDU Model Viewer is a tool to visualize Matlab Simulink and Matlab Stateflow models. YAKINDU Traceability is able to extract blocks, states, and transitions from these models as traceable artifacts. It can also read element (block, state, transition) parameters, including name, path, and type.

The blog post "Traceability for Matlab Simulink and Matlab Stateflow" presents the YAKINDU Model Viewer adapter as our April 2017 „feature of the month”, on the occasion of several improvements we did to the adapter.

Data Access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select YAKINDU Model Viewer files as data access type.

Supported options:

  • resource – A pattern for a project, folder or file in the workspace. Supported formats are MDL and SLX.
  • undefined attribute value – Optional: Specify the value to use when trying to read the parameter of an element when the parameter doesn’t exist, see "Artifact type".

The configuration may contain several resource definitions.

Example:

resource "*.mdl"
undefined attribute value = "<N/A>"

In the above example, elements from files with names ending on .mdl are taken into account.

Artifact type

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured YAKINDU Model Viewer data access in the Data access drop-down list.

Supported options:

  • include blocks – Starts an include blocks expression. An artifact will be created for each block.
  • include states – Starts an include states expression. An artifact will be created for each state.
  • include transitions – Starts an include transitions expression. An artifact will be created for each transition.
  • if – optional expression following an include expression. If no if expression is specified, all elements will be matched. If several conditions are specified in the same expression, an artifact will be created only if the element matches all conditions.
  • valueOf – Retrieves the value of the specified attribute for the current element. The attribute can be the name of any parameter defined in the model for this element. The following attributes are predefined for convenience, but any value can be specified:
    • name – The name of the block, or the label of the state or transition
    • type – The type of the block, empty for states and transitions
    • path – The path of the element. It is unique within a given file resp. model
    • source – For transitions, the name of the source element (state label or junction ID). May be empty.
    • target – For transitions, the name of the target element (state label or junction ID). May be empty.
  • != – „Not equals” operator to use within a condition. The operator will match if the left and right operands have different values.
  • == – „Equals” operator to use within a condition. The operator will match if the left and right operands have the same value.
  • in – „In” operator to use within a condition. The operator will match if the value of the left operand is equal to one of the values in the right operand.
  • contains – „Contains” operator to use within a condition. The operator will match if the value of the right operand is a substring of the value of the left operand.
  • name – Specifies an element name or a generic name of matched artifact.
  • map – Starts a mapping element for an element or a generic mapping for all elements.
  • to – Defines the relation of a custom attribute to the value it is mapped to.
Please note: an empty configuration is valid. In this case, one artifact will be created for each element (block, state, or transition) found in the model. The name of the artifact will correspond to the name of the element. If the element has no name, a default name will be assigned, i.e., _[Block]_, _[State]_, _source -> target_, respectively.

Example:

include blocks if(
	valueOf(name) in ("data""speed""Gain")
	valueOf(type) == "Inport"
){
	name "B1_"+valueOf(name)
	map{
		nameB to valueOf(name)
	}
}
include blocks if( valueOf(path) contains "collision_avoidance/collision avoidance/"){
	name "B2_"+valueOf(name)
	map{
		pathB to valueOf(path)
		typeB to valueOf(type)
	}
}
include states {
	name "S_"+valueOf(name)
	map {
		nameS to valueOf(name)
	}
}
include transitions if(valueOf(name)!=""){
	name  "T_"+valueOf(name)
	map{
		nameT to valueOf(name)
	}
}
map{
	Custom to "Test"+valueOf(name)
	IconDisplay to valueOf("IconDisplay")
}

In the above example:

  • All blocks with a name in („data”„speed”„Gain”) and a type of „Inport” will be matched. The name of their respective YT artifacts will be the name of the Simulink blocks prefixed by „B1”.
  • All blocks with „collision_avoidance/collision avoidance/” in their path will be matched. The name of their respective YT artifacts will be the name of the Simulink blocks prefixed by „B2”.
  • All states will be matched. The name of their respective YT artifacts will be the name of the Simulink states prefixed by „S”.
  • All transitions with a non-empty name will be matched. The name of their respective YT artifacts will be the name of the Simulink transitions prefixed by „T”.
  • The element attributes nameB, pathB, typeB, nameS, and nameT will be mapped to the corresponding attributes of the YT artifact of each element (B: blocks, S: states, T: transitions).
  • The generic attribute Custom will hold the concatenation of the value „Test” and the name of the Simulink element.
  • The generic attribute IconDisplay will hold the value of the element’s „IconDisplay” parameter. If that parameter doesn’t exist for this element the value will be „<N/A>”, as specified in the Data access configuration.

We use the following model from YAKINDU Model Viewer:

And here are the resulting artifacts in YAKINDU Traceability:

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

Using the YAKINDU Model Viewer link type, it is possible to manage links that start at a Simulink artifact and point to any other artifact.

For example, let’s say Simulink blocks should be linked to requirements, which reside in a totally different data source, e.g., PTC Integrity. To achieve this, you can store the requirement ID in a parameter of the Simulink block, e.g., parameter A. You will do so by configuring YT in such a way that on link creation it stores the requirement ID in that parameter.

Generally, such links are maintained by populating a parameter of the Simulink element with the ID(s) of the referenced artifact(s) at the other end of the link. If the cardinality of the link is larger than one, the IDs of the referenced artifacts are joined in the parameter.

Using the YAKINDU Model Viewer link type requires at least one link type mapping with a configured YAKINDU Model Viewer data access. At least one of the artifact types selected for the link type must be a configured YAKINDU Model Viewer artifact type.

Open the YT configuration with the YT configuration editor, and add a new link type as described in section "Configuring a link type".

Supported keywords are :

  • analyze attribute of … locate links by … where … – Defines the condition to be fulfilled in order to derive trace links from a Simulink block. Left from locate, a custom attribute of the source artifact type must be provided. It must reference artifacts of the target type within the parameter. Right from by, a regular expression is required which is matched against the value of the parameter. The constraints right from where define which values have to match between the pattern and the opposite artifact in order to derive a link.
  • group – Defines access to matching groups of the regular expression in the by clause.
  • A.x, B.y – Allows to reference custom attributes of the opposite artifact (depending on the attribute of clause in the mapping).
  • create links by … – Defines an expression to create links appended with a space at the end of the parameter text, for link creation. Afterwards, the text should be identified using the regular expression in order to load the link.

Link creation and deletion are supported for .slx files only.

Example:

analyze attribute of B.valueOf("data.codecomment")
locate links by "Req-(?<ID>\\d+)" {
	where {
		group("ID") = A.IDX
	}
}
create links by {
	"Req-"+A.IDX
}

The sample configuration above describes a link type mapping from artifacts of the YAKINDU Model Viewer artifact type (artifact B) to requirement (artifact A). The custom attribute A.IDX is used in the parameter of the block of type B to reference the artifact.

The configuration tells YT that the IDs of the linked artifacts should be written into or read from the map parameter data in the key codecomment" in blocks of artifact type B. Within that parameter, YT looks for strings starting with the Req- prefix followed by at least one digit. YT derives a link whenever one of the matching IDs is equivalent to B.IDX, i.e., the ID of the requirement.

If a new link is created, the value of B.IDX is prefixed with Req-, and this value is appended to the end of the parameter value.

Links of this link type will never become suspicious.

YAKINDU Model Viewer Decorations

Currently YT supports decorations in order to indicate whether an element opened in the YAKINDU Model Viewer editor is linked to other elements. Accordingly, once an element has been opened in the YAKINDU Model Viewer editor, it is decorated with a YAKINDU logo if it is linked. Additionally, if this decoration icon is hovered upon, a tooltip appears, indicating the number of links referring this element. This is shown in figure "Linked elements are marked in YAKINDU Model Viewer".

Linked elements are marked in YAKINDU Model Viewer

Linked elements are marked in YAKINDU Model Viewer

Once the decoration icon is clicked, a context menu listing the linked artifacts opens, see figure "Listing linked artifacts in YAKINDU Model Viewer". If you hover over the context menu item of one of these elements, a tooltip appears showing a small summary of this element. Clicking one of the linked elements in the context menu opens it.

Listing linked artifacts in YAKINDU Model Viewer

Listing linked artifacts in YAKINDU Model Viewer

Please note: The YAKINDU Model Viewer decoration uses technology that currently requires low DPI settings on Microsoft Windows. To run YT in a low DPI setting, please run YT once using the YT_Low_Dpi.bat executable, located in the YAKINDU Traceability installation folder. To continue working with this setting, you can from there on run YT normally using the YT.exe executable. In order to restore normal DPI settings, run YT once using the YT_High_DPI.bat executable, which is also located in the YAKINDU Traceability installation folder. After that, YT can be run as usual, using the YT.exe executable.

YAKINDU Statechart Tools

The YAKINDU Statechart Tools adapter identifies states and transitions of statecharts created with YAKINDU Statechart Tools as traceable artifacts.

Why should you use YAKINDU Traceability to trace statecharts? The blog post "How to ensure traceability for Statechart Tools" explains it.

Elements traced by YAKINDU Traceability are decorated with a YAKINDU logo in YAKINDU Statechart Tools, as shown in figure "Linked elements are marked in YAKINDU Statechart Tools".

Linked elements are marked in YAKINDU Statechart Tools

Linked elements are marked in YAKINDU Statechart Tools

Once the decoration icon is hovered upon a small tooltip appears showing the number of elements linked to this element. Additionally, a context menu listing the linked artifacts opens once the decoration is clicked, see figure "Listing linked artifacts in YAKINDU Statechart Tools". Clicking one of the linked elements in the context menu shows a tooltip summarizing this element and a double click opens this element.

Listing linked artifacts in YAKINDU Statechart Tools

Listing linked artifacts in YAKINDU Statechart Tools

YT Query-based link extraction

Data access

The YT query-based data access derives links between artifacts based on queries of the YT query language.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Query-based as data access type.

Within the configuration panel, no further configuration will be done. Instead, the link type provides means to define the query, see section Link type.

Example:

The example shows the definition of a query-based data access. Create a new data access, give it a name, and pick Query-based from the Type drop-down list. No further configuration is required.

YAKINDU Traceability can derive links based on the query language.

Please find below the required steps to specify such a derivation rule.

The configuration consists of a query. Usually queries will produce a table with multiple columns as output. In order to derive links and attributes from this table it is required to stick to certain conventions. The query result has to contain one column named ArtifactA and another column called ArtifactB. The values in these columns have to match those specified as Artifact Type A and Artifact Type B, respectively. You can specify additional columns for the query. If the link type defines a custom attribute with the same name as a column, the column’s value in the query result will be assigned to this attribute for the created link.

Example:

The example shows the definition of a query-based link type between EA Operation and TestCases (Excel). The links are inferred by the query that is defined in the mapping section. The query will collect traces from EA Operation to TestCases (Excel). Queries output a table. In order to use a query for link inference it is required to have columns named ArtifactA and ArtifactB as shown in the collect clause.

Links of this link type will never become suspicious.

XML

Data access

The YT adapter for XML files provides access to any nodes in the XML Document Object Model. The adapter can also access nodes in HTML files.

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select XML as data access type.

Within the configuration panel, you may specify file patterns consisting of projects, folders or file name patterns which describe the XML files relevant for traceability.

Supported keywords:

  • resource – A pattern for an XML (or HTML) file path.
  • zipped in – A pattern for a zipped file in the workspace.
  • as html – Indicates that the resource is an HTML file and thus does not have to be well-formed XML.
  • validation DTD – Configures whether the content should be validated or not. Validation is enabled by default. Add validation DTD = false to disable the validation.

The configuration may contain several resource definitions. If zipped in is appended to the resource definition, the resource is the path inside the ZIP file and the pattern following zipped in denotes the archive file in the workspace.

Please note: YT does not support selection propagation for HTML files and resources in ZIP files.

Example:

resource "TESSY_OverviewReport.xml"
validation DTD = true
zipped in "/com.yakindu.yt.mt.spec/test/TESSY_OverviewReport.zip"

If the example file was an HTML file, the configuration would be:

resource "TESSY_OverviewReport.html"
zipped in "/com.yakindu.yt.mt.spec/test/TESSY_OverviewReport.zip" as html

Artifact type

This adapter supports the selection of XML nodes and opening and selecting artifacts within the Eclipse XML Editor, unless the XML file resides in a ZIP archive. The XML files have to be defined in the XML data access.

The adapter also supports to identify nodes within HTML documents as artifacts. Internally, each HTML document is converted into an XML document with the same structure. This allows you to select HTML nodes in the same way as XML nodes.

Configuration

Supported options in the configuration:

  • artifact source ID where – The unique ID for this artifact source. Multiple element sources can be used in the configuration, allowing to use different element matches conditions or mapping configurations.
  • element matches – XPath expression for selecting artifacts
  • name – Name for the matched artifact
  • identified by – An optional key for an artifact in this document. If specified, it should return a value which uniquely identifies the artifact. If the same value is returned for several XML resp. HTML nodes, YT will only create one artifact.
  • map – Starts a mapping block for specifying custom attributes.
  • valueOf – XPath expression
  • joined – Follows a valueOf( XPath Expression) statement and allows to join (concatenate) the elements of a list into a single string, separated by the default separator ,.
  • joined with separator – Follows a valueOf( XPath Expression) statement and allows to join (concatenate) the elements of a list into a single string, separated by the specified separator.

Example:

Adapter configuration:

artifact source Node where (
    element matches "/testrun/testsuite/testcase"
)
{
    name valueOf("@classname") + "." + valueOf("@name")
    identified by valueOf("@classname") + "." + valueOf("@name")
    map {
        fqn to valueOf("../../@project|../@name|@name")
                joined with separator "/"
    }
}

In the above example, the artifacts will be all XML nodes named testcase contained in the specified path, i.e.:

<testrun> <!-- Root element of the document (/testrun) -->
  <testsuite>
    <testcase classname="testClassName" name="matchedTestName"/> <!-- Matched artifact -->
  </testsuite>
</testrun>

The XPath expressions for name, identified by and mapped attributes will be evaluated against the XML node for each artifact. So, the expression @classname will correspond to the attribute classname of the <testcase> node.

Element matcher

Selectable XML nodes are specified by an XPath expression following the element matches keyword. HTML nodes can be addressed in the same way.

Given the following XML document, the above XPath expression /testrun/testsuite/testcase will select a single <testcase> … <testcase>. If the testcase node had siblings, all of them would be selected.

Sample JUnit result:

<?xml version="1.0" encoding="UTF-8"?><testrun name="EmergencyHandlerTest" project="de.itemis.aad.implementation.java" tests="1" started="1" failures="1" errors="0" ignored="0">
  <testsuite name="de.itemis.aad.EmergencyHandlerTest" time="0.001">
    <testcase name="testActivateEmergencyState" classname="de.itemis.aad.EmergencyHandlerTest" time="0.001">
      <failure>java.lang.AssertionError: Failed as expected!
    at org.junit.Assert.fail(Assert.java:88)
    at de.itemis.aad.EmergencyHandlerTest.testActivateEmergencyState(EmergencyHandlerTest.java:11)
      </failure>
    </testcase>
  </testsuite>
</testrun>

See XML Path Language (XPath) Version 2.0 for a complete XPath documentation.

Value references

The name and identified by properties from the previous example are expressed as concatenation of value references:

name valueOf("@classname") + "." + valueOf("@name")

The valueOf keyword introduces a value reference containing an XPath expression. The context of the nested XPath expressions is the matched node from artifact source. For instance the full XPath expression for name valueOf("@classname") is "/testrun/testsuite/testcase/@classname", given that only a single testcase node is contained in the XML document.

If the evaluation of the XPath expression returns a list of elements, it is possible to concatenate the results of this list to obtain a single string attribute. This is achieved using the joined with separator keyword. For instance:

map {
    time to valueOf("//testcase/@time") joined with separator ';'
}

The resulting string will be the concatenation of the time for each testcase contained in the document, separated by semicolon, e.g., 0.001;0.023;0.358. If the separator is not specified, it defaults to a comma ,.