How to configure ClearQuest Web for Collaborative Lifecycle Management integrations

Answer

You can use Collaborative Lifecycle Management (CLM) integrations with products based on Jazz technology, including IBM Rational Team Concert ,IBM Rational Quality Manager, and IBM Rational Requirements Composer, to connect the work of all team members.

Collaborative Lifecycle Management integrations provide a common approach to artifact linking, dashboards, security, and user interface frameworks. Cross-product links support traceability, web-like navigation, commenting, and status tracking across project repositories.

Collaborative Lifecycle Management integrations provide the following capabilities:

• Link to existing artifacts across repositories in integrated products; for example, ClearQuest® records are linked to work items, test cases, and requirements.
• Hover over links to quickly check the status of associated work; for example, testers can monitor the status of a defect that they reported to the development team.
• Add a viewlet to a dashboard to report query results from associated projects; for example, you can display requirements that have not been assigned test plans.
• Add comments to any artifact in an integrated repository.

This technote describes how to configure Rational ClearQuest Web to use the Collaborative Lifecycle Management integrations.

---

I. Applying the ClearQuest OSLCLinks package version 1.0, 1.1, or 1.2

A. About the OSLCLinks packages

Starting in version 7.1.2, ClearQuest provides support for Open Services for Lifecycle Collaboration (OSLC)-based integrations through the ClearQuest OSLCLinks packages.

The OSLCLinks package version 1.0, which is supported in ClearQuest version 7.1.2, provides basic integration capabilities with other Rational products by creating and viewing links between artifacts in the ClearQuest client. For example, you can create links between ClearQuest records, Rational Team Concert work items, and Rational Quality Manager test execution records.

The OSLCLinks package v1.1, which is supported in ClearQuest v7.1.2.1, includes all the functionality in the version 1.0 package and adds state predicate support as defined in the Open Services for Lifecycle Collaboration Change Management Specification Version 2.0. The OSLCLinks package v1.1 is required to use the Requirement Change Management (RCM) feature supported by the Rational ClearQuest v7.1.2.1 integration with Rational DOORS v9.3.0.1. See Technote 1456993 for more information about the OSLC-based integration between Rational ClearQuest v7.1.2.1 and Rational DOORS v9.3.0.1. The OSLCLinks package v1.1 is also required for the OSLC-based integration between Rational ClearQuest and Rational Quality Manager to support custom ClearQuest schemas, including the out-of-the-box Rational ClearQuest ALM schema.

The OSLCLinks package v1.2, which is supported in ClearQuest v7.1.2.2, includes all the functionality in the versions 1.0 and 1.1 packages and adds support for the oslc_cm:verified field, which corresponds to an OSLC-defined state. You must use Rational Quality Manager v3.0.1.3 or later with the OSLCLinks package v1.2 to use the oslc_cm:verified state predicate.

B. Schema changes after applying the OSLCLinks package v1.0

Applying the OSLCLinks package v1.0 to your schema adds a new stateless record type, OSLCLink, and makes several updates to the selected ClearQuest record types.

The new stateless record type, OSLCLink, includes the following components:

• Three new fields:
• oslcl_link_type (Short String 250)
• oslcl_label (Short String 250)
• oslcl_URI (Multiline String)
• Two new type actions, Modify and Delete
• A new OSLCLink form with the linkType, label and URI fields

The following changes are made for each user-selected ClearQuest record type:

• New reference_list field oslc_links that references OSLCLink
• New value-changed hook for the oslc_links field that checks for and removes duplicate links
• New Links tab on the submit/modify form. The tab includes a parent-child control that is associated with the oslc_links field. The parent-children control does not include the Add, New, and Delete buttons, and linkType, label and URI fields are included in the columns of the list control.
• New base action Commit hook that changes the mastership of all associated links when mastership of the parent record changes
• New base action Commit hook that lets you customize the package to participate in a ClearQuest security context system

C. Schema changes after applying the OSLCLinks package v1.1

To enable ClearQuest records to support state predicates as defined in the Open Services for Lifecycle Collaboration Change Management Specification Version 2.0, you must apply the OSLCLinks package v1.1 to your schema and enable one or more record types.

The OSLCLinks package v1.1 is a cumulative update. Applying the v1.1 package to your schema makes all the changes described in the previous section, “Schema changes after applying the OSLCLinks package v1.0” and updates the selected ClearQuest record types to include five new fields that correspond to the OSLC-defined states:

• oslc_cm-closed (INT)
• oslc_cm-inprogress (INT)
• oslc_cm-fixed (INT)
• oslc_cm-approved (INT)
• oslc_cm-reviewed (INT)

