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
Rational Team Concert™ 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 valule
- Map, but do not connect, one or more ClearQuest records with a category
To connect a stateless record with a category:
Show Me
- 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.
- 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.
- 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.
- Click OK. Click Save to
save your changes.
To map one or more ClearQuest record
string-value fields to a category:
- 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.
- 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 Connector 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 Connector applies
the value mapping after the transform so that the work item category
path can be mapped to some other string.
- Click Save to save your changes.
To map an empty external value to a fixed category value:
- 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.
- 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.
- Click Save to save your changes.
To map one or more ClearQuest records
with a category:
- 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 Rational Team Concert 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.
- Click Save to save your changes.
- 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).
- 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.