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 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.

About this task

See Planning synchronization rules for details about creating a planning worksheet before you create synchronization rules. In addition to the topics in this section, see for examples of mapping ClearQuest record field types to EWM item properties.
Note: Content on is governed by the Terms of Use and is provided as is without warranties of any kind.


To create a synchronization rule:

  1. Login to the EWM client.
  2. In the Team Artifacts view, right-click the repository connection and select Administer > Synchronization Rules. In the Synchronization Rules view, right-click the project area and select New > Synchronization Rule. 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.
  3. 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.
  4. 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.

  5. 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.
  6. 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.
  7. 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.

  8. 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.