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

Create Workflow Tasks

The most 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 Integer “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”
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 Task, refer to the Request Additional Fields for Returned Objects section in this documentation.

Filter Results

To filter returned Tasks using ThreatConnect Query Language (TQL), refer to the Filter Results with TQL section in this documentation.

Update Workflow Tasks

To update a Task, the basic format 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”
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

To delete a Task, use the following query:

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 the Delete Case Objects in Bulk section in this documentation.