共用方式為

逐步解說：將 ClearQuest 工作項目移轉至 Team Foundation

  • 發行項

更新：2007 年 11 月

本逐步解說提供將 ClearQuest 工作項目移至 Team Foundation 工作項目追蹤的程序。Team Foundation 包含了轉換公用程式 CQConverter.exe，讓您可以用來執行這項移轉工作。

在這個逐步解說中，您將完成下列工作：

  • 設定移轉過程：編輯可指引移轉過程的組態檔。

  • 分析 ClearQuest 資料庫：執行 ClearQuest 轉換器來分析目前的 ClearQuest 資料庫。這樣的分析會產生一份報告和一組檔案，以描述存在於 ClearQuest 中的工作項目類型。

  • 定義移轉對應：編輯 ClearQuest 資料庫分析期間所產生的 XML 檔案，以自訂移轉過程。

  • 將 ClearQuest 資料庫移轉至 Team Foundation 工作項目追蹤：使用資料庫分析期間所產生的組態檔和對應檔，以移轉資料。

  • 檢閱移轉報告：找出移轉期間發生的任何錯誤和警告的原因，並檢閱移轉狀態。

必要條件

若要完成本逐步解說，您需要在打算執行 CQConverter.exe 的電腦上安裝下列軟體：

  • Team 總管

  • 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 資料庫的 [Super User] 使用權限。如需詳細資訊，請參閱 ClearQuest Administrator's Guide。

移轉前工作

在您開始移轉之前，必須執行下列工作：

  • 安排鎖定 ClearQuest 資料庫的時間：有一個很好的作法就是鎖定資料庫，以避免使用者在移轉過程當中建立新的工作項目。ClearQuest 轉換器在轉換期間並不會偵測工作項目的變更。如需鎖定 ClearQuest 資料庫的詳細資訊，請參閱 ClearQuest 文件。

  • 建立 Visual Studio 問題追蹤Team 專案：建立 Team 專案，並決定哪些工作項目要放到哪個 Team 專案中。如需如何建立 Team Foundation 工作項目追蹤 Team 專案的詳細資訊，請參閱逐步解說：建立新的 Team 專案。

  • 將您要用來執行轉換器的使用者帳戶加入到 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 (User ID)。指定的使用者 ID 必須具有 Super User 權限，才能存取 ClearQuest 資料庫。

<VSTS>

此 VSTS 區段包含了與 Team Foundation 工作項目追蹤伺服器以及您要移轉的目標 Team 專案有關的資訊。

  • URI：Team Foundation Server 易記名稱或完整 URI。例如，"MyAtServer" 或 "http://MyAtServer:8080"。

  • ProjectName：Team Foundation 工作項目追蹤 Team 專案名稱。

其他組態設定

此 XML 檔中的其他區段可讓您指定下列設定：

  • ExitOnError：這個區段接受 true 或 false 的值，如果您想要在某些工作項目移轉期間發生錯誤時停止 ClearQuest 轉換器，請指定 True。

    注意事項：

    這項設定僅套用至非嚴重錯誤。如果是類似 ClearQuest 轉換器無法連接到 ClearQuest 的嚴重錯誤，即使這項設定為 False，轉換器也一定會結束。

  • OutputDirectory：指定您希望產生的檔案放置的目錄。如果您並未指定輸出目錄，轉換器就會以基底實體名稱建立目錄，以便產生輸出檔。如果目錄已經存在，轉換器就會覆寫該目錄中的檔案。

建立組態檔

您可以在任何文字編輯器 (例如 [記事本]) 中建立組態檔。

若要建立組態檔

  1. 收集下列資訊：

    • ClearQuest 連接名稱。

    • ClearQuest 資料庫名稱。

    • ClearQuest 系統管理員的使用者 ID 和密碼。確定此管理使用者具備了在 ClearQuest 中提出問題的權限。

    • Team Foundation 工作項目追蹤伺服器名稱。

    • Team Foundation 工作項目追蹤 Team 專案名稱 (您想要移轉工作項目的目標 Team 專案)。

  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 檔案的參考 (例如包含實體名稱的 SchemaMap 檔)，以及欄位對應檔的參考 (這個檔具有產生的 WorkItem 檔名和 fieldMap 檔案的路徑)。

  • 報告和警告檔 (CQAnalysisReport.xml)。

若要分析 ClearQuest 資料庫

  1. 在 Visual Studio 2008 命令提示字元下，執行下列命令：

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

    ClearQuest 轉換器可能需要數分鐘才會執行完畢。

    注意：如需 ClearQuest 轉換器命令的詳細資訊，請參閱用於移轉 ClearQuest 資料庫的 CQConverter 命令列公用程式。

  2. 在組態檔內指定的輸出目錄中，尋找下列 XML 檔案，這些檔案會在之後的移轉過程中使用：

    • 每一個 ClearQuest 實體型別的 WITD 檔，此檔會命名為 EntityName.xml。例如，ClearQuest Defect 實體的檔案將會命名為 Defect.xml。

    • 每一個 ClearQuest 實體型別的欄位對應檔。這些檔案將指定每一個 ClearQuest 實體中的欄位和欄位值將如何對應至 Team Foundation 工作項目追蹤工作項目類型中的對應欄位。例如，ClearQuest Defect 實體的檔案將會命名為 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. 檢查使用者對應，並視需要更正、加入及刪除。使用者對應的 "to" 一方必須是現有的 Team Foundation Server 使用者。

  3. 在 Team Foundation 工作項目追蹤中，加入使用者對應檔中指定的所有使用者。如需加入使用者的詳細資訊，請參閱 HOW TO：將使用者加入至 Team 專案群組。

    注意事項：

    如果您在移轉期間希望任何 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:path\Schemamap.xml

    其中 path 是結構描述對應檔的路徑。在分析階段，會於指定的輸出目錄中產生結構描述對應檔。

    注意事項：

    若為大型資料庫，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:path\Schemamap.xml

    若為大型資料庫，ClearQuest 轉換器可能需要幾個小時才能完成執行。

    注意事項：

    如需 ClearQuest 轉換器命令的詳細資訊，請參閱從 ClearQuest 移轉。

  5. 當移轉完成時，請檢閱移轉報告，以了解移轉狀態。移轉報告名為 CQMigrationReport.xml 而且建立於您從中執行 ClearQuest 轉換器的資料夾。

驗證工作項目移轉

當移轉執行完畢之後，您可以檢查某些移轉的工作項目，以確認已成功移轉資訊。

若要驗證移轉的工作項目

  1. 在 Team Foundation 工作項目追蹤中開啟移轉的工作項目。

  2. 使用 ClearQuest ID 欄位中的數字，將 Team Foundation 工作項目追蹤工作項目與具有該相同 ID 的 ClearQuest Bug 相比較。

若要尋找對應至特定 ClearQuest 工作項目的 Team Foundation 工作項目

  1. 使用下列查詢子句建立工作項目查詢：

    及/或

    欄位

    運算子

    值

     

    VSTS SourceID

    =

    ClearQuest 工作項目 ID

    [VSTS SourceID] 欄位會對應至您在工作項目表單中看見的 ClearQuest ID 欄位標籤。

    如需如何建立工作項目查詢的詳細資訊，請參閱 HOW TO：加入新的工作項目查詢。

  2. 執行查詢。

請參閱

工作

逐步解說：追蹤工作項目

其他資源

移轉逐步解說