XML 形式での案件のインポートとエクスポート

プロジェクト トラッカーでは、案件を XML 形式でインポートおよびエクスポートできます。

XML インポートについて

XML 案件のインポートでは、すでに XML ファイルにエクスポートされている案件のコンテンツが抽出されます。XML ファイルをインポートすると、案件のフォーマットで表されたコンテンツがプロジェクトにインポートされ、提示された構造に従って再整理されます。

XML 案件をインポートするには、次の操作を行います。

  1. [プロジェクト] タブのプロジェクトの左にあるナビゲーション ペインでプロジェクト トラッカーのリンクを見つけます。
  2. [管理機能] をクリックして、[XML 形式で案件のインポート] のリンクをクリックします。
  3. [参照] ボタンをクリックして、インポートするファイル名を選択します。インポートされるファイルは、scarab-issues.xml のように XML 形式であることが必要です。XML ファイルを見つけることができない場合、[すべてのファイル] ドロップダウン ボックスをクリックし、すべてのファイル リストを表示して、その中から検索します。
  4. [ファイルのインポート] ボタンをクリックして、案件のコンテンツをプロジェクトにインポートします。

XML エクスポートについて

案件を XML 形式でエクスポートすると、案件のコンテンツを他のアプリケーションで使用できます。案件は、クエリ結果のページからエクスポートするか、プロジェクト トラッカーの XML エクスポート ページからエクスポートできます。案件を XML にエクスポートする場合は、現在のプロジェクトに限定されます。プロジェクト間のクエリからは、XML に案件をエクスポートできません。

注意:ステータス属性に定義された移行と依存関係属性に定義されたルールは、XML のインポート時に適用されません。これによって、ステータス移行を定義する前に作成された案件をインポートできます。

案件を XML 形式でクエリ結果ページからエクスポートするには

  1. プロジェクト トラッカーを使用するプロジェクトでは、左のナビゲーション ペインの [プロジェクト トラッカー] > [案件のクエリ] をクリックします。
  2. [新規作成] ボタンをクリックするか、既存のクエリのリンクをクリックします。
  3. 新しいクエリを作成する場合は、条件を入力して [実行] をクリックします。
  4. クエリ結果ページの [クエリ結果] セクションで、[結果を次にエキスポート] というラベルのドロップダウン リストをクリックして [XML (フル案件)] を選択します。

注意:Date 属性が関連付けられた案件タイプの案件に対してクエリを実行する場合は、[結果を次にエクスポート] オプションから Excel (XLS) 形式にエクスポートし、Microsoft Excel などの Excel エディタを使用して開くと、「Date」プロパティを持つセルの日付が、プロジェクト トラッカーに使用されている「YYYY-MM-DD」の形式で表示されない場合があります。これは、実績日は同じですが、Excel エディタで使用される日付設定が異なるためです。エクスポートする Excel ファイルの日付表示を変更するには、Excel エディタで次の手順を実行します。

  1. Date プロパティが関連付けられている Excel シートの列または行の全体または特定のセルを選択します。
  2. 選択範囲を右クリックして [セルの書式設定] を選択します。
  3. [表示形式] タブで、[ユーザ定義] カテゴリ オプションを選択します。
  4. 右側に表示されるサブメニューの [種類] テキスト ボックスに次のように入力します。"yyyy-mm-dd" (引用符は不要)
  5. [OK] ボタンをクリックし、変更を保存します。

これによって、オペレーティング システムで使用されている日付設定に関係なく、日付は「yyyy-mm-dd」形式で表示されます。オペレーティング システムの日付設定を変更すると、他のアプリケーションに影響する可能性があります。

案件を XML 形式でエクスポート ページからエクスポートするには

  1. プロジェクト トラッカーを使用するプロジェクトでは、左側のナビゲーション ペインの [プロジェクト トラッカー] > [XML 形式で案件のエクスポート] をクリックします。
  2. 画面上の指示に従って、1 つ以上の案件 ID を入力します。
  3. エクスポート先にファイルかブラウザ ウィンドウを選択します。
  4. [エクスポート] ボタンをクリックします。

インポート タイプ

インポートを行う方法は 2 つあり、XML ファイルの <import-type> エレメントによって指定されます。

create-same-db (別名 create-different-db) - インポートを行うとき、インポートされた案件はすべて新しい案件とみなされます。既存のデータは無視され、XML ファイル内のすべてのデータが新しいデータとしてインポートされます。

このインポート タイプは、次の目的に使用されます。

update-same-db - システムが <id> エレメントに基づいてデータベース内の既存の案件を検索します。<issue> が表す既存の案件によって、既存の案件が変更されます。同じ XML に、既存の案件と一致しない <id> エレメントを持つ <issue> も含まれている場合があります。これらは新しい案件としてインポートされます。

この既存項目の更新の例として、外部のさまざまな課題トラッカー間で案件を移動するときの推進役として、特定のクライアントで PT を使用する場合が考えられます。この使用方法の詳細は、現時点では明らかではありません。

