Workflow Templates¶

Workflow Templates are codified procedures for the steps to be taken within a Case. ThreatConnect provides a set of Workflow Templates via TC Exchange™, or users and administrators with the requisite permissions can create Workflow Templates from scratch.

Endpoint: /api/v3/workflowTemplates

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/workflowTemplates endpoint: .. code:

OPTIONS /v3/workflowTemplates

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/workflowTemplates endpoint.

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
configAttribute	A list of Attribute Types to include in the Workflow Template [1]	Config Attribute Object	FALSE	TRUE	[{“attributeTypeId”: 271}]
description	The description of the Workflow Template	String	FALSE	TRUE	“Workflow for phishing investigations.”
name	The name of the Workflow Template	String	True	TRUE	“Phishing Investigation Workflow”
version	The version of the Workflow Template	Integer	FALSE	TRUE	1, 2, 3

[1]	To retrieve a list of available Attribute Types that apply to Cases, send the following request: `GET /v3/attributeTypes?tql=associatedType EQ "Case"`. Note that you will need to encode the request URL before sending the request.

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/workflowTemplates endpoint:

OPTIONS /v3/workflowTemplates/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/workflowTemplates endpoint:

OPTIONS /v3/workflowTemplates/tql

Create Workflow Templates¶

The following example illustrates the basic format for creating a Workflow Template:

POST /v3/workflowTemplates
{
    "name": "Example Workflow Template"
}

For example, the following request will create a Workflow Template named Phishing Investigation Workflow and add a description to it:

POST /v3/workflowTemplates
{
    "name": "Phishing Investigation Workflow",
    "description": "Workflow for phishing investigations."
}

JSON Response:

{
    "data": {
        "id": 3,
        "name": "Phishing Investigation Workflow",
        "description": "Workflow for phishing investigations.",
        "active": false,
        "version": 1
    },
    "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/workflowTemplates endpoint.

Retrieve Workflow Templates¶

Retrieve All Workflow Templates¶

Send the following request to retrieve data for all Workflow Templates:

GET /v3/workflowTemplates

JSON Response:

{
    "data": [
        {
            "id": 1,
            "name": "Example Workflow",
            "description": "This is an example Workflow.",
            "active": false,
            "version": 1,
            "configAttribute": [
                {
                    "attributeTypeId": 271
                }
            ]
        },
        {
            "id": 2,
            "name": "Email Analysis",
            "description": "Workflow for analyzing suspicious emails.",
            "configTask": [
                {
                    "configPlaybook": null,
                    "fields": [],
                    "name": "Create a Meeting Notes folder",
                    "required": true,
                    "workflowId": 2,
                    "workflowPhase": 1,
                    "workflowStep": 1,
                    "assignee": {
                        "displayName": "Pat Jones",
                        "id": 2,
                        "name": "[email protected]",
                        "type": "User",
                        "ownerId": 7,
                        "superUser": false,
                        "firstName": "Pat",
                        "lastName": "Jones"
                    },
                    "durationType": "Hours",
                    "duration": 2
                },
                {
                    "configPlaybook": null,
                    "fields": [
                        {
                            "artifactType": "Email Address",
                            "dataType": "String",
                            "intelType": "indicator-EmailAddress",
                            "name": "emailAddress",
                            "required": true,
                            "uiElement": "String",
                            "uiLabel": "Email Address"
                        },
                        {
                            "artifactType": "Email Subject",
                            "dataType": "String",
                            "intelType": "indicator-Email Subject",
                            "name": "emailSubject",
                            "required": true,
                            "uiElement": "String",
                            "uiLabel": "Email Subject"
                        }
                    ],
                    "name": "Analyze Email",
                    "description": "Perform analysis of suspicious email.",
                    "required": true,
                    "workflowId": 2,
                    "workflowPhase": 2,
                    "workflowStep": 2,
                    "workflowStep": 1,
                    "assignee": {
                        "displayName": "SOC Team",
                        "id": 1,
                        "name": "SOC Team",
                        "type": "Group",
                        "ownerId": 7,
                        "superUser": false
                    },
                    "dependentOnTaskName": "Confirm Receipt of Email",
                    "durationType": "Days",
                    "duration": 3
                },
                {
                    "configPlaybook": null,
                    "fields": [],
                    "name": "Confirm Receipt of Email",
                    "required": false,
                    "workflowId": 2,
                    "workflowPhase": 2,
                    "workflowStep": 1,
                    "assignee": null
                }
            ],
            "active": true,
            "version": 1
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Specific Workflow Template¶

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

GET /v3/workflowTemplates/{workflowTemplateId}

For example, the following request will retrieve data for the Workflow Template whose ID is 3:

GET /v3/workflowTemplates/3

JSON Response:

{
    "data": {
        "id": 3,
        "name": "Phishing Investigation Workflow",
        "description": "Workflow for phishing investigations.",
        "active": false,
        "version": 1
    },
    "status": "Success"
}

Update Workflow Templates¶

The following example illustrates the basic format for updating a Workflow Template:

PUT /v3/workflowTemplates/{workflowTemplateId}
{
    {updatedField}: {updatedValue}
}

For example, the following request will update the version number of the Workflow Template whose ID is 3 and add two Attribute Types to it:

PUT /v3/workflowTemplates/3
{
    "version": 2,
    "configAttribute": [
        {
            "attributeTypeId": 269
        },
        {
            "attributeTypeId": 271
        }
    ]
}

JSON Response:

{
    "data": {
        "name": "Phishing Investigation Workflow",
        "description": "Workflow for phishing investigations.",
        "active": false,
        "version": 2,
        "configAttribute": [
            {
                "attributeTypeId": 269
            },
            {
                "attributeTypeId": 271
            }
        ]
    },
    "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 to the /v3/workflowTemplates endpoint.

Delete Workflow Templates¶

Send a request in the following format to delete a Workflow Template:

DELETE /v3/workflowTemplates/{workflowTemplateId}

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

DELETE /v3/workflowTemplates/1

JSON Response:

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

Delete Workflow Templates in Bulk¶

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

TC Exchange™ is a trademark of ThreatConnect, Inc.