Mapping referenced fields

Some ClearQuest® record types include fields that are references to fields in other records. If these reference fields are mandatory, you must provide a way to map a value to them during synchronization.

About this task

You can map a custom attribute of a work item to a field of a referenced record. To enable this mapping, you must edit the project area process configuration and the synchronization rule for the record type. The example in the following steps assumes that the schema contains a stateless record type named OS, which contains a field named Name . The Defect record type contains a field named FoundInPlatform, which is a reference to an OS record.

To map a reference field:

1. In the IBM® Engineering Workflow Management (EWM) client, open the Team Artifacts view.
2. Right-click your project area and select Open.
3. In the Project Area editor click the Process Configuration tab. Expand Project Configuration, then Configuration Data, and then Work Items. Click Types and Attributes. Select the work item type category. In the Custom Attributes area, click Add. Enter a name for the attribute, and select a type that is compatible with the corresponding ClearQuest field type. For example, Found in Platform and smallString. Click OK. Click Save to save your changes to the work item type.
4. 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.
5. In the Synchronization Rule editor, enter a name for the rule. For example: com.ibm.rational.clearquest.sample_schema_repo.FoundInPlatform. Leave the Item type and Item manager fields blank. Enter a name in the External type field that identifies the ClearQuest record type. For example: com.ibm.rational.clearquest.sample_schema_repo.OS identifies the OS record type, which contains the field referenced by the FoundInPlatform field. In the External manager field, select ClearQuest Manager (non-user records). In the Property Mappings section, click Add. In the External property field, enter the name of the field in the record referenced by the other field. For example, the FoundInPlatform field references the Name field in the OS record type. Select External identifier. Click OK. Click Save to save the synchronization rule.
6. In the Synchronization Rules view, double-click the synchronization rule for the record type that contains the reference field to open the Synchronization Rule editor.
7. Click Add to add a property mapping. In the Item property field, select the custom attribute that you created. For example: Found In Platform. In the External property field, select the ClearQuest record reference field and a field in the record it references. For example: FoundInPlatform.Name refers to the FoundInPlatform field that references the Name field in another record. In the Synchronization field, select In/Out. De-select No transformation. In the Value transformer field, select Connect Field to Custom Attribute Transformer.
8. Click Add to define a second property mapping. In the External property field, select the reference field. For example: FoundInPlatform. Leave the Item property field empty. De-select No transformation. In the Reference synchronization rule field, select the synchronization rule that you previously defined. For example: com.ibm.rational.clearquest.sample_schema_repo.FoundInPlatform. Click Save to save the modified synchronization rule.

   You can specify value mappings for the property mapping that uses the Connect Field to Custom Attribute Transformer value transformer. For both incoming and outgoing values, the ClearQuest Synchronizer applies the value mapping after the transform. For example, for a field reference such as Priority.Name, the ClearQuest Synchronizer finds the value of the Name field in the Priority record and then applies the value mappings to that value. In the outgoing direction, the ClearQuest Synchronizer applies the value mappings after it finds the EWM item property.