Analyzing a ClearQuest Database

In the analyze phase, the converter reads the schema from the ClearQuest database and generates files that represent that schema in Team Foundation format. The converter uses the ClearQuest query to determine the ClearQuest base entity type; a query in ClearQuest is based on one entity type. The converter also finds entity types associated with the base entity type. The associated entities of the base entity are the entities to which the base entity refers. This means that the entities that are present in the base entity type as a reference or a reference list. This list of entities that are referenced, excludes the following:

• Entity types that may be referenced as duplicate of.

• User entity   Users are migrated according to the user handling in Team Foundation. Team Foundation does not handle users as an entity.

• Attachment entity   Attachments are migrated according to the core attachment handling of Team Foundation. Team Foundation does not handle attachments as an entity.

• History   History is migrated as per the core History handling of Team Foundation. Team Foundation does not handle history as an entity.

• Groups   Converter does not migrate ClearQuest groups. Groups are handled differently in Team Foundation.

• Ratl_replicas   This entity has no equivalent concept in Team Foundation.

Analysis Phase

At the Visual Studio 2005 Command Prompt, run the following command:

CQConverter /c:analyze /m:CqConverterConfig.xml

The ClearQuest converter may take several minutes to finish running. Several files are generated at the end of the analysis phase.

Converter Configuration File

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

Output Files

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.

Work Item Type Definition File

Work item type definition (WITD) files capture the schema of a work item type in Team Foundation format. You can use a WITD file to create a new work item type in Team Foundation. A WITD file specifies the fields in the work item type, states and state transitions, rules, and the user interface for displaying the work item. For more information about work item type definition files, see Customizing Work Item Types.

The following sections detail how these work item types are generated.

Field Type mappings

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

Field Mappings

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.

Handling of Field Behavior

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.

Fields Added by the Converter in Work Item Types

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

Do not remove these fields. Removing these fields from work item types causes the migration to fail. You can remove them from work item UI (form) if you do not want them displayed. We recommend that you keep these fields as read-only to prevent users from editing them. The fields are as follows:

• Field for the ClearQuest ID of a migrated work item.

  <FIELD name="vsts sourceid" refname="Microsoft.TeamFoundation.Converters.vsts_sourceid" type="String"/>
  

• Field for the ClearQuest database from where a migrated work item came from.

  <FIELD name="vsts sourcedb" refname="Microsoft.TeamFoundation.Converters.vsts_sourcedb" type="String"/>
  

• Field used to track migration status of a particular work item.

  <FIELD name="Migration Status" refname="Microsoft.TeamFoundation.Converters.Migration_Status" type="String"/>
  

• System fields in Team Foundation. When system fields in Team Foundation map to system fields in ClearQuest, the appropriate mapping xml is generated. Some system fields in Team Foundation do not map to system fields in ClearQuest and generates additional fields in each work item type. These fields are identified with a comment similar to the following xml:

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

Handling of List Fields

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>.

Handling of States and State Transitions

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.

Handling of Work Item Form

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

You can put various controls on a work item form in ClearQuest and also to Team Foundation. Team Foundation supports a predefined set of controls you can use. Some controls available in ClearQuest are unavailable in Team Foundation. Although the maximum amount of data is preserved during migration, the difference in available controls affects the display of data on the form in Team Foundation. The following controls are not supported in Team Foundation.

• ActiveX Controls

• Calendar Control

• Check-Box Control

• Combo-Box Control

• Duplicate Base Control

• Duplicate Dependents Control

• Parent/Child Control

• Picture Control

• Push Button Control

• List Box Control

• List view Control

• Option Button Control

• Static Text Box control

As part of migration planning, you should assess the effect the absence of these controls might have on the users.

Field Mapping File(s)

Field mappings file specify how fields are mapped and how values are mapped.

Field Mapping

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.

Value Mapping

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="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://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.

Mapping to Area Path and Iteration Path Fields

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>

User Mapping File

The user map file specifies how the users are mapped between ClearQuest and Team Foundation. For more information, see User Map File Schema.

Schema Map File

The schema map file specifies the source work item type, target work item type, work item definition file, and field map file. For more information, see How to: Edit the Schema Map File.

Analysis Report File

An analysis report file is generated at the end of the migration. The migration report is named CQAnalysisReport.xml and is generated in the folder from where CQConverter was run. An associated folder named _MigrationReport_Files contains the image files and a style sheet to display the report in a browser. At the end of the analysis you should open this file to view any errors or warnings found during the analysis phase. The analysis report displays the following:

• **Summary   **Summary information about the analysis run.

• **Errors   **Any errors found during the analysis run. You should take correct action for any errors listed.

• **Warnings   **Any warnings found during the analysis run. Warnings require your attention, but are not necessarily something that must be fixed.

• Output   This section lists the output files that were generated.

Log File

The converter generates a log file named CQConverter.log. This file is used for debugging and typically you do not have to examine this file. The log file is created in the folder from where CQConverter was run. It contains trace messages and may be helpful in debugging problems found during the converter run.

The level of tracing is controlled by setting the value of the MinLevelForAllSource attribute in the CQConverter.exe.config file. The CQConverter.exe.config file is in the same folder as CQConverter.exe. You can set a value from 1 that is least amount of tracing, to 4 which is most amount of tracing.

Errors file

The converter also generates a file that contains all the errors found during the converter run. The file is named ConverterErrors.txt and is generated in the same folder from where CQConverter was run.

See Also

Tasks

How to: Edit the Schema Map File

Reference

User Map File Schema

Concepts

The Work Item Converter Configuration File

Other Resources

Customizing Work Item Types
Defining Work Item Workflow
Defining the Work Item Form