Editing synchronization rules to specify categories

Edit online

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. The Category property appears as Filed Against in the Work Item editor and Synchronization Rule editor.

About this task

You can provide IBM® Engineering Workflow Management (EWM) 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
  1. Create one or more records of a stateless ClearQuest record type, such as Project, that reasonably corresponds in meaning to category. Ensure that the record type you want to synchronize has a field where users indicate the type of Project (or other stateless record type) that the record belongs to. For example, the Defect record type contains a Project field.
  2. Create a synchronization rule for the stateless record type, such as Project. Set the Item Type to Category - com.ibm.team.workitem. In the Property Mappings section, map at least the Name external property to the Name item property. Click Save to save the synchronization rule.
  3. Open the synchronization rule for the record type, such as Defect, that you want to synchronize with work items. In the Property Mappings section, click Add. Select Filed Against for the Item property. For the External property, select the name of the field that is a reference to the stateless record type you created (for example, Project). In the Synchronization field, select In/Out to enable bidirectional synchronization. In the Reference synchronization rule field, select the synchronization rule that you created for the stateless record type.
  4. Click OK. Click Save to save your changes.

To map one or more ClearQuest record string-value fields to a category:

  1. In the Property Mappings section of the synchronization rule for the record type, select Filed Against for the Item property. Select the ClearQuest field for the External property. You can use multiple ClearQuest fields to compose a multi-level value that corresponds to the category property. For example, you might have a field named Project and another field named Subproject. Specify this hierarchy in the External property by separating the field names with a slash. For example, Project/Subproject.
  2. Deselect No Transformation. In the Value transformer list, select Work Item Category Transformer.

    You can specify value mappings for the property mapping that uses the Work Item Category Transformer value transformer. In the incoming direction, the ClearQuest Synchronizer applies the value mapping before the transform. The External Value must be a simple field reference; the field name cannot contain a period (.) or a slash (/). You can map a field value that is to be interpreted as the name or path of a work item category to some other category name or path. In the outgoing direction, the ClearQuest Synchronizer applies the value mapping after the transform so that the work item category path can be mapped to some other string.

  3. Click Save to save your changes.

To map an empty external value to a fixed category value:

  1. In the Property Mappings section of the synchronization rule for the record type, select Filed Against for the Item property. Enter a name of a nonexistent field, such as Dummy, for External property. In the Mapping Details section, set Synchronization to In.
  2. Deselect No Transformation. In the Value transformer list, select Work Item Category Transformer. Add a mapping in the Value mappings section. Leave the External Value blank. For the Item Value, enter the name of the category that you want to be set on every incoming synchronization operation that creates a work item.
  3. Click Save to save your changes.

To map one or more ClearQuest records with a category:

  1. Create a synchronization rule for each record type that contributes a field value to the item property that the parent record type uses to map to a category. For example, you might compose the item property by combining the values of the Name field in the Project and Subproject record types. The parent record type, such as Defect, contains two fields that are references to Project and Subproject records. In this example, you create synchronization rules for the Project and Subproject record types. In the Synchronization Rule editor, leave the Item type field blank. Because this record type contributes only a name to the parent record type, it is not connected to any EWM item. In the External type field, select the record type for which you are creating the synchronization rule. In the Property Mappings section, enter the name of the field in the External property field. For example, Name. Select External identifier.
  2. Click Save to save your changes.
  3. In the synchronization rule for the parent record type (in this example, Defect), click Add to add a property mapping. Select Filed Against in the Item property field. In the External property field, enter a value that identifies the reference fields in the parent record type and the fields in the referenced record types. Use a period to separate the reference field in the parent record type from the field in the referenced record type. Use a slash to separate the reference fields in the parent record type. For example, Project.Name/Subproject.Name where Project and Subproject are reference fields in the Defect record type that point to Project and Subproject records, respectively. The Project and SubProject record types each contain a Name field. In the Synchronization field, select In/Out. In the Value transformation section, de-select No transformation. Select the Work Item Category Transformer.

    As described in the previous scenario, you can specify value mappings for the property mapping that uses the Work Item Category Transformer value transformer.

    You also need to add property mappings for the reference fields (in this example, Project and Subproject). Click Add in the Property Mappings section. Leave the Item Property blank. Select one of the reference fields (for example, Project) in the External Property. In the Synchronization field, select none. In the Reference synchronization rule field, select the synchronization rule that you created for the record type that is pointed to by the reference field. In this example, the Project field is a reference to a Project record. The Project record type has a synchronization rule. Add a mapping for the second reference field (in this example, Subproject).

  4. Click Save to save your changes.

A variation of the previous scenario is possible. The field in the child record type or types might be a reference, rather than a string-value field, to another record. It is possible to have a chain of references before reaching the record that contains the string-value field. Create a synchronization rule for each record type in the chain of references. In the synchronization rule for the parent record type, select Filed Against in the Item property field. In the External property field, enter a value that identifies the chain of references and the string-value field at the end of the path. Specify the value as a sequence of field names separated by periods (.). This variation is supported for incoming synchronization only.