D. Schema changes after applying the OSLCLinks package v1.2

ClearQuest version 7.1.2.2 introduces support for the OSLCLinks package v1.2. The OSLCLinks package v1.2 contains all the functionality in versions 1.0 and 1.1, and adds support for the following new field, which corresponds to an OSLC-defined state:

• oslc_cm:verified (INT)

Consider upgrading to the OSLCLinks package v1.2 if you want to use the oslc_cm:verified state predicate.

---

E. Applying the OSLCLinks package

This section describes how to apply the OSLCLinks package version 1.0 or 1.1 to your schema by using the Rational ClearQuest Designer that is based on Eclipse technology. Apply the OSLCLinks package v1.0 if you are running ClearQuest v7.1.2. Apply the OSLCLinks package v1.1 if you are running ClearQuest v7.1.2.1.


Procedure

1. In the ClearQuest Designer, right-click the version of the schema to which you want to apply the package and select Packages > Apply Package. The Package Wizard opens.

2. Expand the OSLCLinks node in the list of packages and select version 1.0 or 1.1. Click Next.

3. Select the record types to which you want to apply the package.

4. Optional: If you applied the OSLCLinks package v1.1 and you want to use state predicate support to map ClearQuest states or status to OSLC states, then you must add a global Perl script named OSLC_CQ_State_Mapping and provide an implementation:

a. Navigate to the Global Scripts > Perl node associated with the schema, right click, and select Add.
b. Enter the following text in the Hook name field and then click OK: OSLC_CQ_State_Mapping
c. Add hook code to the OSLC_CQ_State_Mapping script.

See Technote 1456993 for more information about the OSLC-based integration between Rational ClearQuest v7.1.2.1 and Rational DOORS v9.3.0.1.

5. Click Finish.

The OSLCLinks package is applied to the schema that you selected. Look for a new OSLCLink stateless record type in the schema to verify the package installation.

See the Applying Packages topic in the ClearQuest Information Center for more information about applying packages.

---

Example

This section provides an example of applying the OSLCLinks package v1.1 to the DefectTracking schema and enabling the package for the Defect record type.

1. In the ClearQuest Designer, right-click the version of the schema to which you want to apply the package and select Packages > Apply Package. The Package Wizard opens.

2. Expand the OSLCLinks node in the list of packages, select version 1.1, and click Next.

3. Enable the OSLCLinks package for the Defect record type.

4. Add a global Perl script named OSLC_CQ_State_Mapping and provide an implementation.

a. Navigate to the Global Scripts > Perl node associated with the schema, right click, and select Add.
b. Enter the following text in the Hook name field and then click OK: OSLC_CQ_State_Mapping
c. Add hook code to the OSLC_CQ_State_Mapping script. For example:

sub OSLC_CQ_State_Mapping {
my ($myentity, $hook_type) = @_;
my $state = $myentity->GetFieldStringValue("State");

if ($hook_type eq "Validation") {

if (($state eq "Assigned") || ($state eq "Opened")) {
$myentity->SetFieldValue("oslc_cm-inprogress", "1");
} else {
$myentity->SetFieldValue("oslc_cm-inprogress", "0");
}
if ($state eq "Closed") {
$myentity->SetFieldValue("oslc_cm-closed", "1");
} else {
$myentity->SetFieldValue("oslc_cm-closed", "0");
}
}
}

This script is called by the initialization and validation hook of the OSLC_State_Predicates action of a Defect record. The script has two parameters: the current entity and the hook type. Depending on your requirements, you can add different codes according to the value of the hook type parameter. The example script shows a validation hook.

5. Click Finish. The schema revision is checked in.
6. Upgrade the user database.
7. Verify the schema changes:

a. Use your ClearQuest client to log in to the user database.
b. Edit the All Defects query and add the following display fields: oslc_cm-inprogress and oslc_cm-closed.
c. Run the All Defects query.
d. Select a defect in the query results that is in the Submitted state.
e. Close the defect and verify that oslc_cm-closed equals 1 while the other fields with names prefixed with oslc_cm equal 0.
f. Reopen the defect and verify that oslc_cm-inprogress equals 1 while the other fields with names prefixed with oslc_cm equal 0.

---

Client behavior

Using the ClearQuest Web client in ClearQuest versions 7.1.2 and later, you can add, view, and traverse artifact links. In versions of ClearQuest earlier than 7.1.2, you can view and traverse links, but you cannot add new links.

Using the ClearQuest clients for Eclipse and Windows, you can view and traverse artifact links, but you cannot add new links.

---

Security context

