ClearQuest Import Wizard limitations and known problems

This release of the ClearQuest Import Wizard contains several limitations and known problems.

This release contains the following limitations and known problems:

  • You can use the ClearQuest Import Wizard only on a Windows computer.
  • Important: The ClearQuest Import Wizard works only with the 32-bit version of the IBM® Engineering Workflow Management (EWM) client for Eclipse IDE. Starting in version 6.0.6, no 32-bit Rational Team Concert Eclipse client is available to download in the form of compressed zip file. To work around this problem, install a 32-bit version of the Eclipse client. Then, download the EWM client p2 Install Repository and install it in the 32-bit Eclipse client.
  • Use the ClearQuest Import Wizard to generate the default mapping file and then customize it for your needs. If you use other importers, such as the EWM Import Work Items from CSV Wizard, to generate the default mapping file, the mapping file is generic and has no knowledge of ClearQuest data. You will need to add ClearQuest attributes and remove work item attributes that are not used.
  • The ClearQuest Import Wizard imports the ClearQuest Notes field values only if the Notes field was added by the ClearQuest Notes package. The ClearQuest Import Wizard expects the Notes fields to be separated by a pattern like ==== State: Submitted by: cqconnector on 12 July 2012 09:48:37 ====. Customized Notes implementations cannot be imported, and the error indicating such a problem is Error importing ClearQuest record due to Notes_Log field does not conform to the CQ Notes package formatting.
  • Because the ClearQuest Import Wizard internally uses the Bugzilla Import Wizard, the History tab of the imported work items displays Origin (Bugzilla) Bugzilla identifier. The identifier is a ClearQuest record identifier.
  • When saving the mapping XML file, choose UTF-8 as the Encoding. Otherwise, you might receive the error Exception while parsing mapping caused by org.xml.sax.SAXParseException: Content is not allowed in prolog if some fields in the mapping file are in a nonEnglish locale.
  • You cannot use the ClearQuest Import Wizard to import records from a ClearQuest query that has hidden display fields. Choosing to import from such a query can result in a NullPointerException. Ensure that the ClearQuest query does not contain hidden display fields. Likewise, ensure that the query’s Display Fields does not contain any fields that you do not want to import.
  • If you rename the ClearQuest query that you used to select the records to be imported, you cannot run the import operation again during the same session. To re-run the import operation with the renamed query, you must close the ClearQuest Import wizard, then open it again.
  • The ClearQuest importer has a known limitation of importing large set of ClearQuest data into EWM. When importing directly into EWM, or importing from a saved XML file (with size over 50K), you might receive a NullPointerException error. The workaround is to break the large query into several smaller ones, or break the large XML file into several smaller-sized ones, and import each smaller set of records separately.
  • You cannot use the ClearQuest Import Wizard to import ClearQuest records when the same attachment is in multiple ClearQuest attachment fields. To work around this limitation, rename the attachment, or delete it from one of the attachment fields, prior to starting the import process.
  • You cannot use the ClearQuest Import Wizard to import ClearQuest history or ClearQuest e-Signature.
  • If the ClearQuest notes log has dates in one of the following formats, the ClearQuest Synchronizer treats the first two digits as the month and the second two digits as the day, which might not be appropriate for all locales:
    • nn/nn/yyyy
    • nnnnyyyy
    • nn.nn.yyyy
    To change this behavior, edit the rtc-client-install-directory/eclipse.ini file by adding this line to the bottom of the file: -Dcom.ibm.rational.connector.cq.teamapi.common.cq.comment.date.format=date-format. Examples of date formats include the following:
    • dd MMM yyyy HH:mm:ss
    • dd/M/yyyy HH:mm
    • dd.M.yyyy HH:mm
    • M/dd/yyyy hh:mm:ss a
    • M/dd/yyyy HH:mm
    • dd/M/yyyy HH:mm a
  • Do not use the ClearQuest Import Wizard to migrate Open Services for Lifecycle Collaboration (OSLC) links from ClearQuest records. The OSLC links in the external applications will continue to link to the ClearQuest records rather than to the work items that the import operation creates.

Common importing errors

In most cases, when an error occurs during import, the error for the record that is being imported is logged, and the import operation continues to the next record.

An exception to this error flow occurs when the import operation tries to retrieve information about an IBM Rational® ClearQuest® record but the information is corrupt. This corrupt information scenario can occur in the following circumstances:
  • You try to import duplicate information of a duplicate ClearQuest record but the ClearQuest record does not have a link to the original record.
  • You try to import duplicate information of a duplicate ClearQuest record but the ClearQuest record is a duplicate of more than one record, which is not valid.
In such situations, the import operation stops. To work around the problem, either do not import the duplicate properties of a record by removing the is_duplicate column from the query display fields, or exclude the problem record and any records that reference it from the query. It can be difficult to determine the problem record because the duplicate relationship is what is corrupt in the user database.

To see the error log, click Windows > Show View > Error Log.

Table 1 describes some common errors that do not stop the import operation.
Table 1. Common import errors
Error message Description
The user "user@example.com" is not authorized to perform the operation. The "JazzAdmins" role is required to perform this operation. The user does not have the permission to create Jazz contributors. Add the user to the JazzAdmins repository group.
Value of attribute "description" is 60195 bytes, which is greater than the allowed encoded length of 32768 bytes. The value that is being set for the work item description field is larger than what is allowed. Please shorten the incoming description value.
SAXParseException: An invalid XML character (Unicode: 0x1) was found in the element content of the document. There is an invalid character that is not allowed in an xml document. Unfortunately, this doesn't identify the field with the invalid xml character. Please check the description or headline field and remove the character.

video icon Video

Jazz.net channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community

Jazz.net
Jazz.net forums
Jazz.net library

support icon Support

IBM Support Community
Deployment wiki