WorkAction

Method summary

POST /scr/api/WorkAction

Description

Use this method to perform an action on a work item.

Important: First, run WorkDetail to retrieve information about the work item you want to take action on. Use the output of that API to fill in the parameters for WorkAction.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes
Supports OAuth 2 client credentials	Yes using a User Service ID containing Work Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
X-On-Behalf-Of	Header	The user context. The value must be a username in the account. The user must have permission to perform the action in the account and in the specified parent space, if any.	Required if Service ID OAuth credentials are used. Not required when using User Service ID OAuth credential.	String
action	Query	The information for the action to perform. The format for this parameter is shown in the example. Depending on the requested action type, some of the fields are required.	Yes	See Action parameters below
version	Query	The version of the requested API. The only allowed value is 20110917.	Yes	String

Action parameters

Name	Description	Data type
action.subject	The subject for a new work instance.	String
action.runtimeVersion	The array of values provided by WorkDetail.	String
action.workId	The ID of the work item to perform the action on. Use the same ID as you used to call WorkDetails.	String
action.appId	The ID of the application this work relates to. This ID is provided by running WorkDetails.	String
action.timeZoneId	The timezone to start the instance in. If the timezone isn't provided, then the value from the user's current preferences is used. If user's timezone preference is also not set, then the server default is used.	String
action.type	The type of action to perform. This parameter determines what extra fields are required. The following action types are available: COMPLETE Complete the current task. APPROVE Approve current task. Only valid if the task is an approval step. Requires the action.task.id parameter. REJECT Reject current task. Only valid if the task is an approval step. Requires the action.task.id parameter. ADD_TASK Complete current task and add a new one. Requires the action.task.id, action.task.assignedTo, action.task.name, action.task.approvalStep (optional), and action.task.dueDateExpression (optional) parameters. REASSIGN Reassign task. Requires the action.task.id and action.task.assignedTo parameters. CHANGE_SUBJECT Change work subject. Requires the action.subject parameter. CANCEL_INSTANCE Cancel work item. REMOVE_ATTACHMENT Remove attachment from the instance. Requires the action.attachmentId parameter.	String
action.subject	Required by the CHANGE_SUBJECT action. New subject for the work item.	String
action.attachmentId	Required by the REMOVE_ATTACHMENT action. The ID of the attachment to remove from the instance.	String
action.task.id	Required by the ADD_TASK, REASSIGN, APPROVE, COMPLETE, and REJECT actions. The ID of the task that the action is performed on. If an ADD_TASK action is performed, then this task ID is completed and a new one is created.	String
action.task.assignedTo	Required by the REASSIGN and ADD_TASK actions. The ID of the user to whom this task is assigned.	String
action.task.name	Required by the ADD_TASK action. The name of the task.	String
action.task.approvalStep	Optional for the ADD_TASK action, and only needed for work items of workflow type. Indicates whether the task is an approval step. It is assumed to have a value of false if the parameter is not found.	Boolean
action.task.dueDateExpression	Optional for the ADD_TASK action. Indicates the due date for this task, which must be in the YYYY/MM/DD format.	String

Response

Example input

• Using User Service ID OAuth 2 client credentials with user context:

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

• Using Service ID OAuth 2 client credentials with user context:

  curl -i -H "Authorization: Bearer access_token" -H "X-On-Behalf-Of:user_name@domain.com" -H "Content-Type:application/json" 
      -X POST "https://your_server_url/scr/api/WorkAction?version=20110917&action={\"action\":{\"runtimeVersion\":[\"34c2522c-fda6-40f3-abe8-d98cf8e46e65\",\"a0713\",1],\"workId\":\"a0713\",\"appId\":\"80038\",\"type\":\"CANCEL_INSTANCE\",\"timeZoneId\":\"America/Los_Angeles\"}}"

Action parameter examples

{
   "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."
 }
}

Example output

*same as WorkDetail*

{  
   "work":{  
      "runtimeVersion":[  
         "ede1c9df-61be-4774-99ab-196ec6742d57",
         "5f501e134c6bf",
         2
      ],
      "details":"my sample details",
      "canManageWork":true,
      "name":"ProcessApp 1 approval task - New for test.",
      "subject":"New for test.",
      "tasks":[  
         {  
            "isApproved":false,
            "status":"Completed",
            "assignedTo":"7f0002",
            "name":"toBeApproved\/Rejected",
            "id":"5f501e134c6ce",
            "approvalStep":true
         },
         {  
            "status":"NotStarted",
            "dueDate":2554358399278,
            "assignedTo":"7f0002",
            "name":"New task.",
            "id":"5f501e134c6e2",
            "approvalStep":false
         }
      ],
      "attachments":[  
         {  
            "size":3.0,
            "uploadedBy":"7f0002",
            "type":9,
            "name":"foo.txt",
            "id":"5f500e1349358",
            "canDelete":true,
            "uploadedOn":1441206442048
         }
      ],
      "status":"Active",
      "comments":[  

      ],
      "startedAt":1441219222958,
      "startedBy":"7f0002",
      "id":"5f501e134c6bf",
      "appId":"5f500e1349338"
   },
   "app":{  
      "detailsTitle":null,
      "type":"workflow",
      "name":"ProcessApp 1 approval task",
      "id":"5f500e1349338",
      "subjectTitle":null
   },
   "version":"20110917",
   "users":[  
      {  
         "avatarId":"5f500e1260203",
         "name":"admin",
         "id":"7f0002"
      }
   ]
}

