PrototypeTasks

Endpoints to manage tasks

PrototypeTask

Details about the task, including its title, description, type, deadlines, participants, and additional metadata. Please note that the Task object has been updated to accommodate the new task approval process which results in breaking changes to the Tasking endpoints. Some fields like assignee and approvers have been removed, and new fields like approvalSteps have been added. The status field can now only be updated for tasks with a single approval step. For a task with multiple approval steps, the status field will be updated automatically when actions are taken on the task. See the endpoint Submit Task Action for more details.

Properties

Name	Type	Description	Restrictions
approvalSteps	[PrototypeTaskApprovalStep]	The approval process for the task where applicable.
assignees	[TaskUser]	A list of assignees for the task.
created	Action	When the action was performed, and details about the user who did it	read-only
description	string	The task description.
dueDate	string(date-time)¦null	An ISO 8601 datetime indicating a deadline for the task to be completed. Will be converted to UTC if another time zone is included.
id	string	The unique identifier of the task.	read-only
location	PrototypeTaskLocation¦null	Details about what the task is attached to, such as a file ID. If null, the task isn’t attached to anything. Once a location is attached to a task, that location cannot be changed.
modified	Action	When the action was performed, and details about the user who did it	read-only
notificationsDisabled	boolean	Suspend notifications during create/updates. Automated and manual reminders will still be sent. The default value is false.
owner	string	The unique identifier of the user who owns the task.	read-only
sourceUrl	string	The URL of a WDesk resource that is associated with a task.	read-only
status	string	> The status for the task. The default value is Created. The status of the task will be updated automatically as it > progresses through the multiple steps of the approval process.
title	string	The title of the task.	required

Example

{
  "approvalSteps": [
    {
      "completionMode": "ONE",
      "dueDate": "2023-06-11T13:00:00+00:00",
      "participants": [
        {
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "type": "USER"
        }
      ],
      "responses": [
        {
          "action": "REJECT",
          "comment": "please refine",
          "created": {
            "dateTime": "2019-10-30T15:03:27Z",
            "user": {
              "displayName": "John Doe",
              "email": "string",
              "firstName": "John",
              "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
              "lastName": "Doe",
              "userName": "string"
            }
          }
        }
      ]
    }
  ],
  "assignees": [
    {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
      "type": "USER"
    }
  ],
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "description": "Be sure to double-check the balance sheet",
  "dueDate": null,
  "id": "VGFzax41MWNmOGZjMDQxMzc1MmRlYWZjMTA2ZjgyMzJiNDllZg",
  "location": {
    "resource": "124efa2a142f472ba1ceab34ed18915f",
    "segment": "465ttdh2a142y75ehsft5ab34edf5675"
  },
  "modified": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "notificationsDisabled": true,
  "owner": "V0ZVc2VyHzU3MjI2NDY2Mzc0NDUxMjA",
  "sourceUrl": "string",
  "status": "Completed",
  "title": "Please complete the quarterly report"
}

PrototypeTaskAction

An action to be taken on a task approval step.

Properties

Name	Type	Description	Restrictions
action	string		required
comment	string¦null	An optional comment to accompany the action.

Enumerated Values

Property	Value
action	SUBMIT
action	APPROVE
action	REJECT
action	CANCEL
action	RESTART
action	SKIP

Example

{
  "action": "APPROVE",
  "comment": "please refine"
}

PrototypeTaskApprovalResponse

A response to an approval step, including the user, action taken, timestamp, and optional comment.

Properties

Name	Type	Description	Restrictions
action	string		required
comment	string¦null	An optional comment left by the user.
created	Action	When the action was performed, and details about the user who did it	read-only, required

Enumerated Values

Property	Value
action	SKIP
action	APPROVE
action	REJECT

Example

{
  "action": "REJECT",
  "comment": "please refine",
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  }
}

PrototypeTaskApprovalStep

An approval step in the approval process for a task. Each step defines how completion is determined and who participates.

Properties

