通过

演练：将 ClearQuest 工作项迁移到 Team Foundation

更新：2007 年 11 月

本演练提供将 ClearQuest 工作项迁移到 Team Foundation 工作项跟踪的过程。Team Foundation 包含一个转换实用工具 CQConverter.exe，可用来执行此迁移。

在本演练中，您将完成以下任务：

  • 配置迁移过程   编辑配置文件以控制迁移过程。

  • 分析 ClearQuest 数据库   运行 ClearQuest 转换器以分析当前的 ClearQuest 数据库。该分析将生成一份报告以及一组描述 ClearQuest 中存在的工作项类型的文件。

  • 定义迁移映射   编辑在 ClearQuest 数据库分析期间生成的 XML 文件以对迁移过程进行自定义。

  • 将 ClearQuest 数据库迁移到 Team Foundation 工作项跟踪   使用在分析数据库期间生成的配置和映射文件迁移数据。

  • 查看迁移报告   找出在迁移期间出现的任何错误和警告的原因，并检查迁移状态。

先决条件

若要完成本演练，您需要在计划运行 CQConverter.exe 的计算机上安装以下软件：

  • 团队资源管理器

  • ClearQuest 独立客户端版本 2003.06.00

    说明：

    2002.05.20 和 2003.05.00 版可能也可使用，但尚未经过测试。

您还必须制作一份列表，其中列出您希望将 ClearQuest 中的用户名如何映射为 Team Foundation 工作项跟踪 所使用的 Windows 域名。确保包含不会再使用的用户名。

下面的信息和知识很有帮助：

  • 对 XML 的基本了解。

  • 反映您想将 ClearQuest 中的工作项字段如何映射到 Team Foundation 工作项跟踪 的列表。包括有关所需转换的信息。例如，您可能将 ClearQuest 中的字符串字段映射为 Team Foundation 工作项跟踪 中的整数字段。

必需的权限

若要执行此演练，您必须是“Service Accounts”安全组的成员。此外，您还必须是“Readers”安全组的成员，或者“查看此节点中的工作项”权限设置为“允许”。有关更多信息，请参见 Team Foundation Server 权限。您还必须具有 ClearQuest 数据库的“超级用户”权限。有关更多信息，请参见 ClearQuest Administrator's Guide（《ClearQuest 管理员指南》）。

迁移前任务

开始迁移之前，必须执行下列任务：

  • 安排时间锁定 ClearQuest 数据库   锁定数据库以防止用户在迁移过程中创建新的工作项，这是一种很好的做法。转换期间，ClearQuest 转换器不会检测工作项更改。有关如何锁定 ClearQuest 数据库的信息，请参见 ClearQuest 文档。

  • 创建 Visual Studio Issue Tracking团队项目   创建团队项目并确定哪些工作项属于哪个团队项目。有关如何创建 Team Foundation 工作项跟踪 团队项目的更多信息，请参见演练：创建新的团队项目。

  • 将要用来运行转换器的用户帐户添加到“Service Accounts”组   CQConverter 需要服务帐户权限才能运行。使用 TFSSecurity 实用工具将要运行转换器的用户帐户添加到 Team Foundation Server 上的“Service Accounts”组中。有关更多信息，请参见 TFSSecurity 命令行实用工具命令。

转换器限制

开始迁移之前，应该检查 ClearQuest 转换器的限制以及这些限制对组织中的用户可能有何影响。有关更多信息，请参见用于 ClearQuest 数据库迁移的 CQConverter 命令行实用工具。

定义

本演练使用以下术语：

  • 工作项类型   工作项类型是工作项跟踪系统的基本构造块。工作项类型的示例有 bug、要求和任务。

  • 实体   ClearQuest 中的基本数据单元。例如，一个“缺陷”可能链接到某个“客户”，并属于某个“项目”。“缺陷”、“客户”和“项目”都是实体。

  • 字段   工作项包含一些字段，而字段包含有关该工作项的信息。例如，一个“缺陷”工作项可能有“打开者”、“状态”、“解决方法”、“历史记录”、“链接”和“附件”之类的字段。

  • 状态   工作项在过程中可能所处的位置。例如，Bug 可能为“打开”、“已分配”、“已解决”或“已推迟”。

  • 字段行为（字段规则）   指定字段在不同状态下的行为。例如，“修复版本”字段在您创建新的 bug 时可能是不可编辑的，但是当您将该 bug 转换为“已解决”状态时，“修复版本”字段可能需要一个值。

配置迁移过程

在此步骤中，您将更改 ClearQuest 转换器配置文件以控制迁移过程。

配置文件

