WorkAction

作業項目に対するアクションを実行するには、このリソースを使用します。

注記: APIドキュメントは IBM API Hub に移行されました外部リンクは新しいウィンドウまたはタブで開きます

。 API Hub で API Blueworks Live の最新更新情報とドキュメントを確認してください。

メソッドの要約

HTTP メソッド	パス	説明
POST	/scr/api/WorkAction	作業項目に対するアクションを実行します。

POST /scr/api/WorkAction

説明: 作業項目に対するアクションを実行するには、このメソッドを使用します。
重要: まず、操作対象の作業項目に関する情報を取得 WorkDetail するためにを実行してください。その API の出力を WorkAction のパラメーターに埋めてください。

リソース情報

要件	説明
応答フォーマット	JSON
認証が必要	はい
OAuth 2 クライアント資格情報のサポート	はい (実行管理機能カテゴリーを含むユーザー・サービス ID を使用)
指定時間内の数の制限	現在はなし

パラメーター

名前	Location	説明	必須	タイプ
X-On-Behalf-Of	ヘッダー	ユーザー・コンテキスト。値は、アカウントに含まれるユーザー名でなければなりません。ユーザーは、アカウント内と、親スペースを指定した場合はその親スペース内でアクションを実行する権限を持っている必要があります。	サービスID OAuth の認証情報を使用する場合に必要です。ユーザーサービスID OAuth の認証情報を使用する場合、不要です。	ストリング
action	照会	実行するアクションに関する情報。このパラメーターの形式を、例に示します。要求されたアクション・タイプに応じて、一部のフィールドが必須になります。	はい	下記のアクション・パラメーターを参照してください
version	照会	要求する API のバージョン。使用できる値は `20110917` のみです。	はい	ストリング

処置パラメーター

名前	説明	データ型
action.subject	新規作業インスタンスの件名。	ストリング
action.runtimeVersion	. `WorkDetail`によって提供される値の配列	ストリング
action.workId	アクションの実行対象となる作業項目の ID。 WorkDetail を呼び出すときに使用した ID と同じ ID を使用します。	ストリング
action.appId	この作業が関連するアプリケーションのID。この ID は、WorkDetail を実行することで提供されます。	ストリング
action.timeZoneId	インスタンスを開始するタイム・ゾーン。タイム・ゾーンが指定されていない場合は、ユーザーの現行設定の値が使用されます。ユーザーの現行設定にもタイム・ゾーンが指定されていない場合は、サーバーのデフォルトが使用されます。	ストリング
action.type	実行するアクションのタイプ。このパラメーターにより、どの追加フィールドが必須になるかが決まります。次のアクション・タイプを使用できます。 COMPLETE 現在のタスクを完了します。 APPROVE 現在のタスクを承認します。タスクが承認ステップの場合のみ有効です。 `action.task.id` パラメーターが必要です。 REJECT 現在のタスクを拒否します。タスクが承認ステップの場合のみ有効です。 `action.task.id` パラメーターが必要です。 ADD_TASK 現在のタスクを完了し、新規タスクを追加します。 `action.task.id`、`action.task.assignedTo`、`action.task.name`、`action.task.approvalStep` (オプション)、および `action.task.dueDateExpression` (オプション) の各パラメーターが必要です。 REASSIGN タスクを再割り当てします。 `action.task.id` パラメーターおよび `action.task.assignedTo` パラメーターが必要です。 CHANGE_SUBJECT 作業の件名を変更します。 `action.subject` パラメーターが必要です。 CANCEL_INSTANCE 作業項目をキャンセルします。 REMOVE_ATTACHMENT インスタンスから添付ファイルを削除します。 `action.attachmentId` パラメーターが必要です。	ストリング
action.subject	`CHANGE_SUBJECT` アクションに必要です。作業項目の新規件名。	ストリング
action.attachmentId	`REMOVE_ATTACHMENT` アクションに必要です。インスタンスから削除する添付ファイルの ID。	ストリング
action.task.id	`ADD_TASK`、`REASSIGN`、`APPROVE`、`COMPLETE`、および `REJECT` の各アクションに必要です。アクションの実行対象となるタスクの ID。 `ADD_TASK` アクションが実行されると、このタスク ID は完了し、新しいタスク ID が作成されます。	ストリング
action.task.assignedTo	`REASSIGN` アクションおよび `ADD_TASK` アクションに必要です。このタスクが割り当てられるユーザーの ID。	ストリング
action.task.name	`ADD_TASK` アクションに必要です。タスク名。	ストリング
action.task.approvalStep	`ADD_TASK` アクションの場合はオプションで、`workflow` タイプの作業項目にのみ必要です。このタスクが承認ステップかどうかを示します。パラメーターがない場合は、値が false と見なされます。	ブール値
action.task.dueDateExpression	`ADD_TASK` アクションの場合はオプションです。このタスクの期限を示します。`YYYY/MM/DD` の形式で指定する必要があります。	ストリング

