Configuring and using the OSLC-based integration between Rational ClearQuest and Rational DOORS

Answer

Introduced in Rational ClearQuest Version 7.1.2 and Rational DOORS Version 9.3, an integration is available that is based on the OSLC APIs for Change Management. The integration supports the Requirements Gathering, Requirements Implementation, and Requirements Change Management features, discussed next.

The integration between Rational ClearQuest and Rational DOORS provides a scalable and consistent approach for managing and tracking requirements change by leveraging ClearQuest as a flexible change management tool. The integration supports an efficient, configurable, requirements-driven development process that lets you implement best practices and facilitate compliance. The OSLC implementation facilitates seamless integration with other lifecycle management capabilities, such as Rational Team Concert work items for planning, Rational Quality Manager for quality control, and Rational ClearCase UCM for source code control.

---

Table of contents
I. Integration prerequisites

II. Features supported
II.1. Features supported in Rational ClearQuest V7.1.2.1 and Rational DOORS V9.3.0.1
II.2. Features supported in Rational ClearQuest V7.1.2.3 and Rational DOORS V9.3.0.4
II.3. Features supported in Rational ClearQuest V8.0.x and Rational DOORS V9.3.0.5
II.4. Requirements Gathering feature
II.5. Requirements Implementation feature
II.6. Requirements Change Management feature

III. Configuration procedures
III.1. Applying the ClearQuest OSLCLinks package to your schema
III.2. Applying the RequirementsChangeRequest V1.0 package to your schema
III.3. Configuring an existing record type for the Requirements Change Management feature
III.4. Configuring the ClearQuest and DOORS integration

---

I. Integration prerequisites

The following prerequisites apply to the OSLC-based integration between Rational ClearQuest and Rational DOORS:

• You must have Rational ClearQuest installed on a Windows computer and have access to the ClearQuest administration tools to apply the ClearQuest OSLCLinks package and optionally, the ClearQuest RequirementsChangeRequest package to your schema.
• You must have Rational ClearQuest and Rational DOORS installed and configured to use the integration between ClearQuest and DOORS.
• To enable rich-hover capability and to support creating links from the ClearQuest Web client, install and configure the Rational DOORS Web Access client.
• Review the "Introduction to Change Management for Rational DOORS" help in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5) for more information about Rational DOORS Change Management.

---

II. Features supported

Three major use cases are supported by the integration:

• Requirements Gathering automates the start of the product definition phase so that requirements suggestions and proposals can be gathered by using a change management tool and reviewed through configurable workflows. Once approved, change management records are pulled into a DOORS module for further analysis and propagation.

• Requirements Implementation brings comprehensive round-trip traceability from business requirements to change requests to code. This interface reduces scope creep (uncontrolled changes in a project's scope), streamlines development, and provides real-time visibility relationships between requirements and development activities.

• Requirements Change Management provides flexibility to implement any process for managing, tracking, and reporting on all proposed changes against critical requirements, links, requirements structures, specifications, test plans, and other information maintained in the change management database.

---

II.1. Features supported in Rational ClearQuest V7.1.2.1 and Rational DOORS v9.3.0.1

The integration between Rational ClearQuest V7.1.2.1 and Rational DOORS V9.3.0.1 introduces the following additional functionality:

• For Requirements Implementation Feature (requires Rational DOORS Web Access V1.4.0.1):
• OAuth support
• OSLC link rich-hover text support in Rational ClearQuest Web and Rational DOORS Web
• Bidirectional Requirements Implementation feature support
• Requirements Change Management feature support, which includes the RequirementsChangeRequest record type after applying the ClearQuest RequirementsChangeRequest package V1.0 to your schema

---

II.2. Features supported in Rational ClearQuest V7.1.2.3 and Rational DOORS V9.3.0.4

The integration between Rational ClearQuest V7.1.2.3 and Rational DOORS V9.3.0.4 adds support for using your existing, non-RequirementsChangeRequest record types for the Requirements Change Management feature. Additional configuration is required, and not all record types are suitable for the Rational Change Management feature, as described in the following sections.

---

II.3. Features supported in Rational ClearQuest V8.0.x and Rational DOORS V9.3.0.5

If you have upgraded to Rational ClearQuest V8.0 or later and you are using the integration between ClearQuest and DOORS, then you should upgrade to Rational DOORS V9.3.0.5. You can continue to use DOORS Web Access V1.4.0.4.

The integration between Rational ClearQuest V8.0 and Rational DOORS V9.3.0.5 adds enhanced Requirements Gathering feature support. Specifically, a record-type selection menu is added during template configuration, and there are fixes to several issues that existed in earlier releases of the integration.

---

II.4. Requirements Gathering feature

II.4.1. Minimum software requirements

• Rational ClearQuest V7.1.2
• Rational DOORS V9.3

II.4.2. Recommended software requirements

• Rational ClearQuest V7.1.2.x or V8.0.x
• Rational DOORS V9.3.0.5

II.4.3. Restrictions and known limitations

• The Requirements Gathering feature is supported only on the DOORS native client. It is not supported by the DOORS Web Access client or the ClearQuest Web client.

You do not need to make any changes to your ClearQuest schema to use the Requirements Gathering feature.

II.4.4. Scenario for using the Requirements Gathering feature

1. Using the DOORS native client, enable one or more DOORS modules to use the Requirements Gathering feature.
2. Define attribute mapping as described in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5)
• In steps 3 and 4, here are the default attribute mappings for the DOORS Attribute and CM Attribute fields:
  