update-same-db の基本的な使用方法が明らかでないため、この方法が Web サービス API の一部の代替策として利用されるという前提で開発が行われてきました。ただし、CGI パラメータを使用したスクリプトは、直感的に作成できます。以下の例は、現在の実装のさまざまなレベルに対応できます。

前提条件

インポートを正常に行うための現在の前提要件は、XML ファイル内で参照されるプロジェクト、ユーザ名、案件タイプ、属性、属性オプションのすべてが、システム内に存在していることです。それらが見つからなければ、インポートは失敗します。

ユーザインターフェイス

「XML インポート」への入力は、詳細が DTD で指定される単一の XML ファイルです。DTD は記述的なコメントで、詳細な説明は「ここ」にあります。ファイルは、HTTP ファイルのアップロードによって導入されるか、サービスとオペレーション グループ間で合意した手続きの一環でサーバのファイル システムに置かれます。

HTTP ファイルのアップロード

ファイルのアップロード オプションは、プロジェクトに案件を入力する権限を持つユーザが使用できます。ただし、[管理機能] ナビゲーション項目として表示される機能にアクセスするリンクは、通常プロジェクト オーナーおよび他の管理ロールを意味する [プロジェクト課題追跡 - 設定] または [プロジェクト - 編集] の権限を持つユーザにのみ表示されます。

インポートの結果は、HTTP 応答によって提示されるか、時間がプリセットした時間 (現在 30 秒) より長くなれば、ユーザに E-Mail で送信されます。エラー結果は、同様に即時応答されるか、E-Mail の送信になります。E-Mail の場合、成功のメッセージには Web インターフェイスを使用して結果を表示するリンクが記述されます。インポートがスクリプトになっている場合、クエリ パラメータ format=xml を追加して、結果を XML ドキュメントとして返すことができます。このパラメータの値を指定すると、応答はインポートが終了するまで待機します。E-Mail を送信するまでの時間制限はありませんが、HTTP クライアントまたはサーバによって最大時間が制限される場合があります。

ファイル添付エレメントは XML 内にあってもかまいませんが、無視されます。update-same-db タイプでは警告が発行される場合があります。

コマンドライン (サーバ上)

ファイル システムを使用する XML インポートは、プロジェクトを IssueZilla から PT に変換する場合に使用され、サービスによってクライアントからも使用できるようになります。ファイル添付エレメントは XML 内にあってもかまいませんが、サーバ上にあるファイルをポイントする必要があります。サービスは、インポート前にクライアント提供の XML を浄化し、サーバ上の注意が必要なファイルへのアクセスを回避する必要があります。

インポートする複数の XML ファイルを含むディレクトリを指定できます。これは便利な方法で、各ファイルは独立したインポートとして取り扱われます。

警告のない正常なインポートではメッセージも表示されません。エラーと警告は標準出力に出力されます。

検証

検証では DTD に対する XML のチェックを含めることができます。XML ファイルに含まれるデータも、アプリケーションのステータスと比較されます。

XML 検証

XML ファイルに DOCTYPE タグがある場合、リリース 3.0.1 以上では、 <!DOCTYPE scarab-issues SYSTEM "PROTO://www.DOMAIN/dtd/pt.dtd"> として指定し (PROTO は https または http)、リリース 3.0.0 と 2.6.x では <!DOCTYPE scarab-issues SYSTEM "http://project.domain.com/dtd/scarab-0.16.29.dtd"> として指定する必要があります。前記の DOCTYPE タグが指定されている場合、XML は現在のリリースの DTD に対して検証されます。

セマンティクス検証

XML ファイルに含まれるデータは、PT データベース内の現在のメタデータに対してチェックされます。このような案件タイプと属性のすべてのメタデータを使用できることが前提要件として必要です。XML 内で値が指定されている属性は、それらの属性がインアクティブの場合でも、指定された案件の案件タイプに関連付けられている必要があります。XML 内の属性名は、グローバル属性名にマップする必要があります。属性オプションは、プロジェクトまたは案件タイプで使用するオプションに、グローバル名またはエイリアスを使用できます。

依存関係の検証では、関連するタイプと案件が存在することをチェックします。検証されない情報の詳細については、「作成タイプと更新タイプの比較」セクションを参照してください。

XML で指定された日付文字列は、日付に付随するフォーマット文字列に従って解析できることが必要です。

XML 内で使用されるユーザ名は、ドメイン (ホストユーザの場合はホスト) 内の実際のユーザにマップする必要があります。

ファイル添付には、サーバ上のファイルへの有効なパスが必要です。この検証は、ファイル添付が許容されている場合にのみ行われます。

すべてのデータは、インポートの開始前に検証され、検証ステップとインポートの終了の間にメタデータを変更すると、インポートが失敗して案件が部分的にインポートされる場合があります。