応答

入力例

ユーザーサービスID OAuth 2 のクライアント認証情報を使用：

curl -i -X POST
  'https://your_server_url/scr/api/WorkAction?&version=20110917' 
  --data-urlencode 'action={"action":{"runtimeVersion":["34c2522c-fda6-40f3-abe8-d98cf8e46e65","a0713",1],"workId":"a0713","appId":"80038","type":"CANCEL_INSTANCE","timeZoneId":"America/Los_Angeles"}}' 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer access_token'

サービスID OAuth を使用し、ユーザーコンテキストを持つ2つのクライアント認証情報:

curl -i -X POST
  'https://your_server_url/scr/api/WorkAction?&version=20110917' 
  --data-urlencode 'action={"action":{"runtimeVersion":["34c2522c-fda6-40f3-abe8-d98cf8e46e65","a0713",1],"workId":"a0713","appId":"80038","type":"CANCEL_INSTANCE","timeZoneId":"America/Los_Angeles"}}' 
  --header 'Accept: application/json' 
  --header 'Authorization: Bearer access_token'

アクション・パラメーターの例

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "workId":"b0059",
     "appId":"87654",
     "type":"CANCEL_INSTANCE",
     "timeZoneId":"America/Los_Angeles"
 }
}

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "attachmentId":"32345",
     "workId":"b0059",
     "appId":"87654",
     "type":"REMOVE_ATTACHMENT",
     "timeZoneId":"America/Los_Angeles"
 }
}

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "workId":"b0059",
     "appId":"453c78",
     "type":"APPROVE", /* COMPLETE or REJECT */
     "timeZoneId":"America/Los_Angeles",
     "task": {
       "id":"947593"
     }
 }
}

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "workId":"b0059",
     "appId":"98765",
     "type":"ADD_TASK",
     "timeZoneId":"America/Los_Angeles",
     "task": {
       "id":"", /* Id of existing task to close and replace with this one */
       "assignedTo":"94837",
       "name":"New task",
       "dueDateExpression":"2011/09/12",
       "approvalStep":true
     }
 }
}

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "workId":"b0059",
     "appId":"c67890",
     "type":"REASSIGN",
     "timeZoneId":"America/Los_Angeles",
     "task": {
       "id":"97c456",
       "assignedTo":"8654a"
     }
 }
}

{
   "action": {
     "runtimeVersion":[
       "037ee4bb-30c8-40e7-b083-0946e750f889",
       "b0059",
       0
     ],
     "workId":"b0059",
     "appId":"9a3456",
     "type":"CHANGE_SUBJECT",
     "timeZoneId":"America/Los_Angeles",
     "subject":"New subject for this work."
 }
}

出力例

*WorkDetail と同じ*