DOORS Attribute	CM Attribute
Object Heading	Summary
Object Short Text	ID
Object Text	Description

3. Obtain change management data as described in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5).
• In the "Obtaining requirements" help topic (V9.3 and V9.4, V9.5), step 3, here is an example string value for the Query String field:

oslc:cm:status="Assigned"



Back to top

---

II.5. Requirements Implementation feature

II.5.1. Minimum software requirements

• Rational ClearQuest V7.1.2
• Rational DOORS V9.3
• Rational ClearQuest OSLCLinks package V1.0

You must apply the ClearQuest OSLCLinks package V1.0 or later to your schema and enable the package for at least one record type to use the Requirements Implementation (RI) feature. The ClearQuest OSLCLinks package V1.0 is included with Rational ClearQuest V7.1.2, the OSLCLinks package V1.1 is included with ClearQuest V7.1.2.1, and the OSLCLinks package V1.2 is included with ClearQuest V7.1.2.2. See "Applying the ClearQuest OSLCLinks package" in the IBM Rational ClearQuest Information Center (V8.0, V8.0.1) for instructions on how to apply the ClearQuest OSLCLinks package.

See "Implementing Requirements" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5)for information about how to use the new integration between DOORS and ClearQuest.

II.5.2. Additional requirements

• You must use the Change Management menu in a DOORS client to define a template.
• You must enable a DOORS module for the Requirements Implementation feature.

II.5.3. Recommended configuration
OAuth authentication, cross-server configuration, and project relationship configuration are recommended.

II.5.4. Restrictions and known limitations

• Using a version of the DOORS native client earlier than V9.5.1, links to ClearQuest must be created by using the Implementation Request shortcut menu. Do not create links by using the Link shortcut menu.
• Using the DOORS native client V9.5.1 or later, links to ClearQuest must be created by using the Link shortcut menu. The Implementation Request shortcut menu contains only the Sync command.
• Using the DOORS Web Access client, the only supported feature is rich hover links that are created by using either the DOORS native client or the ClearQuest Web client.
• Using the ClearQuest Web client, you can create Requirements Implementation links. However, these links cannot be synchronized from the DOORS native client by using the Implementation Request > Sync command on the shortcut menu. In addition, these links cannot be removed from the DOORS native client by using the Implementation Request > Remove command on the shortcut menu. Instead, you must remove these links by using the ClearQuest Web client.
• There is an exclusive lock on the requirements module. To add or remove links from the ClearQuest Web client, you must first close the requirements module from the DOORS client. Otherwise, the backlink on the requirements module cannot be created or removed.
• You need modify permission on the requirements module. Otherwise, the backlink on the requirements module cannot be created or removed when using the ClearQuest Web client.
• The Rational ClearQuest and Rational DOORS integration displays Rational ClearQuest values in read-only mode in Rational DOORS.

---

