IBM DOORS Next

The IBM DOORS Next adapter supports extraction of traceability information from projects and streams of an IBM DOORS Next database. The database utilized for extraction of this information is the Lifecycle Query Engine (LQE) database. Objects in the database can be recognized as artifacts in YT and relations between these objects can be loaded as trace links in YT.

In the rest of this section, we will refer to „IBM DOORS Next” as „DOORS Next”.

This adapter supports selection propagation from YT to DOORS Next, but not vice versa: double-clicking on a DOORS Next artifact in YT will display this artifact in a web browser.

Data access

The DOORS Next data access configuration specifies the DOORS Next database server to connect to and the projects and streams of artifacts to load.

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 Next as data access type.

Supported keywords:

  • server – The DOORS Next server’s URL or the server’s IP address and port number
  • projects – The project(s) on the DOORS Next server from which YT will load artifacts and links
  • streams – The stream(s) that belong to a specific project or component on the DOORS Next server from which YT will load artifacts and links

Sample configuration:

server "192.168.3.160:9443" 
projects {
"MY_PROJECT_1"
 streams { "MY_PROJECT_1 Initial Stream"},
"MY_PROJECT_2"
 streams { "MY_PROJECT_2_STREAM_1","MY_PROJECT_2_STREAM_2"}
}

In the example above, YT will connect to a DOORS Next database server at the IP address 192.168.3.160 on port 9443. YT will consider objects and links from the stream MY_PROJECT_1 Initial Stream of project MY_PROJECT_1, and from the two streams MY_PROJECT_2_STREAM_1 and MY_PROJECT_2_STREAM_2 of project MY_PROJECT_2.

When you first start YT with the adapter enabled, a dialog will ask you for a user name and password for the database login. You can store this information in Eclipse’s Secure Store such that you don’t need to re-enter it later.

You can also provide the login credentials as java system properties DOORS_NG_LOGIN_USER_NAME and DOORS_NG_LOGIN_PASSWORD. You can set these properties either directly via the the command line or in a configuration file that you specify with YT’s --properties command line option (see Executing YAKINDU Traceability in batch mode ). Alternatively, you can define environment variables with the same names.

Artifact type

The DOORS Next adapter allows for flexible artifact configuration to specify which artifacts YAKINDU Traceability should import from the DOORS Next 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 DOORS Next data access in the Data access drop-down list.

Keywords

Supported keywords:

  • include objects if( cond1 cond2 …) – Defines a filter that decides which objects in the database YT should load as artifacts. Objects will be included only if they fulfill all of the given conditions cond1, cond2, etc. specified in the parentheses. Each condition includes one of the operators given below to compare the value of an object attribute against one or several strings. Please refer to the explanation below this keyword list for more details about how filtering works.
  • collections() – Names of all collections which contain an item. Duplicate names are filtered and all names are comma separated.
  • collections.valueOf( attributeName) – References the value of a collection attribute with the name attributeName.
  • == and != – Checks if the attribute value matches a given string. If it does, == is fulfilled, otherwise != is fulfilled. For attributes that can hold multiple values, == is fulfilled if the given string matches any of the values the attribute holds. However for collections, == is fulfilled if and only if the item is contained in all the collections specified (a string that contains one or more strings separated by commas), otherwise != is fulfilled.
  • contains and !contains – Checks if the attribute value contains a given string. If it does, contains is fulfilled, otherwise !contains is fulfilled. For collections, contains is fulfilled if the item is contained in all the collections specified (a string that contains one or more strings separated by commas). It is also fulfilled if the string specified is contained in the name of a collection. In all other cases !contains is fulfilled.
  • in and !in – Checks if the attribute value is in a given list of strings. If it does, in is fulfilled, otherwise !in is fulfilled. For attributes that can hold multiple values, in is fulfilled if any string in the given list of strings matches any of the values the attribute holds.
  • map – Starts a mapping block. This is optional.
  • name – Defines the name of the artifacts.
  • valueOf( attributeName) – References the value of an object attribute with the name attributeName. It can be either a built-in attribute or a custom attribute. Built-in attributes are:
    • "Type" – The type of an artifact.
    • "Project" – The name of the project where the artifact is contained.
    • "Component" – The name of the component of the artifact.
    • "ArtifactURI" – All URIs for the artifact. Each artifact has at least one URI itself. For each collection containing this artifact an additional URI exists for the context inside the collection.

To filter artifacts delivered by the data access, the include objects if( cond1 cond2) expression is used. It instructs the DOORS Next adapter to only consider objects as artifacts that satisfy all of the specified conditions. If the list of conditions is empty, all objects will be included as YT artifacts.

A condition is defined by the following syntax:

  1. valueOf( attributeName ) operator value
  2. collections.valueOf( attributeName ) operator value