{
   "app": {
      "detailsTitle": "myCustomDetails",
      "id": "5f6000838003c",
      "name": "Detailed ProcessApp with 1 task A",
      "subjectTitle": "myCustomWorkSubject",
      "type": "workflow"
   },
   "users": [
      {
         "avatarId": "5f60008340006",
         "id": "170351",
         "name": "admin"
      }
   ],
   "version": "20110917",
   "work": {
      "appId": "5f6000838003c",
      "attachments": [
      ],
      "canManageWork": true,
      "comments": [
      ],
      "completedAt": 1730704963179,
      "completedBy": "170351",
      "details": "my sample details",
      "id": "5f6000d14000c",
      "name": "Detailed ProcessApp with 1 task A - New for test.",
      "runtimeVersion": [
         "6e711bd6-6718-4aae-96d5-d2b3ea620758",
         "5f6000d14000c",
         2
      ],
      "startedAt": 1730701215969,
      "startedBy": "170351",
      "status": "Completed",
      "subject": "New for test.",
      "tasks": [
         {
            "approvalStep": false,
            "assignedTo": "170351",
            "id": "5f6000d140015",
            "name": "Subject matter expert review",
            "status": "Completed"
         }
      ]
   }
}

応答プロパティー

version

応答の作成に使用された API のバージョン。

work

作業オブジェクト。

work.runtimeVersion

作業インスタンスのバージョンを識別する配列。この値は、型が不明なデータ項目として扱います。は work.runtimeVersion 、に必要なものです WorkAction。

work.name

作業インスタンスの表示名。

work.id

作業インスタンスの ID。

work.subject

インスタンスを作成したユーザーが入力した件名。

work.details

インスタンスを作成したユーザーが入力した詳細。

work.status

作業の状況は、次のいずれかの値になります。

Active
Completed
Cancelled
Overdue

work.startedBy

インスタンスを作成したユーザーの ID。この ID を持つオブジェクトが、当該ユーザーの配列に表示されます。

work.startedAt

インスタンスが開始された日時。値は、エポック、すなわち協定世界時 (UTC) 1970 年 1 月 1 日真夜中からの経過時間 (ミリ秒) で表されます。

work.completedBy

インスタンスを完了またはキャンセルしたユーザーの ID。状況が Completed または Cancelled の場合にのみ存在します。この ID を持つオブジェクトが、当該ユーザーの配列に表示されます。

work.completedAt

インスタンスが完了またはキャンセルされた日時。値は、エポック、すなわち協定世界時 (UTC) 1970 年 1 月 1 日真夜中からの経過時間 (ミリ秒) で表されます。状況が Completed または Cancelled の場合にのみ存在します。

work.appId

インスタンスの開始元アプリケーションの ID。このアプリケーションがアプリケーション・オブジェクトに表示されます。

work.canManageWork

ユーザーが作業のキャンセル、件名の変更、またはタスクの再割り当てを行う権限があるかどうかを示します。

work.tasks

インスタンスと関連付けられたタスクの配列。

work.tasks.name

タスク名。

work.tasks.id

タスクの ID。

work.tasks.assignedTo

タスクが割り当てられているユーザーの ID。この ID を持つオブジェクトが、当該ユーザーの配列に表示されます。

work.tasks.actioner

タスクの所有者ではなく、タスクの状況を最後に変更したユーザーの ID。この ID を持つオブジェクトが、当該ユーザーの配列に表示されます。タスクが再割り当てされた場合は、work.tasks.actioner は再割り当てを行ったユーザーの ID を参照します。一方、assignedTo ユーザーは、タスクが最初に割り当てられたユーザーです。

work.tasks.dueDate

タスクの期限が切れる日。このプロパティーは、タスクに dueDate が設定されている場合にのみ存在します。

work.tasks.status

次のいずれかの値になります。

Pending
NotStarted
InProgress
Completed
Reassigned

work.tasks.reassignmentReason

このプロパティーは、状況が Reassigned の場合にのみ存在します。次のいずれかの値になります。

