メインコンテンツまでスキップ

ユーザー通知一覧の取得

ユーザー通知一覧の取得 API を使用して、自身の通知一覧を取得できます。

GET /system/users/{userId}/notifications

準備​

ユーザー通知一覧の取得 API で指定する自身のユーザー ID をあらかじめ取得します。

自身のユーザー ID の取得​

自身のユーザー ID は、ログインユーザーの取得 API 実行で取得した情報から確認できます。

GET /system/users/me

API を実行すると、以下のようなレスポンスが返ります。

Response
{
  "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 を用いて、通知一覧を取得します。

パラメータの指定​

  • orderBy
    orderBy パラメータにフィールド名を指定することで、そのフィールドで並び替えられた通知一覧を取得します。
    並び替えの順序は、フィールド名の後の空白に続けて desc を指定することで降順になります。
    ここでは通知が作成された順に並び替えるために、 orderBy パラメータに createdAt を指定します。

    GET /system/users/21/notifications?orderBy=createdAt

レスポンス​

上記の API を実行すると、以下のようなレスポンスが返ります。

Response
{
  "totalCount": 5,
  "data": [
    {
      "toUserId": "21",
      "byUserId": "17",
      "message": "AG製品の開発 #20 プロジェクト作成機能設計に柴田 智彦さんがコメントしました。",
      "createdAt": "2023-09-04T02:09:41Z",
      "createdBy": "0",
      "updatedAt": "2023-09-13T10:54:44Z",
      "updatedBy": "21"
      "entityId": "2014",
      "entityType": "WorkItem",
      "isRead": true,
      "readAt": "2019-08-14T10:54:44Z",
      "target": "WorkItem.2014.Comment",
      "id": "50",

    },
    { "toUserId": "21", "byUserId": "23", "message": "T商品の開発 #4 仕様作成 のリーダーに割り当てられました", "createdAt": "2023-09-08T00:36:30Z", ･･･ },
    { "toUserId": "21", "byUserId": "40", "message": "A製品の開発 #205 テスト実施手順について説明会を実施する。 のリーダーに割り当てられました", "createdAt": "2023-09-18T06:01:34Z", ･･･ },
    { "toUserId": "21", "byUserId": "40", "message": "A製品の開発 #201 顧客議事録に記載されている要求をバックログに登録する。に黒川 悠太さんがコメントしました。", "createdAt": "2023-09-18T06:06:34Z", ･･･ },
    { "toUserId": "21", "byUserId": "40", "message": "A製品の開発 #206 顧客提出資料のデータに誤りがないか再確認する。 のリーダーに割り当てられました", "createdAt": "2023-09-18T06:08:04Z", ･･･ }
  ]
}

【発展】 未読の通知一覧の取得​

クエリパラメータをさらに追加し、未読の通知のみを取得します。

パラメータの指定​

  • unread
    unread パラメータで、未読の通知のみ取得するかを指定します。
    true で指定した場合、未読の通知のみ取得対象とします。
    false で指定した場合、全ての通知を取得対象とします。
    ここでは、未読の通知のみ取得するために true を指定します。

    GET /system/users/21/notifications?orderBy=createdAt&unread=true

レスポンス​

上記の API を実行すると以下のようなレスポンスが返り、未読である通知のみを取得します。

Response
{
  "totalCount": 3,
  "data": [
    {
      "toUserId": "21",
      "byUserId": "40",
      "message": "A製品の開発 #205 テスト実施手順について説明会を実施する。 のリーダーに割り当てられました",
      "createdAt": "2023-09-18T06:01:34Z",
      "createdBy": "0",
      "updatedAt": "2023-09-18T06:01:34Z",
      "updatedBy": "0"
      "entityId": "2677",
      "entityType": "WorkItem",
      "isRead": false,
      "readAt": null,
      "target": "WorkItem.2677",
      "id": "291",
    },
    { "toUserId": "21", "byUserId": "40", "message": "A製品の開発 #201 顧客議事録に記載されている要求をバックログに登録する。に黒川 悠太さんがコメントしました。", ･･･, "isRead": false, ･･･ },
    { "toUserId": "21", "byUserId": "40", "message": "A製品の開発 #206 顧客提出資料のデータに誤りがないか再確認する。 のリーダーに割り当てられました", ･･･, "isRead": false, ･･･ }
  ]
}

【発展】 通知情報から対象のワークアイテムを取得​

取得した通知情報とワークアイテムの取得 API を使用して、対象のワークアイテムを取得します。
ここでは、レスポンスで以下のような通知情報を取得した例で説明します。

Response
{
  "totalCount": 1,
  "data": [
    {
      "toUserId": "21",
      "byUserId": "40",
      "message": "A製品の開発 #206 顧客提出資料のデータに誤りがないか再確認する。 のリーダーに割り当てられました",
      "entityId": "2678",
      "entityType": "WorkItem",
      "isRead": false,
      "readAt": null,
      "target": "WorkItem.2678",
      "id": "295",
      "createdAt": "2023-09-18T06:08:04Z",
      "createdBy": "0",
      "updatedAt": "2023-09-18T06:08:04Z",
      "updatedBy": "0"
    }
  ]
}

通知情報からワークアイテム ID を確認​

取得した通知情報の entityType フィールドが WorkItem である場合、 entityId フィールドの値が通知対象のワークアイテムの ID となります。
この例では、 2678 がワークアイテム ID です。

対象ワークアイテムの取得​

ワークアイテムの取得 API に、 ワークアイテム ID を指定します。

GET /workitem/workItems/2678

さらに、 fields パラメータに取得対象とするフィールドを指定します。
この例では、ID 、 プロジェクトID 、 名前 、 進捗率 、 開始日 、 終了日 、親アイテム 、 親アイテム名 を取得対象フィールドとします。

GET /workitem/workItems/2678?&fields=Id,ProjectId,Name,ActualProgress,PlannedStartDate,PlannedFinishDate,ParentId,ParentName

上記の API を実行すると以下のようなレスポンスが返り、対象のワークアイテムを取得します。

Response
[
  {
    "fields": {
      "Id": "2678",
      "ProjectId": "47",
      "ParentId": "2670",
      "ParentName": "アクションアイテム",
      "Name": "顧客提出資料のデータに誤りがないか再確認する。",
      "ActualProgress": 0.0,
      "PlannedStartDate": "2023-09-18T00:00:00",
      "PlannedFinishDate": "2023-09-20T00:00:00",
      "IsAclInherited": false,
      "CanEdit": true
    },
    "isWarning": false,
    "warnings": [],
    "aclId": "0",
    "permission": -1
  }
]
備考

ワークアイテムの取得については、How To の次のリンクを参照ください。：ワークアイテムを ID 指定で取得

に最終更新