Planning synchronization rules

Before you can create synchronization rules, you need to analyze the ClearQuest® record type or types that you want to synchronize with IBM® Engineering Workflow Management (EWM) work items and create a plan for mapping fields in the record types to properties in work items.

About this task

Ideally, the person who plans and creates synchronization rules should be the person who created or maintains the ClearQuest schema. You should also have a basic understanding of Jazz™ and be familiar with project areas and work items.

It is not practical to map every record type to a work item type. The two types should be similar in their purpose, required fields, and state transition model. Review all record types defined in the schema for the user database that you want to connect to a Jazz project area, and identify which record types are good candidates for synchronization.

You can use the ClearQuest Synchronizer Setup Wizard to create initial versions of synchronization rules, but you need to edit those rules to specify additional mapping details. At a minimum, you must edit the synchronization rules to specify how to set the Category property of work items.

As you work through the following planning steps, record information about your record type in the accompanying worksheet. Create a worksheet for each record type that you plan to synchronize. Use the worksheet when you start to create or edit synchronization rules. If you use the ClearQuest Synchronizer Setup Wizard to create initial versions of synchronization rules, open those synchronization rules in the Synchronization Rules editor; compare the mapping details to the requirements in your planning worksheet; and identify any gaps.


  1. Using the EWM Story work item type, develop the use case that describes how your team plans to work in EWM. The Story should indicate the process (such as Scrum), work item types, and workflows your team intends to use.
  2. Based on the Story, identify which ClearQuest record type or types to synchronize with which work item types. If no out-of-the-box EWM work item type is a close match to a ClearQuest record type that you want to synchronize, you can create a work item type to correspond to that record type.
  3. You can map one ClearQuest record type to multiple work item types. For example, your record type might be general, such as Change Request, and contain a field that qualifies it as a Bug or Release Requirement. If you have this situation, indicate the name of the ClearQuest field that you use to qualify the record type, and list the field values and their corresponding work item types.
  4. Define the synchronization direction between the record type and work item type. If you plan to import a set of records from a ClearQuest user database into a Jazz repository, and then have your team work solely in EWM, the synchronization direction is In only. If you intend to work in both EWM and Rational® ClearQuest, the synchronization is In and Out.
  5. Identify the set of required fields in the ClearQuest record type and in the corresponding work item type. If you use the Scrum process, the Defect and Task work item types require entries in only the Summary and Filed Against (Category) fields. On the Overview page of the Work Item editor, the required fields are identified with an asterisk.

    To see the required fields of the ClearQuest record type, open the schema in the ClearQuest Designer. Click Start > All Programs > IBM Rational > IBM Rational ClearQuest > ClearQuest Designer. In the Open Schema wizard, select the schema for the record type that you want to synchronize. In the navigation pane, expand the Record Types folder, the specific record type folder, and then the States and Actions folder. Double-click Behaviors. The Behaviors matrix identifies required fields as Mandatory.

  6. For each of the required ClearQuest fields, identify a field in the work item type to which you can map the ClearQuest field. Similarly, for each required work item type field, identify a corresponding ClearQuest field. In choosing an appropriate mapping field, consider the meaning of the field and the field type. To see field types of ClearQuest record types, open the schema for the record type in the ClearQuest Designer. In the navigation pane, expand the Record Types folder, the specific record type folder, and then double-click Fields to open the Fields matrix.

    To see field types in EWM, login to the EWM client. In the Team Artifacts view, double-click the project area to open it in the Project Area editor. Click the Process Configuration tab. Expand Project Configuration, then Configuration Data, and then Work Items. Click Editor Presentations. Select the editor presentation for the work item type that you are synchronizing. In the Editor Presentation area, expand the tabs and sections to see the list of presentations (fields). The type appears in parentheses after each field name.

  7. If the work item type does not have appropriate fields for mapping to some of the required ClearQuest record type fields, create new fields in the work item type. On the Project Configuration page, expand Project Configuration, then Configuration Data, and then Work Items. Click Types. Select the work item type category. In the Custom Attributes area, click Add. Enter a name for the field, and select a type that is compatible with the corresponding ClearQuest field type. Click OK. Click Save to save your changes to the work item type.
  8. If the record type does not have appropriate fields for mapping to some of the required work item type fields, create new fields in the record type by adding rows in the Fields matrix.
  9. During incoming synchronization, the category property of a work item must be set because the work item is associated with a team area based on its category. You can provideEWM with the category information in the following ways:
    • Connect a stateless ClearQuest record with a category
    • Map one or more ClearQuest record string-value fields to a category
    • Map an empty external value to a fixed category value
    • Map, but do not connect, one or more ClearQuest records with a category

    See Editing synchronization rules to specify categories for details about these methods, then choose one of the methods to use.

  10. Identify any additional, nonrequired, ClearQuest record fields that you want to synchronize with work item fields. Identify the corresponding work item fields. If necessary, create fields in the work item type by adding custom attributes.
  11. Identify any ClearQuest record fields that you want to display in the work item but not synchronize with a work item field.
  12. Do any of the fields that you want to synchronize have choice lists of values, such as a Priority or Severity field? For each such field, identify the mapping of values from the ClearQuest record field to the work item field. If there is not a one-to-one mapping of all values, designate one as the default value.
  13. Do any of the fields that you want to synchronize require special handling to transform their values before those values can be sent to their corresponding work item fields or ClearQuest record fields?

    The ClearQuest Synchronizer provides the following value transformers.

    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. You must use the standard Notes package provided with Rational ClearQuest.
    Work Item Tags Transformer Transforms tags in a work item to keywords in a ClearQuest record.

    Identify any fields that require transformation and list the transformers required.

  14. If the record type includes attachments, you can create a synchronization rule so that when a ClearQuest record is synchronized with a work item, any attachments to the record and work item are also synchronized. Indicate if you plan to synchronize attachments.
  15. Identify any of the ClearQuest record fields that you plan to synchronize that are reference type fields. You must create synchronization rules for the record types referenced by these fields.
  16. Do any of the ClearQuest record fields that you plan to synchronize have hooks that establish dependencies with other fields? For example, a hook associated with one field might use the value that a user enters into that field to determine how to set the value of another field. In this scenario, you must identify the order in which the hooks should be executed to ensure that the ClearQuest record fields are set to the correct values.

    The file includes a parameter, cq.orderedProperties.record-type, that you can use to specify the order in which ClearQuest record field values should be set. All fields that you do not specify with cq.orderedProperties.record-type are processed after the specified fields.

    Another way to specify the order is to use the Web Dependent Fields property on fields in the form definition in the ClearQuest Designer. If you specify both the Web Dependent Fields property and the cq.orderedProperties parameter, the ClearQuest Synchronizer uses the order specified with the cq.orderedProperties parameter.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki