次の方法で共有


FIELD (定義) 要素リファレンス

FIELD (定義) 要素を使用して、作業項目フィールドを定義し、そのフィールドに適用される規則および条件を指定します。 フィールドに割り当てる属性により、データ型、およびレポートに含めることができるかどうかが決定されます。

注意

状態変更中、またはワークフロー遷移中にフィールドに規則と条件を指定するために使用する FIELD (ワークフロー) 要素の詳細については、「FIELD (ワークフロー) 要素」を参照してください。

スキーマの階層

WITD

   WORKITEMTYPE

      FIELDS

            FIELD

<FIELD name="fieldDisplayName" 
refname="fieldReferenceName" 
type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID" 
syncnamechanges ="true | false" 
reportable="Dimension | Detail | Measure"
formula="sum"
reportingname="ReportingDisplayName" 
reportingrefname="ReportingReferenceName" >
   <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
   <ALLOWEXISTINGVALUE />
   <CANNOTLOSEVALUE />
   <COPY />
   <DEFAULT />
   <EMPTY />
   <FROZEN />
   <HELPTEXT> . . . </HELPTEXT>
   <MATCH />
   <NOTSAMEAS />
   <PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES>
   <READONLY />
   <REQUIRED />
   <SERVERDEFAULT />
   <SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES>
   <VALIDUSER />
   <WHEN> . . . </WHEN>
   <WHENNOT> . . . </WHENNOT>
   <WHENCHANGED> . . . </WHENCHANGED>
   <WHENNOTCHANGED> . . . </WHENNOTCHANGED>
</FIELD>

属性および要素

以降のセクションでは、属性、子要素、および親要素について説明します。

属性

属性

説明

name

必ず指定します。 作業項目クエリのドロップダウン メニューに表示されるフィールドの表示名。 表示名は、チーム プロジェクト内で定義されるすべてのフィールドで一意である必要があります。 また、作業項目フォームのフィールドの横に表示されるラベルとは異なる場合があります。 詳細については、「Control XML 要素のリファレンス」を参照してください。

属性型は typelib:FieldName です。 最小長は 1、最大長は 128 です。

パターン値: ^[^\. \[\]]+$

パターン値の例: Assigned To

refname

必ず指定します。 1 つのフィールドと、チーム プロジェクト コレクションで定義される他のすべてのフィールドを区別する固有のラベル。

表示名および参照名のその他の要件については、「作業項目トラッキング オブジェクトの名前付け規則」を参照してください。

属性型は typelib:ReferenceFieldName です。 最小長は 1、最大長は 70 です。

パターン値: ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

パターン値の例: Company.IssueType

type

必ず指定します。 フィールドに設定できるデータの種類を指定します。

注意

別のプロジェクト コレクションのフィールドで、同じ reportingrefname を持つ場合は、 type に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理される際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

次の表に、この属性の有効な値の一覧を示します。

使用方法

DateTime

世界協定時刻 (UTC) に従って日付を指定します。

Double

浮動小数点値を指定します。

GUID

一意の識別子が格納されるフィールドを指定します。

History

ディスカッション スレッドをサポートし、その他の履歴情報を追跡します。

注意

System.History フィールドだけがこのデータ型を使用します。このデータ型を使用して、カスタム フィールドを定義することはできません。

HTML

リッチ テキスト データのキャプチャをサポートし、作業項目の説明など、長いテキストの説明に使用されます。

Integer

32 ビットの符号付き整数値を指定します。

PlainText

255 文字以上の Unicode 文字を含む文字列を入力できます。

String

最大 255 文字の Unicode 文字を含む文字列を入力できます。 String フィールドは、ラベルや、長さが 1 行以下の短い他のテキスト文字列に使用します。

TreePath

製品の領域パスとイテレーション パスを表示するための要件など、階層構造またはツリー構造でエントリを表示するフィールドを指定します。 子ノードを定義するには、「区分およびイテレーション パスの追加および変更」を参照してください。

注意

System.AreaPath フィールドと System.IterationPath フィールドだけがこのデータ型を使用します。このデータ型を使用して、カスタム フィールドを定義することはできません。

syncnamechanges

省略可能です。 Active Directory またはワークグループでの変更に合わせて、更新する名前を作業項目フィールドを使用して格納するかどうかを指定します。 このオプションは、type="String" の場合にのみ有効です。 属性型は xs:boolean です。

データ フィールドの同期を有効にする場合は true を指定し、データ フィールドの同期を無効にする場合は false を指定します。

reportable

省略可能です。 レポートを含めるのにフィールドのデータが使用できるかどうかを指定します。 既定値 None を持つフィールドは、リレーショナル データ ウェアハウスへエクスポートされることもなければ、SQL Server Analysis Services キューブとして処理されることもありません。 レポート可能フィールドの詳細については、「レポート作成をサポートするための作業項目フィールドの追加および変更」を参照してください。

注意

別のプロジェクト コレクションのフィールドで同じ reportingrefname の値を持つ場合は、reportable に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理される際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

次の表に、この属性の有効な値の一覧を示します。

Value

使用方法

Detail

DateTime、Double、Integer、または String 型のフィールドに指定できます。

このフィールドのデータは、リレーショナル ウェアハウス データベースの作業項目テーブルおよび現在の作業項目テーブルに移動されますが、Analysis Services キューブには移動されません。 この型は、レポートで使用する際にキューブが巨大になるのを防ぐことができるため、無制限のテキスト フィールドに適しています。

Dimension

DateTime、Integer、String、または TreePath 型のフィールドに指定できます。

このフィールドのデータは、リレーショナル ウェアハウス データベースおよび Analysis Services キューブに対し、作業項目ディメンションの属性として入力され、レポートのフィルターに使用できます。 この型は、有効値のリストを持つフィールドに対して使用します。 Work Item Type および State はディメンションの典型例です。

Measure

measure 型は、Integer フィールドと Double フィールドに対してのみ使用します。 メジャーは、レポートに含まれる数値です。

Analysis Services キューブが処理される際、データは reportable 属性が測定に設定されるフィールドで事前に計算されます。 たとえば、作業項目と現在の作業項目のメジャー グループには、最初の見積もり、残存時間数、実績作業時間数のフィールドの累積データが含まれます。

measure を指定する場合、formula 属性を指定する必要があります。

None

レポートを含めるフィールドを使用しない場合には、None を指定します。 これは、既定値の割り当てです。

formula

省略可能です。 reportable の種類が measure である場合の集計の種類です。 有効な値は sum のみで、セットのすべての値の合計を返します。

reportingname

省略可能です。 レポートに表示される名前を指定します。 値を指定しない場合は、name 属性に割り当てられた値が使用されます。

注意

別のプロジェクト コレクションのフィールドで同じ reportingrefname を持つ場合は、reportingname に同じ値を割り当てる必要があります。値が異なると、データ ウェアハウスが処理される際にデータの競合が発生する可能性があります。詳細については、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

属性型は typelib:FieldName です。 最小長は 1、最大長は 128 です。

パターン値: ^[^\. \[\]]+$

パターン値の例: Assigned To

reportingrefname

省略可能です。 レポート可能フィールドを処理する際に使用する参照名を指定します。 値を指定しない場合は、refname 属性に割り当てられた値が使用されます。

この属性を使用して、処理されるフィールドをデータ ウェアハウスに結合または分岐することができます。 別の参照名があり、かつ別のプロジェクト コレクションで定義された 2 つのフィールドを結合するには、両方に同じ reportingrefname を割り当てる必要があります。 同じ参照名を持っているが別のプロジェクト コレクションで定義されている 2 つのフィールドを分岐するには、各フィールドに別の reportingrefname を割り当てる必要があります。

ウェアハウスのフィールド数を最小化できる場合やレポート可能フィールドの上限を 1024 に維持できる場合は常に、フィールドを結合する必要があります。 結合されたフィールドを使用して、複数のグループにわたるレポートを生成することができます。

属性型は typelib:ReferenceFieldName です。 最小長は 1、最大長は 70 です。

パターン値: ^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$

パターン値の例: Company.IssueType

子要素

要素

説明

ALLOWEDVALUES

省略可能です。 フィールドの許可値のリストを定義します。 許可される値は、作業項目フォームのフィールド リストおよびクエリ ビルダーで選択可能な値です。 これらの値の 1 つを選択する必要があります。

ALLOWEXISTINGVALUE

省略可能です。 既存の値を許可するようにフィールドを定義します。 この要素は、既に存在するフィールド値が、たとえ無効値であっても使用できるようにします。 新しいフィールド値はすべて有効である必要があります。

CANNOTLOSEVALUE

省略可能です。 値を失わないフィールドとして定義します。 この要素を指定すると、現在のフィールド値が維持され、クリアすることも、空にすることもできません。

COPY

省略可能です。 現在のフィールドに値がコピーされる別のフィールドを指定します。

DEFAULT

省略可能です。 フィールドの既定値を定義します。

EMPTY

省略可能です。 フィールドを空と定義します。

FROZEN

省略可能です。 フィールドを固定として定義します。 変更がコミットされた後、固定されたフィールドを空でない値に変更することはできません。 ただし、手動でフィールドをクリアし、作業項目を保存して、別の値を指定することはできます。

HELPTEXT

省略可能です。 フィールドのツール ヒントに表示されるテキストを定義します。

MATCH

省略可能です。 フィールド値が一致する必要があるフィールドのパターンを定義します。

NOTSAMEAS

省略可能です。 現在のフィールドの値と一致する値を持つことができない別のフィールドを指定します。

PROHIBITEDVALUES

省略可能です。 フィールドで禁止される値のリストを定義します。

READONLY