Name	Type	Description	Restrictions
completionMode	string		required
dueDate	string(date-time)¦null	An ISO 8601 datetime indicating a deadline for this approval step, or null if not set.
participants	[TaskUser]	The participants in this approval step.	required
responses	[PrototypeTaskApprovalResponse]	All APPROVE, REJECT, and SKIP actions for the current approval process are tracked in the response for each step. This surfaces any comments left, and allows for tracking the progress of the approval process. When a REJECT action is left, responses will remain on the task until the task is re-submitted for approval.	read-only

Enumerated Values

Property	Value
completionMode	ONE
completionMode	ALL

Example

{
  "completionMode": "ONE",
  "dueDate": "2023-06-11T13:00:00+00:00",
  "participants": [
    {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
      "type": "USER"
    }
  ],
  "responses": [
    {
      "action": "REJECT",
      "comment": "please refine",
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      }
    }
  ]
}

PrototypeTaskLocation

Details about what the task is attached to, such as a file ID. If null, the task isn’t attached to anything. Once a location is attached to a task, that location cannot be changed.

Properties

Name	Type	Description	Restrictions
resource	string	The unique identifier of the resource. This is the ID of the Document, Spreadsheet, Presentation or Sustainability resource.
segment	string¦null	The unique identifier of the segment. A segment is a Section in a Document, a Sheet in a Spreadsheet, or a Slide in a Presentation.

Example

{
  "resource": "124efa2a142f472ba1ceab34ed18915f",
  "segment": "465ttdh2a142y75ehsft5ab34edf5675"
}

PrototypeTasksListResult

Returns a JSON object with data and @nextLink properties. data contains a list of PrototypeTask objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[PrototypeTask]	Details about the task, including its title, description, type, deadlines, participants, and additional metadata. Please note that the Task object has been updated to accommodate the new task approval process which results in breaking changes to the Tasking endpoints. Some fields like assignee and approvers have been removed, and new fields like approvalSteps have been added. The status field can now only be updated for tasks with a single approval step. For a task with multiple approval steps, the status field will be updated automatically when actions are taken on the task. See the endpoint Submit Task Action for more details.

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "approvalSteps": [
        {
          "completionMode": "ONE",
          "dueDate": "2023-06-11T13:00:00+00:00",
          "participants": [
            {
              "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
              "type": "USER"
            }
          ],
          "responses": [
            {
              "action": "REJECT",
              "comment": "please refine",
              "created": {
                "dateTime": "2019-10-30T15:03:27Z",
                "user": {
                  "displayName": "John Doe",
                  "email": "string",
                  "firstName": "John",
                  "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
                  "lastName": "Doe",
                  "userName": "string"
                }
              }
            }
          ]
        }
      ],
      "assignees": [
        {
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "type": "USER"
        }
      ],
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      },
      "description": "Be sure to double-check the balance sheet",
      "dueDate": null,
      "id": "VGFzax41MWNmOGZjMDQxMzc1MmRlYWZjMTA2ZjgyMzJiNDllZg",
      "location": {
        "resource": "124efa2a142f472ba1ceab34ed18915f",
        "segment": "465ttdh2a142y75ehsft5ab34edf5675"
      },
      "modified": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      },
      "notificationsDisabled": true,
      "owner": "V0ZVc2VyHzU3MjI2NDY2Mzc0NDUxMjA",
      "sourceUrl": "string",
      "status": "Completed",
      "title": "Please complete the quarterly report"
    }
  ]
}

Task

Details about the task, including its ID, status, associated users, and milestone dates.

Properties

Name	Type	Description	Restrictions
assignee	PlatformUser	The user’s ID
completed	Action	When the action was performed, and details about the user who did it	read-only
created	Action	When the action was performed, and details about the user who did it	read-only
description	string	The description of the task, up to 2000 characters	Maximum length: 2000
dueDate	string(date-time)	The task’s due date
id	string	The unique identifier of the task	read-only
location	TaskLocation¦null	Details about what the task is attached to, such as a file ID. If null, the task isn’t attached to anything. Once a location is attached to a task, that location cannot be changed.
modified	Action	When the action was performed, and details about the user who did it	read-only
sourceUrl	string	The link to the task in Wdesk Home or within a document.	read-only
status	string	Whether the task is Created, Completed, or Cancelled	Maximum length: 100
title	string	The title of the task, up to 500 characters	Maximum length: 500

Enumerated Values

Property	Value
status	Approved
status	Awaiting Approval
status	Cancelled
status	Completed
status	Created
status	Returned
status	Reworking
status	Staged
status	Started

Example

{
  "assignee": {
    "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
  },
  "completed": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "created": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "description": "Review document for spelling and grammar",
  "dueDate": "2019-10-30T00:00:00Z",
  "id": "128f274395254cf17eda6b3eb3d021b9",
  "location": {
    "file": "124efa2a142f472ba1ceab34ed18915f",
    "fileSegment": "465ttdh2a142y75ehsft5ab34edf5675"
  },
  "modified": {
    "dateTime": "2019-10-30T15:03:27Z",
    "user": {
      "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
    }
  },
  "sourceUrl": "https://app.wdesk.com/tasks/d/UVdOauIzVaVkQjdxTmzNNUOEUTQOakEnTnpJTE9ENXkuEkdGeaF4OENNJEV3NUTBmA?token=NTc0NDU2MTg1MjM0ODUyTM",
  "status": "Completed",
  "title": "Review Document"
}

TaskLocation

Details about what the task is attached to, such as a file ID. If null, the task isn’t attached to anything. Once a location is attached to a task, that location cannot be changed.

Properties

Name	Type	Description	Restrictions
file	string	The unique identifier of the file
fileSegment	string	The unique identifier of the fileSegment. A fileSegment is a section in a document, a sheet in a spreadsheet, or a slide in a presentation.

Example

{
  "file": "124efa2a142f472ba1ceab34ed18915f",
  "fileSegment": "465ttdh2a142y75ehsft5ab34edf5675"
}

TasksListResult

Returns a JSON object with data and @nextLink properties. data contains a list of Task objects, and @nextLink provides the URL to the next set of results. If there are no additional results, @nextLink doesn’t appear. If the request returns no results at all, data contains an empty array.

Properties

Name	Type	Description	Restrictions
@nextLink	string	Pagination link for next set of results
data	[Task]	Details about the task, including its ID, status, associated users, and milestone dates.

Example

{
  "@nextLink": "<opaque_url>",
  "data": [
    {
      "assignee": {
        "displayName": "John Doe",
        "email": "string",
        "firstName": "John",
        "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
        "lastName": "Doe",
        "userName": "string"
      },
      "completed": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      },
      "created": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      },
      "description": "Review document for spelling and grammar",
      "dueDate": "2019-10-30T00:00:00Z",
      "id": "128f274395254cf17eda6b3eb3d021b9",
      "location": {
        "file": "124efa2a142f472ba1ceab34ed18915f",
        "fileSegment": "465ttdh2a142y75ehsft5ab34edf5675"
      },
      "modified": {
        "dateTime": "2019-10-30T15:03:27Z",
        "user": {
          "displayName": "John Doe",
          "email": "string",
          "firstName": "John",
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
          "lastName": "Doe",
          "userName": "string"
        }
      },
      "sourceUrl": "https://app.wdesk.com/tasks/d/UVdOauIzVaVkQjdxTmzNNUOEUTQOakEnTnpJTE9ENXkuEkdGeaF4OENNJEV3NUTBmA?token=NTc0NDU2MTg1MjM0ODUyTM",
      "status": "Completed",
      "title": "Review Document"
    }
  ]
}

TaskUser

Details about the user, including ID, and type

Properties

Name	Type	Description	Restrictions
id	string	The unique identifier of the user
type	string	Type of the user

Enumerated Values

Property	Value
type	USER

Example

{
  "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD",
  "type": "USER"
}