In some cases, you might want to configure the OSLCLinks package to be part of a ClearQuest security context system, for example, to hide links from unauthorized users. There are additional steps required to configure the new package to work with a security context system after you apply the OSLCLinks package to your schema.

See Creating a Security Model in the ClearQuest Information Center for more information about security and ClearQuest.

Procedure for configuring security context

1. As a user with Schema Designer privileges, run the packageutil setaccess subcommand to enable the OSLCLink record for editing. Here is the command-line synopsis for the packagutil setaccess subcommand:

packageutil setaccess -dbset dbset_name user_name password schema_name
-record -modifiablebyothers OSLCLink

For example:

packageutil setaccess –dbset 7.0.0 admin "" ALM -record
-modifiablebyothers OSLCLink

The display output might be similar to this:

--- Checked out revision 3 of schema 'ALM'
+++ Set access policy for OSLCLink to -modifiablebyothers
+++ Set access policy for select records, fields, and actions

2. In the ClearQuest Designer, add a new REFERENCE field to the OSLCLink record type:

a. In the schema where you applied the OSLCLinks package, expand the Record Types – Stateless node and then expand the OSLCLink node.

b. Right-click the Fields node and click New Field. The New Field dialog box opens.

c. Type a name for the new field and set the Type to REFERENCE.

d. Click Finish. The Properties tab for the new field opens.

e. In the Reference Information section of the Properties tab, set the Reference To property to your security context record type.

f. Select the Security Context option.

3. Still using the ClearQuest Designer, add the following OSLC_GetSecurityFieldName global hook to the schema:

sub OSLC_GetSecurityFieldName
{
my $security_fieldname = "";
my ($entitydef_name) = @_;

# A hash table to keep security field name of each
# entitydef, using entitydef name as the key and security
# field name as the value.

my %security_fields_hash = (
#add entitydef and security context field pairs here
#For example, "ALMTask" => "SecurityPolicy"
);

if (exists $security_fields_hash{$entitydef_name}) {
my $temp_security_fieldname = $security_fields_hash{$entitydef_name};
if ( $::session->GetEntityDef($entitydef_name)->IsSecurityContextField($temp_security_fieldname)) {
$security_fieldname = $temp_security_fieldname;
}
}

return $security_fieldname;
}


The hook returns the security context field name of a specified record type.

4. Update the %security_fields_hash table in the OSLC_GetSecurityFieldName global hook to include a record type/security context field pair for every record type where you applied the OSLCLinks package. For example, if you applied the OSLCLinks package to the ALMTask and ALMRequest record types (whose security context fields are both named SecurityPolicy) and the REFERENCE field that you added in Step 2 is named oslc_SecurityPolicy, then your %security_fields_hash table might look something like this:

my %security_fields_hash = (
"OSLCLink" => "oslc_SecurityPolicy",
"ALMTask" => "SecurityPolicy",
"ALMRequest" => "SecurityPolicy"
);

5. Check in the schema revision and upgrade your user database.

6. To avoid changes to other parts of the OSLCLink record, disable editing by running the packageutil setaccess subcommand with the -modifiablebyowner option. Here again is the command-line synopsis for the packageutil setaccess subcommand:

packageutil setaccess -dbset dbset_name user_name password schema_name
-record -modifiablebyowner OSLCLink

For example:

packageutil setaccess –dbset 7.0.0 admin "" ALM -record -modifiablebyowner OSLCLink

The display output might be similar to this:

--- Checked out revision 4 of schema 'ALM'
+++ Set access policy for OSLCLink to -modifiablebyowner
+++ Set access policy for select records, fields, and actions

---

II. Configuring ClearQuest Web server for CLM integrations

You must perform several configuration tasks on the ClearQuest Web server and the Jazz server to enable the Collaborative Lifecycle Management (CLM) integrations with Rational Team Concert, Rational Quality Manager, and Rational Requirements Composer. You must perform the same configuration tasks on two ClearQuest Web servers to allow users to link records between the two servers. The following information is provided in this section:

• Overview of OAuth access
• Configuring the ClearQuest Web server for cross-server communication
• Configuring project relationships
• Approving consumer keys
• Registering an OAuth consumer key

A. Overview of OAuth access

The OAuth protocol enables web sites or applications (consumers) to access protected resources from a web service (service provider) through an API without requiring users to disclose their service provider credentials to the consumers. Consumers and service providers communicate with each other and share data by establishing OAuth keys to create friend relationships between the servers and to manage the list of cooperating servers. An approval process is required for approving consumer keys.

The ClearQuest Web server and Jazz server-based products can communicate with each other and share data by configuring OAuth access and establishing a friend relationship. Two ClearQuest Web servers can communicate with each other and share data by using the same mechanism.

