共用方式為

分析 ClearQuest 資料庫

  • 發行項

更新：2007 年 11 月

在分析階段，轉換器會從 ClearQuest 資料庫讀取結構描述，並且以 Team Foundation 格式產生代表該結構描述的檔案。轉換器會使用 ClearQuest 查詢來判斷 ClearQuest 基底實體型別。ClearQuest 中的查詢是以一種實體型別為基礎。轉換器也會找出與基底實體型別相關聯的實體型別。與基底實體相關聯的實體就是基底實體所參考的實體。這表示這些實體是以參考或參考清單的形式存在於基底實體型別中。但是，所參考的實體清單中不包含下列項目：

  • 可當做重複項目來參考的實體型別。

  • 使用者實體：使用者會根據 Team Foundation 中的使用者處理方式進行移轉。Team Foundation 不會將使用者當做實體進行處理。

  • 附件實體：附件會根據 Team Foundation 的核心附件處理方式進行移轉。Team Foundation 不會將附件當做實體進行處理。

  • 記錄：記錄會根據 Team Foundation 的核心記錄處理方式進行移轉。Team Foundation 不會將記錄當做實體進行處理。

  • 群組：轉換器不會移轉 ClearQuest 群組。群組在 Team Foundation 中會以不同方式進行處理。

  • Ratl_replicas：這個實體在 Team Foundation 中沒有任何對等概念。

分析階段

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

CQConverter /c:analyze /m:CqConverterConfig.xml

注意事項：

若要分析 ClearQuest 資料庫，CqConverterConfig.xml 檔中指定的使用者 ID 必須擁有 [Super User] 使用權限。如需詳細資訊，請參閱 ClearQuest Administrator's Guide。此外，您也必須是指定之 Team Foundation Server 上 [Service Accounts] 群組的成員。如需詳細資訊，請參閱 Team Foundation Server 使用權限。

ClearQuest 轉換器可能需要數分鐘才會執行完畢。在分析階段結束時會產生數個檔案。

轉換器組態檔

您必須在組態檔中指定轉換器的輸入。如需詳細資訊，請參閱工作項目轉換器組態檔。

輸出檔

分析階段會產生數個輸出檔。這些檔案會儲存至移轉設定檔中 <Outputdirectory> 項目所指定的資料夾。如果沒有指定目錄，則轉換器會建立具有與 ClearQuest 基底實體型別相同名稱的資料夾。如果資料夾已經存在，則會以新產生的 xml 檔覆寫該資料夾的內容。

在分析階段結束時會建立下列檔案：

  • 工作項目類型定義 xml 檔：這些檔案代表 Team Foundation 格式的工作項目類型，在 Team Foundation 中可以用來建立工作項目類型。主要實體和每個參考的實體都會產生一個檔案。這些檔案會以 <EntityType>.xml 的方式來命名。例如，缺失 (Defect) 的工作項目類型便會產生 Defect.xml 檔。

  • 欄位對應 xml 檔：這些檔案會指定將欄位從 ClearQuest 記錄類型對應至 Team Foundation 工作項目類型的方式，以及在資料移轉期間所要套用的任何資料轉換。這些檔案與工作項目類型檔具有一對一關聯性。每個欄位對應檔都會指定對應工作項目類型的對應。這些檔案會以 <EntityName>FieldMap.xml 的方式來命名。例如，缺失 (Defect) 的工作項目類型便會產生 DefectFieldMap.xml 檔。

  • 使用者對應 xml 檔：這個檔案命名為 UserMap.xml。它會指定從 ClearQuest 使用者對應至 Team Foundation 使用者的方式。由於 ClearQuest 擁有個別的使用者資料庫，而且 ClearQuest 使用者名稱可能與 Windows 使用者帳戶不同，因此可能會需要這個檔案。Team Foundation 則需要有 Windows 使用者帳戶。

  • 結構描述對應 xml 檔：這個檔案命名為 SchemaMap.xml。此檔案包含先前所描述之所有檔案的名稱，而且會指定工作項目類型與相關聯檔案之間的其他對應。

  • 分析報告 xml 檔：這個檔案命名為 CQAnalysisReport.xml。伴隨著此檔案會產生一個名稱為 _AnalysisReport_Files 的資料夾，其中包含了在瀏覽器中正確顯示此檔案所需的影像和樣式表。

  • 命名為 CQConverter.log 的記錄檔

    注意事項：

    不論在查詢中所選取的特定工作項目有多少個欄位，轉換器都會選取工作項目類型中的所有欄位來進行分析。輸出檔會包含所有欄位的參考。

