Troubleshooting ClearQuest Converter

If problems occur when you migrate work items from ClearQuest to Team Foundation Server, the ClearQuest converter logs errors and warnings in a report file. The best way to troubleshoot problems is to review the report file to determine what occurred. The following information assists in troubleshooting issues and errors that occur with ClearQuest Converter.

In This Section

Troubleshooting Analysis Problems

The File license.dll was not Found

Analysis Failed and no Analysis Report was Created

Troubleshooting Migration Problems

The Migrate Command Fails

Critical Errors when the Converter Connects

Critical Errors when Provisioning Work Item Types

Sections in the Analysis Report or Migration Report do not Expand

Work Item Schema Changes do not Migrate to Team Foundation Server

Work Item Migration Fails Due to Attachment Upload Failure

Troubleshooting Analysis Problems

When problems occur from running the analyze command, an error is reported to the console, and the report file is generated with details about the problems that occurred. Most of the time, you can correct the cause of the error and restart the converter. If you are not sure about the cause of an error, search for the error number, or exact text in the Team Foundation help. Some errors also list an internal error that was reported from the ClearQuest API that the converter uses. For these errors, you may find additional information in the ClearQuest documentation.

The File license.dll was not Found

When you run the Analyze command, you may receive the error, "This application has failed to start because license.dll was not found. Re-installing the application may fix this problem." After you click OK, you receive an additional error, "TF61118: ClearQuest API call failed with the following error: Retrieving the COM class factory for component with CLSID {94773112-72E8-11D0-A42E-00A024DED613} failed due to the following error: 8007007e. Refer ClearQuest documentation for more help."

These errors occur when the converter cannot load the ClearQuest libraries, because the libraries path is not configured correctly.

Solution

• Verify that the ClearQuest client is installed on the computer. This installs the necessary libraries.

• Verify that you are not running the converter from a console window that was started before you installed ClearQuest. If you were, open a new console window and run the converter again.

• Verify that the PATH environment variable has not been modified after ClearQuest was installed. The PATH environment variable should contain paths to DLL files installed by ClearQuest. If these paths are missing, you may have to reinstall ClearQuest.

Analysis Failed and no Analysis Report was Created

If the converter is unable to load the configuration file, the Analyze command will fail and no report will be created.

Solution

• Use an XML editor or tool and verify that the configuration file XML is well formed.

• Verify that the XML elements and attributes in the configuration file are specified correctly. If you receive validation errors, the error message will indicate the unsupported value, and will indicate the line number where the value is found. For more information, see The Work Item Converter Configuration File.

Troubleshooting Migration Problems

When the converter is run with the Migrate command, there are several points where an error can occur. First the converter reads the configuration file and connects to the ClearQuest database by using the specified connection information. Next, the converter provisions the specified work item types on Team Foundation Server. Finally, the converter migrates work items from ClearQuest to Team Foundation Server.

As the converter is running, it prints status messages to the console. You can use the status messages to determine at what point the migration failed. For example, if the last successful status message was "Validating Users in Team Foundation," it is likely the error concerns the user map file.

The key to troubleshooting migration problems is to examine any errors that are reported. Errors are reported as follows.

1. A message is displayed to the console that indicates errors occurred. For example, if there are 2 warnings and 1 error, you receive the following message Migration completed with 2 warning(s), 1 error(s).

2. A migration report file is created that contains more specific information about the warnings and errors. The name of the report file is CQMigrationReport.xml.

The Migrate Command Fails

During migration, the converter can experience a critical error at any point in time. A critical error stops the converter and no more work items are migrated. A critical error can occur before work items are actually migrated, or after some work items have been migrated. When migration fails, you encounter one of the following two symptoms:

• You see a critical error and the message ‘Migration Failed’ in the migration report file, CQMigrationReport.xml. You will see a string in the report file similar to the following: Migration failed { 1 Critical Error | 2 Errors | 4 Warnings }.

• The migration fails with an error output to the console, but no report is generated.

Solution

• Fix the source of the error and restart the converter. When you restart the converter, it will not re-migrate work items that were already migrated. The converter does not create duplicate work items.

• The causes of critical failures vary and so do the error messages. Most of the error messages provide information that identifies the cause of what is wrong. You can also find more information about some errors by searching for the error text in Team Foundation help. Finally, examine the troubleshooting issues for the Analyze command listed previously in this topic. Many of the same issues apply to the Migrate command.