该配置文件为 XML 文件，它提供了 ClearQuest 转换器的设置。这些设置是在 XML 文件的下列节中指定的：

<ClearQuest>

ClearQuest 节包含有关您要迁移的 ClearQuest 数据库的信息。

  • ConnectionName   ClearQuest 连接名称。

  • UserDatabase   ClearQuest 用户数据库名称。

  • QueryName   保存在 ClearQuest 中的查询的名称。

  • UserID   ClearQuest 用户 ID。指定的用户 ID 对于 ClearQuest 数据库必须有“超级用户”权限。

<VSTS>

VSTS 节包含有关您将迁移到的 Team Foundation 工作项跟踪 服务器和团队项目的信息。

  • URI   Team Foundation Server 友好名称或完整的 URI。例如，“MyAtServer”或“http://MyAtServer:8080”。

  • ProjectName   Team Foundation 工作项跟踪 团队项目名称。

其他配置设置

该 XML 文件中的其他节可使您指定下列设置：

  • ExitOnError   此节接受 true 或 false 值。如果您想在某些工作项的迁移过程中发生错误时停止 ClearQuest 转换器，则指定 True。

    说明：

    此设置仅适用于非错误。对于错误，如 ClearQuest 转换器无法连接 ClearQuest，转换器将总是退出，即使此设置为 False。

  • OutputDirectory   指定您想将生成的文件保存到哪个目录。如果不指定输出目录，则转换器将以基本实体 (Base Entity) 名称创建目录以用于生成输出文件。如果目录已存在，则转换器将覆盖该目录中的文件。

创建配置文件

可使用任何文本编辑器（如“记事本”）创建配置文件。

创建配置文件

  1. 收集以下信息：

    • ClearQuest 连接名称。

    • ClearQuest 数据库名称。

    • ClearQuest 管理员用户 ID 和密码。确保此管理员用户在 ClearQuest 中有提交问题的权限。

    • Team Foundation 工作项跟踪 服务器名称。

    • Team Foundation 工作项跟踪 团队项目名称（要向其中迁移工作项的团队项目）。

  2. 在 ClearQuest 中创建一个查询，用于选择要迁移到 Team Foundation 工作项跟踪 的工作项，然后保存该查询。以任意名称保存该查询，例如“TransitionQuery”。

  3. 确定用来存储分析阶段中生成的文件的目录。

  4. 将下面的 XML 配置文件复制到文本编辑器中。

    <?xml version="1.0" encoding="utf-8"?>
<WorkItemConverter>
  <Source id="ClearQuest">
    <ClearQuest>
      <ConnectionName>CQRep</ConnectionName> 
      <UserDatabase>TEST</UserDatabase> 
      <QueryName>Public Queries/All Defects</QueryName> 
      <UserID>admin</UserID>
    </ClearQuest>
  </Source>
  <VSTS>
    <URI>AdventureWorksServer</URI>
    <ProjectName>AdventureWorksProject</ProjectName> 
  </VSTS>
  <ExitOnError>true</ExitOnError>
  <OutputDirectory>DefectSchema</OutputDirectory>
</WorkItemConverter>

  5. 使用在前面的步骤中收集的信息更改该文件以指定您的设置。例如，在 <QueryName> 下，将查询名称指定为 TransitionQuery 并包含查询路径。有关每一节应包含的内容的信息，请参见前面的“配置文件”部分。

    说明：

    密码不在该文件中输入，稍后在迁移过程中，ClearQuest 转换器工具将提示输入密码。

  6. 保存该文件。

    例如，可将该文件保存为“CqConverterConfig.xml”。

分析 ClearQuest 数据库

在 ClearQuest 数据库分析期间，ClearQuest 到 Team Foundation 的转换器将分析 ClearQuest 数据库并创建下列 XML 文件：

  • 每种 ClearQuest 实体类型的 Team Foundation 工作项跟踪 工作项类型定义 (WITD) 文件，其中包含状态、状态转换、字段、字段类型以及字段行为（如必选或可选）。

  • 将 ClearQuest 字段和值映射为 Team Foundation 工作项跟踪 字段和值的默认字段映射文件。

  • 将 ClearQuest 用户映射为 Windows 用户的用户映射文件。此文件应用于整个系统。

  • 包含对其他 XML 文件的引用的架构映射文件，这些 XML 文件可以是包含实体名称的 SchemaMap 文件、包含生成的 WorkItem 文件名的路径的字段映射文件和 fieldMap 文件，等等。

  • 报告和警告文件 (CQAnalysisReport.xml)。

