You have to specify inputs to the converter in a configuration file. For more information, see The Work Item Converter Configuration File.

The analysis phase generates several output files. The files are saved to the folder that is specified by the <Outputdirectory> element in the migration settings file. If no directory is specified, the converter creates a folder that has the same name as the ClearQuest base entity type. If the folder already exists, the contents of that folder are overwritten with the new generated xml files.

At the end of the analyze phase the following files are created:

• Work Item Type Definition xml file(s)   These files represent the work item types in Team Foundation format and are used to create work item types in Team Foundation. One file is generated for the primary entity and each referenced entity. These files are named as <EntityType>.xml. For example, a work item type of defect generates the file Defect.xml.

• Field Mapping xml file(s)   These files specify how the fields are mapped from ClearQuest record types to Team Foundation work item types and any data transformations to be applied during data migration. These files have a one-to-one relationship with the work item type files. Each field mapping file specifies the mapping for the corresponding work item type. These files are named as <EntityName>FieldMap.xml. For example, work item type of defect generates the file DefectFieldMap.xml.

• User mapping xml file   This file is named UserMap.xml. It specifies how the users from ClearQuest are mapped to Team Foundation users. This file may be required because ClearQuest has a separate user database and ClearQuest user names might not be same as Windows user accounts. Team Foundation requires Windows user accounts.

• Schema Map xml file   This file is named SchemaMap.xml. The file contains the names of all the files described previously and specifies additional mappings between work item types and associated files.

• Analysis report xml file   This file is named CQAnalysisReport.xml. An accompanying folder is generated with this file named _AnalysisReport_Files which contains images and a style sheet to display this file correctly in a browser.

• Log file named as CQConverter.log

  Note:
  Regardless of the number of fields of a particular work item selected in a query, all fields present inside a work item type are selected by the converter for analysis. The output files contain references for all fields.

The converter maps the field types in ClearQuest to appropriate field types in Team Foundation. The following table specifies how the fields are mapped.

Every work item type in ClearQuest uses system fields, and similarly, there are system fields in Team Foundation work item types. The converter maps system fields from ClearQuest to system fields in Team Foundation as appropriate. Besides system fields there are also fields that are typically found in ClearQuest work item types. The converter maps them to Team Foundation fields as appropriate.

The following table specifies how the converter maps system fields.

The following table specifies how the converter maps common fields.

You can specify behavior on fields in ClearQuest. You can also specify different behavior for the fields on different states of a work item. The converter has limitations to migrating behavior in ClearQuest work items. For example, the converter migrates the field behavior specified on the initial state only, that is, the state of a newly created work item.

The behavior defined for different states is not analyzed or generated in the analysis phase. However, Team Foundation supports specifying these behaviors and you can add these behaviors manually in the work item types after the analysis phase. For more information about how to customize behavior for work item types in Team Foundation, see Defining Work Item Workflow.

Work item behavior is migrated as specified in the following table.

The converter generates the following fields in each work item type and also to the fields present in your ClearQuest work item types.

Fields required for converter operation

Fields in ClearQuest may have a set of valid or suggested values defined for them. When the converter reads the fields and their types, it also gathers whether the field is a list field type. If the field is a list field type, the converter also collects the valid or suggested list values. This information is captured in the work item type definition files in the corresponding field section. Look for the elements <AllowedValues>, or <SugggestedValues>.

State-based entity type definitions in ClearQuest schema support the following:

• A set of states.

• Transitions between states called Actions.

• Field behavior associated with the states.

The converter captures the ClearQuest states and actions as states and state transitions in Team Foundation work item type definitions.

The converter does not migrate the form information from your ClearQuest database to Team Foundation. The converter generates a default work item form as a part of the schema generated during the analysis phase; however, this default form bears no resemblance to the original form in ClearQuest. The default form contains minimal formatting and almost always requires editing to be a more usable work item layout. For information about how to edit work item forms, see Defining the Work Item Form.

Controls on the form

The field mapping files specify how fields in ClearQuest are mapped to Team Foundation fields. Most fields in ClearQuest, except for system and common fields, are mapped one-to-one to Team Foundation. You should keep these field mapping files in synchronization with any changes you make to the fields in the work item type definition files. For example, if you rename a field in the work item type definition file, you should change the mapping file to specify the same mapping. Similarly, if you delete some fields from the work item type definition file, you should delete those fields from the corresponding field mapping file.

The field mapping files also specify how the field data is to be transformed during migration. By default, no value mappings are generated. You can specify the value mappings if you want to transform data during migration. You specify these transformations using value mappings to say that a value such as "Pri1" should be mapped to "1."

The field map file is an XML file. The following example shows how to map fields and values:

<?xml version="1.0"?>

<FieldMaps xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <!-- Title is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->

  <FieldMap from="Headline" to="Title" />

  <FieldMap from="Submitter" to="Submitter">

    <ValueMaps refer="UserMap" />

  </FieldMap>

  <!-- Created Date is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->

  <FieldMap from="Submit_Date" to="Created Date" />

  <!-- Assigned To is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->

  <FieldMap from="Owner" to="Assigned To">

    <ValueMaps refer="UserMap" />

  </FieldMap>

</FieldMaps>

For more information about field maps, see Field Map File Schema.

Team Foundation work item tracking organizes the work items into a hierarchy of structural areas and iterations. For more information, see How to: Modify the Team Project Areas, and How to: Modify the Team Project Iterations.

Paths are used to help group work items structurally to represent the various components, projects, or applications your team works on. Iterations are used to help group work items according to major events such as milestones, and project phases. The Area Path and Iteration Path system fields define this information in Team Foundation. Because ClearQuest has no such concept the converter provides a default value for these fields; the default is that all work items go into the root of the Area Path Iteration Path.

Although ClearQuest does not provide Area Path and Iteration Path, you may be using the concepts in some other way. For example you may have a field in your work item types that denotes the particular project a work item belongs to. This roughly corresponds to the Area Path concept. Similarly you may have another field named ‘Fix By’ that denotes the milestone by which you want a particular work item to be fixed. Consider mapping these fields to Area Path and Iteration Path so that the work items appear in these different nodes instead of all in one root node. The mappings are specified in the work item type field mapping files as explained earlier.

The following XML example shows how to map a ClearQuest field named Tree Path with possible values of Area1 and Area2.

<FieldMap from="Tree Path" to="Area Path" exclude="false">

<ValueMaps>

  <ValueMap from="Area1" to="Area1" />

  <ValueMap from="Area2" to="Area2" />

</ValueMaps>

</FieldMap>

The following XML example shows how to map a ClearQuest field named Fix By with possible values of Alpha and Beta.

<FieldMap from="Fix By" to="Iteration Path" exclude="false">

<ValueMaps>

  <ValueMap from= "Alpha" to="Alpha"/>

  <ValueMap from= "Beta" to="Beta"/>

</ValueMaps>

</FieldMap>