省略可能です。 フィールドを読み取り専用として定義します。

REQUIRED

省略可能です。 フィールドを必須として定義します。

SERVERDEFAULT

省略可能です。 フィールドに値を設定するサーバー コンポーネントを指定します。

SUGGESTEDVALUES

省略可能です。 フィールドで推奨される値のリストを定義します。 推奨値は、作業項目フォームのフィールド リストおよびクエリ ビルダーで選択可能な値です。 リストに含まれていない、他の値を入力することもできます。

VALIDUSER

省略可能です。 許容値のリストがシステム内の有効なユーザーのみで構成される必要があることを指定します。

WHEN

省略可能です。 別のフィールドが特定の値を持つときに現在のフィールドに適用する 1 つまたは複数の規則を指定します。

WHENCHANGED

省略可能です。 特定のフィールドの値が変更されたときに現在のフィールドに適用される 1 つ以上の規則を指定します。

WHENNOT

省略可能です。 別のフィールドが特定の値ではないときに現在のフィールドに適用される 1 つ以上の規則を指定します。

WHENNOTCHANGED

省略可能です。 特定のフィールドの値が変更されないときに現在のフィールドに適用される 1 つ以上の規則を指定します。

親要素

要素

説明

FIELDS

必ず指定します。 作業項目の種類フィールドの定義を含みます。

解説

  1. FIELD (定義) は、FIELDS (定義) の必須の子要素です。

  2. TFS プロセス テンプレートに対して定義されたすべてのシステム フィールドおよび定義済みフィールドの概要については、「Visual Studio ALM の作業項目フィールド参照」を参照してください。

  3. System. プレフィックスで始まるカスタム フィールドを定義することはできません。 Microsoft. プレフィックスを使用してフィールドを定義することはできますが、この方法は使用しないことを強くお勧めします。Team Foundation Server の機能が阻害される可能性があるためです。

    フィールドの表示名および参照名のその他の要件については、「作業項目トラッキング オブジェクトの名前付け規則」を参照してください。

  4. フィールドの表示名は変更できますが、フィールドの参照名を変更することはできません。 witadmin コマンド ライン ツールを使用すると、フィールドの一覧表示と、一部のフィールド属性の変更が可能です。「作業項目フィールドの管理 [witadmin]」を参照してください。

  5. 同じチーム プロジェクト コレクション内で 1024 を超える数の作業項目フィールドを定義することはできません。また、すべてのチーム プロジェクト コレクションで 1024 を超える数のフィールドを reportable に設定することもできません。

    プロジェクト コレクションに定義されているすべてのチーム プロジェクトに関して作業項目の種類 (WIT) すべてで定義されているフィールドは、すべてチーム プロジェクト コレクション用です。 このため、ある WIT で定義されるフィールドに割り当てる属性は、コレクション内のすべてのチーム プロジェクトにあるすべての WIT で一致していなければなりません。 また、すべてのコレクションのレポート可能フィールドはすべて、データ ウェアハウスのデータベースにエクスポートされます。

  6. レポート用のフィールドにラベルを付ける方法については、「レポート作成をサポートするための作業項目フィールドの追加および変更」を参照してください。

  7. 既存のフィールドを別の WIT に追加する場合は、現在のフィールド定義と同じになるようにレポート属性を明示的に設定するか、またはそれらの値を既定値のままにしてください。

    異なる WIT 内の同じフィールド、または異なるチーム プロジェクト内の同じ WIT に違うレポート属性が割り当てられると、スキーマの競合が生じる可能性があります。 こうした競合を修正するには、「データ ウェアハウスで発生しているスキーマ競合の解消」を参照してください。

  8. クエリ、レポート、作業項目の追跡をサポートするようにフィールドを使用する方法については、「クエリ、レポート、ワークフローをサポートするフィールドの変更または変更」を参照してください。

  9. 子要素を使用して FIELD で制約や条件を適用する方法の概要については、「作業項目フィールドへの規則の適用」を参照してください。

使用例

<FIELD name="Activity" refname="Microsoft.VSTS.Common.Activity" type="String" reportable="dimension">
   <HELPTEXT>Type of work involved</HELPTEXT>
   <SUGGESTEDVALUES>
      <LISTITEM value="Development"/>
      <LISTITEM value="Testing"/>
      <LISTITEM value="Requirements"/>
      <LISTITEM value="Design"/>
      <LISTITEM value="Deployment"/>
      <LISTITEM value="Documentation"/>
   </SUGGESTEDVALUES>
</FIELD>

参照

関連項目

作業項目フィールドの管理 [witadmin]

概念

作業項目トラッキング オブジェクトの名前付け規則

Visual Studio ALM の作業項目フィールド参照

チームのプロセスをサポートするための作業トラッキング オブジェクトのカスタマイズ

作業項目フィールドの定義と変更

その他の技術情報

作業項目の追跡: XML 要素定義に対するインデックス