Here,

  • operator is one of the boolean operators given in the list above, and
  • value is either
    • a literal string, like „foobar”, in case of ==, !=, contains, and !contains, or
    • a list of strings of the form ( " str1" " str2" … ), in case of in or !in.

As attributeName, you can use the name of a custom attribute that you defined. You may also use the name of a built-in object attribute. You can get a list of the available names via content assist after valueOf( in the configuration editor.

Attributes of DOORS Next objects can have multiple values, while each custom attribute in YT can only have one value. Hence, multi-valued attributes of DOORS Next objects will be concatenated to a single string. As a separator of the individual values, ", " is used (a comma, followed by a single space). To indicate that the string value represents a multi-valued attribute, it is surrounded by brackets, i.e., [ and ]. For example, an attribute with the values One, Two, and Three will be converted to the string [One, Two, Three]. Note that this conversion also happens before YT performs any comparison that is defined in an include objects if condition. There are several examples below that explain each of the supported keywords for conditions.

Examples:

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Created On") !contains "2019"
	valueOf("Status") in ("Approved" "Draft")
	collections() == "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose Type is Feature and whose Created On attribute does not contain the string 2019 and that have a Status of either Approved or Draft and they belong to both the collections Release 1 and Release 2.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") == "2019"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and MultiValuedAttribute has at least one of its values as 2019.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") != "2019"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose MultiValuedAttribute does not hold 2019 as one of the values.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") contains "2019"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose MultiValuedAttribute contains 2019 in any of its values.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") !contains "2019"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose MultiValuedAttribute does not contain 2019 in any of its values.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") in ("2019" "2020")
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose MultiValuedAttribute contains either 2019 or 2020 in any of its values.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("MultiValuedAttribute") !in ("2019" "2020")
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose MultiValuedAttribute contains neither 2019 nor 2020 in any of its values.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Status") == "Approved"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Status is Approved.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Status") != "Approved"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Status is not Approved.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Created On") contains "2020"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Created On contains the string 2020.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Created On") !contains "2020"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Created On does not contain the string 2020.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Status") in ("Approved" "Draft")
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Status is either Approved or Draft.

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Status") !in ("Approved" "Draft")
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and whose Status is neither Approved nor Draft.

include objects if(
	valueOf("Type") == "Feature"
	collections() == "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects belong to both the collection Release 1 and the collection Release 2 and not just one of them.

include objects if(
	valueOf("Type") == "Feature"
	collections() != "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects belong to neither the collection Release 1 nor the collection Release 2.

include objects if(
	valueOf("Type") == "Feature"
	collections() contains "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects belong to both the collection Release 1 and the collection Release 2.

include objects if(
	valueOf("Type") == "Feature"
	collections() !contains "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects are not cointained in neither the collection Release 1 nor the collection Release 2.

include objects if(
	valueOf("Type") == "Feature"
	collections() contains "Milestone"
	collections() !contains "Release"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects belong to the collections whose name contains the string Milestone and the collections whose name does not contain Release.

include objects if(
	valueOf("Type") == "Feature"
	collections() in "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects are in both the collection Release 1 and the collection Release 2 and not just one of them.

include objects if(
	valueOf("Type") == "Feature"
	collections() !in "Release 1, Release 2"
)
name valueOf("Identifier") + ": " + valueOf("Title")

The example above will include DOORS Next objects as artifacts whose whose Type is Feature and if the objects are neither in the collection Release 1 nor in the collection Release 2.

You can map attributes, too. Example:

include objects if(
	valueOf("Type") == "Feature"
	valueOf("Created On") !contains "2019"
	valueOf("Status") in ("Approved" "Draft")
)
name valueOf("Identifier") + ": " + valueOf("Title")
map{
	difficulty to valueOf("Difficulty")
	status to valueOf("Status")
}

This example expands the previous example. Here we are mapping two custom attributes to the values of the attributes Difficulty and Status of a DOORS Next object.

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 DOORS Next adapter allows to specify which links YAKINDU Traceability should import from the DOORS Next 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".

Supported keywords:

  • link source is A|B – This optional statement specifies the link source in DOORS Next. If the configured project in DOORS Next contains a link from an object A to an object B, YT will usually (i.e., without link source statement) create a link from the artifact representing A to the artifact representing B. The statement link source is B turns this around: a DOORS Next link from A to B will be loaded as a link from the artifact for B to the artifact for A. You can specify link source is A, but this is equivalent to an empty configuration, because it just defines the default behavior.

Example:

link source is B

As discussed above, this effectively turns around the link direction when loading links from DOORS Next into YT.

Links of this link type will never become suspicious.