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

Endpoint Options¶

Available Fields¶

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/tasks endpoint:

OPTIONS /v3/tasks

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

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 to the /v3/tasks endpoint.

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 [1]	FALSE	1, 2, 3
caseXid	The XID of the Case that contains the Task	String	TRUE [1]	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

[1]	(1, 2) When adding a Task to a Case, you must include either the `caseId` or `caseXid` field 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.

Include Additional Fields in Responses¶

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/tasks endpoint:

OPTIONS /v3/tasks/fields

Filter Results¶

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/tasks endpoint:

OPTIONS /v3/tasks/tql

Create Workflow Tasks¶

The following example illustrates the basic format for creating a Task:

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

For example, the following request will add a Task named “Create Meeting Notes Folder” to the Case whose ID is 1. It will also complete the following actions for the Task:

Make the Task the third step of the first Workflow Phase for the Case
Make the Task a due at 12:15 p.m. on March 29, 2022

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

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": 3,
        "dueDate": "2022-03-29T12:15:00Z",
        "required": false,
        "status": "Open",
        "owner": "Demo 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 to the /v3/tasks endpoint.

Retrieve Workflow Tasks¶

Retrieve All Tasks¶

Send the following request to retrieve data for all Tasks:

GET /v3/tasks

JSON Response:

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

Retrieve a Specific Task¶

Send a request in the following format to retrieve data for a specific Task:

GET /v3/tasks/{taskId}

For example, the following request will retrieve data for the Task whose ID is 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": 1,
            "workflowStep": 1,
            "dueDate": "2022-03-20T23:59:59Z",
            "required": false,
            "status": "Open",
            "assignee": {
                "type": "User",
                "data": {
                    "id": 2,
                    "userName": "[email protected]"
                }
            },
            "owner": "Demo Organization"
        }
    ],
    "Status": "Success"
}

Update Workflow Tasks¶

The following example illustrates the basic format for updating a Task:

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

For example, the following request will make the Task whose ID is 3 required for completion and due at 10:30 a.m. on April 5, 2022:

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

JSON Response:

{
    "data": {
        "id": 3,
        "xid": "559797fc-bb36-45a7-9d4d-c7c865944548",
        "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.",
        "workflowPhase": 1,
        "workflowStep": 3,
        "dueDate": "2022-04-05T10:30:00Z",
        "required": true,
        "status": "Open",
        "owner": "Demo 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 PUT request to the /v3/tasks endpoint.

Delete Workflow Tasks¶

Send a request in the following format to delete a Task:

DELETE /v3/tasks/{taskId}

For example, the following request will delete the Task whose ID is 1:

DELETE /v3/tasks/1

JSON Response:

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

Delete Tasks in Bulk¶

For instructions on deleting Tasks in bulk, refer to Delete Case Objects in Bulk.