工作項目類型定義檔

工作項目類型定義 (WITD) 檔會以 Team Foundation 格式擷取工作項目類型的結構描述。您可以使用 WITD 檔，在 Team Foundation 中建立新的工作項目類型。WITD 檔會指定工作項目類型中的欄位、狀態和狀態轉換、規則，以及用來顯示工作項目的使用者介面。如需工作項目類型定義檔的詳細資訊，請參閱自訂工作項目類型。

下列各節將詳細說明如何產生這些工作項目類型。

欄位型別對應

轉換器會將 ClearQuest 中的欄位型別對應至 Team Foundation 中的適當欄位型別。下表會指定欄位的對應方式。

ClearQuest 欄位型別

Team Foundation 欄位型別

ATTACHMENT_LIST

不適用。此欄位類型會移轉為附件，而非 Team Foundation 中的欄位。

DATE_TIME

DateTime

INT

Integer

MULTILINE_STRING

Plain Text

REFERENCE

不適用。此欄位類型會移轉為連結，而非 Team Foundation 中的欄位。

REFERENCE_LIST

不適用。此欄位類型會移轉為連結，而非 Team Foundation 中的欄位。

SHORT STRING

String

DBID

不移轉。此欄位類型是保留給 ClearQuest 中的系統欄位，在移轉的工作項目中不需要。

ID

String。此欄位類型會移轉為 Team Foundation 中的 [vsts sourceid] 欄位。

JOURNAL

不適用。此欄位類型是保留給 ClearQuest 中的系統欄位，而且會移轉為 Team Foundation 中的記錄。

State

String。此欄位類型是保留給 ClearQuest 中的系統欄位，而且會移轉為 Team Foundation 中的系統 [狀態] 欄位。

欄位對應

ClearQuest 中的每個工作項目類型都會使用系統欄位；同樣地，Team Foundation 工作項目類型中也有系統欄位。轉換器會將 ClearQuest 中的系統欄位對應至 Team Foundation 中的適當系統欄位。除了系統欄位以外，還有一些在 ClearQuest 工作項目類型中常見的欄位。轉換器會將其對應至適當的 Team Foundation 欄位。

下表會指定轉換器對應系統欄位的方式。

ClearQuest 系統欄位

Team Foundation 系統欄位

ID

vsts sourceid

State

State

下表會指定轉換器對應一般欄位的方式。

ClearQuest 欄位

Team Foundation 系統欄位

Headline

標題

說明

說明

Submitter

建立者

Submit_Date

建立日期

Owner

指派給

User_name (記錄)

變更者

action_timestamp (記錄)

變更日期

欄位行為的處理

您可以在 ClearQuest 中指定欄位上的行為。您也可以為不同工作項目狀態中的欄位指定不同的行為。轉換器對於 ClearQuest 工作項目中的移轉行為有所限制。例如，轉換器只會移轉在初始狀態 (即新建立之工作項目的狀態) 中指定的欄位行為。

在分析階段，不會分析或產生針對不同狀態所定義的行為。但是，Team Foundation 支援指定這些行為，而且您可以在分析階段之後，以手動方式在工作項目類型中加入這些行為。如需如何在 Team Foundation 中為工作項目類型自訂行為的詳細資訊，請參閱定義工作項目工作流程。

工作項目行為會依照下表中指定的方式移轉。

行為

說明

強制性

這項行為會移轉至 Team Foundation。在 Team Foundation 中指定強制性的方式是，在工作項目類型定義中套用 <REQUIRED> 項目。

選擇性

這項行為會移轉至 Team Foundation。選擇性是 Team Foundation 中欄位的預設行為，因此在工作項目類型定義中不需要其他項目。

唯讀

這項行為不會移轉。

Use_hook

這項行為不會移轉。

轉換器在工作項目類型中加入的欄位

除了存在於 ClearQuest 工作項目類型中的欄位以外，轉換器還會在每個工作項目類型中產生下列欄位。

轉換器作業所需的欄位

