IBM Engineering Requirements Management DOORS Next
Overview
IBM Engineering Requirements Management DOORS Next (DOORS Next), formerly known as IBM Rational DOORS Next Generation (DOORS NG), is the requirements tool from IBM that provides support for defining, managing and reporting on requirements.
Business analysts and product managers love using a requirements management tool that’s build specifically for the work they do every day. But when it comes time to share that work with other members of the team, the lack of integration with the tools those colleagues use, creates unnecessary friction.
For example, testers need these requirements in order to create their test strategies. In fact, most test management tools assume that the requirements are surfaced in those tools. Without synchronizing the requirements from DOORS Next to their test management tools, testers are forced to manually copy the requirements from one tool to the next. Similarly, developers need access to the requirements in order to understand what to build.
Planview Hub enables DOORS Next requirements to be viewed and edited in third-party tools. This allows DOORS Next users to take advantage of the definition, management, and reporting capabilities of their tool while other users use different tools for development, testing or project management.
Key Features and Benefits
- Use Artifact Relationship Management to sync the artifacts in DOORS Next complex containment structure of folders, collections and modules, to artifacts in other systems – preserving the relationships between artifacts defined in DOORS Next in the target system.
- Use our OSLC rich hover support, combined with Artifact Relationship Management, to get instant visibility to any tool we connect to, directly in DOORS Next
- Synchronizes artifacts across the lifecycle, allowing information to flow freely between DOORS Next and other tools
- Improve team collaboration by connecting DOORS Next to third party tools and allow artifacts to be synchronized across the lifecycle.
- Support cross-tool traceability and reporting, removing the need for manual processes and spreadsheets.
Common Integration Patterns
Demo Videos
Connector Setup Details
This section describes the basic steps needed to prepare your IBM Engineering Requirements Management DOORS Next (DOORS Next) instance for use with Hub. Note that additional fields for synchronization or configuration of queries may be required depending on the requirements of your integration.
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 here for general help and here for specific license management.
List of minimal user permissions:
- Select Rational DOORS Next Generation - Analyst under Client Access Licenses
- The user will also need to be added as a member of the projects to be used, with the correct roles that allow for reading, creation and update of requirements.
Connecting to the IBM DOORS Next Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format: https://myIBM_DNG_Server.com:9443/rm
- Username
- Password
Optional Fields:
- Global Configuration Management Location:
- Add the Global Configuration application URL, if using Configuration Management
- Example Format: https://myIBM_GC_Server.com:9443/gc
- Throttling Settings: This field indicates the number of API calls that can be made per minute. See details here.
- Note: This field should only be set under the guidance of customer care as the ideal value is highly dependent on each customer's unique environment.
- Connection Security: If checked, insecure connections to this repository will be allowed. See details here.
SSO Authentication
Additionally, DOORS Next supports the following SSO implementations:
- Script (HTTP cookies)
- X.509 Certificate
Learn more about how to set up your repository in Planview Hub here.
Initialization and Changes Queries (Tasktop Sync)
Tasktop Sync uses queries in the ALM systems to determine the artifacts to synchronize and detect changes in the system.
The initialization query represents the full set of artifacts to synchronize and is only run on initial configuration or manually.
The changes query should be defined the same as the initialization query but include some time scoping information (e.g. last 7 days) as this is the query that is executed on the defined schedule to detect changes. In many cases, these queries can be defined in the ALM system, providing the power of the built-in filters to properly scope the synchronization. If this is not possible, Tasktop Sync provides other mechanisms for filtering items in scope.
DOORS Next connector offers various options for limiting the number of artifacts being retrieved from the repository. These are your options:
- Type-based search:Returns all artifacts belonging to a specified artifact type and format category that have been modified within a specified time frame.
- Folder-based search: Returns all artifacts belonging to a selection of folders in a specified project, and modified within a specified time frame.
- Collection-based search: Returns all artifacts belonging to a particular collection in a specified project, and modified within a specified time frame.
- Module-based search: Returns all artifacts belonging to a particular module in a specified project, and modified within a specified time frame.
- Scope-based search: Returns all artifacts belonging to a specified artifact scope. e.g. All folders in a particular project, or all requirements in a particular project.
|
Query |
Instruction |
|---|---|
|
Initialization Query |
Create a filter that will match the scope of the artifacts to be synchronized. For example, you could use Folder based search to only return items in a specified folder.
|
|
Changes Query |
For the Changes query in DOORS Next, start with the filter defined for the initialization query and select a shorter "Last Changed On" period. This will ensure the same artifacts will be in scope and ensure only recently updated artifacts will be updated.
|
Other Configuration Settings
Configuration Management Support
With CLM 6.0, IBM introduced the concept of Configuration Management, hereafter referred to CM. CM allows a DOORS Next user to create multiple versions of their entire project. These versions are realized as a Stream. Streams can be either local to the DOORS Next server or can be allowed to interact with external tools via Global Configuration Management (GCM). GCM allows an organization to aggregate streams from multiple tools within a single GCM Component. This allows a business analyst in DOORS Next and a tester in IBM Engineering Test Management to create multiple versions of a requirement in DOORS Next and associate multiple versions of a single test in RQM. This allows great reuse within the CLM ecosystem.
Hub supports DOORS Next CM by querying against a given requirement stream as it appears in a given Component. This requires a DOORS Next admin to create a Component in their GCM application and add their DOORS Next stream of interest to that Component. Then, in Hub, when requested, pick the DOORS Next project and Component of interest. This will encompass the DOORS Next stream of interest. If multiple streams are expected to be synchronized to another tool, each stream will need to be added to a separate Component and each of those Components will synchronize to a separate container in the target repository.
Since non-CLM tools do not support versioned artifacts in the same manner as IBM, each version of a given DOORS Next requirement involved in an integration will appear in the other tool as a separate and distinct artifact.
Hub supports GCM baselines as well. Simply treat a baseline as you would treat a stream. One item of note is that baselined requirements cannot be altered, therefore an integration with a DOORS Next baseline will by definition be a one-way integration out of DOORS Next.
If Global Configuration Management is implemented, please note that the ability to read/write specific links on DOORS Next artifacts may be removed. While a DOORS Next user can see these links in the DOORS Next UI, these links do not actually 'live' on the DOORS Next artifact and are not retrievable via the APIs Hub uses to retrieve artifacts and artifact attributes. The DOORS Next links are actually stored (and surfaced in the UI by) the IBM link index service.
A non-exclusive list of these links are:
-
Tracked By
-
Validated By
-
Implemented By
-
Affected By
If these specific link names are needed in an integration, we recommend creating a custom link type with a similar, but different name to take the place of these default links.
Note: OSLC rich hover capabilities are not supported in DOORS Next projects that have implemented global configuration management.
Change Set Management
Planview Hub: 19.4.1 and later
Tasktop Sync: 4.20.1 and later
IBM Engineering Requirements Management DOORS Next: 6.0.5 and later
Change set management is supported in the versions listed above. Please be aware of the following configuration requirements:
- In the DOORS Next stream details page, ensure that the following option is not enabled: To deliver this stream, change sets must be linked to an approved change request or work item
- In order to integrate with change set enabled streams, users must select a collection that includes the specific stream or configuration they want to integrate with. Collections that do not specify their stream or configuration cannot be supported with change set management.
Person Reconciliation
For person reconciliation, the following fields are available:
|
Fields Used for Hub’s Default Person Reconciliation Algorithm |
Field Names for Person Reconciliation Extensions (Note that these are case sensitive) |
Label in DOORS Next |
|---|---|---|
|
ID |
person-id |
Username |
|
Username |
person-username |
Username |
|
|
person-email |
Email Address |
|
N/A |
person-display-name |
Display Name |
Learn more about how to configure person reconciliation in Planview Hub here.
Module Support (Tasktop Sync Only)
Tasktop Sync supports integrations involving requirements within a DOORS Next Module. In order to do so, select the Module-based search in Tasktop Sync. Although a single requirement can reside in more than one Module, IBM recommends that users do not reuse requirements in this fashion. Currently, Tasktop Sync only supports read-only integrations for Module based integrations.
Planview Hub does not currently support Module-based containment.
Collection Support (Tasktop Sync Only)
Tasktop Sync supports integrations involving requirements in a DOORS Next Collection. In order to do so, select the Collection-based search in Tasktop Sync. DOORS Next requirements can live in multiple Collections. A DOORS Next Collection is an alternate organizational structure that is orthogonal to DOORS Next Folders. Since altering a requirement in one Collection will alter the requirement in all other Collections it's in, Tasktop Sync supports read-only integrations with Collection-based search.
Planview Hub does not currently support Collection-based containment.
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:
- Relationships (Multi-artifact link) fields
- Web links
Learn more about how to configure change detection and full scan intervals in Planview Hub here.
Frequently Asked Questions
Supported Features
Special Features Supported
|
Feature |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|
|
|
||
|
|
||
|
|
||
|
(State can flow as text - no transitions) |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
Supported Artifacts
Supported Work Items
Learn about the difference between containers and work items in Planview Hub here.
|
Supported Work Item Type |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
Requirement |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
Yes |
Supported Containers
Learn more about containment in Planview Hub here.
|
Containers that can synchronize between repositories |
Applicable Hub Versions |
Applicable Repository Versions |
Unique URL? |
|---|---|---|---|
|
Folders See Functional Limitations table for details Note: Beginning in Hub version 22.4, containers can be treated as work items. Learn more here. |
Planview Hub: 17.4 and later Tasktop Sync: 4.0 and later |
Any supported repository version: |
Yes |
|
Containers used to define the boundary of a collection (When clicking 'Manage Projects' on a Collection) |
|||
|
Projects |
Planview Hub: All |
Any supported repository version: |
N/A |
|
Containers used for artifact routing |
|
|
|
|
Projects, Folders |
Planview Hub: All |
Any supported repository version: |
N/A |
Supported Field Types
Note: If one field of a given type is supported, others that are also that type in theory should also work. However, sometimes there are instances in which this is not the case due to the repository. So, while we can claim support for fields at the type level, there is a chance that some specific fields of a given type will not synchronize properly.
|
Standard Field Type |
Does Hub support custom fields of this type? |
How is field type referenced in the repository? |
Sample Repository Fields Supported |
Particular Repository Fields NOT Supported |
|---|---|---|---|---|
|
|
|
String |
Revision Resource ID Formatted ID Summary Description |
|
|
|
|
Single Select |
Priority Severity Type Requirement Context Category Risk Status Priority |
|
|
|
|
Integer/Value |
|
|
|
|
|
Boolean |
|
|
|
|
|
Date |
Created On |
|
|
|
|
DateTime |
Modified On |
|
|
|
|
|
|
|
|
|
|
Float |
|
|
|
|
|
Integer |
|
|
|
|
|
|
Creator Owner |
|
|
|
|
|
|
Third Party Functional Limitation |
|
Learn how to configure relationships in Planview Hub here. |
|
|
|
|
|
|
N/A |
String |
Primary Text |
|
|
|
|
OSLC Links, Web Links |
|
|
|
|
|
|
|
|
String
Functional Limitations
|
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
Configuration Requirement |
Custom Field URI Custom field URI's must not end with any of the following text: tasktopProject, type, artifactFormatCategory, requirementContext, resourceID, uri, $resourceUri, ETag, configuration, component. If any of the above text is used, you will encounter errors when creating collections in Hub or artifact sets in Viz. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Known Defect |
State Field DOORS Next 7.0 does not return the allowable values for the State field. |
Planview Hub: All Tasktop Sync: 4.0 and later |
DOORS Next 7.0 |
|
Third Party API Limitation |
Module Requirements Updating the parent folder of a Module Requirement is no longer possible through the API in DOORS Next 7.0. |
Planview Hub: All Tasktop Sync: 4.0 and later |
DOORS Next 7.0 |
|
Third Party API Limitation |
Locked Requirements Updating a locked requirement will have no effect and DOORS Next will not give any indication that anything is wrong. Previous versions of DNG allowed Hub to detect the lock and retry the update, but this is no longer possible due to API changes. |
Planview Hub: All Tasktop Sync: 4.0 and later |
DOORS Next 7.0 |
|
Third Party API Limitation |
Configuration Management Due to a limitation in DOORS Next's API, the following links are not supported in Hub if GCM is active: Tracked By, Validated By, Implemented By, and Affected By. If any of these links are required for your integration, we recommend creating a custom link type with a similar name. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
State Field Options cannot be mapped for the State field, due to DOORS Next bug PI92794. |
Planview Hub: All Tasktop Sync: 4.0 and later |
DOORS Next 6.0.5 - 6.0.5 iFix002 |
|
Feature Unsupported |
Folders Folders are not supported as an artifact type (meaning they cannot flow to a target repository) in Planview Hub 17.1-17.3. In Planview Hub 17.4, Folders can only flow to a target repository as a work item (not as a container). For example, you could flow a Folder in Blueprint to a Requirement (a work item) in a target repository, but not to a Folder (a container) in that target repository. This functionality (flowing folders to a work item) is only possible with the Hub container-to-work-item add-on. In Planview Hub 18.1 and later, users can flow Folders to a target repository as a container. |
Planview Hub: All |
Any supported repository version: |
|
Third Party API Limitation |
Folders Folders can be created, but they cannot be updated by Hub, due to API limitations. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Known Defect |
Folders Hub does not work with DOORS Next projects with folders whose names contain the characters "&", "<", or ">". Folders with these characters in their names may cause the server to return invalid XML, causing synchronization to fail, with parsing errors. |
Planview Hub: All Tasktop Sync: 4.0 and later |
4.0 to 4.0.4 |
|
Known Defect |
Artifact Type Once an artifact type has been synchronized (e.g., functional requirement, feature, non-functional requirement, term), if a user changes the artifact type, it may stop synchronizing. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Field Management Summary and Description with special characters appear encoded. Due to a DOORS Next defect in versions 4.0.4 and 4.0.5, summaries and descriptions containing special characters (e.g. "&") will appear encoded (e.g. "&") in the task editor and in the systems they are synchronized to. Because of this, the Description field should not be used as a proxy field for DOORS Next versions 4.0.4 and 4.0.5. If the Description is used as the proxy field, Hub will not work. |
Planview Hub: All Tasktop Sync: 4.0 and later |
4.0.4, 4.0.5 |
|
Third Party API Limitation |
Relationships DOORS Next does not support duplicate links. Some versions quietly ignore duplicates, while others throw an exception. For all versions, Hub will explicitly filter out duplicates and log a warning. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Requirements 'Contextual' requirements within a module cannot be created by Hub. They must be added to a module through the DOORS Next application. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Requirements As customers should expect, updating fields (except link types) on a 'contextual' requirement immediately updates the corresponding 'base' requirement. However change detection in Hub only works on 'base' requirements when the 'contextual' requirement is changed. This is because DOORS Next does not update the last-modified date of 'contextual' requirements when associated 'base'/'contextual' requirements are changed. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Non-Text Requirements Artifacts with artifact format other than "Text" cannot be created through Hub. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Non-Text Requirements Artifacts with artifact format other than "Text" can only have their parent folder and internal/external links updated. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Third Party API Limitation |
Non-Text Requirements Artifacts with artifact format other than "Text" do not contain the 'content' field that includes the IBM proprietary visual content such as use-case diagrams, storyboards, etc. All other metadata fields are provided by Hub. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Configuration Limitation |
Web Server Configuration Web server should be configured to accept URLs of at least 6500+ characters. Otherwise queries with long parameters (eg. folder-based query on 1000+ folders) may be rejected by the server. This is frequently the default setting, so it is possible that no additional action will be needed, though this depends on the chosen web server. |
Planview Hub: All Tasktop Sync: 4.0 and later |
Any supported repository version: |
|
Configuration Limitation |
Relationships User cannot create a custom link with the same title and forward label as a built-in link-type. There is no way for Hub to distinguish between the custom type and built-in type. If a user does this, it will result in the same links created on the custom type being created on the built-in type. |
Planview Hub: All Tasktop Sync: 4.3 and later
|
Any supported repository version: |
|
Third Party API Limitation |
Deleted Artifacts DOORS Next 6.0 does not support the detection of deleted artifacts via OSLC. If you try to retrieve an artifact that has been deleted the artifact is returned instead of a 410 gone error. If a customer deletes an artifact in DOORS Next it will still appear in search. |
Planview Hub: All Tasktop Sync: 4.4 and later |
6.0 |
|
Third Party API Limitation |
Field Management DOORS Next 6.0 server is unable to parse the characters: \u0x64f, \u0x064d or \u0x064b. These characters result in a 500 error being returned from the server. |
Planview Hub: All Tasktop Sync: 4.4 and later |
6.0 and up |
|
Third Party API Limitation |
Module-based Search Module based search (used for repository queries in Hub) does not work in DOORS Next 6.0, 6.0.1, and 6.0.2 versions without iFix. iFix for defect was released by IBM in June 2016, so DOORS Next versions with iFixes later than that date should not experience this issue. |
Planview Hub: All Tasktop Sync: All |
6.0, 6.0.1 and 6.0.2 |
|
Third Party API Limitation |
Field Management Summary with XML or HTML tags (or rather, with < or > characters) will have those characters encoded when retrieved via REST API. |
Planview Hub: All Tasktop Sync: 4.0 and later |
4.0.4 and up |
|
Third Party API Limitation |
Field Management The customizability of DOORS Next does not allow for consistent standard fields. As a result, the required Standard Fields: Priority, Status, Resolution, Closed, and Completed will not be automatically mapped in Hub. |
Planview Hub: All Tasktop Sync: All |
Any supported repository version: |
|
Third Party API Limitation |
Relationships Once Versioning is enabled for a project, Hub will not be able to write links of the following types (both internal and external ARM): "Validates/ValidatedBy, Affects/AffectedBy, Implements/ImplementedBy and Tracks/TrackedBy" |
Planview Hub: All Tasktop Sync: 4.5 and later |
6.0 and up |
|
Configuration Requirement |
Global Configuration Management To access artifacts in a non-default stream on a version management enabled DOORS Next, the global configuration management application URL has to be set in the repository settings |
Planview Hub: All Tasktop Sync: 4.7 and later |
6.0 and up |