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

[アーティクル]
07/08/2015

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	必ず指定します。作業項目の種類フィールドの定義を含みます。

解説

FIELD (定義) は、FIELDS (定義) の必須の子要素です。
TFS プロセステンプレートに対して定義されたすべてのシステムフィールドおよび定義済みフィールドの概要については、「Visual Studio ALM の作業項目フィールド参照」を参照してください。
System. プレフィックスで始まるカスタムフィールドを定義することはできません。 Microsoft. プレフィックスを使用してフィールドを定義することはできますが、この方法は使用しないことを強くお勧めします。Team Foundation Server の機能が阻害される可能性があるためです。

フィールドの表示名および参照名のその他の要件については、「作業項目トラッキングオブジェクトの名前付け規則」を参照してください。
フィールドの表示名は変更できますが、フィールドの参照名を変更することはできません。 witadmin コマンドラインツールを使用すると、フィールドの一覧表示と、一部のフィールド属性の変更が可能です。「作業項目フィールドの管理 [witadmin]」を参照してください。
同じチームプロジェクトコレクション内で 1024 を超える数の作業項目フィールドを定義することはできません。また、すべてのチームプロジェクトコレクションで 1024 を超える数のフィールドを reportable に設定することもできません。

プロジェクトコレクションに定義されているすべてのチームプロジェクトに関して作業項目の種類 (WIT) すべてで定義されているフィールドは、すべてチームプロジェクトコレクション用です。このため、ある WIT で定義されるフィールドに割り当てる属性は、コレクション内のすべてのチームプロジェクトにあるすべての WIT で一致していなければなりません。また、すべてのコレクションのレポート可能フィールドはすべて、データウェアハウスのデータベースにエクスポートされます。
レポート用のフィールドにラベルを付ける方法については、「レポート作成をサポートするための作業項目フィールドの追加および変更」を参照してください。
既存のフィールドを別の WIT に追加する場合は、現在のフィールド定義と同じになるようにレポート属性を明示的に設定するか、またはそれらの値を既定値のままにしてください。

異なる WIT 内の同じフィールド、または異なるチームプロジェクト内の同じ WIT に違うレポート属性が割り当てられると、スキーマの競合が生じる可能性があります。こうした競合を修正するには、「データウェアハウスで発生しているスキーマ競合の解消」を参照してください。
クエリ、レポート、作業項目の追跡をサポートするようにフィールドを使用する方法については、「クエリ、レポート、ワークフローをサポートするフィールドの変更または変更」を参照してください。
子要素を使用して 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>