As an administrator, you can request a provisional OAuth consumer key for the ClearQuest Web server to communicate with a target server, store information for accessing other target servers in the ClearQuest Web server friends list, and manage entries in the server friends list.

For more information about the OAuth protocol, see http://oauth.net.

B. Configuring the ClearQuest Web server for cross-server communication

Use the Cross-Server Communication window of the Site Configuration interface to specify a target OSLC service provider with which you want to establish server-to-server communication. Enter the location information of the target server and a code phrase to use as the OAuth secret. Then request access to that server to create an OAuth consumer key and store the information in the friends list. Once the OAuth key is authorized by the other server, the ClearQuest Web server can interact with the target server.

---

Procedure

1. Log on to ClearQuest Web as a user with Super User privileges.

2. Click Site Administration > Cross-Server Communication on the ClearQuest Web toolbar. The Cross-Server Communication window opens.

3. Specify the requested information about the target server with which you want to establish communication:

A. In the Title field, enter a title to identify a target server. For example:
• My RTC Server to identify a Rational Team Concert server
• My RQM Server to identify a Rational Quality Manager server
• My RRC Server to identify a Rational Requirements Composer server
• My CQWeb Server2 to identify another ClearQuest Web server
B. In the Root Services URI field, enter the URI for the target root services of the application that you want to add as a friend by using the following format:

For Jazz server-based products:

https://friend-server:port-number/context/rootservices

where the variables have the following meanings:

friend-server
Host name of the friend server.

Attention: Be sure to specify the host name by using the public URL with a fully qualified domain name. Do not specify the IP address.


port-number
Port number on which to access the server.

context
Application context. This is a configurable parameter. Following are the default values:
• Rational Team Concert:


Attention: The application context for Rational Team Concert has changed from version 2.0.0.x to version 3.0 and later. You must update the Root Services URI in the Site Administration > Cross-Server Communication window if you previously configured cross-server communication with Rational Team Concert 2.0.0.x and you now want to configure communication with Rational Team Concert 3.0 and later.

• In Rational Team Concert 2.0.0.x: jazz
• In Rational Team Concert 3.0 and later: ccm
• Rational Quality Manager:


Attention: The application context for Rational Quality Manager has changed in version 3.0.1 and later. You must update the Root Services URI in the Site Administration > Cross-Server Communication window if you previously configured cross-server communication with an earlier version of Rational Quality Manager.

• In Rational Quality Manager 3.0: jazz
• In Rational Quality Manager 3.0.1: qm
• Rational Requirements Composer:


• In Rational Requirements Composer 3.0.1: rm

Attention: If a Rational Requirements Composer 2.x project is upgraded to 3.0.1, you must retain the rdm application context instead of using the rm context. See the following topics for details:
• Migration upgrade limitations
• Upgrading the Jazz Team Server and the CLM applications



---

For ClearQuest Web server:

Attention: The application context for ClearQuest Web server has changed from Rational ClearQuest version 7.1.1 (oslc/cqrest) to version 7.1.2 (cqweb/oslc). You must update any code that uses the ClearQuest OSLC Change Management URI to use the new base URI, as described next. See the ClearQuest OSLC Change Management API Specification for details.

Attention: Configuring ClearQuest Web server communication to use SSL is highly recommended because a user's password is sent in unencrypted text format when the user logs on.

For ClearQuest versions 7.1.2 and 7.1.2.1, SSL is only supported on port 12443. Rich hover does not function when port 12443 is used.


• For ClearQuest versions 7.1.2 and 7.1.2.1:


• If SSL is configured:

https://hostname:12443/context/oslc/repo/dbset/discovery
• If SSL is not configured:

http://hostname/context/oslc/repo/dbset/discovery

• For ClearQuest version 7.1.2.2:


• If SSL is configured:

https://hostname/context/oslc/repo/dbset/discovery
• If SSL is not configured:

http://hostname/context/oslc/repo/dbset/discovery
where the variables have the following meanings:

hostname
Host name of the friend server.

Attention: Be sure to specify the host name by using the public URL with a fully qualified domain name. Do not specify the IP address.

context
Application context. For example, cqweb for ClearQuest Web server.

dbset
Repository (database set) name.


The discovery node in the URI is ClearQuest Web server equivalent of the Jazz server rootservices node.

C. In the OAuth Secret and Re-type Secret fields, enter an OAuth Secret code phrase to associate with the new OAuth consumer key.

Attention: In this step, you do not enter the key itself; you enter a shorter phrase to associate with the key.

