Rational Change for ClearQuest Interface Help
Version 1.0
Setting up the Change Database
Setting up the ClearQuest Database
Contacting IBM Rational Software
Support
This document assumes that you have a basic understanding of how to use IBM® Rational® Change and Rational ClearQuest™. It also assumes that you are familiar with Rational Synchronization Server™.
The integration Rational Change for ClearQuest Interface runs under Rational Synchronization Server as a plug-in. This integration lets users create synchronizers to selectively synchronize change requests between one Rational Change server database and one Rational ClearQuest user database. This integration provides a web interface for creating and configuring synchronizers. Users can configure a synchronizer to define rules of synchronization that govern what attributes and states are to be synchronized and how.
© Copyright IBM Corporation 2009
US Government Users Restricted Rights—Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send written license inquiries to:
IBM Director of Licensing
IBM Corporation
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send written inquiries to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
The following paragraph
does not apply to the
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions. Therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
Intellectual Property Dept. for Rational Software
IBM Corporation
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
See http://www.ibm.com/legal/copytrade.html.
The
following products are required to run the Rational Change for ClearQuest
Interface:
·
Rational Change 5.1 with Rational® Synergy™ 6.6a
·
Rational Change 5.1 with Rational® Synergy™ 7.0
·
Rational Change 5.2 with Rational® Synergy™ 7.1
·
Rational Synchronization Server 1.4
·
Rational
ClearQuest 7.0 or 7.1
Before installing this integration install the following:
·
Rational Change
·
Rational ClearQuest
·
Rational Synchronization Server. Refer to Synchronization
Server Help for more details.
Note: The Synchronization Server must be installed on the same machine as Rational ClearQuest.
Before running this synchronizer, you need to set up one Change database. You must create two attributes with dbtype string in the CRProcess of each Change server. One attribute will contain the ClearQuest record ID of the record in the ClearQuest database. The other attribute will contain the location identifier of the record within ClearQuest. The values contained in these fields will be the same for this synchronizer.
These attributes are used later in General Settings Node
You must also set up one ClearQuest database. You must create two attributes with type SHORT_STRING through the ClearQuest Designer. Both of these fields should be set to have a minimum length of 254 characters. One attribute will contain the Change Request ID of the change request in the Change database. The other attribute will contain a hyperlink to the Change Request in the Change database.
These attributes are used later in General Settings Node
The Rational Change for ClearQuest Interface provides a web interface which can be used to manage synchronizers. You can use this interface to create a new synchronizer, modify an existing synchronizer and delete a synchronizer. To access the web interface you will need to log in to Synchronization Server’s admin interface. To access the admin interface, you can use the address http://server:port/TlogicIntegration/admin/SyncFramework.html, where server is hostname of the server hosting Synchronization Server and port is the port number.
Click the link Rational Change for ClearQuest Interface to open the web interface of the integration. The integration’s web interface consists of two panes. The first pane displays all the existing synchronizers in a tree form. The second pane displays details of the selected tree node as a web page.
The top level synchronizer node represents the following information about the synchronizer:
This is the name of synchronizer.
This is the name of the link file associated with the synchronizer. This field can not be changed.
This is the name of template file associated with the synchronizer. You may pick another existing file. A template contains information about the Change server, state mapping, and attribute mapping.
This is the name of the ClearQuest link file associated with the synchronizer. You may pick another existing file. A ClearQuest link file typically contains database and ClearQuest query information specific to the ClearQuest server.
This is the name of the ClearQuest template file associated with the synchronizer. You may pick another existing file. A ClearQuest template file typically contains server details and default attribute information specific to the ClearQuest server.
Specifies how often the synchronizer will run. If the time interval is specified as 30 minutes, the synchronizer will run every 30 minutes.
This is unit of time interval. It may be specified as minutes, hours or days.
If this filed is set to Yes, the synchronizer will run whenever Tomcat server starts up. The default value of this field is Yes.
This node represents information related to the Change server.
This is the address of the Change server. It must be specified in the form of http://server:port where server is the IP address of the Change server.
This is the Change database location and name.
This is the user role. This role is used when connecting with the Rational Change server.
This is the account ID of the user connecting with the Rational Change server.
This is the password for the User ID. The password is encrypted and saved on the server.
If this option is checked, all the new change requests will automatically be migrated to the ClearQuest server during synchronization.
This must be a valid Rational Change server query string. This is used in querying the Rational Change server for new change requests that will be migrated to the ClearQuest server. If this field is blank, all new change requests are migrated.
Click this button to get all available databases and user roles from the specified Rational Change server.
This node represents information related to the ClearQuest server.
This is the account ID of the user connecting to the ClearQuest server.
This is the password for the User ID.
Click this button to get all available databases from the ClearQuest server.
This is the ClearQuest user database location and name. A list of databases will appear after a valid user ID and password have been entered and the Connect button has been clicked.
If this option is checked, all the new ClearQuest records will automatically be migrated to the Rational Change server during synchronization.
This is a ClearQuest server query string that is selected from the drop-down list that is automatically populated when a CQ Database is selected. This is used in querying the ClearQuest server for new records that will be migrated to the Rational Change server as change requests. If this field is blank, all new ClearQuest items are migrated.
This node represents some general information.
This represents the date format used internally between the generic Change synchronizer and ClearQuest. IBM Rational recommends that you do not change the value specified in this field. The default value is MM/dd/yyyy HH:mm:ss.
Check this field if you wish to synchronize files attached to change requests and records.
Check this field if you wish to synchronize user comments.
Check this field if you wish to synchronize the status of change requests and records.
This is key information for the synchronizer, as the synchronizer links a change request with a ClearQuest record by storing the ID of each other in a predefined attribute. You must create these attributes before using this integration. See Setting up the Change Database and Setting up the ClearQuest Database for more details. Once you map a Rational Change attribute with a ClearQuest attribute, you will not be able to delete the mapping. However, you can replace it by choosing another set of attributes and clicking Map.
When the synchronizer links a change request and a ClearQuest record, it also stores a hyperlink of each in a predefined attribute. You must create these attributes before using this integration. See Setting up the Change Database and Setting up the ClearQuest Database for more details. The purpose of storing the hyperlink of change requests and records is to help you navigate from one change request to a record. Once you map a Rational Change attribute with a ClearQuest attribute, you will not be able to delete the mapping. However, you can replace it by choosing another set of attributes and clicking Map.
This node represents information about default attributes.
When the synchronizer migrates ClearQuest records from ClearQuest to the Rational Change server, you may want certain attributes to default to specific values. This field specifies all such attributes and their values. For a Date/Time type attribute, the value must adhere to the date format specified in the General Settings page.
When the synchronizer migrates change requests from a Rational Change server to a ClearQuest server you may want certain attributes to default to specific values. This field specifies all such attributes and their values. For a Date/Time type attribute, the value must adhere to the date format specified in the General Settings page.
This node represents information about how change request and record states are handled during migration and synchronization.
During migration Change Requests and ClearQuest records are submitted to a submit state. This field specifies the states for submission of Change Requests and ClearQuest records during migration. These states are used when a suitable state mapping is not available. Please note that the state you select here must be a valid submit state.
When you define a state mapping in the Rational Change for ClearQuest Interface, you are declaring that if a Change Request is transitioned to that state, it should be transitioned to the mapped state in the ClearQuest server. The choices you make in the Change to ClearQuest section means that whenever a CR is transitioned to a state on the Rational Change server, it will be transitioned to the mapped state on the ClearQuest server. Mappings in the ClearQuest to Change section mean that if a record is transitioned to a state in the ClearQuest server, it will be transitioned to the mapped state on the Rational Change server. In the case where the CR and record is transitioned in both the Rational Change and ClearQuest servers, the state will be used from the CR or record that was modified most recently. The ability to define the mappings in each direction allows you maximum flexibility in determining how your synchronization will work. For example, you can have three review states in one process mapped to a single review state in the other process.
This node represents how change request and record attributes are handled during synchronization.
The synchronizer synchronizes a change request with a ClearQuest record over a list of mapped attributes. Attribute mapping takes an attribute from the Change server and another like attribute from the ClearQuest server and assigns a direction of synchronization. The available directions of synchronization are described below:
|
Direction |
Description |
|
on |
The change request/record which was modified last will retain the value of mapped attribute. |
|
changetoadapter |
The change request from the Rational Change server will retain the value of mapped attribute. |
|
adaptertochange |
The record from the ClearQuest server will retain the value of mapped attribute. |
Note: The synchronizer filters out certain Rational Change attributes from the Attribute Mapping page. This is done to make sure unwanted attributes are not mapped by the user. For example, the Rational Change attribute problem_number should not participate in synchronization and therefore it is not available for mapping. Users can modify the list of filtered attributes by modifying the content of the properties file CATALINA_HOME\webapps\TlogicIntegration\WEB-INF\conf\etc\attributefilter.properties, where CATALINA_HOME is the path to your Tomcat installation.
|
Property |
Description |
|
ccs.attributes |
Specify Change attributes delimited by a comma (,). All these attributes will be filtered. The default list is: problem_number, crstatus, transition_log, creator, create_time, created_in, owner, modifiable_in, modify_user, modify_time
|
|
ccs.dbtypes |
Specify dbtype of Change attributes delimited by a comma (,) that you want to filter. The default list is: child, sibling
|
|
ccs.webtypes |
Specify webtype of Change attributes delimited by a comma (,) that you want to filter. The default list is: CCM_SUBSCRIPTION, CCM_E_SIGNATURE |
|
ccs.startswith |
Specify first character of Change attributes delimited by a comma (,) that you want to filter. The default character is underscore (_)
|
|
ccs.endswith |
Specify last character of Change attributes delimited by a comma (,) that you want to filter. The default character is underscore (_)
|
|
ccs.contains |
Specify substring present in Change attributes delimited by a comma (,) that you want to filter. This is not a regular expression. The substring has to be exact. The default substring is ***
|
Use the web interface to create new Synchronizer. Perform the following steps:
There are four xml files associated with a synchronizer.
Link File:
Located atCATALINA_HOME\webapps\TlogicIntegration\WEB-INF\ conf\Links\cqchangeadapter\changeadapter_link_MMddyyyyHHmmss.xml
Template File:
Located at CATALINA_HOME\webapps\TlogicIntegration\WEB-INF\ conf\Templates\cqchangeadapter\changeadapter_template_MMddyyyyHHmmss.xml
ClearQuest Link File:
Located at CATALINA_HOME\webapps\TlogicIntegration\WEB-INF\conf\Templates\cqchangeadapter\adapterlinks\cqadapter_adapter_link_MMddyyyyHHmmss.xml
ClearQuest Template File:
Located at CATALINA_HOME\webapps\TlogicIntegration\WEB-INF\conf\Templates\ changechangeadapter\adaptertemplates\cqadapter_adapter_template_MMddyyyyHHmmss.xml
Where
CATALINA_HOME is the path to your Tomcat installation. MMddyyyyHHmmss represents the time the synchronizer was created.
From the tree pane, select the synchronizer you want to modify. Choose the relevant web page and make necessary changes. Click Save.
From the tree pane, select the synchronizer you want to delete. Click Delete. All the XML files related to the selected synchronizer will be deleted.
The Rational Change for ClearQuest Interface is operated by the Synchronization Server. The Synchronization Server loads the synchronizer based on the information present in the Link file. The synchronizer then examines the Template file, the ClearQuest Link File and the ClearQuest Template file to gather Change and ClearQuest server logon information, state mapping, attribute mapping and the rest of the information. The synchronizer verifies the logon information and then logs on to the Change and ClearQuest servers and performs the following tasks:
Query:
Using the migrate query; it queries the Change server for new change requests.
Using the migrate query for ClearQuest, it queries the ClearQuest server for new ClearQuest records.
The synchronizer queries the Change server for change requests that were linked earlier as a result of migration, and that were modified since the last sync time. If the last sync time is not available, then all linked change requests are considered.
The synchronizer also queries the ClearQuest servers for ClearQuest records that were linked earlier as a result of migration, and that were modified since last sync time. If the last sync time is not available, then all linked ClearQuest records are considered.
Migrate:
Having queried new and modified change requests, the synchronizers migrates all new change requests from the Change server to the ClearQuest server. For each new change request in the Rational Change server, a ClearQuest record is created in the ClearQuest server. The change request and ClearQuest record are linked together using ID Mapping and URL Mapping as described above (see General Settings Node). The state of the ClearQuest record created in the ClearQuest server is deduced from the state mapping information (see State Mapping Node). If the option Synchronize Attachments (see General Settings Node) is enabled, change request attachments are also migrated.
Likewise, the synchronizer also migrates new ClearQuest records in the ClearQuest server to the Rational Change server. Attachments are migrated if the option Synchronize Attachments (see General Settings Node) is enabled.
Synchronize:
The
synchronizer walks through the list of modified change requests and for each
change request, identifies the linked ClearQuest record in the ClearQuest
server. The change request and ClearQuest record are synchronized over
mapped attributes only. Attributes are updated according to the direction of
synchronization. If the direction of synchronization is set to on, the
attributes of a change request overwrite the attributes of a ClearQuest
record, if the change request was modified last. Similarly, attributes of a
ClearQuest record overwrite the attributes of a change request if the ClearQuest
record was modified last.
It’s important to notice which attributes in ClearQuest are normally set using a drop-down list in the ClearQuest client. If there is a mapping relationship set between a Change attribute and one of these specified attributes, i.e. Severity (Change) to Severity (ClearQuest), the value of the attribute in Change must match a valid selection in the drop-down list of the mapped attribute in ClearQuest, or the synchronization may fail.
The change request states and ClearQuest record states are updated according to state mapping rules (see State Mapping Node).
Files attached to change requests and ClearQuest records are synchronized if the option Synchronize Attachments (see General Settings Node) is enabled. The file name is used as the key in synchronizing attachments. If a change request has more than one attachment with the same file name, only the first attachment with that name will be synchronized. Synchronization of attachments is always two ways, irrespective of the modification time of both the change request and ClearQuest record.
Likewise, the synchronizer walks through the list of modified ClearQuest records, and for each ClearQuest record, it identifies the linked change request and performs synchronization.
Note: If synchronization was successful, the time at the beginning of the synchronization will be saved as the last sync time to be used during the next run. The synchronizer uses the time at the beginning of the synchronization rather than the time at the end of the synchronization in order to ensure that any modifications that happened during the synchronization process are captured during the next synchronization.
The first things to check in the event of synchronization failure:
Make sure the Rational Change server URL, usernames, and passwords are correct. Make sure the Rational Change database path is valid.
Make sure the ClearQuest usernames and passwords are correct.
Logging:
Logs for the Synchronizer are located at CATALINA_HOME/webapps/TlogicIntegration/WEB-INF/logs. The log will have the same name as the link file. The synchronizer logs warnings, errors, and informational messages about the actions it is taking. These logs should be sent to IBM Rational Support to help diagnose the cause of any errors. If debugging is enabled in the Synchronization Server, the Rational Change for ClearQuest Interface will log debug messages as well.
If the self-help resources have not
provided a resolution to your problem, you can contact IBM® Rational® Software
Support for assistance in resolving product issues.
Note: If you are a heritage Telelogic
customer, a single reference site for all support resources is located at http://www.ibm.com/software/rational/support/telelogic/
To submit your problem to IBM
Rational Software Support, you must have an active Passport Advantage® software
maintenance agreement. Passport Advantage is the IBM comprehensive software
licensing and software maintenance (product upgrades and technical support)
offering. You can enroll online in Passport Advantage from http://www.ibm.com/software/lotus/passportadvantage/howtoenroll.html
To submit your problem online (from
the IBM Web site) to IBM Rational Software Support, you must additionally:
To submit your problem to IBM Rational
Software Support:
1.
Determine
the business impact of your problem. When you report a problem to IBM, you are
asked to supply a severity level. Therefore, you need to understand and assess
the business impact of the problem that you are reporting.
Use the following table to determine the severity level.
|
Severity |
Description |
|
1 |
The problem has a critical business impact: You are
unable to use the program, resulting in a critical impact on operations. This
condition requires an immediate solution. |
|
2 |
This problem has a significant business impact: The
program is usable, but it is severely limited. |
|
3 |
The problem has some business impact: The program is usable,
but less significant features (not critical to operations) are unavailable. |
|
4 |
The problem has minimal business impact: The problem
causes little impact on operations or a reasonable circumvention to the
problem was implemented. |
2.
Describe
your problem and gather background information. When describing a problem to
IBM, be as specific as possible. Include all relevant background information so
that IBM Rational Software Support specialists can help you solve the problem
efficiently. To save time, know the answers to these questions:
o
Start
the IBM Installation Manager and select File
> View Installed Packages. Expand
a package group and select a package to see the package name and version
number.
o
Start
your product, and click Help > About to see the offering name and
version number.
3.
Submit
your problem to IBM Rational Software Support. You can submit your problem to
IBM Rational Software Support in the following ways: