Tasks

Tasks enable users to manage projects, organize responsibilities, and meet deadlines in the Workiva platform. Use these endpoints to create and manage tasks.

Task

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	[TaskApprovalStep]	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	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
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": {
              "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
            }
          }
        }
      ]
    }
  ],
  "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"
}

TaskAction

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

TaskApprovalResponse

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

TaskApprovalStep

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	[TaskApprovalResponse]	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": {
          "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
        }
      }
    }
  ]
}

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

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 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": {
                  "id": "V1ZVd2VyFzU3NiQ1NDA4NjIzNzk2MjD"
                }
              }
            }
          ]
        }
      ],
      "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"
    }
  ]
}

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