Mapping record types to work item types

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.

Before you begin

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

Depending upon which process template your project area uses, you might have multiple types of work items, such as defects, tasks, and enhancements. You can create synchronization rules to map these multiple work item types to multiple ClearQuest record types. The Synchronization Rule editor includes an Item type qualifier field, which you can use to indicate that the rule applies to a specific type of work item or a category of work item types. A type category defines characteristics that are common to all types that belong to that category. For example, all types in a category use the same workflow. The following table lists the categories and types for the Scrum process.
Table 1. Work item categories and types for Scrum process
Type category Types
workItemType - com.ibm.team.workitem.workItemType Defect, Task
epic - com.ibm.team.workitem.workItemType.epic Epic
impediment - com.ibm.team.workitem.workItemType.impediment Impediment
retrospective - com.ibm.team.workitem.workItemType.retrospective Retrospective
story - com.ibm.team.workitem.workItemType.story Story
Currently, the epic, retrospective, impediment, and story categories each contain only one type. The workItemType category contains two types.

Use the work item type qualifier to map different ClearQuest record types to different work item types.

Use the work item type category qualifier if you have one ClearQuest record type that maps to multiple work item types. Typically, the ClearQuest record type has a field whose value indicates the type of change request.

Do not specify the same qualifier in more than one synchronization rule, as this causes unpredictable synchronization behavior.

To specify mapping using the type categories provided with the Scrum process:

Show Me

Procedure

  1. 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 or double-click an existing rule to open it.
  2. In the Item type field, select WorkItem - com.ibm.team.workitem. To map one ClearQuest record type to multiple work item types, select TypeCategory: workItemType - com.ibm.team.workitem in the Item type qualifier field, and select the record type in the External type field. In the Property Mappings section, click Add to add a mapping. Select Type in the Item property field. In the External property field select the field in the ClearQuest record type that you use to indicate the type of change request. In the Value transformation section, deselect No transformation. In the Value mappings section, add entries to map the values of the record type field, such as Defect, Enhancement, and Task, to the corresponding work item types.

    If you have multiple ClearQuest record types and want to map each one to a different work item type, create separate synchronization rules for each record type. In the Item type qualifier field, select the type. For example to map a ClearQuest enhancement record type to the Enhancement work item type, select Enhancement. In the Property Mappings section, select Type in the Item property field. Select record_type in the External property field. In the Synchronization field, select In. Deselect No transformation. In the Value mappings section, add an entry that maps the record type to the work item type. For example, Enhancement and Enhancement.

Results

Note: Users can change the type of a work item. If a user changes the type after the work item has been mapped to a ClearQuest record, a different synchronization rule might be used the next time that work item is synchronized. You cannot change the record type of a ClearQuest record. If the new work item type uses a different workflow than the previous type, problems occur during synchronization because that workflow does not correspond to the state transition model defined for the ClearQuest record type.

Feedback

Did this help? You can provide feedback at Jazz.net (registration required): Comment in the forums or submit a bug