Tasks

A Workflow Task is a step to perform within a Case. Workflow Tasks can be manual (i.e., performed by a user) or automated (i.e., performed by a Workflow Playbook).

Endpoint: /api/v3/tasks

Available Fields

You can retrieve a list of available fields for the /v3/tasks endpoint, including the field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/tasks

Note

To view all fields, including read-only fields, include the ?show=readonly query parameter.

Create Workflow Tasks

The basic format for creating a Task is:

POST /v3/tasks/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "name": "Example Task for Workflow Case"
}

Additional fields can be included when creating a Task. Refer to the following table for a list of available fields for the tasks object:

Field Description Required Type Example Value(s)
artifacts A list of Artifacts associated with the Task FALSE String {“data”: [{“summary”: “badguy@bad.com”, “type”: “Email Address”]}}
assignee The user or group Assignee object for the Task FALSE String {“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}
caseId The ID of the Case that contains the Task TRUE Integer 1, 2, 3
caseXid The XID of the Case that contains the Task TRUE String “a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”
completedDate The completion date of the Task FALSE Date “2021-04-30T00:00:00Z”
dependentOnId The ID of another Task that this Task is dependent upon FALSE Integer 1, 2, 3
description The description of the Task FALSE String “Example task description.”
dueDate The due date of the Task FALSE Date “2021-04-30T00:00:00Z”
name The name of the Task TRUE String “Example Task”
notes A list of Notes corresponding to the Task FALSE String {“data”: [{“text”: “Note about task”}]}
required Flag indicating whether or not the Task is required FALSE Boolean true, false
status The status of the Task FALSE String “Pending”, “Open”, “Reopened”, or “Closed”
workflowPhase The Workflow phase where the Task takes place FALSE Integer 1, 2, 3
workflowStep The step of the Workflow where the Task takes place FALSE Integer 1, 2, 3

For example, the following query will create a new Task for the Case with ID 1. This Task’s name will be “Create Shared Drive Folder for Case” and it will be the second step of the first Workflow phase:

POST /v3/tasks/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "name": "Create Meeting Notes Folder",
  "description": "If Case listed a Severity of High or Critical, create a Meeting Notes folder inside the Case folder.",
  "workflowPhase": 1,
  "workflowStep": 2
}

JSON Response:

{
  "data": {
      "id": 2,
      "xid": "b2b2b2b2-b2b2-b2b2-b2b2-b2b2b2b2b2b2",
      "name": "Create Meeting Notes Folder",
      "description": "If Case lists a Severity of High or Critical, create a Meeting Notes folder inside the Case folder.",
      "workflowPhase": 1,
      "workflowStep": 2,
      "required": false,
      "status": "Open",
      "notes": {
          "count": 0
      }
  },
  "message": "Created",
  "status": "Success"
}

Retrieve Workflow Tasks

Retrieve All Tasks

To retrieve all Tasks, use the following query:

GET /v3/tasks/

JSON Response:

{
  "data": [{
    "id": 1,
    "name": "Create Shared Drive Folder for Case",
    "workflowPhase": 1,
    "workflowStep": 1,
    "required": false,
    "status": "Open"
  }, {
    "id": 2,
    "name": "Create Meeting Notes Folder",
    "description": "If Case listed a Severity of High or Critical, create a Meeting Notes folder inside the Case folder.",
    "workflowPhase": 1,
    "workflowStep": 2,
    "required": true,
    "status": "Open"
  }],
  "count": 2,
  "status": "Success"
}

Retrieve a Single Task

To retrieve a specific Task, use a query in the following format:

GET /v3/tasks/{taskId}

For example, the following query will return information about the Task with ID 1:

GET /v3/tasks/1

JSON Response:

{
  "data": [{
    "id": 1,
    "name": "Create Shared Drive Folder for Case",
    "workflowPhase": 1,
    "workflowStep": 1,
    "required": false,
    "status": "Open"
  }],
  "status": "Success"
}

Request Additional Fields

To request additional fields not automatically provided with each returned object, refer to Request Additional Fields for Returned Objects.

Filter Results

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Workflow Tasks

The basic format for updating a Task is:

PUT /v3/tasks/{taskId}
{
    {updatedField}: {updatedValue}
}

Refer to the following table for a list of available fields that can be updated for the tasks object:

Field Description Type Example Value(s)
artifacts A list of Artifacts associated with the Task String {“data”: [{“summary”: “badguy@bad.com”, “type”: “Email Address”]}}
assignee The user or group Assignee object for the Task String {“type”: “User”, “data”: {“userName”: “jonsmith@threatconnect.com”}}
description The description of the Task String “New task description”
dueDate The due date of the Task Date “2021-04-30T00:00:00Z”
name The name of the Task String “New Workflow Task Name”
notes A list of Notes corresponding to the Task String {“data”: [{“text”: “Note about task”}]}
required Flag indicating whether or not the Task is required Boolean true, false
status The status of the Task String “Pending”, “Open”, “Reopened”, or “Closed”

For example, the following query will make the Task with ID 1 required to complete and assign it a due date of April 30, 2021:

PUT /v3/tasks/1
{
  "dueDate": "2021-04-30",
  "required": true
}

JSON Response:

{
  "data": {
      "id": 1,
      "xid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
      "name": "Create Shared Drive Folder for Case",
      "description": "If Case listed a Severity of High or Critical, create a Meeting Notes folder inside the Case folder.",
      "workflowPhase": 1,
      "workflowStep": 1,
      "dueDate": "2021-04-30T00:00:00Z",
      "required": true,
      "status": "Open",
      "notes": {
          "count": 0
      }
  },
  "message": "Updated",
  "status": "Success"
}

Delete Workflow Tasks

The basic format to delete a Task is:

DELETE /v3/tasks/{taskId}

For example, the following query will delete the Task with ID 1:

DELETE /v3/tasks/1

JSON Response:

{
  "message": "Deleted",
  "status": "Success"
}

Delete Tasks in Bulk

To delete Tasks in bulk, refer to Delete Case Objects in Bulk.