You can use the ClearQuest Connector Setup Wizard to create synchronization rules or templates of synchronization rules. However, after using the wizard to generate synchronization rules, you still need to review and modify the rules before they are ready to be used. This topic describes how to create and modify rules by using the Synchronization Rule editor in the Rational Team Concert Eclipse client.
To create, modify, and delete synchronization rules, you must be assigned either a Developer or ClearQuest Connector Client Access License. In addition, the project area must be configured to grant permissions to your user role. To set permissions, open the project area; click the Process Configuration tab; click Project Configuration > Permissions; select a role; and select Item Connectors in the Permitted Actions list.
Be sure to start the ClearQuest Gateway before you create a synchronization rule; otherwise, the Synchronization Rule editor lists are not populated with fields from ClearQuest record types.
To create a synchronization rule:
When a new work item is created, its Type field is mandatory. The synchronization rules that you create to map record types to work items must indicate how to set the value of the work item Type field. See Mapping record types to work item types for details.
The Mapping Details section shows the details for the mapping selected in the Property Mappings table. To clear an entry in either the Item property or External property field, select None under Item Property or External Property. Use the Synchronization field to specify the synchronization direction. In/Out enables bi-directional synchronization. In enables synchronization only from the ClearQuest user database to Rational Team Concert items. Out enables synchronization only from Rational Team Concert items to the ClearQuest user database. Item identifier is selected when the property is used as the lookup key for mapping an item to a ClearQuest record. External identifier is selected when the ClearQuest field is used as the lookup key for mapping a ClearQuest record to aRational Team Concert item. Typically, you should not have to set the Item identifier or External identifier fields. Assuming the ClearQuest Gateway is running, the Synchronization Rule editor sets these two fields when necessary.
By default, when changes to ClearQuest records are synchronized with Rational Team Concert items, the update operation is executed using the Jazz user account that the ClearQuest Gateway uses to login to the Jazz repository. The External modifier field lets you configure the synchronization rule so that changes are recorded in the context of the user who makes them. See Configuring synchronization rules for external users for details.
If a property value is a reference to another object that has a synchronization rule defined, select that synchronization rule in the Reference synchronization rule list. For example, if the ClearQuest Defect record type contains a field with a reference to the users record type, select the synchronization rule for the users record type. During synchronization, that synchronization rule is processed and a reference from the Rational Team Concert item to the Jazz user is established. If a property is a reference to another work item, it does not matter which work item synchronization rule you specify as the reference synchronization rule. The synchronization operation uses the correct synchronization rule when it determines the type of the referenced object. For example, assume that the Defect and Enhancement work item types each contain the DuplicateOf property, which is a reference to another work item. The property mapping for DuplicateOf in the Defect synchronization rule specifies the Defect synchronization rule as the reference synchronization rule. Likewise, the property mapping for DuplicateOf in the Enhancement synchronization rule specifies the Enhancement synchronization rule as the reference synchronization rule. If the synchronization operation determines that a Defect is marked as a duplicate of an Enhancement, it uses the Enhancement synchronization rule.
Use the Value transformer section to specify any special handling that needs to be done to transform data being propagated between the Rational Team Concert item and the ClearQuest record field. Leave No transformation selected if you do not need to transform data; otherwise deselect it to activate the other fields. The ClearQuest Connector provides the following value transformers. You can add transformers by creating plug-in extensions.
| Transformer name | Description |
|---|---|
| Connect Field to Custom Attribute Transformer | Maps the value of a custom attribute of a work item to a field in a ClearQuest record that is referenced by a field in another record. |
| Contributor Details Transformer | Not currently used with the ClearQuest Connector. |
| Display Referenced Record Fields in Custom Attribute Transformer | Maps the contents of a referenced ClearQuest record to a work item custom attribute so that the contents can be displayed in the work item editor. |
| Project Area Transformer | Not currently used with the ClearQuest Connector. |
| Timestamp/Days Transformer | Converts a string that identifies the number of days in a ClearQuest record to the number of milliseconds, which is what the timestamp uses to determine time. |
| Work Item Action Transformer | Computes the action to take when transitioning
from one state to another during incoming synchronization This is
needed if theRational Team Concert item
work flow definition contains ambiguous state transitions where more
than one action is possible to transition between two states. Unlike Rational ClearQuest record types, Rational Team Concert work item types allow more than one action to transition from one state to another. If you do not use the Work Item Action Transformer to synchronize items that contain multiple actions for state transitions, a synchronization operation following a state transition generates an error saying that the ClearQuest record cannot be transitioned to another state. |
| Work Item Attachments Transformer | Converts a Rational Team Concert attachment to a ClearQuest record attachment. |
| Work Item Category Transformer | Maintains the hierarchical structure of Rational Team Concert categories mapped to ClearQuest records when the value is a path. |
| Work Item Comments Transformer | Converts a Rational Team Concert Comment to a ClearQuest record Note. |
| Work Item Tags Transformer | Transforms tags in a work item to keywords in a ClearQuest record. |
Some value transformers might require additional properties before they can transform the data. If necessary, click Set other input properties needed by transformer, and select the properties in the Required Properties dialog box.
Use the Value mappings section to specify values to map from items to records. Click Add. Enter an item value and the corresponding ClearQuest record field value. If there is not a one-to-one mapping of all values, designate one as the default value. For example, the ClearQuest Priority field might have four values (1, 2, 3, and 4) and the Team Concert Priority property might have three values (High, Medium, and Low). If you map High to both 1 and 2, select 1 or 2 as the Default external value. To specify a value of empty for a ClearQuest record field, leave the value blank. Rather than adding value mappings one at a time, you can click Initialize to create an initial set of mappings based on matching, or partial matching, value names. You can then go through the list and remove or edit value mappings as necessary.
Rational ClearQuest and Rational Team Concert allow you to identify duplicate records and items, respectively. To synchronize duplicates, map the Item property DuplicateOf to the External property original. In the Reference synchronization rule field, select the synchronization rule used for work items.
Anytime you add a synchronization rule, or add or remove a query, you must stop and restart the ClearQuest Gateway so that the ClearQuest Connector uses the new synchronization criteria.
Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug