IBM Engineering Requirements Management DOORS Family

Key Features and Benefits

• Synchronizes requirements in DOORS to Agile planning, test management and other tools, allowing information to flow freely between DOORS and other tools
• Improves team collaboration by allowing systems engineers to specify requirements in DOORS, and software engineers to receive and work on the requirements in their tool of choice
• Provides traceability of requirements across Systems Engineering and Software Engineering, removing the need for manual processes and spreadsheets
• Ensures that changes in DOORS are instantly exposed to the software team
• Ensures that requirements are up to date in all tools

Common Integration Patterns

• Providing Developers with Early Visibility into Requirements
• Providing Testers with Early Visibility into Requirements
• Associating Requirements to Detailed Design
• Linking Code Changes to the Originating Feature or Defect
• Sharing Customer Feature Requests with Product

Demo Videos

Minimal User Permissions & Hub User

We recommend that you create a new user within your external tool, to be used only for your Hub integration. This is the user information you will enter when setting up your repository connection within Planview Hub. By creating a new user, you will ensure that the correct permissions are granted, and allow for traceability of the modifications that are made by the synchronization. 

In general, your user account should have sufficient permissions to create, read, and update artifacts in your repository. However, depending on the use case, your user may need different permissions. For example, if you are only interested in flowing data out of your repository, your user may not need to have full CRUD access, as the 'create' and 'update' permissions may not be needed.

Your user should have a secure password or token. Please be aware that Hub will not allow you to save a repository connection utilizing a weak password/token, such as 'tasktop.'

See instructions on how to create a custom user in IBM Engineering Requirements Management DOORS Family.

List of minimal permissions:

• The Hub user must have Edit DXL power to create repository connections without error.

Note: We recommend disabling the Enable DXL Restrictions option if enabled. To disable this setting, navigate to the database properties window, open the DXL Security tab and deselect the Enable DXL Restrictions option.

Connecting to the IBM Engineering Requirements Management DOORS Family

Note: The DOORS connector runs only on Windows.

Before connecting, follow the instructions below:

1. Go to the Services menu in Windows.

2. Right click Tasktop and select Properties.

3. Go to the Log On tab and add the credentials used to log onto Windows. The user must have sufficient privileges to run Tasktop as a service. In general, the Administrator should have the necessary permissions.

Once these steps are completed, you can configure your repository connection in Planview Hub.

Required Fields:

• Location/Connection URL
  • Example Format: doors://DOORSserver.com:36677/

    • Note: The URL for server connection requires specific formatting: doors://<server>:<port>(e.g., doors://localhost:36677). Note that this is slightly different from the format used by DOORS (i.e., 36677@localhost). The default for port is 36677 and can be omitted in that case.

• Path to doors.exe
  • The DOORS connector requires the DOORS client to be installed. The path to the doors.exe file must be provided when specifying connection settings. Please consult DOORS documentation for instructions on how to install the client on your machine.
  • Example Path: C:\IBM\DOORS\Family\9.5\bin\doors.exe. This is the same executable used to launch the DOORS native client.
• Username
• Password

Optional Fields:

• Folder Hierarchy Filters
  • This field improves performance by specifying the subset of your Doors Folder Hierarchy that you'd like available for your Planview Hub collection.
    • Note: All entries should be separated by comma and start with a / and end without a / (e.g., /Project 1, /Project 2/Folder 1)
  • The descendant folders and modules of the hierarchy specified will also be available.

Note: Please ensure that the DOORS client is configured to communicate with the DOORS server in a way that aligns with your security policy.

Learn more about how to set up your repository in Planview Hub here.

Object ID Field

DOORS has a field called “Object ID” that is constructed from the Module Prefix and Absolute Number field. This field functions as a unique ID for requirement objects. 

If you'd like to flow the entire Object ID from DOORS, please follow the instructions below:

1. Map both the Module Prefix and the Absolute Number field on the DOORS side to the Formatted ID field on the model side:
   

2. Create an extension to concatenate the two fields (please review full instructions here)

   var inputTypes = [‘String’, ‘Long’]; 
   var outputTypes = ‘String’;
   
   
   function transform(context, input) {
   return input0+input1 }
   

3. Click 'Configure' next to your field mapping and select the extension on the right (model) side.

Attachments

Attachments are supported one way out of the DOORS repository.  Embedded images will be taken out of the description and synchronized as file attachments in the integration. 

Learn more about how to configure attachment flow in Planview Hub here.

Full Scan

Due to third party API limitations, changes to the following fields may not trigger change detection or cause a synchronization immediately. To ensure these updates synchronize, a high fidelity full scan must occur or another qualifying change must be made to the artifact:

• Absolute Position field

Learn more about how to configure change detection and full scan intervals in Planview Hub here. 

Requirements Ordering

Note: Requirements Ordering is only supported for DOORS-codeBeamer integrations.

For requirements ordering to function correctly, the following fields must be mapped in your integration:

• Absolute Position

• Parent

• Predecessor

• Successor

Additionally, the field flow for the above fields must be set to always update to the target side, the conflict resolution must be set to the source side, and artifact creation flow should be one way from the source side to the target side.

Note: During integration, you may see a large number of errors with the message “Predecessor and Successor are not in the right place yet..." These exceptions should clear with sufficient retries. If not, you will need to trigger a full scan through the “Process All Artifacts” button.

Architectural Challenges

Aligning differently architected systems is challenging, as it requires creating a common language across systems built for different purposes. For DOORS and Agile tools such as Jira, there are a few things to keep in mind when designing an integration:

While DOORS presents an organized, document-based view of objects, Agile tools, such as Jira do not have such a logical view: Jira projects are big buckets of individual artifacts (such as stories or defects) that can be managed and scheduled. While DOORS presents a logical and ordered outline-based view of requirements, an Agile tool such as Jira does not contain any intrinsic order to its artifacts.  When viewing a list of stories in a Jira backlog, for example, there is no logical connection between two Jira stories listed in a row.

While the DOORS architecture allows you to have multiple objects contribute to the same logical entity (requirement), each Agile artifact is represented by one object. Trying to manipulate multiple individual DOORS objects into one Jira object can present various integration challenges:

• Change of order or change of indention can interfere with the correct information being synchronized for requirements

• If a requirement spans multiple items in DOORS, this cannot translate to an individual artifact-based architecture of an Agile tool

Integration Solutions

At Hub, we have worked with many customers and identified integration patterns that can alleviate some of the challenges listed above.

Below are some of the best practices we suggest to our customers based on the use cases we most often see:

Integration Planning

Before configuring your integration, take a step back and decide what information users in your Agile tool will truly need access to.  Since Agile tools such as Jira do not allow for logical document outlines, we must think in terms of singular artifacts.  For example, in a sample document below, what Jira users really care about are the two requirements at the bottom of the document.

Special Features Supported

Supported Work Items