分析 ClearQuest 数据库

  1. 在 Visual Studio 2008 命令提示处，运行下面的命令：

    CQConverter.exe /c:analyze /m:CqConverterConfig.xml

    ClearQuest 转换器可能需要几分钟才能完成运行。

    说明   有关 ClearQuest 转换器命令的更多信息，请参见用于 ClearQuest 数据库迁移的 CQConverter 命令行实用工具。

  2. 在配置文件中所指定的输出目录中，查找下列 XML 文件。这些文件将在以后的迁移过程中使用：

    • 与每种 ClearQuest 实体类型对应的、名为“实体名称.xml”的 WITD 文件。例如，ClearQuest“缺陷”实体的文件将名为“Defect.xml”。

    • 每种 ClearQuest 实体类型的字段映射文件。这些文件指定每个 ClearQuest 实体中的字段和字段值将如何映射到 Team Foundation 工作项跟踪 工作项类型中对应的字段。例如，ClearQuest“缺陷”实体的文件将名为“DefectFieldMap.xml”。

    • 用户映射文件。指定 ClearQuest 用户如何映射为 Team Foundation 工作项跟踪 用户的文件。

    • schemamap.xml 文件。描述架构和字段映射的文件。

  3. 迁移之前，在运行转换器的目录中查找“CQAnalysisReport.xml”文件以查看任何警告和错误。

定义迁移映射

分析工作生成了一组捕获来自 ClearQuest 数据库的信息的文件。为了按照您所需要的方式迁移数据库，您可能需要更改其中的某些文件。至少必须更改用户映射文件和工作项类型定义文件。

有关如何修改工作项类型的定义文件的更多信息，请参见演练：对工作项类型进行基本自定义。

编辑架构映射文件

更改 schemamap.xml 文件

  1. 打开 Schemamap.xml 文件。

    下面是此文件的示例：

    <Mappings>
  <SchemaMaps>
    <SchemaMap SourceEntity="Defect" TargetWIT="Defect"
      WITDFile="Defect.xml" FieldMapFile="DefectFieldMap.xml"/> 
    <SchemaMap SourceEntity="Customer" TargetWIT="Customer"
      WITDFile="Customer.xml" FieldMapFile="CustomerFieldMap.xml"/> 
  </SchemaMaps>
  <UserMap File="UserMap.xml" /> 
</Mappings>

  2. 相应更改此文件中的各节。

    • SourceEntity   确保此节包含正确的 ClearQuest 实体。

    • TargetWIT   确保此节指向应在 Team Foundation 工作项跟踪 中创建的正确的工作项类型。

    • WITDFile   此节指定工作项类型定义 (WITD) XML 文件。

    • FieldMapFile   此节指定字段映射 XML 文件。

    • UserMap   此节指定用户映射 XML 文件。

编辑用户映射文件

ClearQuest 转换器使用用户映射文件将 ClearQuest 数据库中的用户 ID 映射为等效的 Team Foundation 工作项跟踪用户 ID。通过将用户 ID 字段值转换为 Team Foundation 工作项跟踪中的有效值有助于保留工作项历史记录。Team Foundation 工作项跟踪使用 Windows 域用户 ID。

此文件的默认版本由 ClearQuest 转换器在分析阶段生成。在继续进行转换之前，请确保此文件准确，因为转换器将检查该文件，如果存在问题转换将会失败。

更改用户映射文件

  1. 打开 usermap.xml 文件。示例如下：

    <UserMappings">
  <UserMap From="admin" To="admin" />
  <UserMap From="user" To="user" />
  <UserMap From="QE" To="QE" />
  <UserMap From="lead" To="lead" /> 
  <UserMap From="engineer" To="engineer" />
</UserMappings>

  2. 检查用户映射，并根据需要进行更正、添加和删除。用户映射的“映射到”方必须为现有的 Team Foundation Server 用户。

  3. 在 Team Foundation 工作项跟踪 中，添加用户映射文件中指定的所有用户。有关添加用户的更多信息，请参见如何：向团队项目组添加用户。

    说明：

    如果您想在迁移期间将任何一个 ClearQuest 用户按原样映射到 Team Foundation Server 中，可在用户映射文件中删除对应这些用户的行。如果您不想执行任何用户映射，则可以删除 <UserMap> 节中指定用户映射的所有行。仅应删除 <UserMap> 节中的各个项，而不要删除整个节或该文件的任何其他部分。
    警告：

    如果迁移期间用户未映射为有效的 Team Foundation Server 用户，则在您开始使用工作项中的用户字段时，您可能必须修复这些字段。转换器运行时不会验证字段值，但是一旦您开始编辑工作项，就会要求您为用户字段提供有效的用户。

编辑字段映射文件

