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 each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/tasks

Hint

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

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for the tasks object.

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

Note

*When creating a Task, either caseId or caseXid must be included in the body of the POST request. Only one needs to be included in the body of the POST request, but both can be included, if desired.

Create Workflow Tasks¶

The basic format for creating a Task is:

POST /v3/tasks
{
    "caseId": 1,
    "name": "Example Task for Workflow Case"
}

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,
    "name": "Create Meeting Notes Folder",
    "description": "If the Case listed a Severity of High or Critical, create a Meeting Notes folder inside the Case folder.",
    "dueDate": "2022-03-29T12:15:00Z",
    "workflowPhase": 1,
    "workflowStep": 2
}

JSON Response:

{
    "data": {
        "id": 3,
        "xid": "559797fc-bb36-45a7-9d4d-c7c865944548",
        "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,
        "dueDate": "2022-03-29T12:15:00Z",
        "required": false,
        "status": "Open",
        "notes": {},
        "owner": "Example Organization"
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields and section for a list of available fields that can be included in the body of a POST request for the tasks object.

Retrieve Workflow Tasks¶

Retrieve All Tasks¶

To retrieve all Tasks, use the following query:

GET /v3/tasks

JSON Response:

{
    "data": [
        {
            "id": 1,
            "xid": "bf710c31-7641-4100-9edf-461c1f6bb354",
            "name": "Read ThreatConnect's Building a Basic Workflow Blog",
            "workflowPhase": 0,
            "workflowStep": 1,
            "dueDate": "2022-03-20T23:59:59Z",
            "required": false,
            "status": "Open",
            "assignee": {
                "type": "User",
                "data": {
                    "id": 2,
                    "userName": "[email protected]",
                    "firstName": "Patrick",
                    "lastName": "Jones",
                    "pseudonym": "patjones",
                    "role": "User"
                }
            },
            "owner": "Example Organization"
        },
        {
            "id": 2,
            "xid": "93e9aced-7419-4121-bef1-5276737936ab",
            "name": "Gather the subject line and email body",
            "workflowPhase": 0,
            "workflowStep": 2,
            "required": true,
            "dependentOnId": 8,
            "status": "Pending",
            "assignee": {
                "type": "Group",
                "data": {
                    "id": 1,
                    "name": "SOC Team",
                    "description": "SOC Team user group"
                }
            },
            "owner": "Example Organization"
        },
        {...}
    ],
    "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,
            "xid": "bf710c31-7641-4100-9edf-461c1f6bb354",
            "name": "Read ThreatConnect's Building a Basic Workflow Blog",
            "workflowPhase": 0,
            "workflowStep": 1,
            "dueDate": "2022-03-20T23:59:59Z",
            "required": false,
            "status": "Open",
            "assignee": {
                "type": "User",
                "data": {
                    "id": 2,
                    "userName": "[email protected]",
                    "firstName": "Patrick",
                    "lastName": "Jones",
                    "pseudonym": "patjones",
                    "role": "User"
                }
            },
            "owner": "Example Organization"
        }
    ],
    "Status": "Success"
}

Request Additional Fields¶

To request additional fields not automatically included 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}
}

For example, the following query will make the following changes to the Task with ID 1:

The Task will be due at 10:30 a.m. on April 5, 2022;
The Task will be required to complete.

PUT /v3/tasks/1
{
    "dueDate": "2022-04-05T10:30:00Z",
    "required": true
}

JSON Response:

{
    "data": {
        "id": 1,
        "xid": "bf710c31-7641-4100-9edf-461c1f6bb354",
        "name": "Read ThreatConnect's Building a Basic Workflow Blog",
        "workflowPhase": 0,
        "workflowStep": 1,
        "dueDate": "2022-04-05T10:30:00Z",
        "required": false,
        "status": "Open",
        "assignee": {
            "type": "User",
            "data": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Patrick",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "role": "User"
            }
        },
        "notes": {},
        "owner": "Example Organization"
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields and section for a list of available fields that can be included in the body of a PUT request for the tasks object.

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.