前日の実績工数の取得
実績工数一覧の取得 API を使用することで、自身の前日の実績工数を取得できます。
GET /system/users/{userId}/timeEntries
準備
実績工数取得時には自身のユーザー ID を指定する必要があるため、あらかじめ取得します。
自身のユーザー ID の取得
自身のユーザー ID は、ログインユーザーの取得 API を実行して取得した情報から確認します。
GET /system/users/me
API を実行すると、以下のようなレスポンスが返ります。
{
"name": "岡本 直哉",
"englishName": "",
"loginName": "okamoto",
"email": "",
"code": "008",
"organizationName": "開発2課",
"avatarUrl": "https://example.com/timetrackernx/avatar/....",
"language": "ja-JP",
"timeZone": "Asia/Tokyo",
"isDeleted": false,
"unitCost": 8000.0,
"organizationId": "7",
"timeEntryLockedDate": "1753-01-01T00:00:00",
"description": "",
"ldapLoginName": "",
"systemRoleId": "1",
"systemRoleName": "システム管理者",
"availableFeatures": ["Berkley", "Berkley Admin"],
"canEdit": true,
"aclId": "0",
"permission": -1,
"id": "21",
"authenticationType": "Bearer",
"allowLocalAuthentication": false,
"createdAt": "2023-09-07T07:29:22Z",
"createdBy": "0",
"updatedAt": "2023-09-12T12:42:58Z",
"updatedBy": "0"
}
idに書かれている値が自身のユーザー ID となります。
ログインユーザーの取得 については、How To の次のリンクを参照ください。：ログインユーザーの取得
【発展】 プロジェクトメンバーのユーザー ID の取得
プロジェクトメンバーの前日の実績工数を取得する場合、ユーザー一覧の取得 API を使用してプロジェクトメンバーのユーザー ID を取得します。
assignedProjectIds パラメータにプロジェクトの ID を指定することで、指定したプロジェクトのプロジェクトメンバーの情報を取得します。
GET /system/users?assignedProjectIds=47
API を実行すると以下のようなレスポンスが返ります。
id の値がユーザー ID を表します。
{
"totalCount": 4,
"data": [
{
"name": "岡本 直哉",
"englishName": "",
"loginName": "okamoto",
"email": "",
"code": "008",
"organizationName": "開発2課",
"language": "ja-JP",
"timeZone": "Asia/Tokyo",
"isDeleted": false,
"unitCost": 8000.0,
"organizationId": "7",
"timeEntryLockedDate": "1753-01-01T00:00:00",
"description": "",
"ldapLoginName": "",
"systemRoleId": "1",
"systemRoleName": "システム管理者",
"avatarUrl": null,
"canEdit": true,
"allowLocalAuthentication": false,
"aclId": "0",
"permission": -1,
"id": "21",
"createdAt": "2023-09-07T07:29:22Z",
"createdBy": "0",
"updatedAt": "2023-09-14T07:17:47Z",
"updatedBy": "21"
},
{ "name": "黒川 悠太", "englishName": "", "loginName": "kurokawa", "id": "40", ･･･ },
{ "name": "高畑 哲也", "englishName": "", "loginName": "takahata", "id": "43", ･･･ },
{ "name": "高木 拓也", "englishName": "", "loginName": "takagi", "id": "83", ･･･ }
]
}
プロジェクトメンバーの取得については、How To の次のリンクを参照ください。：プロジェクトメンバーの取得
実績工数一覧の取得
必要な情報が揃ったら、実績工数一覧の取得 API を使用して自身の前日の実績工数を取得します。
以下では、2023/9/13 に前日の実績工数を取得する例で説明します。
パラメータの指定
-
startDate と finishDate
前日の実績工数のみを取得するために、startDateパラメータ とfinishDateパラメータに前日となる2023-09-12を指定します。
実行する API は以 下のようになります。GET /system/users/21/timeEntries?startDate=2023-09-12&finishDate=2023-09-12
レスポンス
レスポンスには、検索条件に該当する実績工数の総数と、取得した実績工数情報が返ります。
-
前日の実績工数が入力されている場合
前日の実績工数が入力されている場合、以下のようなレスポンスとなります。Response{
"totalCount": 3,
"data": [
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T09:00:00",
"finishTime": "2023-09-12T12:00:00",
"time": 180,
"memo": "",
"workItemId": "2086",
"workItemName": "仕様作成",
"workItemNumber": "3",
"workItemTypeId": "3",
"userId": "21",
"userName": "岡本 直哉",
"timeEntryCategoryId": "4",
"timeEntryCategory": "作業",
"processCategoryId": "7",
"processCategory": "外部仕様設計",
"isLocked": false,
"isDeleted": false,
"id": "16919",
"createdAt": "2023-09-13T05:03:22Z",
"createdBy": "21",
"updatedAt": "2023-09-13T05:30:31Z",
"updatedBy": "21"
},
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T16:00:00",
"finishTime": "2023-09-12T18:00:00",
"time": 120,
"memo": "",
"workItemId": "2088",
"workItemName": "指摘修正",
･･･,
"updatedBy": "21"
},
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T13:00:00",
"finishTime": "2023-09-12T15:00:00",
"time": 120,
"memo": "",
"workItemId": "2087",
"workItemName": "仕様レビュー",
･･･,
"updatedBy": "21"
}
]
} -
前日の実績工数が 1 つも入力されていない場合
前日の実績工数が 1 つも入力されていない状態で API を実行した場合、以下のようなレスポンスが返ります。Response{
"totalCount": 0,
"data": []
}取得した実績工数の総数を表す
totalCountの値が 0 であること、またdataに 1 つも実績工数情報が存在しないことから、前日の実績工数が 1 つも入力されていないことが分かります。
【発展】 orderby パラメータを指定して実行することで工数の入力漏れを確認
API 実行時に orderby のクエリパラメータを指定することで、指定通りに並び替えられた状態で実績工数を取得します。
並び替えの順序は、フィールド名の後の空白に続けて desc を指定することで降順になります。
上で実行した API に、startTime フィールドの昇順で並び替えを行うよう指定した場合、以下のようになります。
GET /system/users/21/timeEntries?startDate=2023-09-12&finishDate=2023-09-12&orderby=startTime
レスポンスは以下のようになります。
{
"totalCount": 3,
"data": [
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T09:00:00",
"finishTime": "2023-09-12T12:00:00",
"time": 180,
"memo": "",
"workItemId": "2086",
"workItemName": "仕様作成",
"workItemNumber": "3",
"workItemTypeId": "3",
"userId": "21",
"userName": "岡本 直哉",
"timeEntryCategoryId": "4",
"timeEntryCategory": "作業",
"processCategoryId": "7",
"processCategory": "外部仕様設計",
"isLocked": false,
"isDeleted": false,
"id": "16919",
"createdAt": "2023-09-13T05:03:22Z",
"createdBy": "21",
"updatedAt": "2023-09-13T05:30:31Z",
"updatedBy": "21"
},
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T13:00:00",
"finishTime": "2023-09-12T15:00:00",
"time": 120,
"memo": "",
"workItemId": "2087",
"workItemName": "仕様レビュー",
･･･,
"updatedBy": "21"
},
{
"projectId": "27",
"projectName": "S機器の開発",
"projectCode": "PRJ-010",
"workDate": "2023-09-12T00:00:00",
"startTime": "2023-09-12T16:00:00",
"finishTime": "2023-09-12T18:00:00",
"time": 120,
"memo": "",
"workItemId": "2088",
"workItemName": "指摘修正",
･･･,
"updatedBy": "21"
}
]
}
実績工数情報を startTime 順に並び替えることで、各実績工数情報の startTime や finishTime をたどって工数の入力漏れ確認を行うこともできます。