請不要移除這些欄位。如果從工作項目類型中移除這些欄位，將會導致移轉失敗。如果您不要顯示這些欄位，可以將它們從工作項目 UI (表單) 中移除。如果不要讓使用者編輯這些欄位，建議您將它們保留為唯讀狀態。這些欄位如下所示：

  • 移轉之工作項目的 ClearQuest ID 欄位。

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

  • 移轉之工作項目來源所在的 ClearQuest 資料庫欄位。

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

  • 用來追蹤特定工作項目之移轉狀態的欄位。

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

  • Team Foundation 中的系統欄位。當 Team Foundation 中的系統欄位對應至 ClearQuest 中的系統欄位時，會產生適當的對應 xml 檔。Team Foundation 中的某些系統欄位不會對應至 ClearQuest 中的系統欄位，而且會在每個工作項目類型中產生其他欄位。這些欄位會使用類似以下 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-->

清單欄位的處理

ClearQuest 中的欄位可能已經定義了一組有效或建議的值。當轉換器讀取欄位及其型別時，也會設法判斷欄位是否為清單欄位型別。如果欄位為清單欄位型別，則轉換器也會收集有效或建議的清單值。這項資訊是在對應欄位區段的工作項目類型定義檔中所擷取的。請尋找 <AllowedValues> 項目或 <SugggestedValues> 項目。

狀態和狀態轉換的處理

ClearQuest 結構描述中以狀態為基礎的實體型別定義支援下列項目：

  • 狀態集合

  • 狀態之間的轉換 (稱為動作)

  • 與狀態相關聯的欄位行為

轉換器會擷取 ClearQuest 狀態和動作，正如同 Team Foundation 工作項目類型定義中的狀態和狀態轉換。

工作項目表單的處理

轉換器不會將表單資訊從 ClearQuest 資料庫移轉至 Team Foundation。轉換器會產生預設的工作項目表單，這是在分析階段中所產生之結構描述的一部分，不過，這個預設表單與 ClearQuest 中的原始表單並不相像。預設表單包含極少的格式，通常都必須經過編輯才能變成比較有用的工作項目配置。如需如何編輯工作項目表單的詳細資訊，請參閱定義工作項目表單。

表單上的控制項

除了 Team Foundation 以外，您也可以在 ClearQuest 中的工作項目表單上放置各種不同的控制項。Team Foundation 支援一組預先定義的控制項，可供您使用。在 ClearQuest 中可以使用的某些控制項，在 Team Foundation 中則無法使用。雖然在移轉期間會保留最大的資料量，但由於可使用的控制項不同，也會影響 Team Foundation 中表單資料的顯示方式。在 Team Foundation 中不支援下列控制項：

  • ActiveX 控制項

  • 月曆控制項

  • 核取方塊控制項

  • 下拉式方塊控制項

  • 重複基底控制項

  • 重複相依性控制項

  • 父/子控制項

  • 圖片控制項

  • 按鈕控制項

  • 清單方塊控制項

  • 清單檢視控制項

  • 選項按鈕控制項

  • 靜態文字方塊控制項

在進行移轉規劃時，應該評估缺少這些控制項對使用者可能造成的影響。

欄位對應檔

欄位對應檔會指定欄位的對應方式以及欄位值的對應方式。

欄位對應

欄位對應檔會指定如何將 ClearQuest 中的欄位對應至 Team Foundation 欄位。ClearQuest 中的大多數欄位 (除了系統欄位和一般欄位以外) 都會以一對一方式對應至 Team Foundation。如果您在工作項目類型定義檔中對欄位做了任何變更，在這些欄位對應檔中也應該要保持同步處理。例如，如果您在工作項目類型定義檔中重新命名了某個欄位，就應該變更對應檔以指定相同的對應。同樣地，如果您從工作項目類型定義檔中刪除了某些欄位，則應該從對應的欄位對應檔中刪除相同的欄位。

欄位值對應

欄位對應檔也會指定在移轉期間要如何轉換欄位資料。根據預設，不會產生任何欄位值對應。如果您想要在移轉期間轉換資料，可以指定欄位值對應。您可以使用值對應來指定這些轉換，例如，指定 "Pri1" 這個值應該對應至 "1"。

欄位對應檔是一個 XML 檔。下列範例會說明如何對應欄位和欄位值：

<?xml version="1.0"?>

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

如需欄位對應的詳細資訊，請參閱欄位對應檔結構描述。

對應至區域路徑和反覆項目路徑欄位

Team Foundation 工作項目追蹤會將工作項目組織成一個包含結構化區域和反覆項目的階層架構。如需詳細資訊，請參閱 HOW TO：修改 Team 專案區域和 HOW TO：修改 Team 專案反覆項目。