II.6. Requirements Change Management feature

II.6.1. Minimum software requirements

• Rational ClearQuest V7.1.2.1
• Rational DOORS V9.3.0.1

You can use either the RequirementsChangeRequest record type that is included with the ClearQuest RequirementsChangeRequest package, or an existing record type for the Requirements Change Management (RCM) feature.

II.6.2. Restrictions and known limitations
The following limitations apply for the Requirements Change Management feature:

• You must use the RationalChangeRequest record type for the Requirements Change Management use case.

Important: This restriction is lifted when you upgrade to ClearQuest V7.1.2.3 and DOORS V9.3.0.4.



• You cannot rename the RequirementsChangeRequest record type.

Important: This restriction is lifted when you upgrade to ClearQuest V7.1.2.3 and DOORS V9.3.0.4.

• You are discouraged from editing the RequirementsChangeRequest and OSLCLinks packages. Customizing these packages could break the integration. Also, some customizations might need to be re-implemented when you upgrade to a future version of the packages.
  
• If you must customize the RequirementsChangeRequest record type, do not add any required fields when moving from the Assigned state to the Review state, or from the Approved state to the Applied state.
  
• If you use Rational ClearQuest V7.1.2.3 or later with a DOORS release earlier than V9.3.0.4, only the RequirementsChangeRequest record type is supported for the Requirments Change Management feature.
  
• If you use Rational ClearQuest V7.1.2.3 or later with a DOORS release earlier than V9.3.0.4, you must change the value of com.ibm.rational.cm.web.component.restrict.rcr.types in the cqrest.properties file (typically located in $RATIONAL_COMMON\CM\profiles\cmprofile\installedApps\dfltCell\TeamEAR.ear\cqweb.war\WEB-INF\classes) to true:

# Set this option to "true" to allow only the RequirementsChangeRequest record type from
# the RequirementsChangeRequest package to be used as an Requirements Change Request
# record in the OSLC-based integration of ClearQuest and DOORS.
com.ibm.rational.cm.web.component.restrict.rcr.types=true


Then restart the ClearQuest Web server.

See "Managing change requirements" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5) for information on how to use the new integration between DOORS and ClearQuest.

---

II.6.3. Using the RequirementsChangeRequest record type for the Requirements Change Management feature

II.6.3.1. Minimum software requirements:

• Rational ClearQuest V7.1.2.1
• Rational DOORS V9.3.0.1
• Rational ClearQuest RequirementsChangeRequest package V1.0

You must apply the Rational ClearQuest RequirementsChangeRequest package V1.0 to your schema to use the RequirementsChangeRequest record.

The ClearQuest RequirementsChangeRequest package has an internal dependency on the OSLCLinks package V1.1, the latter of which adds support for OSLC state predicates. OSLC state predicate support is required to use the Requirements Change Management feature. The OSLCLinks package V1.1 is automatically applied to your schema when you apply the RequirementsChangeRequest package.

II.6.3.2. RequirementsChangeRequest record type

The RequirementsChangeRequest package provides a RequirementsChangeRequest record type to use with the Requirements Change Management feature. This stateful record type defines the following states:

• Created
• Assigned
• Review
• Approved
• Rejected
• Applied

These states correspond to the states defined in the DOORS requirements module. You change these states by applying the following actions:

• Submit
• Assign
• Review
• Approve
• Reject
• Apply
• Reassigned

The RequirementsChangeRequest record type maps a reference list to a ReviewApproval stateless record type. You use the ReviewApproval record type to specify one or more mandatory or optional reviewers or approvers for its parent RequirementsChangeRequest record. A designated reviewer can approve or reject a ReviewApproval request only when its parent RequirementsChangeRequest record is in the Review state. A RequirementsChangeRequest record can be approved only when all its mandatory ReviewApproval requests have a status of Approved. The optional ReviewApproval requests are not taken into account. Note that only the owner of the RequirementChangeRequest record can edit the reviewers and approvers. This restriction is intended to reduce the possibility of unintended or malicious updating of the reviewer or approver.

You can customize the permission for these actions on the RequirementsChangeRequest record type by adding the RCR_Action_Permission global script.

---

II.6.4 Using an existing record type for the Requirements Change Management feature