D. Optional: Select the Trusted check box. Trusted consumers can share authorization with other trusted consumers and do not require user approval to access data.

Attention: For external products or web sites, it is a best practice to clear the Trusted check box.

E. Click Request Access. A provisional key is requested on the target server and the access information is added to the Server Friends List section of the page. A new entry is added to the Authorize Provisional Key section.

F. Authorize the provisional OAuth consumer key.
At this point, the access request is not authorized on the target server. Use one of the following methods to approve the request:

i. Click Grant access for the provisional key if this link appears in the Authorize Provisional Key section and you have administrator privileges (member of the JazzAdmins group for Jazz-based servers) on the target server. If the target server is a Jazz-based server, see the Rational Team Concert help for instructions on authorizing a provisional key. If the target server is another ClearQuest Web server, see II.E. Approving consumer keys.

Note: The Grant access for the provisional key link does not appear if the OAuth provider does not provide an authorization URI. Rational ClearQuest and Rational Team Concert might provide this link; Rational Quality Manager does not. You must choose option ii below if the Grant access for the provisional key link does not appear in the Authorize Provisional Key section or you do not have administrator privileges on the target server.

ii. Record the provisional key value. If you have administrator privileges on the target server, you can log on to the target server and approve the request by yourself. Otherwise, you must ask a target server administrator to approve your request. You might need to provide the provisional key value to the target server administrator.

---

C. Configuring project relationships

After configuring the ClearQuest Web server for cross-server communication, configure project relationship links. These links represent relationships between projects and service providers such as projects on other servers. Link types reflect the nature of the service that a provider makes available to the project. Establishing a project link enables linking between artifacts in the project and artifacts that the service provider makes accessible.

Procedure

1. Click Site Administration > Project Relationships on the ClearQuest Web toolbar. The Project Relationships window opens.

2. Select a server from the Server list to create a link with the ClearQuest Web application. An authentication window might open that prompts for credentials for the remote service. Enter the user name and password and then click OK.

3. Select a service provider from the Service Providers list.

4. Click Add to add the project relationship link. Project relationship links appear in the Project Relationship section of the page.

---

D. Configuring the target server for cross-server communication

You must configure the target OSLC service provider for cross-server communication back to the ClearQuest Web server to complete configuring ClearQuest Web for the Collaborative Lifecycle Management integration.

• If the target OSLC service provider is Jazz Team Server, see the Rational Team Concert help topics that discuss configuring cross-server communication. For example, for Rational Team Concert version 2.0.0.2, see Configuring cross-server communication. For Rational Team Concert version 3.0.1.x and the Rational Solution for Collaborative Lifecycle Management 2011, see Establishing cross-server communication.

• If the target OSLC service provider is another ClearQuest Web server, repeat the instructions in sections II.B and II.C of this document.

E. Approving consumer keys

If an administrator on the Jazz server is configuring cross-server communication with the ClearQuest Web server and the administrator does not have Super User privileges on the ClearQuest Web server, the ClearQuest Web administrator can use the OAuth Consumer Management window to approve the provisional consumer key.

Procedure:

1. Click Site Administration > OAuth Consumer Management on the ClearQuest Web toolbar. The OAuth Consumer Management window opens.
2. View the Provisional Keys section for new requests.
3. Select Approve or Reject for a request.

F. Registering an OAuth consumer key

You can register an OAuth consumer’s secret to create a new consumer key. Use this function when the OAuth consumer does not have an interface to request access to ClearQuest Web, for example, non-Jazz-based clients (consumers) that want to access OSLC links by using the OAuth protocol.

Procedure

1. Click Site Administration > OAuth Consumer Management on the ClearQuest Web toolbar. The OAuth Consumer Management window opens.

2. In the Consumer Name field, enter the name of the consumer that uses the consumer key. For example, oslcapplication.bldg5.japan.companyA.com

3. In the Consumer Key field, enter the OAuth key value to be associated with the consumer.

4. In the Consumer Secret and Re-type Consumer Secret fields, enter the consumer secret provided by the Jazz server administrator.

Attention: In this step, you do not enter the key itself; you enter a shorter phrase to associate with the key.

5. Optional: Select the Trusted check box. Trusted consumers can share authorization with other trusted consumers and do not require user approval to access data.

Attention: For external products or web sites, it is a best practice to clear the Trusted check box.

6. Click Register. The new key appears in the Authorized Keys section of the page.

G. Creating, viewing, and traversing links between CLM applications

After you have completed the steps described in Section II of this document, you can create, view, and traverse OSLC links between Collaborative Lifecycle Management applications. See the end-user documentation for your application for information on creating, viewing, and traversing OSLC links.