Creating synchronization rules
You need to create synchronization rules for the ClearQuest® record types that you plan to map to IBM® Engineering Workflow Management (EWM) items.
Before you begin
You can use the ClearQuest Synchronizer 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 EWM Eclipse client.
To create, modify, and delete synchronization rules, you must be assigned either a Developer or ClearQuest Synchronizer 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 ; 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.
About this task
To create a synchronization rule:
- Login to the EWM client.
- In the Team Artifacts view, right-click the repository connection and select . In the Synchronization Rules view, right-click the project area and select . To edit an existing synchronization rule, expand the project area node to see the synchronization rules. Double-click a rule to open it in the Synchronization Rule editor.
- In the Synchronization Rule editor, enter a unique name for the rule in the Name property. Using a naming convention similar to that for naming Java™ packages is one way help ensure unique naming. For example: com.sapphire.clearquest.SchemaName.RecordType where SchemaName is the name of the ClearQuest schema and RecordType is the name of the record type in that schema that you want to synchronize.
- In the Type Mapping section, select
the item type that you want to synchronize with the ClearQuest record type. The Item manager
property is set to the manager that creates and synchronizes the item
type you selected. In the External repository field,
select the external repository connection to be used when processing
this synchronization rule. Select ClearQuest Manager (non-user
records) as the External manager for
all record types except users. For the users record type, select ClearQuest
Manager (user records). Note: becauseEWM user items do not belong to one project area, you can have only one synchronization rule for the users record type per Jazz® Team Server. In the External type field select the ClearQuest record type that you want to synchronize with the EWM item.
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.
- In the Enabled Team Areas section, select and de-select team areas to limit the scope of the synchronization rule. By default, all EWM items associated with a project area that has synchronization rules are candidates for outgoing synchronization. You might want to create ClearQuest records only for items associated with certain team areas. If a parent team area is selected, all of its child team areas are also selected. You can select a child team area without selecting its parent team area.
- Use the Maximum cycle count field to specify the number of synchronization cycles the ClearQuest Synchronizer should attempt before the synchronization operation fails. When writing a synchronization rule for a stateful record type, select Synchronize all item states. For stateless record types, do not select Synchronize all item states.
- In the Property Mappings section
specify which work item properties map to which ClearQuest record type fields. Click Add to
create a mapping. Select an item property and a corresponding external
property (ClearQuest record
type field). To map a work item relationship, select one of the following
item properties: Related, Blocks, DependsOn, Parent, or Children.
Then select the external property that references the related ClearQuest record. Rather than adding mappings one at a time, you can click Initialize to create an initial set of mappings based on matching, or partial matching, property names. You can then go through the list and remove or edit mappings as necessary.
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 EWM items. Out enables synchronization only from EWM 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 aEWM 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 EWM 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 EWM 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 EWM 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 Synchronizer provides the following value transformers. You can add transformers by creating plug-in extensions.
Table 1. ClearQuest Synchronizer transformers 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 Synchronizer. 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 Synchronizer. 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 theEWM 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, EWM 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 EWM attachment to a ClearQuest record attachment. Work Item Category Transformer Maintains the hierarchical structure of EWM categories mapped to ClearQuest records when the value is a path. Work Item Comments Transformer Converts a EWM 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 EWM 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.
- Click Save to save your work.
What to do next
Anytime you add a synchronization rule, or add or remove a query, you must stop and restart the ClearQuest Gateway so that the ClearQuest Synchronizer uses the new synchronization criteria.