Critical Errors when the Converter Connects

Critical errors can occur when the converter tries to connect to ClearQuest or Team Foundation Server. You encounter one or more error messages in the report that indicates a connection problem.

Solution

Verify that you can connect to ClearQuest through the ClearQuest client and to Team Foundation Server through Team Explorer. Connection problems are frequently easier to diagnose through the messages from these clients. Also, remember to start these clients when you are logged in under the user account that will run the converter. This will cache necessary data for the converter to run correctly.

Critical Errors when Provisioning Work Item Types

Critical errors that occur when work item types are provisioned can occur because of field naming issues. You encounter an error message that resembles the following:

"Migration failed due to "TF61013: The converter could not provision the work item type specified in the file \\<computername>\e$\temp\CQOGF\Defect.xml because of the following error: TF26177: The field Microsoft.TeamFoundation.Converters.Priority_String cannot be renamed from 'Priority String' to 'Priority String1'. Team Foundation does not support renaming fields."

The fields in Team Foundation Server have a naming scope at the server level. The combination of Name, Reference Name, and Type for a field should be unique on the server. The converter analysis phase has logic to prevent clashes. When the converter detects a clash, it modifies the generated field names appropriately. However there may be a time gap between when the field names are generated from the analysis command, and when you run the migration command. A work item type on the server could be modified in that time period before the clash. Or you could have edited the generated work item types and unknowingly chosen a name that clashes with an existing field.

Solution

• Modify your work item types to resolve the conflict by modifying the name, the reference name, or both. Frequently, you may be able to just use the field names that already exist. To view the existing work item types, you must export the work item type definition files from Team Foundation Server. For more information, see witexport.

• Use the witfields command-line utility to rename or delete the conflicting field on Team Foundation Server. However, know that renaming and deleting existing work item fields is not always possible. For more information, see witfields.

Sections in the Analysis Report or Migration Report do not Expand

Sections in the analysis report or migration report do not expand correctly under the default security settings of Internet Explorer. The expand and collapse buttons are controlled by scripts and the default Internet Explorer security prevents the scripts from running.

Solution

You can correct this problem by changing the Internet Explorer security to allow for active content for the report.

To change security to allow for active content on reports

1. Locate the yellow security bar near the top of the browser that reads To help protect your security, Internet Explorer has restricted this file from showing active content that could access your computer.

2. Click the yellow security bar, and then click Allow Blocked Content.

3. On the Security Warning dialog box, click Yes.

Work Item Schema Changes do not Migrate to Team Foundation Server

Work item schema changes are not applied if the work item type was already provisioned. This typically occurs when you run the Migrate command one time, modify the work item type definitions in the schema map files, and then run the Migrate command again. The modifications do not appear in Team Foundation Server. Also, the following warning appears in the migration report; "Work item type <type name> cannot be created because it already exists on your Team Foundation Server."

The converter has explicit checks to make sure that it does not overwrite an existing work item type. Therefore, as soon as the work item type is provisioned by the converter, even when you modify the work item type, the changes are not incorporated because the work item type was already provisioned.

Solution

To update the work item types on the Team Foundation server, use the witimport command-line utility to import the work item types to the Team Foundation Server. Then the converter will use the updated types when you migrate work items. Be careful not to modify or delete work item data when you use the witimport command-line utility. For more information, see witimport.

Work Item Migration Fails Due to Attachment Upload Failure

If attachments are larger than the allowed attachment size, those attachments are not migrated. Also, the following error is listed in the migration report file; "TF61015: Attachment <filename> save failed for work item <id> with the following error: The file being uploaded is greater than the allowed file upload maximum size (4MB)."

Solution

• You can increase the maximum size of attachments on the Team Foundation server to fix this problem. The default size is 4 MB, but you can increase the size to as much as 2 GB (2147483648 bytes).

To set the maximum attachment size for work items

1. In Internet Explorer, locate the following URL:

   https://<tfsserver>:8080/WorkItemTracking/v1.0/ConfigurationSettingsService.asmx?op=SetMaxAttachmentSize

   where <tfsserver> represents the name of the Team Foundation server.

2. In the maxSize box, enter the maximum attachment size in bytes, and then click Invoke. The maximum attachment size is 2 gigabytes.

See Also

Concepts

Team Foundation Server Permissions

Other Resources

Troubleshooting Work Item Migration