II.6.4.1. Minimum software requirements:

• Rational ClearQuest V7.1.2.3
• Rational DOORS V9.3.0.4
• Rational ClearQuest OSLCLinks package V1.1

The following requirements and considerations apply when using an existing record type:

• The existing record type must have states that can be mapped to the states defined in the DOORS requirements module.
• You must apply the OSLCLinks package V1.1 or later to your schema and enable the schema for the record type that you choose.
• You must implement state predicate by using the OSLC_CQ_State_Mapping global hook.

See Section III, Configuration procedures, for information about configuring your ClearQuest schema and the DOORS integration with ClearQuest to use the Requirements Change Management feature.

---

III. Configuration procedures

This section describes the following configuration procedures:

• Applying the ClearQuest OSLCLinks package to your schema
• Applying the RequirementsChangeRequest V1.0 package to your schema
• Configuring an existing record type for the Requirements Change Management feature
• Configuring the ClearQuest and DOORS integration

III.1. Applying the ClearQuest OSLCLinks package to your schema

You must apply the ClearQuest OSLCLinks package to your schema to support the following features:

• Requirements Implementation feature.
• Requirements Change Management feature with non-RequirementsChangeRequest record types for schemas where you have not applied the RequirementsChangeRequest V1.0 package. Note that applying the RequirementsChangeRequest package to your schema automatically applies the ClearQuest OSLCLinks package.
• Requirements Gathering feature.

See "Applying the ClearQuest OSLCLinks package" in the IBM Rational ClearQuest Information Center (V8.0, V8.0.1) for instructions.

---

III.2. Applying the RequirementsChangeRequest package V1.0 to your schema

This procedure is required if you choose to use the RequirementsChangeRequest record type for the Requirements Change Management feature.

Procedure

1. Use the Eclipse-based ClearQuest Designer to apply the RequirementsChangeRequest package v1.0 to your schema.
   
   The OSLCLinks package V1.1 is automatically applied when you apply the RequirementsChangeRequest package. Two new record types are added to your schema after applying the package:
• RequirementsChangeManagement
• ReviewApproval
  
2. Check in your schema.
3. Upgrade the user database.

See "Applying packages" help in the IBM Rational ClearQuest Information Center (V7.1.2, V8.0, V8.0.1) for details about applying packages to your schema.

---

III.3. Configuring an existing record type for the Requirements Change Management feature

This procedure is required if you choose to use an existing record type for the Requirements Change Management feature.

Procedure
1. Choose an existing record type.

The record type that you choose must have a state model that lets you logically map ClearQuest states to the DOORS requirements module workflow.

See "Managing change requirements" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5) for information about the DOORS change management feature and workflow.

2. Apply the OSLCLinks package to your schema.

a. Use the Eclipse-based ClearQuest Designer to apply the OSLCLinks package V1.1 to your schema.
b. Enable the record type that you chose in Step 1.
c. Check in your schema.
d. Upgrade the user database.

See "Applying packages" help in the IBM Rational ClearQuest Information Center (V7.1.2, V8.0, V8.0.1) for more information about applying packages to your schema.

3. Map the ClearQuest record type states to the OSLC Change Management states.

Map the states of the ClearQuest record type to the OSLC Change Management states as defined in the Open Services for Lifecycle Collaboration Change Management Specification Version 2.0.

The following states are required for the Requirements Change Management feature:
• oslc_cm:inprogress
• oslc_cm:fixed
• oslc_cm:approved
• oslc_cm:closed

Here is an example of an OSLC_CQ_State_Mapping global script implemented in Perl. The subroutine maps the ClearQuest states (Assigned, Opened, Resolved and Closed) of a Defect record type that is included with the out-of-the-box DefectTracking schema to the corresponding oslc_cm-xxx states. The following mappings are defined in the global script:

Assigned --> oslc_cm:inprogress is "1" (all other oslc_cm-* fields are "0")
Opened --> oslc_cm:fixed is "1" (all other oslc_cm-* fields are "0")
Resolved --> oslc_cm:approved is "1" (all other oslc_cm-* fields are "0")
Closed --> oslc_cm:closed is "1" (all other oslc_cm-* fields are "0")


