IBM Rational ClearQuest
Overview
Large scale software development requires adherence to process but with the flexibility to orchestrate complex, custom workflows. With IBM Rational ClearQuest you can do just that – however, without integrating the resulting artifacts into the rest of your software delivery ecosystem, the benefits for your overall software delivery processes is limited.
Imagine a change request that actually originates as a trouble ticket, or incident, in your ITSM tool, such as BMC Helix ITSM. You want the benefits of having that change request managed in ClearQuest, while at the same time providing automated visibility of the status of that change request directly in your ITSM tool, via the originating incident request. Additionally, if that change request results in a new feature being developed, it would be ideal if that new feature could be automatically created in an agile development tool, such as Jira. That way, you can take advantage of the flexible orchestration that IBM ClearQuest, while allowing agile teams and support staff to continue to use their tools of choice to manage their ITSM and agile development processes.
For example:
- Support engineers are using an ITSM tool, such as ServiceNow or BMC Helix ITSM, to manage their ITIL processes.
- When a trouble ticket is received, that ticket should be managed in their ITSM tool, however, the resulting defect or change request should be managed in their change and defect management application.
- This can be achieved by integrating the tools – the trouble ticket, if designated to be a change request or defect, can be automatically created in IBM ClearQuest. Developers in IBM ClearQuest can then see the defect or change request, fix it and have seamless communication back to the support engineers.
Key Features and Benefits
- Leverage the flexibility of IBM ClearQuest to orchestrate complex and custom workflows but ensure seamless collaboration with other teams.
- Synchronizes artifacts across the lifecycle, allowing information to flow freely between IBM ClearQuest and other tools.
- Improve team collaboration by connecting IBM ClearQuest 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 Rational ClearQuest 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 instructions on how to create a custom user in IBM Rational ClearQuest.
List of minimal user permissions:
- User must have adequate permissions to create, update, and retrieve items.
Connecting to the IBM Rational ClearQuest Repository
Standard Authentication
Required Fields:
- Location/Connection URL
- Example Format: http://someserver.com:8080/cqweb
- Username
- ClearQuest Repository Name
- This can be found when you log in to ClearQuest.
Optional Fields:
- Test Database Names:
- A comma separated list of test database names. This can be found in ClearQuest Designer in Database Admin for your Repository.
- Attachment Field Identifier
- The name of the writable attachment field. This field must exist on all artifact types that require attachment support. For example, if you install the IBM provided attachment package, your attachment field name will be "Attachments"
- 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.
Learn more about how to set up your repository in Planview Hub here.
Creating a Proxy Association Attribute (Tasktop Sync)
What is Proxy Association Attribute?
A custom string attribute is recommended to be used as the proxy association storage. Tasktop Sync needs to keep track of the association between a task and its proxy task. The association is persisted in a proxy store allowing the synchronization to be restored if there is any catastrophic failure of Tasktop Sync.
A proxy association attribute must be created for each artifact type to be synchronized.
The Proxy Association Attribute field must be a text/string type field in your ALM repository. We recommend creating this field with the name "Tasktop Sync Proxy."
Additional Instructions:
A Proxy Association Attribute must be created for each artifact type to be synchronized. This may be done by creating a custom field on the artifact.
Open ClearQuest Designer and select the schema that you’re going to be making the modifications to in the ClearQuest Schema Repository Explorer view. Right-click and select Revision Control, then select CheckOut, as shown.
After providing a message, click OK on the dialog that appears. In the list view, expand Record Types, then expand the artifact that you want to modify. Right-click on Fields and select New Field. Give an appropriate name (such as TasktopProxy) and select MULTILINE_STRING as the field type, as shown in the dialog below.
Select the schema once more and right-click, select Revision Control and then CheckIn to check in the schema.
Go to the ClearQuest Database Admin view, right-click the repository and select Upgrade Database
Initialization and Changes Queries (Tasktop Sync)
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.
In ClearQuest you can choose to use either a pre-defined project based query that will return all items of a specific type from the database or a saved search.
Help instructions for creating and running queries.
|
Query |
Instructions |
|---|---|
|
Initialization Query |
Saved searches can help easily limit the number of artifacts being retrieved from the repository. Saved searches are based on custom queries created in the CQ application. To utilize this functionality, create your query in the CQ Web App and save it. Further, in Tasktop Sync, choose to use the "By predefined query" type search and retrieve the saved search.
|
|
Changes Query |
For changes query, use the same query as above. |
Other Configuration Settings
Modify Action
Any artifact types that are going to be updated will have one or more actions of type MODIFY listed in the ClearQuest Designer. To ensure that the ClearQuest connector can properly function with these artifacts, please ensure that your primary MODIFY action is named “Modify”, as shown in the table below.
Attachments
Attachments are supported and can be enabled by specifying the attachment field name in the Repository Connection Settings.
The Attachment Field Identifier field on the Repository Connection screen refers to the name of the writable attachment field. This field must exist on all artifact types that require attachment support. For example, if you install the IBM provided attachment package, your attachment field name will be "Attachments."
This restriction exists because of the flexibility of ClearQuest. Since Hub cannot know if and what field is the attachment field, you must specify the field identifier name.
Learn more about how to configure attachment flow in Planview Hub here.
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 ClearQuest |
|---|---|---|
|
ID |
login_name |
Login Name |
|
Username |
person-username |
Login Name |
|
|
|
Email Address |
| N/A |
fullname |
Full Name |
Learn more about how to configure person reconciliation in Planview Hub here.
Full Scan
In general, a full scan is not required to synchronize updates from this repository. However, it is possible that some read-only fields may require a full scan. Please consult with customer care for additional details.
Supported Features
Special Features Supported
|
Feature |
Custom Type Supported? |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
Planview Hub: All Tasktop Sync: 4.8 and later |
Any supported repository version: |
|
|
|
Planview Hub: All Tasktop Sync: 4.9 and later |
Any supported repository version: |
Time Worked (Worklogs)
Attachments
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 Version |
Unique URL? |
|---|---|---|---|
|
All resources that are stateful and submittable. By enabling default templates, you will have artifacts like:
|
Planview Hub: All Tasktop Sync: 4.3 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? |
|---|---|---|---|
|
N/A |
|
|
|
|
Containers used to define the boundary of a collection |
|
|
|
|
Databases |
Planview Hub: All |
Any supported repository version: |
N/A |
|
Containers used for artifact routing |
|
|
|
|
Databases |
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 |
|---|---|---|---|---|
|
|
|
Short String Multi Line String |
Formatted ID Headline Revision |
|
|
|
|
Short String/Reference - Constant List Short String/Reference - Perl |
Type State Severity |
|
|
Supported in: Planview Hub 18.2 and later Tasktop Sync 4.14 and later |
|
Reference List |
Role(s) Category Path |
|
|
|
|
|
|
|
|
|
N/A |
|
Modified Created |
|
|
|
|
Date Time |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Int |
Lock version Is Duplicate Is Active Identifier |
|
|
|
|
Reference to User |
Owner Creator |
|
|
Supported in: Planview Hub 18.2 and later Tasktop Sync 4.14 and later |
Custom Field Type Supported in: Planview Hub 18.2 and later Tasktop Sync 4.14 and later |
Reference List (persons) |
Assignees Authors |
|
|
Learn how to configure relationships in Planview Hub here. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
String
Functional Limitations
|
Category |
Limitation |
Applicable Hub Versions |
Applicable Repository Versions |
|---|---|---|---|
|
Third Party API Limitation |
Artifact Retrieval If you have 100+ fields on an artifact and field names starting with a digit, you may not be able to retrieve artifacts as the URL to request the artifact may be too long. |
Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party API Limitation |
Unicode Characters Attachments will not synchronize properly if the description field in ClearQuest includes unicode characters (e.g., unicode quotes, emojis, etc). |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Field Support The ClearQuest repository does not support fields with names starting with a digit. If a ClearQuest field starts with a digit, the ClearQuest server will produce invalid XML when this field is retrieved or should be updated. Therefore, the repository does not consider such fields starting with a digit as part of the artifact and will not trigger XML parsing errors. If such a field is required, the ClearQuest repository cannot support artifact creation. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party Functional Limitation |
Single- and Multi-Selects If a Perl script has been applied that dynamically changes the options list based on some component Hub cannot control (i.e. time of day), Hub will not be able to retrieve the field values for mapping. |
Planview Hub: 18.2 and later Tasktop Sync: 4.14 and later |
Any supported repository version: |
|
Configuration Requirement |
Performance ClearQuest operations may time out if too many operations are running concurrently. During these events, Planview Hub users may experience that operations need to be manually retried. If this occurs often, we recommend lowering the Concurrency Limit on the ClearQuest Repository Connection screen from its default value to a lower value, such as 2. Note: The ideal concurrency limit depends on each user's unique environment, and users should be cautious when updating this value. Setting the value too low when there is a large number of projects configured in collections and a low "Change Detection Polling Interval" setting can potentially cause Hub to be unable to process artifact changes. Please contact customer care if you have any questions. |
Planview Hub: All |
Any supported repository version: |
|
Configuration Requirement |
Configuration The CQWeb service must be installed, as it contains the REST endpoints used by the connector. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Configuration Requirement |
Querying The ClearQuest repository does not return artifact history with saved searches. history.action_timestamp or history.user_name need to be added to queries. When retrieving saved queries, history information is not automatically returned with the search, preventing us from adding revision information to the fetched artifacts. Server administrators must configure their queries to return the history.action_timestamp, history.user_name, and id fields to their query result set in order to overcome this limitation. Failing to do so will result in NPE. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Configuration Requirement |
Querying Connector does not support querying for more then 5000 artifacts at one time. Sync/Mylyn has an upper limit of 5000 hits per query. Since CQ 7.1.2.0 only supports search by artifact type, queries can only be set up against artifact types with less than 5000 items on the repository. |
Planview Hub: All Tasktop Sync: 4.3 and later |
7.1.2.0 |
|
Third Party API Limitation |
Querying Connector will display saved searches for artifact types not supported by the connector. Saved queries in ClearQuest do not specify their artifact type on the search. Therefore the connector will display all saved queries, regardless of whether they are for a supported artifact type or not. Executing a search for an unsupported artifact type will result in an empty set. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party API Limitation |
Script-Based Single-Select Fields Connector may return invalid options for scripted reference based single-selects. In ClearQuest, if a script based single-select field is dependent on the value of another field that has not been set, the API cannot return the proper list of valid values for the single-select field. In CQ 7 the API will return all values of the given reference type, whether or not they are valid. In CQ 8 the API will return an empty list. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party API Limitation |
Performance In order to work around a performance issue in 4.3.7 and in 4.4, the connector will no longer attempt to fetch all references for read-only reference based single-select fields. The connector will also not attempt to fetch references for script-based single select fields if the first options operation returns empty. To enable submission on those fields, all reference based single-select fields are marked as accepting new values |
Planview Hub: All Tasktop Sync: 4.3.7 and later |
Any supported repository version: |
|
Third Party API Limitation |
Unicode Connector does not support unicode field labels. ClearQuest REST API encodes unicode field labels into invalid XML, which causes connector failures. Unicode field values do not suffer from this and are therefore supported. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Third Party API Limitation |
Date/Time Fields Once a date time field's value is set, the connector cannot remove the value. There is a defect in the ClearQuest REST API in 7.1.2 that causes an un-parseable date exception when sending an empty date. |
Planview Hub: All Tasktop Sync: 4.3 and later |
7.1.2 |
|
Third Party API Limitation |
"/" in Name Connector does not support ClearQuest repositories or databases with / in the name. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |
|
Configuration Requirement |
Configuration In order to update artifacts, customers/administrators should ensure that all artifact types they want to work with have a MODIFY action labelled "Modify". ClearQuest can have 0 to many MODIFY actions available on an artifact type. If we don't explicitly name a MODIFY action when updating an artifact,ClearQuest will attempt to perform a default action, but this will fail when more than one MODIFY action is available. To avoid this problem, we've resorted to explicitly calling the MODIFY action labelled "Modify", which should be a reasonable default. |
Planview Hub: All Tasktop Sync: 4.4 and later |
Any supported repository version: |
|
Configuration Requirement |
Configuration It is highly recommended that customers use HTTPS for the ClearQuest server. |
Planview Hub: All Tasktop Sync: 4.3 and later |
Any supported repository version: |