注意:XML インポート機能を使用して属性をインポートした場合、必須属性は無視されます。これは、CollabNet ユーザ インターフェイスを使用して新しい案件を作成する場合、必須とマークされている ("*" で示される) すべての属性に値を指定する必要があることを意味します。ただし、必須属性の値がなくても、XML インポートを使用して新しい案件を作成することは許されます。

属性の依存関係

スレッドのインポートでは無効になります。監査情報は、移行と必須属性では使用できません。したがって、過去のいずれかの時点のアクティビティを含む案件のインポートが有効だったかどうかを確認できません。プロジェクト トラッカーがこの情報の監査を保持していても、XML インポート機能は従来の課題トラッカーからデータをインポートできるので、案件でのアクティビティがプロジェクト トラッカー内のメタデータの変更より前に行われた可能性があります。データはどの時点でも、そのときのステータスにおける要件を満たしていることが前提です。

案件は、必須属性の値がない場合もインポートできます。必要な値は、案件が最初にプロジェクト トラッカーで編集されるとき、強制されます。

案件の依存関係

依存関係は、同じ XML ファイル内の各案件の間に指定されます。インポートする別々の XML ファイル内の案件間では、依存関係を宣言できません。create-same-db タイプの場合、XML 内の案件と PT にすでに入力されている案件間に依存関係は指定できません。update-same-db タイプを使用すると、すでに入力されている案件に対して依存関係を指定できます。

アクティビティ セット

アクティビティは同時に発生する場合、グループ化できますが、通常他の案件とグループ化できない案件もあり、そのような案件は次のように 1 つのアクティビティを含むアクティビティ セットとして指定されます。

  1. 案件にファイル添付を追加する。
  2. 案件にコメントを追加する。

属性値と依存関係を変更するアクティビティは、1 つのアクティビティ セットに含めることができます。ただし、次のようなアクティビティ エントリは持つことができません。たとえば、同じアクティビティ セット内の「ステータスが [新規] から [開始済み] に変更された」入力と「ステータスが [新規] から [修正済み] に変更された」別の入力です。このような組み合わせは検証では把握されません。

作成日および変更日情報は、コメント/理由、URL、およびファイルを含む添付エレメントでは無視されます。ファイル添付は、XML が Web からアップロードされる場合、無視されます。XML 内の以前の添付と同じ ID の添付を使用するアクティビティでは、最初の添付に別の履歴レコードが作成され、元の添付が変更されることはありません。したがって、XML 内の添付の最初の参照は、最終状態である必要があります。通常、その他の参照も同じですが、同一の ID を共有する限り無視されます。

アクティビティ内の古い値と新しい値のエレメントを使用して、属性値を追加または変更します。単一値属性に古い値と新しい値の両方が含まれる場合は、値が変更されたと解釈されます。複数値属性は、エレメントを 1 つだけ持つ場合もあり、他のエレメントを持つ場合もあります。担当者が 'user1' から 'user2' に変更されるのではなく、'user1' が担当者として削除され、'user2' が担当者として追加されるものと考えることができます。古い値としてオプションまたはユーザ名があり、かつ新しい値がない場合は、値が削除されていると解釈されます。

サンプル XML

XML のより関連するセクションを示す変更例は、「アクティビティ サイン ドキュメント」に記載されています。いくつかの例は以下にも記載されています。

作成タイプと更新タイプの比較

検証

「更新」タイプの場合、XML 内の依存関係は、システムにすでに入力されている案件を参照できます。「作成」タイプでは、XML 内の依存関係と案件間に自己矛盾のないことが必要です。

新しい案件

「作成」タイプは、各課題エレメントについて常に案件が XML に新たに保存されます。「更新」タイプを使用すると、ID エレメントは保存された案件と比較されます。ID が保存された案件と一致するとその案件は変更されます。一致しなければ「作成」タイプと同様に新しい案件が作成されます。新たに保存された案件には、プロジェクトで使用しているプリフィックスとカウンタに従って新しい ID が割り当てられます。

アクティビティ セット

「作成」タイプでは、XML 入力で指定されたとおりにアクティビティ セットの日付が使用されます。update-same-db インポートの場合、案件が更新されていれば、アクティビティ セットの created-date が案件の最終変更日および現在の時刻の両方と比較されます。最終変更日前のアクティビティ セットは無視され、警告が発行されます。将来の日付はインポートが実行された時刻に変換されます。これにより、DTD の制約範囲内で更新が現在の時刻を使用するように指定できます。

アクティビティ

end-date がヌルのアクティビティは、どちらかのタイプの新しいアクティビティになります。通常、属性に関連するアクティビティの end-date がヌルの場合、アクティビティはその属性の現在の値を示します。end-date の値が指定されたアクティビティは、「更新」インポート タイプでは無視されます。

依存関係

すでに存在する依存関係を追加、または存在しない依存関係を削除しようとすると、「更新」タイプでは何も起こらずに無視されます。「作成」タイプで同様のことを行うと、例外が発生してその依存関係とその後発生する依存関係が保存されません。ただし、すべての案件が保存されます。存在しない依存関係の更新は、両方のタイプとも無視されます。