sub OSLC_CQ_State_Mapping {
my ($myentity, $hook_type) = @_;
if ($hook_type eq "Validation") {
my $state = $myentity->GetFieldStringValue("State");
if ($state eq "Assigned") {
$myentity->SetFieldValue("oslc_cm-inprogress", "1");
} else {
$myentity->SetFieldValue("oslc_cm-inprogress", "0");
}
if ($state eq "Resolved") {
$myentity->SetFieldValue("oslc_cm-approved", "1");
} else {
$myentity->SetFieldValue("oslc_cm-approved", "0");
}
if ($state eq "Closed") {
$myentity->SetFieldValue("oslc_cm-closed", "1");
} else {
$myentity->SetFieldValue("oslc_cm-closed", "0");
}
if ($state eq "ReadyToReview") {
$myentity->SetFieldValue("oslc_cm-fixed", "1");
} else {
$myentity->SetFieldValue("oslc_cm-fixed", "0");
}
}
}

---

III.4 Configuring the ClearQuest and DOORS integration

Configuring the ClearQuest and DOORS integration involves the following tasks:

• Configuring cross-server communication
• Defining the configuration templates
• Configuring the DOORS modules to use with the Requirements Change Management feature

III.4.1. Configuring cross-server communication

ClearQuest v7.1.2.1 and later and Rational DOORS V9.3.0.1 and later add support for cross-server communication and OAuth authentication. You must configure cross-server communication on both the ClearQuest Web server and the DOORS Web Access (DWA) server.

Important: When configuring the integration between Rational ClearQuest and Rational DOORS, you must specify a consistent URL format. Either all URLs must be specified by using the host name and domain name, or all URLs must be specified by only using the host name. The URL format must be consistent in the doorsRedirector.properties and festival.xml properties files as well. The doorsRedirector.properties and festival.xml files are located in the following directory: DWA-home-directory\1.4.0.x\server\festival\config The DWA server cannot connect to the ClearQuest Web server if you specify the URLs in mixed formats, resulting in an error similar to this: GET failed with http code 401

Procedure
1. Configure Rational ClearQuest Web by performing the tasks documented in the following help topics:

A. Perform the tasks in "Configuring ClearQuest Web server for cross-server communication" in the IBM Rational ClearQuest Information Center (V8.0, V8.0.1).
i. In step 3.a., enter a title to identify the DOORS Web Access server. For example, My DWA Server

ii. In step 3.b., enter the DOORS Web Access server root services URI by using the following format:
For DOORS Versions 9.3.0.1 - 9.4.x.x:
http://DWA-server:port-number/dwa/rdm/discovery/rootservices

For DOORS Versions 9.5 and later:
http://DWA-server:port-number/dwa/public/rootservices


where DWA-server:port-number is the port number of the Doors Web Access server.

Restrictions and known limitations
There is a known problem in establishing cross-server communication when the DOORS Web Access server is SSL-enabled. The issue is reported in APAR PM53794. Note that the problem is fixed in ClearQuest V7.1.2.5 and later, and in ClearQuest V8.0.0.1 and later.

B. Perform the tasks in "Configuring project relationships" in the IBM Rational ClearQuest Information Center (V8.0, V8.0.1).
i. In Step 2, select the DOORS server from the Server list. A DOORS Web Access authentication window might open prompting you for credentials for the remote service. Enter your DOORS administrative user name and password and click OK.

ii. In Step 3, select the DOORS Database--(Implements) service provider from the Service Providers list.

C. Perform the tasks in "Configuring the target server for cross-server communication" in the IBM Rational ClearQuest Information Center (V8.0, V8.0.1).

2. Configure Rational DOORS.

A. Log in to Rational DOORS as someone with administrator privileges.

B. Open the DOORS Database Properties window.

C. Go to the Remote Services tab and click Add. The Register Server window opens.

i. In the Name field, enter a name to identify the Rational ClearQuest Web server.
ii. In the Root Services URI field, enter the application context URI for the ClearQuest Web server:

• If SSL is configured:
  https://cq-server-hostname/cqweb/oslc/repo/dbset/discovery
• If SSL is not configured:
  http://cq-server-hostname/cqweb/oslc/repo/dbset/discovery
