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 → Adapters. 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 include an „/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.

Launcher for the DOORS client

By default the doors client is started against the doors server configured while it was installed. If no client is running, YT starts the doors client with default parameters against this database. Instead of launching the client by the official API, a launcher, like a batch file, can be configured. Whenever a client is required and no one is running, the launcher will be used to open the doors client. The launcher is specified in the preferences.

  • Goto Window → Preferences, YAKINDU Traceability → Adapters.
  • In the IBM DOORS block the path to the executable can be entered or selected.

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
  • contains_not – Constraint for absence of a substring
  • in – „In” operator to use within a condition. The operator will match if the value, or one value in case of multi value enumarations, of the left operand is equal to one of the values in the right operand.
  • not_in – Negation of „in” operator to use within a condition. The operator will match no value of the left operand is equal to any of the values in the right operand.
  • 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.

YT supports two kind of link information in doors. Doors internal links are native doors links between doors objects and saved in link modules. Links can be stored as external link in doors also.

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. The operator will match if the value of the left operand is equal to one of the values in the right operand.
  • 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”.

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

The configuration panel allows to define the direction of a DOORS link in YT. By default the external link is read from link end A, which needs to be an artifact from doors in this case. The configuration language offers content assist to guide you through the various options.

Supported keywords:

  • external link – Specifies that the link is mapped by external link data of a DOORS objects. By default link end A is evaluated and needs to be a DOORS object
  • source is A|B – Explicit define the link end artifact whose external link data is evaluated and written for invasive storage of links.

Links of this link type will never become suspicious.