Imprint Privacy policy Terms & Conditions Sitemap

Attribute mapping

Using the attribute mapping adapter, itemis ANALYZE 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.

This was just an simple example. If you want to read about more capabilities of Attribute Mapping go to the Mathematical Background chapter.

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 ANALYZE configuration with the ANALYZE 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 ANALYZE configuration with the ANALYZE 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 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]

You can combine several conditions in a logical conjunction by using the keyword and:

  • where A.attribute1 in B.attribute1 and A.attribute2 in B.attribute2
    • Creates links between all artifacts a and b where A.attribute1 has the same value as B.attribute1 and additionally A.attribute2 has the same value as B.attribute2.

You can switch A and B for each individual condition. For instance, you could switch A and B in the first condition of the previous where clause and leave the second condition as it is.

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.
    • and – You can use this boolean operator to combine several conditions. The adapter will only create a link between artifacts a and b when all of these conditions match for these artifacts.

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, itemis ANALYZE 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 the first example, we will configure ANALYZE to derive links between requirements defined in a Text 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 Text requirements. To match the identifier in the list to the specific Text requirement the contents in the Excel cell is traversed. The comma serves as separator to find out where the next identifier starts.

  • Activate ANALYZE’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.

In this second example, ANALYZE will be configured to derive links between test cases defined in a Microsoft Excel file (e.g. TestCases.xlsx) and their related test results which are stored in a copy of the TestCases.xlsx only with different suffix (e.g „TestReport.xlsx”).

The derivation is based on references in Excel: Each test case in Excel has a cell containing a unique identification number (id). These ids will be mapped to the corresponding ids in the test results table. In addition to the mapping of the identifiers, the resource names of both Excel files are also getting mapped to ensure that the test cases belong to the right test results.

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

  • Define the TestCases artifact type, including custom attributes:

  • Define the TestResults artifact type, including custom attributes:

  • Define a link type linking TestCases and TestResults 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 test case and test result artifacts belonging together.

Links of this link type will never become suspicious.

Mathematical background

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.

Common concepts Codebeamer