主なフィールドとその使い方
ワークアイテムには、開始日、終了日、計画工数、進捗率、ステータスなど、作業を追跡するためのフィールドが多数あります。 あらかじめ定義されたフィールドでは不足する場合に、ユーザーが独自にフィールドを作成することもできます。
フィールドの属性
フィールドにはフィールド名、システム名、データ型などの属性があります。
| 属性 | 説明 |
|---|---|
| フィールド名 | 画面上に表示されるフィールドの名前です。 |
| システム名 | システム内部でフィールドを識別するために使用される名前です。 |
| データ型 | 単一行テキストや整数など、フィールドに入力できる値の種類を表します。 |
フィールドに関する情報はフィールド一覧の取得の API で取得できます。
GET /system/fieldtypes
フィールドの種類
フィールドには、システムであらかじめ定義されたシステムフィールドと、ユーザーが独自に作成したカスタムフィールドがあります。
システムフィールド
システムであらかじめ定義されたフィールドであり、ユーザーはフィールドを削除することはできません。 システムフィールドには以下のようなフィールドがあります。
| フィールド名 | システム名 | 説明 |
|---|---|---|
| 名前 | Name | ワークアイテムを簡潔に表現する一行のテキストです。空にすることはできません。 |
| 説明 | Description | ワークアイテムの詳細を説明する複数行のテキストです。 |
| アイテムタイプ | ItemTypeId | 不具合や要求など、ワークアイテムの種類を表します。プロファイルによってアイテムタイプごとに使用できるフィールドやステータスを定義できます。 |
| ステータス | StatusTypeId | ワークアイテムの現在のステータスを表します。 |
| 進捗率 | ActualProgress | ワークアイテムの進捗率を表します。 |
| 開始日 | PlannedStartDate | ワークアイテムの計画上の開始日です。 |
| 終了日 | PlannedFinishDate | ワークアイテムの計画上の終了日です。 |
| リーダー | LeaderId | ワークアイテムの主担当となるユーザーです。 |
| 計画工数 | PlannedTime | ワークアイテムの計画工数です。 |
| 実績工数 | ActualTime | ワークアイテムの実績工数です。タイムシートで入力した実績工数が集計されるため、直接変更することはできません。 |
| 残り作業時間 | RemainingTime | ワークアイテムを完了するのに必要な残りの作業時間です。 |
| 計画コスト | PlannedCost | ワークアイテムのコストの計画値です。 |
| 実績コスト | ActualCost | ワークアイテムのコストの実績値です。 |
| 計画成果量 | OutputScalePlan | ワークアイテムの成果量の計画値です。 |
| 実績成果量 | OutputScaleActual | ワークアイテムの成果量の実績値です。 |
カスタムフィールド
カスタムフィールドはユーザーが独自に作成したフィールドです。 システム名とデータ型はフィールド作成後に変更することはできません。 また、システム名が既存のフィールドと重複するフィールドは作成できません。
フィールドの決定方法
各フィールドには、フィールドの値とは別に、フィールドの値を算出するための決定方法を保持しています。 フィールドの値は、そのフィールドに設定された決定方法に従って算出されます。
フィールドごとに設定可能な決定方法は異なります。 設定可能な決定方法が「なし」のみの場合、そのフィールドの値はシステムで自動的に計算され、ユーザーはそのフィールドを編集することはできません。 編集可能なフィールドに対して、値を直接入力した場合、そのフィールドの決定方法は自動的に「ユーザー入力値」となり、入力した値がそのままフィールドの値となります。
フィールドの決定方法には以下があります。
| 名前 | 識別子 | 説明 | フィールドの例 |
|---|---|---|---|
| なし | None | ユーザーは編集できません。 | 実績工数、など |
| ユーザー入力値 | UserInput | ユーザーが入力した値をフィールド値とします。 | 名前、など |
| 子の最小値 | Min | 子アイテムの最小値をフィールド値とします。 | 開始日、など |
| 子の最大値 | Max | 子アイテムの最大値をフィールド値とします。 | 終了日、など |
| 子の合計値 | Sum | 子アイテムの合計値をフィールド値とします。 | 計画工数、など |
| 子の平均値 | Average | 子アイテムの平均値をフィールド値とします。 | 整数型のカスタムフィールド、実数型のカスタムフィールド |
| 子の個数 | Count | 子アイテムの個数をフィールド値とします。 | 整数型のカスタムフィールド、実数型のカスタムフィールド |
| 論理積 | And | 子アイテムの論理積をフィールド値とします。 | 論理値型のカスタムフィールド |
| 論理和 | Or | 子アイテムの論理和をフィールド値とします。 | 論理値型のカスタムフィールド |
| 加重平均 | ProgressWeightedAverage | 計画工数で重み付けした子アイテムの進捗率の平均値です。 | 進捗率 |
| 規模進捗 | ProgressOutputScale | 実績成果量を計画成果量で割った値です。 | 進捗率 |
| 残作業時間 | ProgressRemainingTime | 計画工数から残り作業時間を引いた値を、計画工数で割った値です。 | 進捗率 |
| 管理しない | ProgressNA | 進捗率の値を NA にします | 進捗率 |
| 実績から算出 | CalcFromActualTime | 現 在の実績工数と進捗率から最終的な実績工数を計算し、必要な残りの工数を計算します。 | 残り作業時間 |
| 自動計算 | Auto | コスト単価などから計算します。 | 計画コスト、実績コスト |
| 計算式 | Expression | 計算式に従って計算します。 | 計画工数、など |
フィールドに設定可能な決定方法は、フィールド一覧の取得の API で取得した各フィールドの allowedFieldCalcTypes から取得できます。
プロファイルとの関係
フィールドはシステムで定義されるため、同じフィールドを複数のプロジェクトで使用できますが、実際にプロジェクトのワークアイテムでどのフィールドを使用できるかは、プロジェクトに適用するプロファイルで決まります。 システムフィールドはすべてのプロファイルにあらかじめ含まれているため、プロジェクトにどのプロファイルを適用しても使用できます。 カスタムフィールドを使用するには、プロファイルを編集して対象のフィールドをプロファイル内のアイテムタイプに追加する必要があります。
Web API での指定方法
ワークアイテムの API でフィールドを指定する場合はフィールドのシステム名を使用します。
ワークアイテムの取得
ワークアイテムの取得の API では、fields パラメータにフィールドのシステム名を指定することで、指定したフィールドの情報のみ取得できます。
GET /workitem/workitems/123?fields=Name,StatusTypeId
fields パラメータで指定したフィールド以外に、いくつかのメタ情報も返されます。
ワークアイテムの追加・更新
ワークアイテムの追加や更新の API では、リクエストボディの fields パラメータに、フィー ルドのシステム名とフィールドの値をキー・バリューの形式で指定します。
POST /workitem/workitems/123/subitems
{
"fields": {
"Name": "ワークアイテムの名前",
"Description": "ワークアイテムの説明",
"ItemTypeId": "3",
"PlannedStartDate": "2022-10-24",
"PlannedStartDate": "2022-10-28"
}
}
フィールドの値でなく決定方法を変更するには、リクエストボディの fieldCalcTypes パラメータに、フィールドのシステム名と決定方法をキー・バリューの形式で指定します。
PUT /workitem/workitems/123
{
"fieldCalcTypes": {
"PlannedTime": "Sum"
}
}
特別なパラメータ
一部のシステムフィールドに対しては、フィールドの更新のために特別なパラメータが存在します。
アイテムタイプを変更する
既存のワークアイテムに対してアイテムタイプを変更するには、changeItemTypeTo パラメータに変更後のアイテムタイプの ID を指定します。
PUT /workitem/workitems/123
{
"changeItemTypeTo": "5"
}
開始日と終了日をクリアする
既存のワークアイテムに対して開始日と終了日をクリアするには、clearSchedule パラメータを true にします。
PUT /workitem/workitems/123
{
"clearSchedule": true
}
割り当てを変更する
既存のワークアイテムに対して割り当てを変更するには、assignmentChange パラメータを使用します。
詳細は次のリンクを参照ください。：ワークアイテムのリソース割り当て
アイテムを完了にする
setCompleted パラメータに true を指定することで、対象のワークアイテムとその子のワークアイテムの進捗率を一括で 100% に設定できます。
PUT /workitem/workitems/123
{
"setCompleted": true
}
setCompleted パラメータに false を指定すると、進捗率を 0% に設定します。
進捗率の決定方法が「管理しない」になっているワークアイテムは更新されません。
実績入力をロックする
setTimeEntryLocked パラメータを使用することで、対象のワークアイテムおよびその子のワークアイテムでの実績入力をロックしたり、ロックを解除できます。
PUT /workitem/workitems/123
{
"setTimeEntryLocked": true
}