Response properties

version

The version of the API used to create the response.

work

The work object.

work.runtimeVersion

The array that identifies the version of the work instance. Treat this value as an opaque data item. The work.runtimeVersion is required for the WorkAction.

work.name

The name to display for the work instance.

work.id

The ID of the work instance.

work.subject

The subject entered by the user who created the instance.

work.details

The details entered by the user who created the instance.

work.status

The status of work includes one of the following values:

• Active
• Completed
• Cancelled
• Overdue

work.startedBy

The ID of the user who created the instance. An object with this ID appears in the user's array.

work.startedAt

The date and time when the instance was started. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC).

work.completedBy

The ID of the user who completed or canceled the instance. Only present if the status is Completed or Cancelled. An object with this ID appears in the user's array.

work.completedAt

The date and time when the instance was completed or canceled. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC). Only present if the status is Completed or Cancelled.

work.appId

The ID of application from which the instance was started. This application appears in the application object.

work.canManageWork

Indicates whether the user has permissions to cancel work, change subject, or reassign tasks.

work.tasks

The array of tasks associated with the instance.

work.tasks.name

The name of the task.

work.tasks.id

The ID of the task.

work.tasks.assignedTo

The ID of user to whom the task is assigned. An object with this ID appears in the user's array.

work.tasks.actioner

The ID of the user who is not the task owner and who created the last change in the task status. An object with this ID appears in the user's array. When a task is reassigned, the work.tasks.actioner refers to the ID of the user who did the reassigning, while the assignedTo user is the user to whom the task was originally assigned.

work.tasks.dueDate

The date when the task is due. This property is present only if a dueDate is set for the task.

work.tasks.status

Contains one of the following possible values:

• Pending
• NotStarted
• InProgress
• Completed
• Reassigned

work.tasks.reassignmentReason

This property is present only if the status is Reassigned. Contains one of the following possible values:

• TaskReassigned
• OwnerDowngraded
• OwnerArchived

work.tasks.approvalStep

The value is either true or false.

work.tasks.isApproved

If the task is an approval step, that is approvalStep is true, and the task is completed, that is the status value is Completed, then isApproved is present, and the value is true or false.

work.attachments

The array of attachments associated with the instance or the application it was started from.

work.attachments.name

The name of the attachment.

work.attachments.id

The ID of the attachment.

work.attachments.uploadedBy

The ID of the user who uploaded the attachment. An object with this ID appears in the users array.

work.attachments.uploadedOn

The date and time when the attachment was uploaded. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC).

work.attachments.size

The size of the attachment in bytes.

work.attachments.type

The type of attachment file with the associated numeric value.

Attachment type	Description
1	Generic document. Used if the file doesn't fall under one of the other values.
2	Microsoft Excel file
3	Image
4	PDF document
5	Microsoft PowerPoint document
6	Microsoft Project document
7	Microsoft Visio document
8	Microsoft Word document

work.attachments.canDelete

Indicates whether the user has permissions to delete the attachment.

work.attachments.deletedOn

The date and time when the attachment was deleted. The value is expressed in milliseconds since epoch, that is 1 January 1970 at midnight Coordinated Universal Time (UTC). This field is present only if the file was deleted from the account through the admin pages. In this case, you can't download the file using FileDownload.

work.attachments.deletedBy

The name of the user who deleted the attachment. This field is present only if the file was deleted from the account through the admin pages.

work.comments

The array of comments on the instance.

work.comments.from

The ID of the user who created the comment. An object with this ID appears in the user's array.

work.comments.id

The ID of the comment.

work.comments.commentDate

The date when the comment was created.

work.comments.text

The text of the comment.

work.comments.canDelete

Indicates whether the user can delete the comment.

work.comments.replies

The list of replies to the parent comment.

app

The information about the application that the instance was started from.

app.name

The name of the application that the work instance was started from.

app.id

The ID of the application from that the work instance was started from.

app.subjectTitle

The title for edit area where the user entered a subject for the instance.

app.detailsTitle

The title for edit area where the user entered details for the instance.

app.type

The type of the application that contains one of the following possible values:

• workflow
• checklist

users

The array of users whose IDs are referenced from other locations in the JSON.

users.name

The full name of the user.

users.id

The ID of the user.

users.avatarId

The ID of the avatar the user set. This property is present only if the user set an avatar.

Response messages

HTTP code	Reason
200	The request was completed successfully.
400	There was an error processing the request. Required parameters were missing or contained invalid values.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user doesn't have access to this work. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.