TaskReassigned
OwnerDowngraded
OwnerArchived

work.tasks.approvalStep

値は、true または false のいずれかです。

work.tasks.isApproved

タスクが承認ステップ (つまり approvalStep が true) であり、そのタスクが完了済み (つまり status 値が Completed) である場合は、isApproved が存在し、その値は true または false になります。

work.attachments

インスタンスまたはその開始元のアプリケーションに関連付けられた添付ファイルの配列。

work.attachments.name

添付ファイルの名前。

work.attachments.id

添付ファイルの ID。

work.attachments.uploadedBy

添付ファイルをアップロードしたユーザーの ID。この ID を持つオブジェクトがユーザー配列に表示されます。

work.attachments.uploadedOn

添付ファイルがアップロードされた日時。値は、エポック、すなわち協定世界時 (UTC) 1970 年 1 月 1 日真夜中からの経過時間 (ミリ秒) で表されます。

work.attachments.size

添付ファイルのサイズ (バイト単位)。

work.attachments.type

添付ファイルのタイプ (関連付けられた数値で示される)。

接続タイプ	説明
1	一般文書。ファイルが他のどの値にも該当しない場合に使用されます。
2	Microsoft Excel ファイル
3	画像
4	PDF 文書
5	Microsoft PowerPoint 文書
6	Microsoft Project 文書
7	Microsoft Visio 文書
8	Microsoft Word 文書

work.attachments.canDelete

ユーザーが添付ファイルの削除権限を持っているかどうかを示します。

work.attachments.deletedOn

添付ファイルが削除された日時。値は、エポック、すなわち協定世界時 (UTC) 1970 年 1 月 1 日真夜中からの経過時間 (ミリ秒) で表されます。このフィールドが存在するのは、管理ページを通じてアカウントからファイルが削除された場合のみです。この場合、FileDownload を使用してファイルをダウンロードすることはできません。

work.attachments.deletedBy

添付ファイルを削除したユーザーの名前。このフィールドが存在するのは、管理ページを通じてアカウントからファイルが削除された場合のみです。

work.comments

インスタンスに関するコメントの配列。

work.comments.from

コメントを作成したユーザーの ID。この ID を持つオブジェクトが、当該ユーザーの配列に表示されます。

work.comments.id

コメントの ID。

work.comments.commentDate

コメントが作成された日。

work.comments.text

コメントのテキスト。

work.comments.canDelete

ユーザーがコメントを削除できるかどうかを示します。

work.comments.replies

親コメントに対する返信のリスト。

app

インスタンスの開始元となったアプリケーションについての情報。

app.name

作業インスタンスの開始元となったアプリケーションの名前。

app.id

作業インスタンスの開始元となったアプリケーションの ID。

app.subjectTitle

ユーザーがインスタンスの件名を入力した編集域のタイトル。

app.detailsTitle

ユーザーがインスタンスの詳細を入力した編集域のタイトル。

app.type

以下の可能な値のいずれかを含むアプリケーションのタイプ。

workflow
checklist

users

JSON で他の場所から ID を参照されているユーザーの配列。

users.name

ユーザーのフルネーム。

users.id

ユーザーの ID。

users.avatarId

ユーザーが設定したアバターの ID。このプロパティーは、ユーザーがアバターを設定した場合にのみ存在します。

応答メッセージ

HTTP コード	理由
200	要求は正常に完了しました。
400	要求の処理中にエラーが発生しました。必須パラメーターが欠落していたか、無効な値が含まれていました。
401	ユーザーには、要求を行う権限がありません。
403	アクセスは禁止されています。このメッセージは、次のいずれかの理由で表示される場合があります。指定された資格情報が無効である。このユーザーにこの作業へのアクセス権限がない。 API が管理者によって有効にされていない。 API は「アカウント情報」タブで有効にする必要がある。管理者がサービスの利用条件に同意しなかった。