Before you can create synchronization rules, you need to
analyze the ClearQuest® record
type or types that you want to synchronize with Rational Team Concert™ 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 Connector
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 Connector 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.
To
plan your synchronization rules:
- Using the Rational Team Concert Story
work item type, develop the use case that describes how your team
plans to work in Rational Team Concert.
The Story should indicate the process (such as Scrum), work item types,
and workflows your team intends to use.
- Based on the Story, identify which ClearQuest record type or types to synchronize
with which work item types. If no out-of-the-box Rational Team Concert 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.
- 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.
- 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 Rational Team Concert,
the synchronization direction is In only. If you intend to work in
both Rational Team Concert and Rational® ClearQuest,
the synchronization is In and Out.
- 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 . 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.
- 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 Rational Team Concert,
login to the Rational Team Concert 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.
- 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.
- 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.
- 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 provideRational 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 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.
- 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.
- Identify any ClearQuest record
fields that you want to display in the work item but not synchronize
with a work item field.
- 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.
- 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 Connector provides
the following value transformers.
Table 1. ClearQuest Connector 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 Connector. |
| 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 Connector. |
| 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 theRational Team Concert 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, Rational Team Concert 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 Rational Team Concert attachment
to a ClearQuest record
attachment. |
| Work Item Category Transformer |
Maintains the hierarchical structure of Rational Team Concert categories
mapped to ClearQuest records
when the value is a path. |
| Work Item Comments Transformer |
Converts a Rational Team Concert 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.
- 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.
- 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.
- 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 cqconnector.properties
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 Connector uses
the order specified with the cq.orderedProperties parameter.