路徑是用來協助以結構化方式將工作項目群組起來，以代表小組所使用的各種元件、專案或應用程式。反覆項目是用來協助根據主要事件 (例如里程碑) 和專案階段，將工作項目群組起來。[區域路徑] 和 [反覆項目路徑] 系統欄位會在 Team Foundation 中定義這項資訊。由於 ClearQuest 沒有這樣的概念，因此轉換器會提供預設值給這些欄位。預設為所有工作項目都要放在 [區域路徑] 和 [反覆項目路徑] 的根部。

雖然 ClearQuest 不提供 [區域路徑] 和 [反覆項目路徑]，但是您可以用其他方式來運用這些概念。例如，在您的工作項目類型中，可能有一個欄位是用來表示工作項目所屬的特定專案。這大致類似於 [區域路徑] 的概念。同樣地，您可能有另一個名為 [Fix By] 欄位，用來表示您希望特定工作項目能夠完成修正的里程碑。請考慮將這些欄位對應至 [區域路徑] 和 [反覆項目路徑]，讓工作項目出現在不同的節點中，而非全部都出現在一個根節點中。這些對應是依照之前說明的方式，在工作項目類型欄位對應檔中指定的。

下列 XML 範例會說明如何用可能的 Area1 和 Area2 值來對應名稱為 Tree Path 的 ClearQuest 欄位。

<FieldMap from="Tree Path" to="Area Path" exclude="false">

<ValueMaps>

  <ValueMap from="Area1" to="Area1" />

  <ValueMap from="Area2" to="Area2" />

</ValueMaps>

</FieldMap>

下列 XML 範例會說明如何用可能的 Alpha 和 Beta 值來對應名稱為 Fix By 的 ClearQuest 欄位。

<FieldMap from="Fix By" to="Iteration Path" exclude="false">

<ValueMaps>

  <ValueMap from= "Alpha" to="Alpha"/>

  <ValueMap from= "Beta" to="Beta"/>

</ValueMaps>

</FieldMap>

使用者對應檔

使用者對應檔會指出在 ClearQuest 和 Team Foundation 之間對應使用者的方式。如需詳細資訊，請參閱 使用者檔案對應結構描述。

結構描述對應檔

結構描述對應檔會指定來源工作項目類型、目標工作項目類型、工作項目定義檔和欄位對應檔。如需詳細資訊，請參閱 HOW TO：編輯結構描述對應檔案。

分析報告檔

分析報告檔是在移轉結束時產生的。移轉報告的名稱為 CQAnalysisReport.xml，是產生在執行 CQConverter 所在的資料夾中。另外有一個名稱為 _MigrationReport_Files 的相關聯資料夾，其中包含了在瀏覽器中顯示報告所需的影像檔和樣式表。在分析結束時，請開啟此檔案，以檢視在分析階段中所找到的任何錯誤或警告。分析報告會顯示下列項目：

  • 摘要：有關分析執行的摘要資訊。

  • 錯誤：在分析執行期間所找到的任何錯誤。您必須針對所列的任何錯誤，採取正確的動作。

  • 警告：在分析執行期間所找到的任何警告。警告需要您加以注意，但是不一定非修正不可。

  • 輸出：這個部分會列出所產生的輸出檔。

記錄檔

轉換器會產生一個名稱為 CQConverter.log 的記錄檔。這個檔案是用來進行偵錯，通常您並不需要檢視這個檔案。記錄檔是建立在執行 CQConverter 所在的資料夾中，其中包含了追蹤訊息 (Trace Message)，並且有助於排除在轉換器執行期間所找到的錯誤。

若要控制追蹤層級，請在 CQConverter.exe.config 檔中設定 [MinLevelForAllSource] 屬性的值。CQConverter.exe.config 檔位於 CQConverter.exe 所在的同一個資料夾中。您可以設定從 1 (最少的追蹤數量) 到 4 (最多的追蹤數量) 的值。

注意事項：

請注意，追蹤層級越大，轉換器效能就會越慢，而且記錄檔也可能變得非常大。

錯誤檔

轉換器還會產生另外一個檔案，其中包含在轉換器執行期間所找到的所有錯誤。這個檔案的名稱為 ConverterErrors.txt，是產生在執行 CQConverter 所在的同一個資料夾中。

請參閱

工作

HOW TO：編輯結構描述對應檔案

概念

工作項目轉換器組態檔

參考

使用者檔案對應結構描述

其他資源

自訂工作項目類型

定義工作項目工作流程

定義工作項目表單