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.