iii. In the Consumer Key field, enter the OAuth key value to associate with the consumer.
iv. In the OAuth Secret and Confirm Secret fields, enter an OAuth secret code to associate with the new OAuth consumer key.

3. Register the DOORS server OAuth consumer key in ClearQuest Web.

A. Log in to ClearQuest Web as a user with Super User privileges.

B. Click Site Administration > OAuth Consumer Management on the ClearQuest Web toolbar. The OAuth Consumer Management window opens.
i. In the Consumer Name field, enter a name to identify the DOORS server.
ii. In the Consumer Key field, enter the same OAuth consumer key value that you entered in step 2.C.iii.
iii. In the Consumer Secret and Re-type Consumer Secret fields, enter the same OAuth secret that you entered in step 2.C.iv.
iv. Ensure that the Trusted check box is selected.
v. Click Register.

4. Finish configuring the DOORS server by adding a collaboration link, which is similar to establishing a project relationship on the ClearQuest Web server.

A. In the DOORS Database Properties window, Remote Services page, Collaboration Links section, click Add. The Add Service Link Type window opens.

B. Expand the Change Management node, select your ClearQuest user database, and click Add. The Add Service Link Type window closes and the ClearQuest user database is added to the Collaboration Links list in the DOORS Database Properties window.

C. Click OK. The DOORS Database Properties window closes.

---

III.4.2. Defining the configuration templates

Restrictions and known limitations
There is a known problem with Basic Auth if the ClearQuest Web server is SSL-enabled. The issue is reported in APAR PM53794. Note that the problem is fixed in ClearQuest v7.1.2.5 and later, and in ClearQuest 8.0.0.1 and later.

Procedure
1. See "Introduction to Change Management for Rational DOORS" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5) for general information about Change Management for Rational DOORS.

2. See "Defining configuration templates" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5) for information about defining the configuration templates.

A. In Step 4, choose the authentication method: OAuth or Basic OAuth.

For OAuth:
i. Before creating a configuration template, ensure that you have added the correct value for the Collaboration Link on the Remote Services tab of the DOORS Database Properties window.
ii. In Step 5, select the appropriate service provider in the Select a CM Tool list on the Rational Change Management Server Configuration window.

For Basic OAuth:
i. In Step 5, use one of the following formats to specify the ClearQuest Change Managment Server (CM Server) URL:
http://cqwebserver:port /cqweb/oslc
https://cqwebserver:port /cqweb/oslc
ii. Also in Step 5, after you click Connect, a list of ClearQuest repositories appears.
• Select a repository. You are prompted for your ClearQuest user name and password.

Important: You must specify a non-blank password. The password field cannot be empty.

• Select a user database for the integration.

B. You only need to perform Steps 7–12 if you want to use the Requirements Change Management feature.

C. In Steps 8 and 9, enter the appropriate values depending on whether you are using the out-of-the-box RequirementsChangeRequest record type or an existing record type for the Requirements Change Management feature:

• If you are using the RequirementsChangeRequest record type:
i. Enter the following states in the Values section:
Assigned, Review, Approved, Applied

ii. Select the For ClearQuest option.
iii. Enter Apply in the Apply Action Attribute field.
iv. Enter Review in the Review Action Attribute field.

• If you are using an existing record type, enter the appropriate ClearQuest states and actions.

D. In Step 10, select the record type (for example, RequirementsChangeRequest) in the RequirementsChangeRequest Submit Form section.

E. Step 13 is needed only if you want to use the Requirements Implementation feature. For the Use Submit Form and Use Add Form fields, enter the ClearQuest record type that you are using. The record type must have the OSLCLinks package enabled.

F. Perform Steps 14 and 15 if you want to use the Requirements Gathering feature. In the Default Query String field, enter the appropriate OSLC query string. For example: oslc:CM:Status="Assigned"

---

III.4.3. Configuring the DOORS modules to use with the Requirements Change Management feature

Enable one or more DOORS modules to use with either the Requirements Change Management feature or the Requirements Implementation feature.

See "Configuring modules for use with the change management feature" in the IBM Rational DOORS Information Center (V9.3 and V9.4, V9.5). Accept all the default options.

---