Azure Boards での作業項目のフィールドと属性
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
作業項目のフィールドは、情報を追跡するために使われます。 フィールドは、組織に対して定義され、その組織で定義されているすべてのプロジェクト間で共有されます。 2 つのツールのいずれかを使って、組織に定義されているフィールドを確認できます。 これらのツールは、継承 XML プロセス モデルとホストされた XML プロセス モデルの両方で使用できます。
作業項目のフィールドは、情報を追跡するために使われます。 フィールドは、コレクションに対して定義され、そのコレクションで定義されているすべてのプロジェクト間で共有されます。 2 つのツールのいずれかを使って、コレクションに定義されているフィールドを確認できます。
- [プロセス] > [フィールド] Web ページ: 継承プロセス モデルで使用できます
- 作業項目フィールド エクスプローラー: 継承 XML プロセス モデルとオンプレミス XML プロセス モデルで使用できます。
システム プロセスで定義されている各フィールドの説明については、作業項目フィールド インデックスに関する記事をご覧ください。
前提条件
- 組織またはコレクションに定義されているフィールドを表示するには、プロジェクト コレクションの有効なユーザー アプリケーション グループのメンバーであるか、組織またはコレクションに対するインスタンスレベル情報の表示アクセス許可が許可に設定されている必要があります。
フィールドを一覧表示または確認する
フィールドを一覧表示または確認するには、プロセス モデル (継承、ホストされた XML、またはオンプレミス XML) に応じて、次のいずれかのツールを使用できます。 既定のプロセス内で定義されているフィールドのインデックスについては、作業項目フィールド インデックスに関する記事をご覧ください。
ツール | 継承 | ホストされた XML | オンプレミス XML |
---|---|---|---|
Web ポータル: 継承されたフィールドとカスタム定義フィールドを一覧表示する | ✔️ | ✔️1 | |
作業項目フィールド エクスプローラー | ✔️ | ✔️ | ✔️ |
witadmin listfields コマンド ライン ツール | ✔️ | ✔️ | ✔️ |
注意
- 既定のプロセス (アジャイル、CMMI、スクラム) でのみサポートされます。
フィールドのデータ型と名前
各作業項目の種類で、その種類を参照する作業項目に対して定義されているフィールドが指定されています。 各フィールドは、多数の属性に関連付けられています。その多くはシステムによって設定され、変更できません。
各フィールドは、次の 3 つの属性によって定義されます。
- データ型: Boolean、Double、Integer、HTML、String など、フィールドに入力できるデータの型を指定します。 各データ型の説明については、クエリのフィールド、演算子、マクロに関する記事をご覧ください。
- フレンドリ名: フィールドに割り当てられた名前を指定し、クエリ句の Field ではこれを選択します。 この名前は、作業項目フォームに表示される名前と異なっていてもかまいません。
- 参照名: REST API コマンドを使って、または XML の作業項目の種類の定義を定義することで、WIQL クエリまたは計画外の作業項目テンプレートを作成するときに使う名前を指定します。 定義した参照名を変更することはできません。
各フィールド属性の説明と、それらを一覧表示する方法については、この記事で後述する「フィールド属性」と「フィールド属性を一覧表示する」をご覧ください。 WIT と作業項目の概要については、ユーザー ストーリー、イシュー、バグ、フィーチャー、エピックでの作業の追跡に関する記事をご覧ください。
フィールドとは何か? フィールド名はどのように使用されるか?
各作業項目の種類は、31 個のシステム フィールドと、種類固有の複数のフィールドに関連付けられています。 作業項目は、プロジェクトの計画と追跡に使います。
各フィールドは、実行する作業に関する情報の追跡をサポートします。 フィールドに割り当てた値は、作業追跡データ ストアに格納され、それを使って、状態と傾向を判断するためのクエリを作成できます。
コア システム プロセス (アジャイル、基本、スクラム、CMMI プロセス) に定義されている各フィールドの説明と使用方法については、作業項目フィールド インデックスに関する記事をご覧ください。
フィールド名
作業項目のフィールド名は、各作業項目フィールドを一意に識別します。 フィールド名が次のガイドラインに当てはまることを確認します。
- フィールド名は、アカウントやプロジェクト コレクション内で一意である必要があります
- フィールド名は、Unicode 文字で 128 文字以下にする必要があります
- フィールド名の先頭または末尾をスペースにすること、または 2 つ以上連続するスペースを含めることはできません
- フィールド名には、少なくとも 1 つの英字が含まれる必要があります
- フィールド名に次の文字を含めることはできません:
.,;'`:~\/\*|?"&%$!+=()[]{}<>
。
カスタム フィールドは組織またはコレクションに対して定義されるため、別のプロセスに追加したものと同じフィールド名でプロセスにカスタム フィールドを追加することはできません。
詳しくは、「名前付けの制限と規則」をご覧ください。
システム フィールドと定義済みフィールド
システム定義のすべてのフィールドの参照名は、System で始まっています。たとえば、System.AreaPath、System.AssignedTo というパターンで続きます。
既定のプロセスにより定義される定義済みフィールドは、Microsoft.VSTS で始まり、その後は用途により異なります。 共通で使用される定義済みフィールド、スケジューリング用で Office Project と統合される定義済みフィールド、Team Foundation ビルドと統合される定義済みフィールド、およびテスト ケース管理(TCM) と統合される定義済みフィールドの例は以下のとおりです。
- Microsoft.VSTS.Common.Priority
- Microsoft.VSTS.Scheduling.DueDate
- Microsoft.VSTS.Build.FoundIn
- Microsoft.VSTS.TCM.Steps
既定のプロセスやプロセス テンプレート用に定義されているすべてのシステム フィールドと定義済みフィールドの概要については、作業項目フィールド インデックスに関する記事をご覧ください。 フィールド名の指定について詳しくは、名前付けの制限に関する記事をご覧ください。
カスタム フィールド
カスタム フィールドは組織またはプロジェクト コレクションに対して定義されるため、別のプロセスに追加したものと同じフィールド名でプロセスにカスタム フィールドを追加することはできません。
カスタム フィールドを追加するときは、次の制限に注意してください。
- WIT ごとに定義できるフィールドは最大 64 個です
- プロセスごとに定義できるフィールドは最大 512 個です
フィールドのデータ型により、フィールドに格納できるデータの種類とサイズが決まります。 フィールドは、プロジェクト コレクション内で定義されている 1 つの型だけを持つことができます。 この制約によって、組織は、プロジェクトおよび作業項目の種類にわたって共通のフィールドを使用できます。
継承されたプロセスにカスタム フィールドを追加すると、Azure DevOps によって割り当てられる参照名は、スペースが除去されたフィールド名の前に、プレフィックス Custom が付いたものになります。 たとえば、DevOps Triage という名前のフィールドを追加すると、参照名は Custom.DevOpsTriage になります。 参照名内にスペースは使用できません。
フィールドのデータ型を確認する方法
[プロセス] > [フィールド] ページを開くことで、組織に定義されているフィールドのデータ型を確認できます。
プロジェクト コレクションで継承プロセス モデルを使って作業の追跡をカスタマイズしている場合は、[プロセス] > [フィールド] ページを開くことによって、フィールドのデータ型を確認できます。
オンプレミス XML プロセス モデルが使われている場合は、作業項目フィールド インデックスを使ってデータ型を調べることができます。 または、作業項目フィールド エクスプローラーを開いて、定義されているフィールドとその属性の割り当てを確認したり、witadmin listfields コマンドを使ってフィールド属性の一覧を表示したりできます。 詳細については、この記事で後述する「作業項目フィールド エクスプローラー」および「リスト フィールド属性」を参照してください。
[プロセス] > [フィールド] Web ページ
組織またはコレクションに定義されているフィールドの一覧を確認するには、[組織の設定] > [プロセス] > [フィールド] を開きます。
Azure DevOps のロゴを選んで、[プロジェクト] を開きます。 次に、[組織の設定] を選びます。
次に、[プロセス] を選択します。
注意
[プロセス] が表示されない場合は、TFS-2018 以前のバージョンから作業しています。 [プロセス] ページはサポートされていません。 オンプレミス XML プロセス モデルでサポートされている機能を使う必要があります。
次に、[フィールド] を選択します。
一覧表示されるフィールドは、組織またはコレクションに定義されているすべてのフィールドに対応します。 これには、すべてのカスタム フィールドと、システム プロセス用に定義されたものが含まれます。
注意
[フィールド] が表示されない場合は、コレクションでオンプレミス XML プロセスが使われています。 [フィールド] ページは、そのプロセスではサポートされていません。
各フィールドの説明と使用方法、および各フィールドの参照名は、作業項目フィールド インデックスから調べることができます。 作業項目の種類フィールド - List REST API でフィールドの参照名を取得することもできます。
作業項目フィールド エクスプローラー
作業項目フィールド エクスプローラー ツールを使って、フィールド属性の割り当てを調べることができます。
作業項目フィールド エクスプローラーにアクセスするには、プロセス エディター ツールをインストールする必要があります。 インストールされている Visual Studio のバージョンに基づいて、次のいずれかの拡張機能からプロセス エディター ツールを取得します。
- Visual Studio 2019 & 2022: 現時点では、特定のプロセス テンプレート エディター拡張機能は使用できません。 ただし、任意のテキスト エディターや XML エディターなどの他のツールを使用して、プロセス テンプレートをカスタマイズすることもできます。 また、特定のカスタマイズ (特に継承されたプロセスの場合) には、Azure DevOps Web ポータルを使用することもできます。
- Visual Studio 2017: TFS Process Template Editor。 このバージョンのプロセス エディターを使って、古いスタイルの作業項目フォームも変更できます。 これを使って、新しい Web フォームに関連付けられているフォームを編集することはできません。
- Visual Studio 2015: TFS Power Tools。
フィールド属性
作業項目フィールドごとに、変更できない属性と非表示の属性が多数あります。 次の表は、各属性を示しています。 属性の名前は、Fields - GetREST API で取得した場合と、作業項目フィールド エクスプローラー (WIFE) ツールで表示した場合では異なります。
フィールドに割り当てられる属性は、使用するプラットフォームとバージョンによって異なります。 たとえば、一部の属性は継承プロセスではサポートされていません。 フィールドの参照名の検索については、作業項目フィールド インデックスに関する記事をご覧ください。
属性
属性の型
説明
REST:
WIFE: AllowedValues
collection
候補リストの値を含むフィールドの有効な値のコレクションを取得します。 候補リストまたはグローバル リスト (オンプレミス) を指定することで、これを変更できます。
変更可能? = はい
REST: canSortBy
WIFE: CanSortBy
boolean
このフィールドを使ってクエリ結果を並べ替えることができるかどうかを示します。
変更可能? = いいえ
REST: description
WIFE: HelpText
string
フィールドの説明を指定します。これは、作業項目フォーム内のフィールドをポイントすると表示されるヘルプ テキストも定義します。
変更可能? = はい
REST:
WIFE: ID
Integer
フィールドの内部 ID を指定します。
変更可能? = いいえ
REST:
WIFE: IsCloneable
boolean
ユーザーが作業項目のコピーを選んだときに、フィールドに定義されている値がコピーされるかどうかを示します。 たとえば、[タイトル]、[タグ]、[説明] フィールドはコピーされますが、[ID] と [履歴] フィールドはコピーされません。
変更可能? = いいえ
REST:
WIFE: IsComputed
boolean
このフィールドによって設定される値が、システムによって計算されるか (True) されないか (False) を示します。 計算フィールドの例としては、[ID]、[更新日]、[変更日]、[外部リンク数] など、システムによって設定されるフィールドがあります。
変更可能? = いいえ
REST:
WIFE: IsCoreField
boolean
このフィールドがすべての作業項目の種類に対して指定されるかどうかを示します。
変更可能? = いいえ
REST:
WIFE: IsEditable
boolean
ユーザーがこのフィールドを変更できるか (True) できないか (False) を示します。 編集できないフィールドの例としては、[ID]、[リビジョン]、[作成者]、[変更者] フィールドなど、システムによって設定されるフィールドがあります
変更可能? = いいえ
REST: isIdentity
WIFE: IsIdentity
boolean
このフィールドが ID フィールドであるかどうかを示します。 ID フィールドは、ユーザー ID を格納するために使われる文字列フィールドです。
変更可能? = いいえ
REST:
WIFE: IsIndexed1
boolean
検索をサポートするためにこのフィールドにインデックスが付けられるかどうかを示します。
変更可能? = いいえ
REST:
WIFE: IsLongText
boolean
PlainText、HTML、History のデータ型が割り当てられたフィールドなど、フィールドが 255 文字を超える文字を格納できることを示します。
変更可能? = いいえ
REST: isPicklist2 WIFE:
boolean
フィールドが候補リストに関連付けられているかどうかを示します。 Azure DevOps にカスタム フィールドが定義され、[候補リスト (文字列)] または [候補リスト (整数)] 型が選択されている場合、この値は True に設定されます。 候補リストを定義する継承されたフィールドの場合、値は False に設定されます。
変更可能? = いいえ
REST: isPicklistSuggested2 WIFE:
boolean
ユーザーが候補リストに独自の値を入力できるかどうかを示します。 Azure DevOps にカスタム フィールドが定義され、[候補リスト (文字列)] または [候補リスト (整数)] 型が選択されていて、[Allow users to set their own values] (独自の値の設定をユーザーに許可する) チェックボックスがオンになっている場合、この値は True に設定されます。
変更可能? = はい
REST: isQueryable
WIFE: IsQueryable
boolean
作業項目クエリをフィルター処理するために追加できるフィールドのセット内にフィールドが表示されるか (True)、されないか (False) を示します。 ほとんどのフィールドはクエリ可能です。
変更可能? = いいえ
REST:
WIFE: IsReportable 3
boolean
レポート可能属性が定義されているか、または None 以外に設定されているかを示します。 オンプレミス環境では、この属性を変更できます。
変更可能? = はい
REST:
WIFE: IsUsedInGlobalWorkflow
boolean
フィールドがグローバル ワークフロー内で定義されているかどうかを示します。
変更可能? = いいえ
REST:
WIFE: IsUserNameField
boolean
フィールドが ID フィールドの表示に使われるかどうかを示します。
変更可能? = いいえ
REST: name
WIFE: Name
string
フィールドに割り当てられたフレンドリ名。 Azure DevOps のフレンドリ名は変更できませんが、オンプレミスの場合は witadmin changefield コマンドを使って変更できます。
変更可能? = オンプレミスのみ
REST: picklistId
WIFE: HelpText
GUID
フィールドが候補リストの場合は、関連付けられている候補リストの識別子。それ以外の場合は null。 Azure DevOps にカスタム フィールドが定義され、[候補リスト (文字列)] または [候補リスト (整数)] 型が選択されている場合、一意の GUID 値が割り当てられます。
変更可能? = いいえ
REST:
WIFE: ProhibitedValues
collection
禁止値が指定されているフィールドに対するそのような値のコレクションを取得します。 オンプレミスの展開に対してのみ、禁止値を定義できます。
変更可能? = オンプレミスのみ
REST: readOnly
WIFE:
boolean
フィールドが読み取り専用に設定されているかどうかを示します。 Azure DevOps Services の場合、読み取り専用に変更できるのはカスタム フィールドのみです。 システム フィールドは変更できません。
変更可能? = はい
REST: referenceName
WIFE: ReferenceName
string
フィールドの参照名を指定します。
変更可能? = いいえ
REST:
WIFE: ReportingAttributes3
フィールドをレポートに含めるかどうか、およびその方法に応じて、Detail、Dimension、または Measure を指定します。 この属性に None 以外の値が指定されたフィールドのデータは、データ ウェアハウスにエクスポートされ、SQL レポートに含めることができます。
変更可能? = オンプレミスのみ
REST:
WIFE: ReportingName3
string
SQL レポートにデータが表示される場合のフィールドのラベルを指定します。 値を指定しないと、フィールドのフレンドリ名が使われます。
変更可能? = オンプレミスのみ
REST:
WIFE: ReportingReferenceName3
string
データがリレーショナル データ ウェアハウスにエクスポートされるときに使われるフィールドに、別の参照名を指定します。 値を指定しないと、フィールドの参照名が使われます。
変更可能? = オンプレミスのみ
REST: supportedOperations
WIFE:
set
このフィールドを参照するときに使用できるクエリ演算子のセット。 データ型に基づいてサポートされている演算のクイック リファレンスについては、「クエリのクイック リファレンス」の「各データ型でサポートされる演算子とマクロ」をご覧ください。
変更可能? = いいえ
REST:
WIFE: SupportsTextQuery
boolean
Contains Words や Does Not Contains Words などのテキスト クエリをフィールドがサポートするかどうかを示します。
変更可能? = いいえ
REST:
WIFE: SystemType
string
System.DateTime や System.String などのシステム名を参照するフィールドのデータ型を指定します。
変更可能? = いいえ
REST: type
WIFE: FieldType
string
Boolean、DateTime、Integer、String など、フィールドのデータ型を指定します。 完全な一覧と説明については、クエリのフィールド、演算子、マクロに関する記事をご覧ください。
変更可能? = いいえ
REST: usage
WIFE: Usage
string
フィールドが作業項目 (WorkItem) オブジェクトまたは作業項目リンク (WorkItemLink) オブジェクトで使うためのものかどうかを指定します。 ほとんどのフィールドの用途は WorkItem です。 用途の値の完全な一覧については、フィールドの取得の FieldUsage に関する記事をご覧ください。
変更可能? = いいえ
注意
- オンプレミスの展開の場合、フィールドのインデックス作成を有効にすることで、そのフィールドでフィルター処理するときのクエリの応答時間を短縮できます。 詳しくは、この記事で後述する「インデックス付きフィールド」をご覧ください。
- isPicklist と isPicklistSuggested 属性は、継承プロセスに対して定義されたカスタム フィールドにのみ割り当てられます。 継承プロセス モデルは、Azure DevOps Server 2019 以降のバージョンでサポートされています。 詳細については、「継承されたプロセス モデル」を参照してください。
- すべてのレポート属性は、SQL Server Reporting と SQL Server Analysis Services をサポートするようにプロジェクトが構成されているオンプレミスの展開に対してのみ有効です。
レポート可能な属性
すべてのレポート属性は、SQL Server Reporting と SQL Server Analysis Services をサポートするようにプロジェクトが構成されているオンプレミスの展開に対してのみ有効です。 詳細については、「プロジェクトへのレポートの追加」を参照してください。
レポート可能各属性の説明については、「[レポートを作成するための作業項目フィールドの追加方法と変更方法](/previous-versions/azure/devops/reference/xml/add-or-modify-work-item-fields-to-support-reporting)」をご覧ください。
レポート可能属性が既定で定義されているフィールドの一覧については、「レポート可能フィールド リファレンス」をご覧ください。
インデックス付きフィールド
witadmin indexfield コマンドを使って、作業項目フィールドのインデックス作成を有効または無効にできます。 フィールドのインデックス作成を有効にすると、クエリでそのフィールドを指定する作業項目を検索するパフォーマンスが向上することがあります。 既定では、"担当者"、"作成日"、"変更者"、"状態"、"理由"、"区分 ID"、"イテレーション ID"、"作業項目の種類" の各フィールドにインデックスが付けられます。
作業項目クエリの多くで使用するカスタム フィールドを追加した場合、そのフィールドのインデックス作成を有効にすることをお勧めします。 詳しくは、「作業項目フィールドの管理」 (witadmin) をご覧ください。
フィールド属性の一覧を表示する
Fields - Get REST API を使うことで、フィールドに割り当てられた属性の一覧を表示できます。 OrganizationName には組織の名前を入力します。
https://dev.azure.com/OrganizationName/_apis/wit/fields/FieldReferenceName
たとえば、次の場合は、fabrikam 組織の参照名 System.IterationPath
を指定して、イテレーション パスの属性の一覧を表示します。
https://dev.azure.com/fabrikam/_apis/wit/fields/System.IterationPath
返されるデータ:
{
"name": "Iteration Path",
"referenceName": "System.IterationPath",
"description": "The iteration within which this bug will be fixed",
"type": "treePath",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "SupportedOperations.Under",
"name": "Under"
},
{
"referenceName": "SupportedOperations.NotUnder",
"name": "Not Under"
},
{
"referenceName": "SupportedOperations.Equals",
"name": "="
},
{
"referenceName": "SupportedOperations.NotEquals",
"name": "<>"
},
{
"referenceName": "SupportedOperations.In",
"name": "In"
},
{
"name": "Not In"
}
],
"isIdentity": false,
"isPicklist": false,
"isPicklistSuggested": false,
"url": "https://dev.azure.com/mseng/_apis/wit/fields/System.IterationPath"
}
Fields - Get REST API を使うことで、フィールドに割り当てられた属性の一覧を表示できます。 OrganizationName には組織の名前を入力します。 REST を使い始めるには、「Azure DevOps Services REST API リファレンス」をご覧ください
https://{ServerName:Port}/tfs/{Collection}/_apis/wit/fields/FieldReferenceName?api-version={version}
たとえば、次の場合は、fabrikam サーバーの参照名 System.IterationPath
を指定して、イテレーション パスの属性の一覧を表示します。
https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1
返されるデータ:
{
"name": "Iteration Path",
"referenceName": "System.IterationPath",
"description": "The iteration within which this bug will be fixed",
"type": "treePath",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "SupportedOperations.Under",
"name": "Under"
},
{
"referenceName": "SupportedOperations.NotUnder",
"name": "Not Under"
},
{
"referenceName": "SupportedOperations.Equals",
"name": "="
},
{
"referenceName": "SupportedOperations.NotEquals",
"name": "<>"
},
{
"referenceName": "SupportedOperations.In",
"name": "In"
},
{
"name": "Not In"
}
],
"isIdentity": false,
"isPicklist": false,
"isPicklistSuggested": false,
"url": "https://fabrikam:8080/tfs/DefaultCollection/_apis/wit/fields/System.IterationPath?api-version=4.1"
}
witadmin
コマンド ライン ツールを使用して属性の一覧を表示する
witadmin listfields コマンドを使って、選択したフィールド属性 (データ型、レポート可能属性、インデックス作成など) の一覧を表示できます。
たとえば、次のコマンドを入力すると、Microsoft.VSTS.Common.Issue など、指定したフィールドに定義されている属性の一覧を表示できます。
witadmin listfields /collection:http://fabrikam:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Issue
次に示すように、指定したフィールドのフィールドおよび属性情報が表示されます。
Field: Microsoft.VSTS.Common.Issue
Name: Issue
Type: String
Reportable As: dimension
Use: Adventure Works (Shared Steps), AW Future (Shared Steps), AW Current (Shared Steps)
Indexed: False
Use パラメーターは、各プロジェクトの名前と、フィールドが使用されている作業項目の種類を示します。
フィールドを追加および変更する
プロセスにフィールドを追加するには、1 つ以上の作業項目の種類にそれを追加します。 詳細については、「 継承プロセスをカスタマイズする」を参照してください。
WIT に含まれるフィールドの追加や変更、またはカスタム WIT の追加を行うことができます。 詳細については、以下を参照してください:
- 継承プロセス モデルを使用するプロジェクト コレクションの場合: 継承プロセスをカスタマイズする。
- オンプレミス XML プロセス モデルを使用するプロジェクト コレクションの場合: オンプレミス XML プロセス モデルをカスタマイズする。
witadmin コマンド ライン ツールを使う、システム フィールドを除く任意のフィールドについて、フィールド名、インデックス、レポート属性を変更できます。 詳しくは、「作業項目フィールドの管理」 (witadmin) をご覧ください。