ClearQuest 转换器使用字段映射文件将每个 ClearQuest 实体中的字段映射为等效的 Team Foundation 工作项跟踪 工作项字段。

更改字段映射文件

  1. 打开一个字段映射文件。例如，打开“DefectFieldMap.xml”。示例如下：

    <FieldMap from="Criticality" to="Severity">
  <ValueMaps>
        <ValueMap from="1-Critical" to = "1"/>
        <ValueMap from="2-Major" to = "2"/>
  </ValueMaps>
</FieldMap>

  2. 检查字段映射行（以“ValueMap”开头），并确保“from”后面指示的字段映射为“to”后面正确的字段。通过添加更多“ValueMap”行，可添加更多字段映射。如果已经在架构文件（在本例中为 defect.xml）中指定，则这些值应该在允许值列表中。

    说明：

    如果您更改字段映射，请确保映射工作项表单上的必选字段

  3. 打开其他字段映射文件并适当进行编辑。

定义工作项类型定义

分析阶段结束后，转换器会为每个 ClearQuest 记录类型生成工作项类型定义 (WITD)。例如，ClearQuest Defect 记录类型的文件名为 Defect.xml。在分析阶段，作为架构生成的一部分，转换器会生成一个默认的工作项窗体。但是，此默认表单只包含最少量的格式设置，并且几乎总是需要进行编辑才能获得您所需要的工作项布局。有关如何更改工作项类型的定义文件的信息，请参见演练：对工作项类型进行基本自定义和演练：对工作项类型进行高级自定义。

迁移 ClearQuest 工作项

迁移工作项

  1. 在 Visual Studio 2008 命令提示处，运行下面的命令：

    CQConverter.exe /c:migrate /m:CqConverterConfig.xml /s:路径\Schemamap.xml

    其中“路径”是架构映射文件的路径。架构映射文件是在分析阶段在指定输出目录中生成的。

    说明：

    对于大型数据库，ClearQuest 转换器可能需要几个小时才能完成运行。
    说明：

    有关 ClearQuest 转换器命令的更多信息，请参见从 ClearQuest 迁移。

  2. 迁移完成后，查看迁移报告以了解迁移状态以及其他问题，如由于字段映射不一致造成的缺陷未迁移。

    迁移报告名为“CQMigrationReport.xml”，并且是在运行 ClearQuest 转换器的文件夹中创建的。

    说明：

    由于转换器转换指定查询中包含的所有工作项以及这些工作项所链接到的所有工作项，因此被迁移的实际工作项数可能与查询中工作项数不同。

  3. 如果所有工作项未全部迁移，则可以在解决迁移报告中所列出的问题之后再次运行转换。

若要将更多工作项从 ClearQuest 迁移到 Team Foundation 工作项跟踪，可再次运行迁移过程。

对同一个 ClearQuest 数据库再次运行迁移

  1. 更正上一次迁移的迁移报告中列出的所有问题。

  2. 在 ClearQuest 中生成一个返回所需工作项的查询，或者，如果您想迁移第一次未迁移的工作项，则可以运行相同的查询。

  3. 更改配置文件中的“<QueryName>”节以指定新的查询名称。

  4. 打开 Visual Studio 2008 命令提示，键入迁移命令：

    CQConverter.exe /c:migrate /m:CqConverterConfig.xml /s:路径\Schemamap.xml

    对于大型数据库，ClearQuest 转换器可能需要几个小时才能完成运行。

    说明：

    有关 ClearQuest 转换器命令的更多信息，请参见从 ClearQuest 迁移。

  5. 迁移完成后，查看迁移报告以了解迁移的状态。迁移报告名为“CQMigrationReport.xml”，并且是在运行 ClearQuest 转换器的文件夹中创建的。

验证工作项迁移

执行迁移后，可检查某些已迁移的工作项以验证信息是否迁移成功。

验证已迁移的工作项

  1. 在 Team Foundation 工作项跟踪 中打开一个已迁移的工作项。

  2. 使用 ClearQuest ID 字段中的数字将 Team Foundation 工作项跟踪 工作项与具有相同 ID 的 ClearQuest bug 进行比较。

查找与特定的 ClearQuest 工作项对应的 Team Foundation 工作项

  1. 用以下查询子句创建一个工作项查询：

    And/Or

    字段

    运算符

    值

     

    VSTS SourceID

    =

    ClearQuest 工作项 ID

    “VSTS SourceID”字段与您在工作项表单上看到的 ClearQuest ID 字段标签相对应。

    有关如何创建工作项查询的更多信息，请参见如何：添加新的工作项查询。

  2. 运行查询。

请参见

任务

演练：跟踪工作项

其他资源

迁移演练